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 0000000..6dd2d75
--- /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