8. Included Programs

Included with GnuTLS are also a few command line tools that let you use the library for common tasks without writing an application. The applications are discussed in this chapter.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

8.1 Invoking certtool

This is a program to generate X.509 certificates, certificate requests, CRLs and private keys.

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

The program can be used interactively or non interactively by specifying the --template command line option. See below for an example of a template file.

How to use certtool interactively:

To generate parameters for Diffie Hellman key exchange, use the command:
$ certtool --generate-dh-params --outfile dh.pem
To generate parameters for the RSA-EXPORT key exchange, use the command:
$ certtool --generate-privkey --bits 512 --outfile rsa.pem

To create a self signed certificate, use the command:
$ certtool --generate-privkey --outfile ca-key.pem $ certtool --generate-self-signed --load-privkey ca-key.pem \ --outfile ca-cert.pem
Note that a self-signed certificate usually belongs to a certificate authority, that signs other certificates.

To create a private key, run:

$ certtool --generate-privkey --outfile key.pem

To generate a certificate using the private key, use the command:

$ certtool --generate-certificate --load-privkey key.pem \
   --outfile cert.pem --load-ca-certificate ca-cert.pem \
   --load-ca-privkey ca-key.pem

To create a certificate request (needed when the certificate is issued by another party), run:
$ certtool --generate-request --load-privkey key.pem \ --outfile request.pem

To generate a certificate using the previous request, use the command:

$ certtool --generate-certificate --load-request request.pem \
   --outfile cert.pem \
   --load-ca-certificate ca-cert.pem --load-ca-privkey ca-key.pem

To view the certificate information, use:

$ certtool --certificate-info --infile cert.pem

To generate a PKCS #12 structure using the previous key and certificate, use the command:

$ certtool --load-certificate cert.pem --load-privkey key.pem \
  --to-p12 --outder --outfile key.p12

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:
$ 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

To create an empty Certificate Revocation List (CRL) do:

$ certtool --generate-crl --load-ca-privkey x509-ca-key.pem --load-ca-certificate x509-ca.pem

To create a CRL that contains some revoked certificates, place the certificates in a file and use --load-certificate as follows:

$ certtool --generate-crl --load-ca-privkey x509-ca-key.pem --load-ca-certificate x509-ca.pem --load-certificate revoked-certs.pem

To verify a Certificate Revocation List (CRL) do:

$ certtool --verify-crl --load-ca-certificate x509-ca.pem < crl.pem

Certtool's template file format:

Firstly create a file named 'cert.cfg' that contains the information about the certificate. An example file is listed below.

Then execute:

$ certtool --generate-certificate cert.pem --load-privkey key.pem  \
   --template cert.cfg \
   --load-ca-certificate ca-cert.pem --load-ca-privkey ca-key.pem

An example certtool template file:

# 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"
#dns_name = "www.morethanone.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

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

8.2 Invoking 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.

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

To connect to a server using PSK authentication, you may use something like:

$ gnutls-cli -p 5556 test.gnutls.org --pskusername jas --pskkey 9e32cf7786321a828ef7668f09fb35db --priority NORMAL:+PSK:-RSA:-DHE-RSA -d 4711

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

8.2.1 Example client PSK connection

If your server only supports the PSK ciphersuite, connecting to it should be as simple as connecting to the server:

$ ./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:

If the server supports several cipher suites, you may need to force it to chose PSK by using a cipher priority parameter such as --priority NORMAL:+PSK:-RSA:-DHE-RSA:-DHE-PSK.

Instead of using the Netconf-way to derive the PSK key from a password, you can also give the PSK username and key directly on the command line:

$ ./gnutls-cli -p 5556 localhost --pskusername psk_identity --pskkey 88f3824b3e5659f52d00e959bacab954b6540344 
Resolving 'localhost'...
Connecting to '127.0.0.1:5556'...
- 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:

By keeping the --pskusername parameter and removing the --pskkey parameter, it will query only for the password during the handshake.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

8.3 Invoking gnutls-cli-debug

This program was created to assist in debugging GnuTLS, but it might be useful to extract a TLS server's capabilities. It's purpose is to connect onto a TLS server, perform some tests and print the server's capabilities. If called with the `-v' parameter a more checks will be performed. An example output is:

