diff options
Diffstat (limited to 'doc/gnutls-serv-examples.texi')
| -rw-r--r-- | doc/gnutls-serv-examples.texi | 147 |
1 files changed, 147 insertions, 0 deletions
diff --git a/doc/gnutls-serv-examples.texi b/doc/gnutls-serv-examples.texi new file mode 100644 index 0000000000..6dd2d75c8f --- /dev/null +++ b/doc/gnutls-serv-examples.texi @@ -0,0 +1,147 @@ +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: + +@example +gnutls-serv --http --priority "NORMAL:+ANON-ECDH:+ANON-DH" +@end example + +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: + +@example +$ 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 example + +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. + +@example +$ 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 example + +For icing, we'll create a proxy certificate for the client too. + +@example +$ 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 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 ECDSA, you can also +create a ECDSA key and certificate for the server. These credentials +will be used in the final example below. + +@example +$ certtool --generate-privkey --ecdsa > x509-server-key-ecc.pem +$ certtool --generate-certificate --load-privkey x509-server-key-ecc.pem \ + --load-ca-certificate x509-ca.pem --load-ca-privkey x509-ca-key.pem \ + --template server.tmpl --outfile x509-server-ecc.pem +@end example + + +The next step is to add support for SRP authentication. This requires +an SRP password file created with @code{srptool}. +To start the server with SRP support: + +@example +gnutls-serv --http --priority NORMAL:+SRP-RSA:+SRP \ + --srppasswdconf srp-tpasswd.conf \ + --srppasswd srp-passwd.txt +@end example + +Let's also start a server with support for PSK. This would require +a password file created with @code{psktool}. + +@example +gnutls-serv --http --priority NORMAL:+ECDHE-PSK:+PSK \ + --pskpasswd psk-passwd.txt +@end example + +If you want a server with support for raw public-keys we can also add these +credentials. Note however that there is no identity information linked to these +keys as is the case with regular x509 certificates. Authentication must be done +via different means. Also we need to explicitly enable raw public-key certificates +via the priority strings. + +@example +gnutls-serv --http --priority NORMAL:+CTYPE-CLI-RAWPK:+CTYPE-SRV-RAWPK \ + --rawpkfile srv.rawpk.pem \ + --rawpkkeyfile srv.key.pem +@end example + + +Finally, we start the server with all the earlier parameters and you +get this command: + +@example +gnutls-serv --http --priority NORMAL:+PSK:+SRP:+CTYPE-CLI-RAWPK:+CTYPE-SRV-RAWPK \ + --x509cafile x509-ca.pem \ + --x509keyfile x509-server-key.pem \ + --x509certfile x509-server.pem \ + --x509keyfile x509-server-key-ecc.pem \ + --x509certfile x509-server-ecc.pem \ + --srppasswdconf srp-tpasswd.conf \ + --srppasswd srp-passwd.txt \ + --pskpasswd psk-passwd.txt \ + --rawpkfile srv.rawpk.pem \ + --rawpkkeyfile srv.key.pem +@end example |