doc: re-organized and modernized examplestmp-psk-doc-update

Signed-off-by: Nikos Mavrogiannopoulos <nmav@redhat.com>

4 files changed, 190 insertions, 194 deletions

diff --git a/doc/cha-cert-auth.texi b/doc/cha-cert-auth.texi
index 5c106da4f4..d48e1bb814 100644
--- a/doc/cha-cert-auth.texi
+++ b/doc/cha-cert-auth.texi
@@ -513,7 +513,7 @@ failure is not enough to compromise the system. For example a server compromise
 may be detected using OCSP, and a CA compromise can be detected using
 the trust on first use method.
 Such a hybrid system with X.509 and trust on first use authentication is 
-shown in @ref{Simple client example with SSH-style certificate verification}.
+shown in @ref{Client example with SSH-style certificate verification}.
 
 See @ref{Certificate verification} on how to use the available functionality.
 
diff --git a/doc/cha-gtls-examples.texi b/doc/cha-gtls-examples.texi
index a760503822..bb8bca3004 100644
--- a/doc/cha-gtls-examples.texi
+++ b/doc/cha-gtls-examples.texi
@@ -11,6 +11,7 @@ no error checking.
 @menu
 * Client examples::
 * Server examples::
+* More advanced client and servers::
 * OCSP example::
 * Miscellaneous examples::
 @end menu
@@ -23,24 +24,15 @@ clients, using @acronym{GnuTLS}. Note that some of the examples require function
 implemented by another example.
 
 @menu
-* Simple client example with X.509 certificate support::
-* Simple client example with SSH-style certificate verification::
-* Simple client example with anonymous authentication::
-* Simple Datagram TLS client example::
-* Obtaining session information::
-* Using a callback to select the certificate to use::
-* Verifying a certificate::
+* Client example with X.509 certificate support::
+* Datagram TLS client example::
 * Client using a smart card with TLS::
 * Client with Resume capability example::
-* Simple client example with SRP authentication::
-* Legacy client example with X.509 certificate support::
-* Simple client example in C++::
-* Helper functions for TCP connections::
-* Helper functions for UDP connections::
+* Client example with SSH-style certificate verification::
 @end menu
 
