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
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
@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
projects / thirdparty / gnutls.git / commitdiff
