path: root/doc/cha-programs.texi

@node Other included programs
@chapter Other included programs

Included with @acronym{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.

@menu
* The gnutls-cli tool::
* The gnutls-serv tool::
* The gnutls-cli-debug tool::
@end menu

@node The gnutls-cli tool
@section The gnutls-cli tool
@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.

@example
GnuTLS 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.
     --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.
     --priority PRIORITY STRING
                              Priorities string.
     --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.
     --pgpcertfile FILE       PGP Public Key (certificate) file to
                              use.
     --pgpsubkey HEX|auto     PGP subkey 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.
     --pskusername NAME       PSK username to use.
     --pskkey KEY             PSK key (in hex) to use.
     --opaque-prf-input DATA
                              Use Opaque PRF Input DATA.
     -p, --port PORT          The port to connect to.
     --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
@end example

@menu
* Example client PSK connection::
@end menu

@node Example client PSK connection
@subsection Example client PSK connection
@cindex PSK client

To connect to a server using PSK authentication, you need to enable
the choice of PSK by using a cipher priority parameter such as in the
example below.

@smallexample
$ ./gnutls-cli -p 5556 localhost --pskusername psk_identity \
  --pskkey 88f3824b3e5659f52d00e959bacab954b6540344 \
  --priority NORMAL:-KX-ALL:+ECDHE-PSK:+DHE-PSK:+PSK
Resolving 'localhost'...
Connecting to '127.0.0.1:5556'...
- PSK authentication.
- Version: TLS1.1
- Key Exchange: PSK
- Cipher: AES-128-CBC
- MAC: SHA1
- Compression: NULL
- Handshake was completed

- Simple Client Mode:
@end smallexample

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

@node The gnutls-serv tool
@section The gnutls-serv tool
@cindex gnutls-serv

Simple server program that listens to incoming TLS connections.

@example
GnuTLS 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.
     --pgpkeyfile FILE        PGP Key file to use.
     --pgpcertfile FILE       PGP Public Key (certificate) file to
                              use.
     --pgpsubkey HEX|auto     PGP subkey 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.
     -r, --require-cert       Require a valid certificate.
     -a, --disable-client-cert
                              Disable request for a client
                              certificate.
     --pskpasswd FILE         PSK password file to use.
     --pskhint HINT           PSK identity hint to use.
     --srppasswd FILE         SRP password file to use.
     --srppasswdconf FILE     SRP password conf file to use.
     --opaque-prf-input DATA
                              Use Opaque PRF Input DATA.
     --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.
     --priority PRIORITY STRING
                              Priorities string.
     -l, --list               Print a list of the supported
                              algorithms  and modes.
     -h, --help               prints this help
     -v, --version            prints the program's version number
@end example

@subsection Setting up a test HTTPS server
@cindex HTTPS server
@cindex debug 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 @code{gnutls-serv} as a simple HTTPS server.

The most basic server can be started as:

@smallexample
gnutls-serv --http
@end smallexample

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:

@smallexample
$ 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
...
@end smallexample

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.

@example
$ 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
...
@end example

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

@example
$ 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
...
@end example

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.

@smallexample
$ certtool --to-p12 --load-ca-certificate x509-ca.pem \
  --load-privkey x509-client-key.pem --load-certificate x509-client.pem \
  --outder --outfile x509-client.p12
@end smallexample

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

@smallexample
$ 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
...
@end smallexample

Then start the server again:

@smallexample
$ gnutls-serv --http \
            --x509cafile x509-ca.pem \
            --x509keyfile x509-server-key.pem \
            --x509certfile x509-server.pem
@end smallexample

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.

@smallexample
$ 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 smallexample

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

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

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.

@smallexample
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 smallexample

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

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

The next step is to add support for SRP authentication. This requires
an SRP password file (see @ref{Invoking srptool}).
To start the server with SRP support:

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

Let's also start a server with support for PSK. This would require
a password file created with @code{psktool} (see @ref{Invoking psktool}).

@smallexample
gnutls-serv --http \
            --pskpasswd psk-passwd.txt
@end smallexample

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

@smallexample
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 smallexample


@node The gnutls-cli-debug tool
@section The gnutls-cli-debug tool
@cindex gnutls-cli-debug

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

@example
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 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 max record size (TLS extension)... yes
Checking for SRP authentication support (TLS extension)... yes
Checking for OpenPGP authentication support (TLS extension)... no
@end example