1 files changed, 340 insertions, 0 deletions
diff --git a/doc/cha-gtls-examples.texi b/doc/cha-gtls-examples.texi
new file mode 100644
index 0000000..8a8675e
--- /dev/null
+++ b/doc/cha-gtls-examples.texi
@@ -0,0 +1,340 @@
+@node GnuTLS application examples
+@chapter GnuTLS application examples
+@anchor{examples}
+@cindex example programs
+@cindex examples
+
+In this chapter several examples of real-world use cases are listed.
+The examples are simplified to promote readability and contain little or 
+no error checking.  
+
+@menu
+* Client examples::
+* Server examples::
+* More advanced client and servers::
+* OCSP example::
+* Miscellaneous examples::
+@end menu
+
+@node Client examples
+@section Client examples
+
+This section contains examples of @acronym{TLS} and @acronym{SSL}
+clients, using @acronym{GnuTLS}. Note that some of the examples require functions
+implemented by another example.
+
+@menu
+* Client example with X.509 certificate support::
+* Datagram TLS client example::
+* Client using a smart card with TLS::
+* Client with Resume capability example::
+* Client example with SSH-style certificate verification::
+@end menu
+
+@node Client example with X.509 certificate support
+@subsection Client example with @acronym{X.509} certificate support
+@anchor{ex-verify}
+
+Let's assume now that we want to create a TCP client which
+communicates with servers that use @acronym{X.509} certificate authentication.
+The following client is a very simple @acronym{TLS} client, which uses
+the high level verification functions for certificates, but does not support session
+resumption.
+
+Note that this client utilizes functionality present in the latest GnuTLS
+version. For a reasonably portable version see @ref{Legacy client example with X.509 certificate support}.
+
+@verbatiminclude examples/ex-client-x509.c
+
+
+@node Datagram TLS client example
+@subsection Datagram @acronym{TLS} client example
+
+This is a client that uses @acronym{UDP} to connect to a
+server. This is the @acronym{DTLS} equivalent to the TLS example
+with X.509 certificates.
+
+@verbatiminclude examples/ex-client-dtls.c
+
+
+@node Client using a smart card with TLS
+@subsection Using a smart card with TLS
+@anchor{ex-pkcs11-client}
+@cindex Smart card example
+
+This example will demonstrate how to load keys and certificates
+from a smart-card or any other @acronym{PKCS} #11 token, and 
+use it in a TLS connection. The difference between this and the
+@ref{Client example with X.509 certificate support} is that the
+client keys are provided as PKCS #11 URIs instead of files.
+
+@verbatiminclude examples/ex-cert-select-pkcs11.c
+
+
+@node Client with Resume capability example
+@subsection Client with resume capability example
+@anchor{ex-resume-client}
+
+This is a modification of the simple client example. Here we
+demonstrate the use of session resumption. The client tries to connect
+once using @acronym{TLS}, close the connection and then try to
+establish a new connection using the previously negotiated data.
+
+@verbatiminclude examples/ex-client-resume.c
+
+
+
+
+@node Client example with SSH-style certificate verification
+@subsection Client example with SSH-style certificate verification
+
+This is an alternative verification function that will use the
+X.509 certificate authorities for verification, but also assume an
+trust on first use (SSH-like) authentication system. That is the user is 
+prompted on unknown public keys and known public keys are considered 
+trusted.
+
+@verbatiminclude examples/ex-verify-ssh.c
+
+@node Server examples
+@section Server examples
+
+This section contains examples of @acronym{TLS} and @acronym{SSL}
+servers, using @acronym{GnuTLS}.
+
+@menu
+* Echo server with X.509 authentication::
+* DTLS echo server with X.509 authentication::
+@end menu
+
+@node Echo server with X.509 authentication
+@subsection Echo server with @acronym{X.509} authentication
+
+This example is a very simple echo server which supports
+@acronym{X.509} authentication.
+
+@verbatiminclude examples/ex-serv-x509.c
+
+
+@node DTLS echo server with X.509 authentication
+@subsection DTLS echo server with @acronym{X.509} authentication
+
+This example is a very simple echo server using Datagram TLS and 
+@acronym{X.509} authentication.
+
+@verbatiminclude examples/ex-serv-dtls.c
+
+
+
+
+@node More advanced client and servers
+@section More advanced client and servers
+
+This section has various, more advanced topics in client and servers.
+
+@menu
+* Client example with anonymous authentication::
+* Using a callback to select the certificate to use::
+* Obtaining session information::
+* Advanced certificate verification example::
+* Client example with PSK authentication::
+* Client example with SRP authentication::
+* Legacy client example with X.509 certificate support::
+* Client example in C++::
+* Echo server with PSK authentication::
+* Echo server with SRP authentication::
+* Echo server with anonymous authentication::
+* Helper functions for TCP connections::
+* Helper functions for UDP connections::
+@end menu
+
+@node Client example with anonymous authentication
+@subsection Client example with anonymous authentication
+
+The simplest client using TLS is the one that doesn't do any
+authentication.  This means no external certificates or passwords are
+needed to set up the connection.  As could be expected, the connection
+is vulnerable to man-in-the-middle (active or redirection) attacks.
+However, the data are integrity protected and encrypted from
+passive eavesdroppers.
+
+Note that due to the vulnerable nature of this method very few public
+servers support it.
+
+@verbatiminclude examples/ex-client-anon.c
+
+@node Using a callback to select the certificate to use
+@subsection Using a callback to select the certificate to use
+
+There are cases where a client holds several certificate and key
+pairs, and may not want to load all of them in the credentials
+structure.  The following example demonstrates the use of the
+certificate selection callback.
+
+@verbatiminclude examples/ex-cert-select.c
+
+
+@node Obtaining session information
+@subsection Obtaining session information
+
+Most of the times it is desirable to know the security properties of
+the current established session.  This includes the underlying ciphers
+and the protocols involved.  That is the purpose of the following
+function.  Note that this function will print meaningful values only
+if called after a successful @funcref{gnutls_handshake}.
+
+@verbatiminclude examples/ex-session-info.c
+
+
+
+@node Advanced certificate verification example
+@subsection Advanced certificate verification
+@anchor{ex-verify2}
+
+An example is listed below which uses the high level verification
+functions to verify a given certificate chain against a set of CAs
+and CRLs.
+
+@verbatiminclude examples/ex-verify.c
+
+
+@node Client example with PSK authentication
+@subsection Client example with @acronym{PSK} authentication
+
+The following client is a very simple @acronym{PSK} @acronym{TLS}
+client which connects to a server and authenticates using a
+@emph{username} and a @emph{key}.
+
+@verbatiminclude examples/ex-client-psk.c
+
+
+@node Client example with SRP authentication
+@subsection Client example with @acronym{SRP} authentication
+
+The following client is a very simple @acronym{SRP} @acronym{TLS}
+client which connects to a server and authenticates using a
+@emph{username} and a @emph{password}. The server may authenticate
+itself using a certificate, and in that case it has to be verified.
+
+@verbatiminclude examples/ex-client-srp.c
+
+
+@node Legacy client example with X.509 certificate support
+@subsection Legacy client example with @acronym{X.509} certificate support
+@anchor{ex-verify-legacy}
+
+For applications that need to maintain compatibility with the GnuTLS 3.1.x
+library, this client example is identical to @ref{Client example with X.509 certificate support}
+but utilizes APIs that were available in GnuTLS 3.1.4. 
+
+@verbatiminclude examples/ex-client-x509-3.1.c
+
+@node Client example in C++
+@subsection Client example using the C++ API
+
+The following client is a simple example of a client client utilizing
+the GnuTLS C++ API.
+
+@verbatiminclude examples/ex-cxx.cpp
+
+
+@node Echo server with PSK authentication
+@subsection Echo server with @acronym{PSK} authentication
+
+This is a server which supports @acronym{PSK} authentication.
+
+@verbatiminclude examples/ex-serv-psk.c
+
+
+@node Echo server with SRP authentication
+@subsection Echo server with @acronym{SRP} authentication
+
+This is a server which supports @acronym{SRP} authentication. It is
+also possible to combine this functionality with a certificate
+server. Here it is separate for simplicity.
+
+@verbatiminclude examples/ex-serv-srp.c
+
+
+@node Echo server with anonymous authentication
+@subsection Echo server with anonymous authentication
+
+This example server supports anonymous authentication, and could be
+used to serve the example client for anonymous authentication.
+
+@verbatiminclude examples/ex-serv-anon.c
+
+
+
+@node Helper functions for TCP connections
+@subsection Helper functions for TCP connections
+
+Those helper function abstract away TCP connection handling from the
+other examples.  It is required to build some examples.
+
+@verbatiminclude examples/tcp.c
+
+@node Helper functions for UDP connections
+@subsection Helper functions for UDP connections
+
+The UDP helper functions abstract away UDP connection handling from the
+other examples.  It is required to build the examples using UDP.
+
+@verbatiminclude examples/udp.c
+
+
+
+@node OCSP example
+@section OCSP example
+
+@anchor{Generate OCSP request}
+@subheading Generate @acronym{OCSP} request
+
+A small tool to generate OCSP requests.
+
+@verbatiminclude examples/ex-ocsp-client.c
+
+@node Miscellaneous examples
+@section Miscellaneous examples
+
+@menu
+* Checking for an alert::
+* X.509 certificate parsing example::
+* Listing the ciphersuites in a priority string::
+* PKCS12 structure generation example::
+@end menu
+
+@node Checking for an alert
+@subsection Checking for an alert
+
+This is a function that checks if an alert has been received in the
+current session.
+
+@verbatiminclude examples/ex-alert.c
+
+@node X.509 certificate parsing example
+@subsection @acronym{X.509} certificate parsing example
+@anchor{ex-x509-info}
+
+To demonstrate the @acronym{X.509} parsing capabilities an example program is
+listed below.  That program reads the peer's certificate, and prints
+information about it.
+
+@verbatiminclude examples/ex-x509-info.c
+
+@node Listing the ciphersuites in a priority string
+@subsection Listing the ciphersuites in a priority string
+
+This is a small program to list the enabled ciphersuites by a 
+priority string.
+
+@verbatiminclude examples/print-ciphersuites.c
+
+@node PKCS12 structure generation example
+@subsection PKCS #12 structure generation example
+
+This small program demonstrates the usage of the PKCS #12 API, by generating
+such a structure.
+
+@verbatiminclude examples/ex-pkcs12.c
+