crystal:/cvs/gnutls/src$ ./gnutls-cli-debug localhost -p 5556
Resolving 'localhost'...
Connecting to '127.0.0.1:5556'...
Checking for TLS 1.1 support... yes
Checking fallback from TLS 1.1 to... N/A
Checking for TLS 1.0 support... yes
Checking for SSL 3.0 support... yes
Checking for version rollback bug in RSA PMS... no
Checking for version rollback bug in Client Hello... no
Checking whether we need to disable TLS 1.0... N/A
Checking whether the server ignores the RSA PMS version... no
Checking whether the server can accept Hello Extensions... yes
Checking whether the server can accept cipher suites not in SSL 3.0 spec... yes
Checking whether the server can accept a bogus TLS record version in the client hello... yes
Checking for certificate information... N/A
Checking for trusted CAs... N/A
Checking whether the server understands TLS closure alerts... yes
Checking whether the server supports session resumption... yes
Checking for export-grade ciphersuite support... no
Checking RSA-export ciphersuite info... N/A
Checking for anonymous authentication support... no
Checking anonymous Diffie Hellman group info... N/A
Checking for ephemeral Diffie Hellman support... no
Checking ephemeral Diffie Hellman group info... N/A
Checking for AES cipher support (TLS extension)... yes
Checking for 3DES cipher support... yes
Checking for ARCFOUR 128 cipher support... yes
Checking for ARCFOUR 40 cipher support... no
Checking for MD5 MAC support... yes
Checking for SHA1 MAC support... yes
Checking for ZLIB compression support (TLS extension)... yes
Checking for LZO compression support (GnuTLS extension)... yes
Checking for max record size (TLS extension)... yes
Checking for SRP authentication support (TLS extension)... yes
Checking for OpenPGP authentication support (TLS extension)... no

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

8.4 Invoking gnutls-serv

Simple server program that listens to incoming TLS connections.

GNU TLS test server
Usage: gnutls-serv [options]

     -d, --debug integer      Enable debugging
     -g, --generate           Generate Diffie Hellman Parameters.
     -p, --port integer       The port to connect to.
     -q, --quiet              Suppress some messages.
     --nodb                   Does not use the resume database.
     --http                   Act as an HTTP Server.
     --echo                   Act as an Echo Server.
     --dhparams FILE          DH params file to use.
     --x509fmtder             Use DER format for certificates
     --x509cafile FILE        Certificate file to use.
     --x509crlfile FILE       CRL file to use.
     --pgpkeyring FILE        PGP Key ring file to use.
     --pgptrustdb FILE        PGP trustdb file to use.
     --pgpkeyfile FILE        PGP Key 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.
     --x509dsakeyfile FILE    Alternative X.509 key file to use.
     --x509dsacertfile FILE   Alternative X.509 certificate file to
                              use.
     --srppasswd FILE         SRP password file to use.
     --srppasswdconf FILE     SRP password conf file to use.
     --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.
     -l, --list               Print a list of the supported
                              algorithms  and modes.
     -h, --help               prints this help
     -v, --version            prints the program's version number

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

8.4.1 Setting Up a Test HTTPS Server

Running your own TLS server based on GnuTLS can be useful when debugging clients and/or GnuTLS itself. This section describes how to use gnutls-serv as a simple HTTPS server.

The most basic server can be started as:

gnutls-serv --http

It will only support anonymous ciphersuites, which many TLS clients refuse to use.

The next step is to add support for X.509. First we generate a CA:

certtool --generate-privkey > x509-ca-key.pem
echo 'cn = GnuTLS test CA' > ca.tmpl
echo 'ca' >> ca.tmpl
echo 'cert_signing_key' >> ca.tmpl
certtool --generate-self-signed --load-privkey x509-ca-key.pem \
  --template ca.tmpl --outfile x509-ca.pem
...

Then generate a server certificate. Remember to change the dns_name value to the name of your server host, or skip that command to avoid the field.

certtool --generate-privkey > x509-server-key.pem
echo 'organization = GnuTLS test server' > server.tmpl
echo 'cn = test.gnutls.org' >> server.tmpl
echo 'tls_www_server' >> server.tmpl
echo 'encryption_key' >> server.tmpl
echo 'signing_key' >> server.tmpl
echo 'dns_name = test.gnutls.org' >> server.tmpl
certtool --generate-certificate --load-privkey x509-server-key.pem \
  --load-ca-certificate x509-ca.pem --load-ca-privkey x509-ca-key.pem \
  --template server.tmpl --outfile x509-server.pem
...

For use in the client, you may want to generate a client certificate as well.