-@node Simple client example with X.509 certificate support
-@subsection Simple client example with @acronym{X.509} certificate support
+@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
@@ -54,8 +46,47 @@ version. For a reasonably portable version see @ref{Legacy client example with X
 
 @verbatiminclude examples/ex-client-x509.c
 
-@node Simple client example with SSH-style certificate verification
-@subsection Simple client example with SSH-style certificate verification
+
+@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
@@ -65,8 +96,58 @@ trusted.
 
 @verbatiminclude examples/ex-verify-ssh.c
 
-@node Simple client example with anonymous authentication
-@subsection Simple client example with anonymous authentication
+@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 SRP authentication::
+* Legacy client example with X.509 certificate support::
+* Client example in C++::
+* 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
@@ -80,15 +161,16 @@ 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
 
-@node Simple Datagram TLS client example
-@subsection Simple datagram @acronym{TLS} client example
+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.
 
-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-cert-select.c
 
-@verbatiminclude examples/ex-client-dtls.c
 
 @node Obtaining session information
 @subsection Obtaining session information
@@ -101,51 +183,20 @@ if called after a successful @funcref{gnutls_handshake}.
 
 @verbatiminclude examples/ex-session-info.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 Verifying a certificate
-@subsection Verifying a certificate
+@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 list.
+functions to verify a given certificate chain against a set of CAs
+and CRLs.
 
 @verbatiminclude examples/ex-verify.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.
-
-@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 Simple client example with SRP authentication
-@subsection Simple client example with @acronym{SRP} authentication
+@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
@@ -160,56 +211,19 @@ itself using a certificate, and in that case it has to be verified.
 @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{Simple client example with X.509 certificate support}
+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 Simple client example in C++
-@subsection Simple client example using the C++ API
+@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 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 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::
-* Echo server with SRP authentication::
-* Echo server with anonymous 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 Echo server with SRP authentication
 @subsection Echo server with @acronym{SRP} authentication
@@ -220,6 +234,7 @@ 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
 
@@ -228,13 +243,24 @@ used to serve the example client for anonymous authentication.
 
 @verbatiminclude examples/ex-serv-anon.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 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
diff --git a/doc/examples/ex-client-resume.c b/doc/examples/ex-client-resume.c
index 218cc4447a..cf67bfcf1b 100644
--- a/doc/examples/ex-client-resume.c
+++ b/doc/examples/ex-client-resume.c
@@ -7,16 +7,22 @@
 #include <string.h>
 #include <stdio.h>
 #include <stdlib.h>
+#include <assert.h>
 #include <gnutls/gnutls.h>
 
-/* Those functions are defined in other examples.
- */
 extern void check_alert(gnutls_session_t session, int ret);
 extern int tcp_connect(void);
 extern void tcp_close(int sd);
 
+/* A very basic TLS client, with X.509 authentication and server certificate
+ * verification as well as session resumption.
+ *
+ * Note that error recovery is minimal for simplicity.
+ */
+
+#define CHECK(x) assert((x)>=0)
+
 #define MAX_BUF 1024
-#define CAFILE "/etc/ssl/certs/ca-certificates.crt"
 #define MSG "GET / HTTP/1.0\r\n\r\n"
 
 int main(void)
@@ -30,41 +36,41 @@ int main(void)
         /* variables used in session resuming 
          */
         int t;
-        char *session_data = NULL;
-        size_t session_data_size = 0;
-
-        gnutls_global_init();
+        gnutls_datum_t sdata;
 
-        /* X509 stuff */
-        gnutls_certificate_allocate_credentials(&xcred);
+        /* for backwards compatibility with gnutls < 3.3.0 */
+        CHECK(gnutls_global_init());
 
-        gnutls_certificate_set_x509_trust_file(xcred, CAFILE,
-                                               GNUTLS_X509_FMT_PEM);
+        CHECK(gnutls_certificate_allocate_credentials(&xcred));
+        CHECK(gnutls_certificate_set_x509_system_trust(xcred));
 
         for (t = 0; t < 2; t++) {       /* connect 2 times to the server */
 
                 sd = tcp_connect();
 
-                gnutls_init(&session, GNUTLS_CLIENT);
+                CHECK(gnutls_init(&session, GNUTLS_CLIENT));
 
-                gnutls_priority_set_direct(session,
-                                           "PERFORMANCE:!ARCFOUR-128",
-                                           NULL);
+                CHECK(gnutls_server_name_set(session, GNUTLS_NAME_DNS,
+                                             "my_host_name",
+                                             strlen("my_host_name")));
+                gnutls_session_set_verify_cert(session, "my_host_name", 0);
+
+                CHECK(gnutls_set_default_priority(session));
+
+                gnutls_transport_set_int(session, sd);
+                gnutls_handshake_set_timeout(session,
+                                             GNUTLS_DEFAULT_HANDSHAKE_TIMEOUT);
 
                 gnutls_credentials_set(session, GNUTLS_CRD_CERTIFICATE,
                                        xcred);
 
                 if (t > 0) {
                         /* if this is not the first time we connect */
-                        gnutls_session_set_data(session, session_data,
-                                                session_data_size);
-                        free(session_data);
+                        CHECK(gnutls_session_set_data(session, sdata.data,
+                                                      sdata.size));
+                        gnutls_free(sdata.data);
                 }
 
-                gnutls_transport_set_int(session, sd);
-                gnutls_handshake_set_timeout(session,
-                                             GNUTLS_DEFAULT_HANDSHAKE_TIMEOUT);
-
                 /* Perform the TLS handshake
                  */
                 do {
@@ -81,16 +87,9 @@ int main(void)
                 }
 
                 if (t == 0) {   /* the first time we connect */
-                        /* get the session data size */
-                        gnutls_session_get_data(session, NULL,
-                                                &session_data_size);
-                        session_data = malloc(session_data_size);
-
-                        /* put session data to the session variable */
-                        gnutls_session_get_data(session, session_data,
-                                                &session_data_size);
-
-                } else {        /* the second time we connect */
+                        /* get the session data */
+                        CHECK(gnutls_session_get_data2(session, &sdata));
+                } else { /* the second time we connect */
 
                         /* check if we actually resumed the previous session */
                         if (gnutls_session_is_resumed(session) != 0) {
@@ -101,10 +100,6 @@ int main(void)
                         }
                 }
 
-                /* This function was defined in a previous example
-                 */
-                /* print_info(session); */
-
                 gnutls_record_send(session, MSG, strlen(MSG));
 
                 ret = gnutls_record_recv(session, buffer, MAX_BUF);
diff --git a/doc/examples/ex-session-info.c b/doc/examples/ex-session-info.c
index 7838e43105..6cbf1905bf 100644
--- a/doc/examples/ex-session-info.c
+++ b/doc/examples/ex-session-info.c
@@ -16,29 +16,27 @@
  */
 int print_info(gnutls_session_t session)
 {
-        const char *tmp;
         gnutls_credentials_type_t cred;
         gnutls_kx_algorithm_t kx;
-        int dhe, ecdh;
+        int dhe, ecdh, group;
+        char *desc;
+
+        /* get a description of the session connection, protocol,
+         * cipher/key exchange */
+        desc = gnutls_session_get_desc(session);
+        if (desc != NULL) {
+                printf("- Session: %s\n", desc);
+        }
 
         dhe = ecdh = 0;
 
-        /* print the key exchange's algorithm name
-         */
         kx = gnutls_kx_get(session);
-        tmp = gnutls_kx_get_name(kx);
-        printf("- Key Exchange: %s\n", tmp);
 
         /* Check the authentication type used and switch
          * to the appropriate.
          */
         cred = gnutls_auth_get_type(session);
         switch (cred) {
-        case GNUTLS_CRD_IA:
-                printf("- TLS/IA session\n");
-                break;
-
-
 #ifdef ENABLE_SRP
         case GNUTLS_CRD_SRP:
                 printf("- SRP session with username %s\n",
@@ -87,48 +85,25 @@ int print_info(gnutls_session_t session)
                  * print some information about it.
                  */
                 print_x509_certificate_info(session);
-
+                break;
+	default:
+		break;
         }                       /* switch */
 
-        if (ecdh != 0)
-                printf("- Ephemeral ECDH using curve %s\n",
-                       gnutls_ecc_curve_get_name(gnutls_ecc_curve_get
-                                                 (session)));
-        else if (dhe != 0)
-                printf("- Ephemeral DH using prime of %d bits\n",
-                       gnutls_dh_get_prime_bits(session));
-
-        /* print the protocol's name (ie TLS 1.0) 
-         */
-        tmp =
-            gnutls_protocol_get_name(gnutls_protocol_get_version(session));
-        printf("- Protocol: %s\n", tmp);
-
-        /* print the certificate type of the peer.
-         * ie X.509
-         */
-        tmp =
-            gnutls_certificate_type_get_name(gnutls_certificate_type_get
-                                             (session));
-
-        printf("- Certificate Type: %s\n", tmp);
-
-        /* print the compression algorithm (if any)
-         */
-        tmp = gnutls_compression_get_name(gnutls_compression_get(session));
-        printf("- Compression: %s\n", tmp);
-
-        /* print the name of the cipher used.
-         * ie 3DES.
-         */
-        tmp = gnutls_cipher_get_name(gnutls_cipher_get(session));
-        printf("- Cipher: %s\n", tmp);
-
-        /* Print the MAC algorithms name.
-         * ie SHA1
-         */
-        tmp = gnutls_mac_get_name(gnutls_mac_get(session));
-        printf("- MAC: %s\n", tmp);
+        /* read the negotiated group - if any */
+        group = gnutls_group_get(session);
+        if (group != 0) {
+                printf("- Negotiated group %s\n",
+                       gnutls_group_get_name(group));
+        } else {
+                if (ecdh != 0)
+                        printf("- Ephemeral ECDH using curve %s\n",
+	                       gnutls_ecc_curve_get_name(gnutls_ecc_curve_get
+                             		                 (session)));
+	        else if (dhe != 0)
+        	        printf("- Ephemeral DH using prime of %d bits\n",
+                	       gnutls_dh_get_prime_bits(session));
+        }
 
         return 0;
 }