From: Simon Josefsson Date: Thu, 5 Jun 2008 14:14:01 +0000 (+0200) Subject: Reorder. X-Git-Tag: gnutls_2_3_13~33 X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=081f072c298cbbecc7aecd9306caad021a358c3f;p=thirdparty%2Fgnutls.git Reorder. --- diff --git a/doc/gnutls.texi b/doc/gnutls.texi index 198e6b6c60..5cec27d6e6 100644 --- a/doc/gnutls.texi +++ b/doc/gnutls.texi @@ -2524,155 +2524,413 @@ let you use the library for common tasks without writing an application. The applications are discussed in this chapter. @menu -* Invoking srptool:: +* Invoking certtool:: * Invoking gnutls-cli:: * Invoking gnutls-cli-debug:: * Invoking gnutls-serv:: -* Invoking certtool:: * Invoking psktool:: +* Invoking srptool:: @end menu -@node Invoking srptool -@section Invoking srptool -@anchor{srptool} -@cindex srptool +@node Invoking certtool +@section Invoking certtool +@cindex certtool -The @file{srptool} is a very simple program that emulates the programs -in the @emph{Stanford SRP libraries}. It is intended for use in -places where you don't expect @acronym{SRP} authentication to be the -used for system users. Traditionally @emph{libsrp} used two -files. One called 'tpasswd' which holds usernames and verifiers, and -'tpasswd.conf' which holds generators and primes. +This is a program to generate @acronym{X.509} certificates, certificate +requests, CRLs and private keys. -How to use srptool: +@verbatim +Certtool help +Usage: certtool [options] + -s, --generate-self-signed + Generate a self-signed certificate. + -c, --generate-certificate + Generate a signed certificate. + --generate-proxy Generate a proxy certificate. + --generate-crl Generate a CRL. + -u, --update-certificate + Update a signed certificate. + -p, --generate-privkey Generate a private key. + -q, --generate-request Generate a PKCS #10 certificate + request. + -e, --verify-chain Verify a PEM encoded certificate chain. + The last certificate in the chain must + be a self signed one. + --verify-crl Verify a CRL. + --generate-dh-params Generate PKCS #3 encoded Diffie Hellman + parameters. + --get-dh-params Get the included PKCS #3 encoded Diffie + Hellman parameters. + --load-privkey FILE Private key file to use. + --load-request FILE Certificate request file to use. + --load-certificate FILE + Certificate file to use. + --load-ca-privkey FILE Certificate authority's private key + file to use. + --load-ca-certificate FILE + Certificate authority's certificate + file to use. + --password PASSWORD Password to use. + -i, --certificate-info Print information on a certificate. + -l, --crl-info Print information on a CRL. + --p12-info Print information on a PKCS #12 + structure. + --p7-info Print information on a PKCS #7 + structure. + --smime-to-p7 Convert S/MIME to PKCS #7 structure. + -k, --key-info Print information on a private key. + --fix-key Regenerate the parameters in a private + key. + --to-p12 Generate a PKCS #12 structure. + -8, --pkcs8 Use PKCS #8 format for private keys. + --dsa Use DSA keys. + --hash STR Hash algorithm to use for signing + (MD5,SHA1,RMD160). + --export-ciphers Use weak encryption algorithms. + --inder Use DER format for input certificates + and private keys. + --outder Use DER format for output certificates + and private keys. + --bits BITS specify the number of bits for key + generation. + --outfile FILE Output file. + --infile FILE Input file. + --template FILE Template file to use for non + interactive operation. + -d, --debug LEVEL specify the debug level. Default is 1. + -h, --help shows this help text + -v, --version shows the program's version + --copyright shows the program's license +@end verbatim + +The program can be used interactively or non interactively by +specifying the @code{--template} command line option. See below for an +example of a template file. + +How to use certtool interactively: @itemize +@item +To generate parameters for Diffie Hellman key exchange, use the command: +@example +$ certtool --generate-dh-params --outfile dh.pem +@end example @item -To create tpasswd.conf which holds the g and n values for -@acronym{SRP} protocol (generator and a large prime), run: +To generate parameters for the RSA-EXPORT key exchange, use the command: +@example +$ certtool --generate-privkey --bits 512 --outfile rsa.pem +@end example + +@end itemize + +@itemize +@item +To create a self signed certificate, use the command: @example -$ srptool --create-conf /etc/tpasswd.conf +$ certtool --generate-privkey --outfile ca-key.pem +$ certtool --generate-self-signed --load-privkey ca-key.pem \ + --outfile ca-cert.pem @end example +Note that a self-signed certificate usually belongs to a certificate +authority, that signs other certificates. + @item -This command will create /etc/tpasswd and will add user 'test' (you -will also be prompted for a password). Verifiers are stored by default -in the way libsrp expects. +To create a private key, run: @example -$ srptool --passwd /etc/tpasswd \ - --passwd-conf /etc/tpasswd.conf -u test +$ certtool --generate-privkey --outfile key.pem @end example @item -This command will check against a password. If the password matches -the one in /etc/tpasswd you will get an ok. +To generate a certificate using the private key, use the command: @example -$ srptool --passwd /etc/tpasswd \ - --passwd-conf /etc/tpasswd.conf --verify -u test +$ certtool --generate-certificate --load-privkey key.pem \ + --outfile cert.pem --load-ca-certificate ca-cert.pem \ + --load-ca-privkey ca-key.pem @end example -@end itemize +@item +To create a certificate request (needed when the certificate is issued by +another party), run: -@node Invoking gnutls-cli -@section Invoking gnutls-cli -@cindex gnutls-cli +@example +$ certtool --generate-request --load-privkey key.pem \ + --outfile request.pem +@end example -Simple client program to set up a TLS connection to some other -computer. It sets up a TLS connection and forwards data from the -standard input to the secured socket and vice versa. +@item +To generate a certificate using the previous request, use the command: -@verbatim -GNU TLS test client -Usage: gnutls-cli [options] hostname +@example +$ certtool --generate-certificate --load-request request.pem \ + --outfile cert.pem \ + --load-ca-certificate ca-cert.pem --load-ca-privkey ca-key.pem +@end example - -d, --debug integer Enable debugging - -r, --resume Connect, establish a session. Connect - again and resume this session. - -s, --starttls Connect, establish a plain session and - start TLS when EOF or a SIGALRM is - received. - --crlf Send CR LF instead of LF. - --x509fmtder Use DER format for certificates to read - from. - -f, --fingerprint Send the openpgp fingerprint, instead - of the key. - --disable-extensions Disable all the TLS extensions. - --print-cert Print the certificate in PEM format. - -p, --port integer The port to connect to. - --recordsize integer The maximum record size to advertize. - -V, --verbose More verbose output. - --ciphers cipher1 cipher2... - Ciphers to enable. - --protocols protocol1 protocol2... - Protocols to enable. - --comp comp1 comp2... Compression methods to enable. - --macs mac1 mac2... MACs to enable. - --kx kx1 kx2... Key exchange methods to enable. - --ctypes certType1 certType2... - Certificate types to enable. - --x509cafile FILE Certificate file to use. - --x509crlfile FILE CRL file to use. - --pgpkeyfile FILE PGP Key file to use. - --pgpkeyring FILE PGP Key ring file to use. - --pgptrustdb FILE PGP trustdb file to use. - --pgpcertfile FILE PGP Public Key (certificate) file to - use. - --x509keyfile FILE X.509 key file to use. - --x509certfile FILE X.509 Certificate file to use. - --srpusername NAME SRP username to use. - --srppasswd PASSWD SRP password to use. - --insecure Don't abort program if server - certificate can't be validated. - -l, --list Print a list of the supported - algorithms and modes. - -h, --help prints this help - -v, --version prints the program's version number - --copyright prints the program's license -@end verbatim +@item +To view the certificate information, use: -To connect to a server using PSK authentication, you may use something -like: +@example +$ certtool --certificate-info --infile cert.pem +@end example -@smallexample -$ gnutls-cli -p 5556 test.gnutls.org --pskusername jas --pskkey 9e32cf7786321a828ef7668f09fb35db --priority NORMAL:+PSK:-RSA:-DHE-RSA -d 4711 -@end smallexample +@item +To generate a @acronym{PKCS} #12 structure using the previous key and +certificate, use the command: -@menu -* Example client PSK connection:: -@end menu +@example +$ certtool --load-certificate cert.pem --load-privkey key.pem \ + --to-p12 --outder --outfile key.p12 +@end example -@node Example client PSK connection -@subsection Example client PSK connection -@cindex PSK client +@item +Proxy certificate can be used to delegate your credential to a +temporary, typically short-lived, certificate. To create one from the +previously created certificate, first create a temporary key and then +generate a proxy certificate for it, using the commands: -If your server only supports the PSK ciphersuite, connecting to it -should be as simple as connecting to the server: +@example +$ certtool --generate-privkey > proxy-key.pem +$ certtool --generate-proxy --load-ca-privkey key.pem \ + --load-privkey proxy-key.pem --load-certificate cert.pem \ + --outfile proxy-cert.pem +@end example -@smallexample -$ ./gnutls-cli -p 5556 localhost -Resolving 'localhost'... -Connecting to '127.0.0.1:5556'... -- PSK client callback. PSK hint 'psk_identity_hint' -Enter PSK identity: psk_identity -Enter password: -- PSK authentication. PSK hint 'psk_identity_hint' -- Version: TLS1.1 -- Key Exchange: PSK -- Cipher: AES-128-CBC -- MAC: SHA1 -- Compression: NULL -- Handshake was completed +@item +To create an empty Certificate Revocation List (CRL) do: -- Simple Client Mode: -@end smallexample +@example +$ certtool --generate-crl --load-ca-privkey x509-ca-key.pem --load-ca-certificate x509-ca.pem +@end example -If the server supports several cipher suites, you may need to force it -to chose PSK by using a cipher priority parameter such as -@code{--priority NORMAL:+PSK:-RSA:-DHE-RSA:-DHE-PSK}. +To create a CRL that contains some revoked certificates, place the +certificates in a file and use @code{--load-certificate} as follows: + +@example +$ certtool --generate-crl --load-ca-privkey x509-ca-key.pem --load-ca-certificate x509-ca.pem --load-certificate revoked-certs.pem +@end example + +@item +To verify a Certificate Revocation List (CRL) do: + +@example +$ certtool --verify-crl --load-ca-certificate x509-ca.pem < crl.pem +@end example + +@end itemize + +Certtool's template file format: + +@itemize + +@item +Firstly create a file named 'cert.cfg' that contains the information +about the certificate. An example file is listed below. + +@item +Then execute: + +@example +$ certtool --generate-certificate cert.pem --load-privkey key.pem \ + --template cert.cfg \ + --load-ca-certificate ca-cert.pem --load-ca-privkey ca-key.pem +@end example + +@end itemize + +An example certtool template file: + +@example +# X.509 Certificate options +# +# DN options + +# The organization of the subject. +organization = "Koko inc." + +# The organizational unit of the subject. +unit = "sleeping dept." + +# The locality of the subject. +# locality = + +# The state of the certificate owner. +state = "Attiki" + +# The country of the subject. Two letter code. +country = GR + +# The common name of the certificate owner. +cn = "Cindy Lauper" + +# A user id of the certificate owner. +#uid = "clauper" + +# If the supported DN OIDs are not adequate you can set +# any OID here. +# For example set the X.520 Title and the X.520 Pseudonym +# by using OID and string pairs. +#dn_oid = "2.5.4.12" "Dr." "2.5.4.65" "jackal" + +# This is deprecated and should not be used in new +# certificates. +# pkcs9_email = "none@@none.org" + +# The serial number of the certificate +serial = 007 + +# In how many days, counting from today, this certificate will expire. +expiration_days = 700 + +# X.509 v3 extensions + +# A dnsname in case of a WWW server. +#dns_name = "www.none.org" + +# An IP address in case of a server. +#ip_address = "192.168.1.1" + +# An email in case of a person +email = "none@@none.org" + +# An URL that has CRLs (certificate revocation lists) +# available. Needed in CA certificates. +#crl_dist_points = "http://www.getcrl.crl/getcrl/" + +# Whether this is a CA certificate or not +#ca + +# Whether this certificate will be used for a TLS client +#tls_www_client + +# Whether this certificate will be used for a TLS server +#tls_www_server + +# Whether this certificate will be used to sign data (needed +# in TLS DHE ciphersuites). +signing_key + +# Whether this certificate will be used to encrypt data (needed +# in TLS RSA ciphersuites). Note that it is prefered to use different +# keys for encryption and signing. +#encryption_key + +# Whether this key will be used to sign other certificates. +#cert_signing_key + +# Whether this key will be used to sign CRLs. +#crl_signing_key + +# Whether this key will be used to sign code. +#code_signing_key + +# Whether this key will be used to sign OCSP data. +#ocsp_signing_key + +# Whether this key will be used for time stamping. +#time_stamping_key +@end example + +@node Invoking gnutls-cli +@section Invoking gnutls-cli +@cindex gnutls-cli + +Simple client program to set up a TLS connection to some other +computer. It sets up a TLS connection and forwards data from the +standard input to the secured socket and vice versa. + +@verbatim +GNU TLS test client +Usage: gnutls-cli [options] hostname + + -d, --debug integer Enable debugging + -r, --resume Connect, establish a session. Connect + again and resume this session. + -s, --starttls Connect, establish a plain session and + start TLS when EOF or a SIGALRM is + received. + --crlf Send CR LF instead of LF. + --x509fmtder Use DER format for certificates to read + from. + -f, --fingerprint Send the openpgp fingerprint, instead + of the key. + --disable-extensions Disable all the TLS extensions. + --print-cert Print the certificate in PEM format. + -p, --port integer The port to connect to. + --recordsize integer The maximum record size to advertize. + -V, --verbose More verbose output. + --ciphers cipher1 cipher2... + Ciphers to enable. + --protocols protocol1 protocol2... + Protocols to enable. + --comp comp1 comp2... Compression methods to enable. + --macs mac1 mac2... MACs to enable. + --kx kx1 kx2... Key exchange methods to enable. + --ctypes certType1 certType2... + Certificate types to enable. + --x509cafile FILE Certificate file to use. + --x509crlfile FILE CRL file to use. + --pgpkeyfile FILE PGP Key file to use. + --pgpkeyring FILE PGP Key ring file to use. + --pgptrustdb FILE PGP trustdb file to use. + --pgpcertfile FILE PGP Public Key (certificate) file to + use. + --x509keyfile FILE X.509 key file to use. + --x509certfile FILE X.509 Certificate file to use. + --srpusername NAME SRP username to use. + --srppasswd PASSWD SRP password to use. + --insecure Don't abort program if server + certificate can't be validated. + -l, --list Print a list of the supported + algorithms and modes. + -h, --help prints this help + -v, --version prints the program's version number + --copyright prints the program's license +@end verbatim + +To connect to a server using PSK authentication, you may use something +like: + +@smallexample +$ gnutls-cli -p 5556 test.gnutls.org --pskusername jas --pskkey 9e32cf7786321a828ef7668f09fb35db --priority NORMAL:+PSK:-RSA:-DHE-RSA -d 4711 +@end smallexample + +@menu +* Example client PSK connection:: +@end menu + +@node Example client PSK connection +@subsection Example client PSK connection +@cindex PSK client + +If your server only supports the PSK ciphersuite, connecting to it +should be as simple as connecting to the server: + +@smallexample +$ ./gnutls-cli -p 5556 localhost +Resolving 'localhost'... +Connecting to '127.0.0.1:5556'... +- PSK client callback. PSK hint 'psk_identity_hint' +Enter PSK identity: psk_identity +Enter password: +- PSK authentication. PSK hint 'psk_identity_hint' +- Version: TLS1.1 +- Key Exchange: PSK +- Cipher: AES-128-CBC +- MAC: SHA1 +- Compression: NULL +- Handshake was completed + +- Simple Client Mode: +@end smallexample + +If the server supports several cipher suites, you may need to force it +to chose PSK by using a cipher priority parameter such as +@code{--priority NORMAL:+PSK:-RSA:-DHE-RSA:-DHE-PSK}. @cindex Netconf Instead of using the Netconf-way to derive the PSK key from a @@ -2873,441 +3131,138 @@ echo 'cn = GnuTLS test client proxy' > proxy.tmpl certtool --generate-proxy --load-privkey x509-proxy-key.pem \ --load-ca-certificate x509-client.pem --load-ca-privkey x509-client-key.pem \ --load-certificate x509-client.pem --template proxy.tmpl \ - --outfile x509-proxy.pem -... -@end example - -Then start the server again: - -@example -gnutls-serv --http \ - --x509cafile x509-ca.pem \ - --x509keyfile x509-server-key.pem \ - --x509certfile x509-server.pem -@end example - -Try connecting to the server using your web browser. Note that the -server listens to port 5556 by default. - -While you are at it, to allow connections using DSA, you can also -create a DSA key and certificate for the server. These credentials -will be used in the final example below. - -@example -certtool --generate-privkey --dsa > x509-server-key-dsa.pem -certtool --generate-certificate --load-privkey x509-server-key-dsa.pem \ - --load-ca-certificate x509-ca.pem --load-ca-privkey x509-ca-key.pem \ - --template server.tmpl --outfile x509-server-dsa.pem -... -@end example - -The next step is to create OpenPGP credentials for the server. - -@example -gpg --gen-key -...enter whatever details you want, use 'test.gnutls.org' as name... -@end example - -Make a note of the OpenPGP key identifier of the newly generated key, -here it was @code{5D1D14D8}. You will need to export the key for -GnuTLS to be able to use it. - -@example -gpg -a --export 5D1D14D8 > openpgp-server.txt -gpg --export 5D1D14D8 > openpgp-server.bin -gpg --export-secret-keys 5D1D14D8 > openpgp-server-key.bin -gpg -a --export-secret-keys 5D1D14D8 > openpgp-server-key.txt -@end example - -Let's start the server with support for OpenPGP credentials: - -@example -gnutls-serv --http \ - --pgpkeyfile openpgp-server-key.txt \ - --pgpcertfile openpgp-server.txt -@end example - -The next step is to add support for SRP authentication. - -@example -srptool --create-conf srp-tpasswd.conf -srptool --passwd-conf srp-tpasswd.conf --username jas --passwd srp-passwd.txt -Enter password: [TYPE "foo"] -@end example - -Start the server with SRP support: - -@example -gnutls-serv --http \ - --srppasswdconf srp-tpasswd.conf \ - --srppasswd srp-passwd.txt -@end example - -Let's also add support for PSK. - -@example -$ psktool --passwd psk-passwd.txt -@end example - -Start the server with PSK support: - -@example -gnutls-serv --http \ - --pskpasswd psk-passwd.txt -@end example - -Finally, we start the server with all the earlier parameters and you -get this command: - -@example -gnutls-serv --http \ - --x509cafile x509-ca.pem \ - --x509keyfile x509-server-key.pem \ - --x509certfile x509-server.pem \ - --x509dsakeyfile x509-server-key-dsa.pem \ - --x509dsacertfile x509-server-dsa.pem \ - --pgpkeyfile openpgp-server-key.txt \ - --pgpcertfile openpgp-server.txt \ - --srppasswdconf srp-tpasswd.conf \ - --srppasswd srp-passwd.txt \ - --pskpasswd psk-passwd.txt -@end example - -@menu -* Example server PSK connection:: -@end menu - -@node Example server PSK connection -@subsection Example server PSK connection -@cindex PSK server - -To set up a PSK server with @code{gnutls-serv} you need to create PSK -password file (@pxref{Invoking psktool}). In the example below, I -type @code{password} at the prompt. - -@smallexample -$ ./psktool -u psk_identity -p psks.txt -n psk_identity_hint -Enter password: -Key stored to psks.txt -$ cat psks.txt -psk_identity:88f3824b3e5659f52d00e959bacab954b6540344 -$ -@end smallexample - -After this, start the server pointing to the password file. We -disable DHE-PSK. - -@smallexample -$ ./gnutls-serv --pskpasswd psks.txt --pskhint psk_identity_hint --priority NORMAL:-DHE-PSK -Set static Diffie Hellman parameters, consider --dhparams. -Echo Server ready. Listening to port '5556'. -@end smallexample - -You can now connect to the server using a PSK client (@pxref{Example -client PSK connection}). - -@node Invoking certtool -@section Invoking certtool -@cindex certtool - -This is a program to generate @acronym{X.509} certificates, certificate -requests, CRLs and private keys. - -@verbatim -Certtool help -Usage: certtool [options] - -s, --generate-self-signed - Generate a self-signed certificate. - -c, --generate-certificate - Generate a signed certificate. - --generate-proxy Generate a proxy certificate. - --generate-crl Generate a CRL. - -u, --update-certificate - Update a signed certificate. - -p, --generate-privkey Generate a private key. - -q, --generate-request Generate a PKCS #10 certificate - request. - -e, --verify-chain Verify a PEM encoded certificate chain. - The last certificate in the chain must - be a self signed one. - --verify-crl Verify a CRL. - --generate-dh-params Generate PKCS #3 encoded Diffie Hellman - parameters. - --get-dh-params Get the included PKCS #3 encoded Diffie - Hellman parameters. - --load-privkey FILE Private key file to use. - --load-request FILE Certificate request file to use. - --load-certificate FILE - Certificate file to use. - --load-ca-privkey FILE Certificate authority's private key - file to use. - --load-ca-certificate FILE - Certificate authority's certificate - file to use. - --password PASSWORD Password to use. - -i, --certificate-info Print information on a certificate. - -l, --crl-info Print information on a CRL. - --p12-info Print information on a PKCS #12 - structure. - --p7-info Print information on a PKCS #7 - structure. - --smime-to-p7 Convert S/MIME to PKCS #7 structure. - -k, --key-info Print information on a private key. - --fix-key Regenerate the parameters in a private - key. - --to-p12 Generate a PKCS #12 structure. - -8, --pkcs8 Use PKCS #8 format for private keys. - --dsa Use DSA keys. - --hash STR Hash algorithm to use for signing - (MD5,SHA1,RMD160). - --export-ciphers Use weak encryption algorithms. - --inder Use DER format for input certificates - and private keys. - --outder Use DER format for output certificates - and private keys. - --bits BITS specify the number of bits for key - generation. - --outfile FILE Output file. - --infile FILE Input file. - --template FILE Template file to use for non - interactive operation. - -d, --debug LEVEL specify the debug level. Default is 1. - -h, --help shows this help text - -v, --version shows the program's version - --copyright shows the program's license -@end verbatim - -The program can be used interactively or non interactively by -specifying the @code{--template} command line option. See below for an -example of a template file. - -How to use certtool interactively: - -@itemize -@item -To generate parameters for Diffie Hellman key exchange, use the command: -@example -$ certtool --generate-dh-params --outfile dh.pem -@end example - -@item -To generate parameters for the RSA-EXPORT key exchange, use the command: -@example -$ certtool --generate-privkey --bits 512 --outfile rsa.pem -@end example - -@end itemize - -@itemize - -@item -To create a self signed certificate, use the command: -@example -$ certtool --generate-privkey --outfile ca-key.pem -$ certtool --generate-self-signed --load-privkey ca-key.pem \ - --outfile ca-cert.pem -@end example - -Note that a self-signed certificate usually belongs to a certificate -authority, that signs other certificates. - -@item -To create a private key, run: - -@example -$ certtool --generate-privkey --outfile key.pem -@end example - -@item -To generate a certificate using the private key, use the command: - -@example -$ certtool --generate-certificate --load-privkey key.pem \ - --outfile cert.pem --load-ca-certificate ca-cert.pem \ - --load-ca-privkey ca-key.pem -@end example - -@item -To create a certificate request (needed when the certificate is issued by -another party), run: - -@example -$ certtool --generate-request --load-privkey key.pem \ - --outfile request.pem -@end example - -@item -To generate a certificate using the previous request, use the command: - -@example -$ certtool --generate-certificate --load-request request.pem \ - --outfile cert.pem \ - --load-ca-certificate ca-cert.pem --load-ca-privkey ca-key.pem + --outfile x509-proxy.pem +... @end example -@item -To view the certificate information, use: +Then start the server again: @example -$ certtool --certificate-info --infile cert.pem +gnutls-serv --http \ + --x509cafile x509-ca.pem \ + --x509keyfile x509-server-key.pem \ + --x509certfile x509-server.pem @end example -@item -To generate a @acronym{PKCS} #12 structure using the previous key and -certificate, use the command: +Try connecting to the server using your web browser. Note that the +server listens to port 5556 by default. + +While you are at it, to allow connections using DSA, you can also +create a DSA key and certificate for the server. These credentials +will be used in the final example below. @example -$ certtool --load-certificate cert.pem --load-privkey key.pem \ - --to-p12 --outder --outfile key.p12 +certtool --generate-privkey --dsa > x509-server-key-dsa.pem +certtool --generate-certificate --load-privkey x509-server-key-dsa.pem \ + --load-ca-certificate x509-ca.pem --load-ca-privkey x509-ca-key.pem \ + --template server.tmpl --outfile x509-server-dsa.pem +... @end example -@item -Proxy certificate can be used to delegate your credential to a -temporary, typically short-lived, certificate. To create one from the -previously created certificate, first create a temporary key and then -generate a proxy certificate for it, using the commands: +The next step is to create OpenPGP credentials for the server. @example -$ certtool --generate-privkey > proxy-key.pem -$ certtool --generate-proxy --load-ca-privkey key.pem \ - --load-privkey proxy-key.pem --load-certificate cert.pem \ - --outfile proxy-cert.pem +gpg --gen-key +...enter whatever details you want, use 'test.gnutls.org' as name... @end example -@item -To create an empty Certificate Revocation List (CRL) do: +Make a note of the OpenPGP key identifier of the newly generated key, +here it was @code{5D1D14D8}. You will need to export the key for +GnuTLS to be able to use it. @example -$ certtool --generate-crl --load-ca-privkey x509-ca-key.pem --load-ca-certificate x509-ca.pem +gpg -a --export 5D1D14D8 > openpgp-server.txt +gpg --export 5D1D14D8 > openpgp-server.bin +gpg --export-secret-keys 5D1D14D8 > openpgp-server-key.bin +gpg -a --export-secret-keys 5D1D14D8 > openpgp-server-key.txt @end example -To create a CRL that contains some revoked certificates, place the -certificates in a file and use @code{--load-certificate} as follows: +Let's start the server with support for OpenPGP credentials: @example -$ certtool --generate-crl --load-ca-privkey x509-ca-key.pem --load-ca-certificate x509-ca.pem --load-certificate revoked-certs.pem +gnutls-serv --http \ + --pgpkeyfile openpgp-server-key.txt \ + --pgpcertfile openpgp-server.txt @end example -@item -To verify a Certificate Revocation List (CRL) do: +The next step is to add support for SRP authentication. @example -$ certtool --verify-crl --load-ca-certificate x509-ca.pem < crl.pem +srptool --create-conf srp-tpasswd.conf +srptool --passwd-conf srp-tpasswd.conf --username jas --passwd srp-passwd.txt +Enter password: [TYPE "foo"] @end example -@end itemize - -Certtool's template file format: - -@itemize - -@item -Firstly create a file named 'cert.cfg' that contains the information -about the certificate. An example file is listed below. - -@item -Then execute: +Start the server with SRP support: @example -$ certtool --generate-certificate cert.pem --load-privkey key.pem \ - --template cert.cfg \ - --load-ca-certificate ca-cert.pem --load-ca-privkey ca-key.pem +gnutls-serv --http \ + --srppasswdconf srp-tpasswd.conf \ + --srppasswd srp-passwd.txt @end example -@end itemize - -An example certtool template file: +Let's also add support for PSK. @example -# X.509 Certificate options -# -# DN options - -# The organization of the subject. -organization = "Koko inc." - -# The organizational unit of the subject. -unit = "sleeping dept." - -# The locality of the subject. -# locality = - -# The state of the certificate owner. -state = "Attiki" - -# The country of the subject. Two letter code. -country = GR - -# The common name of the certificate owner. -cn = "Cindy Lauper" - -# A user id of the certificate owner. -#uid = "clauper" - -# If the supported DN OIDs are not adequate you can set -# any OID here. -# For example set the X.520 Title and the X.520 Pseudonym -# by using OID and string pairs. -#dn_oid = "2.5.4.12" "Dr." "2.5.4.65" "jackal" - -# This is deprecated and should not be used in new -# certificates. -# pkcs9_email = "none@@none.org" - -# The serial number of the certificate -serial = 007 - -# In how many days, counting from today, this certificate will expire. -expiration_days = 700 - -# X.509 v3 extensions - -# A dnsname in case of a WWW server. -#dns_name = "www.none.org" - -# An IP address in case of a server. -#ip_address = "192.168.1.1" - -# An email in case of a person -email = "none@@none.org" +$ psktool --passwd psk-passwd.txt +@end example -# An URL that has CRLs (certificate revocation lists) -# available. Needed in CA certificates. -#crl_dist_points = "http://www.getcrl.crl/getcrl/" +Start the server with PSK support: -# Whether this is a CA certificate or not -#ca +@example +gnutls-serv --http \ + --pskpasswd psk-passwd.txt +@end example -# Whether this certificate will be used for a TLS client -#tls_www_client +Finally, we start the server with all the earlier parameters and you +get this command: -# Whether this certificate will be used for a TLS server -#tls_www_server +@example +gnutls-serv --http \ + --x509cafile x509-ca.pem \ + --x509keyfile x509-server-key.pem \ + --x509certfile x509-server.pem \ + --x509dsakeyfile x509-server-key-dsa.pem \ + --x509dsacertfile x509-server-dsa.pem \ + --pgpkeyfile openpgp-server-key.txt \ + --pgpcertfile openpgp-server.txt \ + --srppasswdconf srp-tpasswd.conf \ + --srppasswd srp-passwd.txt \ + --pskpasswd psk-passwd.txt +@end example -# Whether this certificate will be used to sign data (needed -# in TLS DHE ciphersuites). -signing_key +@menu +* Example server PSK connection:: +@end menu -# Whether this certificate will be used to encrypt data (needed -# in TLS RSA ciphersuites). Note that it is prefered to use different -# keys for encryption and signing. -#encryption_key +@node Example server PSK connection +@subsection Example server PSK connection +@cindex PSK server -# Whether this key will be used to sign other certificates. -#cert_signing_key +To set up a PSK server with @code{gnutls-serv} you need to create PSK +password file (@pxref{Invoking psktool}). In the example below, I +type @code{password} at the prompt. -# Whether this key will be used to sign CRLs. -#crl_signing_key +@smallexample +$ ./psktool -u psk_identity -p psks.txt -n psk_identity_hint +Enter password: +Key stored to psks.txt +$ cat psks.txt +psk_identity:88f3824b3e5659f52d00e959bacab954b6540344 +$ +@end smallexample -# Whether this key will be used to sign code. -#code_signing_key +After this, start the server pointing to the password file. We +disable DHE-PSK. -# Whether this key will be used to sign OCSP data. -#ocsp_signing_key +@smallexample +$ ./gnutls-serv --pskpasswd psks.txt --pskhint psk_identity_hint --priority NORMAL:-DHE-PSK +Set static Diffie Hellman parameters, consider --dhparams. +Echo Server ready. Listening to port '5556'. +@end smallexample -# Whether this key will be used for time stamping. -#time_stamping_key -@end example +You can now connect to the server using a PSK client (@pxref{Example +client PSK connection}). @node Invoking psktool @section Invoking psktool @@ -3336,6 +3291,51 @@ needs a PSK identity hint, which you specify using @code{--netconf-hint}. To derive a PSK key from a password with an empty PSK identity hint, using @code{--netconf-hint ""}. +@node Invoking srptool +@section Invoking srptool +@anchor{srptool} +@cindex srptool + +The @file{srptool} is a very simple program that emulates the programs +in the @emph{Stanford SRP libraries}. It is intended for use in +places where you don't expect @acronym{SRP} authentication to be the +used for system users. Traditionally @emph{libsrp} used two +files. One called 'tpasswd' which holds usernames and verifiers, and +'tpasswd.conf' which holds generators and primes. + +How to use srptool: + +@itemize + +@item +To create tpasswd.conf which holds the g and n values for +@acronym{SRP} protocol (generator and a large prime), run: + +@example +$ srptool --create-conf /etc/tpasswd.conf +@end example + +@item +This command will create /etc/tpasswd and will add user 'test' (you +will also be prompted for a password). Verifiers are stored by default +in the way libsrp expects. + +@example +$ srptool --passwd /etc/tpasswd \ + --passwd-conf /etc/tpasswd.conf -u test +@end example + +@item +This command will check against a password. If the password matches +the one in /etc/tpasswd you will get an ok. + +@example +$ srptool --passwd /etc/tpasswd \ + --passwd-conf /etc/tpasswd.conf --verify -u test +@end example + +@end itemize + @node Function reference @chapter Function Reference @cindex Function reference