certtool --generate-privkey > x509-client-key.pem
echo 'cn = GnuTLS test client' > client.tmpl
echo 'tls_www_client' >> client.tmpl
echo 'encryption_key' >> client.tmpl
echo 'signing_key' >> client.tmpl
certtool --generate-certificate --load-privkey x509-client-key.pem \
  --load-ca-certificate x509-ca.pem --load-ca-privkey x509-ca-key.pem \
  --template client.tmpl --outfile x509-client.pem
...

To be able to import the client key/certificate into some applications, you will need to convert them into a PKCS#12 structure. This also encrypts the security sensitive key with a password.

certtool --to-p12 --load-privkey x509-client-key.pem --load-certificate x509-client.pem --outder --outfile x509-client.p12

For icing, we'll create a proxy certificate for the client too.

certtool --generate-privkey > x509-proxy-key.pem
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
...

Then start the server again:

gnutls-serv --http \
            --x509cafile x509-ca.pem \
            --x509keyfile x509-server-key.pem \
            --x509certfile x509-server.pem

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.

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
...

The next step is to create OpenPGP credentials for the server.

gpg --gen-key
...enter whatever details you want, use 'test.gnutls.org' as name...

Make a note of the OpenPGP key identifier of the newly generated key, here it was 5D1D14D8. You will need to export the key for GnuTLS to be able to use it.

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

Let's start the server with support for OpenPGP credentials:

gnutls-serv --http \
            --pgpkeyfile openpgp-server-key.txt \
            --pgpcertfile openpgp-server.txt

The next step is to add support for SRP authentication.

srptool --create-conf srp-tpasswd.conf
srptool --passwd-conf srp-tpasswd.conf --username jas --passwd srp-passwd.txt
Enter password: [TYPE "foo"]

Start the server with SRP support:

gnutls-serv --http \
            --srppasswdconf srp-tpasswd.conf \
            --srppasswd srp-passwd.txt

Let's also add support for PSK.

$ psktool --passwd psk-passwd.txt

Start the server with PSK support:

gnutls-serv --http \
            --pskpasswd psk-passwd.txt

Finally, we start the server with all the earlier parameters and you get this command:

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

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

8.4.2 Example server PSK connection

To set up a PSK server with gnutls-serv you need to create PSK password file (see section Invoking psktool). In the example below, I type password at the prompt.

$ ./psktool -u psk_identity -p psks.txt -n psk_identity_hint
Enter password:
Key stored to psks.txt
$ cat psks.txt
psk_identity:88f3824b3e5659f52d00e959bacab954b6540344
$

After this, start the server pointing to the password file. We disable DHE-PSK.

$ ./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'.

You can now connect to the server using a PSK client (see section Example client PSK connection).

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

8.5 Invoking psktool

This is a program to manage PSK username and keys.

PSKtool help
Usage : psktool [options]
     -u, --username username
                              specify username.
     -p, --passwd FILE        specify a password file.
     -n, --netconf-hint HINT
                              derive key from Netconf password, using 
                              HINT as the psk_identity_hint.
     -s, --keysize SIZE       specify the key size in bytes.
     -v, --version            prints the program's version number
     -h, --help               shows this help text

Normally the file will generate random keys for the indicate username. You may also derive PSK keys from passwords, using the algorithm specified in `draft-ietf-netconf-tls-02.txt'. The algorithm needs a PSK identity hint, which you specify using --netconf-hint. To derive a PSK key from a password with an empty PSK identity hint, using --netconf-hint "".

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

8.6 Invoking srptool

The `srptool' is a very simple program that emulates the programs in the Stanford SRP libraries. It is intended for use in places where you don't expect SRP authentication to be the used for system users. Traditionally libsrp used two files. One called 'tpasswd' which holds usernames and verifiers, and 'tpasswd.conf' which holds generators and primes.

How to use srptool:

To create tpasswd.conf which holds the g and n values for SRP protocol (generator and a large prime), run:
$ srptool --create-conf /etc/tpasswd.conf
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.
$ srptool --passwd /etc/tpasswd \ --passwd-conf /etc/tpasswd.conf -u test
This command will check against a password. If the password matches the one in /etc/tpasswd you will get an ok.
$ srptool --passwd /etc/tpasswd \ --passwd-conf /etc/tpasswd.conf --verify -u test

[ << ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

This document was generated on July, 20 2009 using texi2html 1.76.