*** empty log message ***

7 files changed, 70 insertions, 86 deletions

diff --git a/doc/tex/ex-cert-select.tex b/doc/tex/ex-cert-select.tex
index a24ab350ad..796f2e568f 100644
--- a/doc/tex/ex-cert-select.tex
+++ b/doc/tex/ex-cert-select.tex
@@ -15,7 +15,8 @@ static int cert_callback(gnutls_session session,
 			 const gnutls_datum * req_ca_rdn, int nreqs)
 {
    char issuer_dn[256];
-   int len, i, ret;
+   int i, ret;
+   size_t len;
 
    /* Print the server's trusted CAs
     */
diff --git a/doc/tex/ex-client-resume.tex b/doc/tex/ex-client-resume.tex
index 12e634f18f..f3eb4b2b91 100644
--- a/doc/tex/ex-client-resume.tex
+++ b/doc/tex/ex-client-resume.tex
@@ -8,7 +8,7 @@
  */
 extern void check_alert(gnutls_session session, int ret);
 extern int tcp_connect( void);
-void tcp_close( int sd);
+extern void tcp_close( int sd);
 
 #define MAX_BUF 1024
 #define CRLFILE "crl.pem"
@@ -28,7 +28,7 @@ int main()
     */
    int t;
    char *session_data;
-   int session_data_size;
+   size_t session_data_size;
 
    gnutls_global_init();
 
diff --git a/doc/tex/ex-client-srp.tex b/doc/tex/ex-client-srp.tex
index 4cca62c0bd..777ee92f7a 100644
--- a/doc/tex/ex-client-srp.tex
+++ b/doc/tex/ex-client-srp.tex
@@ -9,15 +9,17 @@
  */
 extern void check_alert(gnutls_session session, int ret);
 extern int tcp_connect( void);
-void tcp_close( int sd);
+extern void tcp_close( int sd);
 
 #define MAX_BUF 1024
 #define USERNAME "user"
 #define PASSWORD "pass"
+#define CAFILE "ca.pem"
 #define SA struct sockaddr
 #define MSG "GET / HTTP/1.0\r\n\r\n"
 
-const int kx_priority[] = { GNUTLS_KX_SRP, 0 };
+const int kx_priority[] = { GNUTLS_KX_SRP, GNUTLS_KX_SRP_DSS, 
+   GNUTLS_KX_SRP_RSA, 0 };
 
 int main()
 {
@@ -25,25 +27,21 @@ int main()
    int sd, ii;
    gnutls_session session;
    char buffer[MAX_BUF + 1];
-   gnutls_srp_client_credentials xcred;
+   gnutls_srp_client_credentials srp_cred;
+   gnutls_certificate_client_credentials cert_cred;
 
-   if (gnutls_global_init() < 0) {
-      fprintf(stderr, "global state initialization error\n");
-      exit(1);
-   }
+   gnutls_global_init();
 
    /* now enable the gnutls-extra library which contains the
-    * SRP stuff. */
-   if (gnutls_global_init_extra() < 0) {
-      fprintf(stderr, "global state initialization error\n");
-      exit(1);
-   }
+    * SRP stuff. 
+    */
+   gnutls_global_init_extra();
 
-   if (gnutls_srp_allocate_client_credentials(&xcred) < 0) {
-      fprintf(stderr, "memory error\n");
-      exit(1);
-   }
-   gnutls_srp_set_client_credentials(xcred, USERNAME, PASSWORD);
+   gnutls_srp_allocate_client_credentials(&srp_cred);
+   gnutls_certificate_allocate_client_credentials(&cert_cred);
+
+   gnutls_certificate_set_x509_trust_file(cert_cred, CAFILE, GNUTLS_X509_FMT_PEM);
+   gnutls_srp_set_client_credentials(srp_cred, USERNAME, PASSWORD);
 
    /* connects to server 
     */
@@ -62,7 +60,8 @@ int main()
 
    /* put the SRP credentials to the current session
     */
-   gnutls_credentials_set(session, GNUTLS_CRD_SRP, xcred);
+   gnutls_credentials_set(session, GNUTLS_CRD_SRP, srp_cred);
+   gnutls_credentials_set(session, GNUTLS_CRD_CERTIFICATE, cert_cred);
 
    gnutls_transport_set_ptr( session, (gnutls_transport_ptr)sd);
 
@@ -107,7 +106,8 @@ int main()
 
    gnutls_deinit(session);
 
-   gnutls_srp_free_client_credentials(xcred);
+   gnutls_srp_free_client_credentials(srp_cred);
+   gnutls_certificate_free_credentials(cert_cred);
 
    gnutls_global_deinit();
 
diff --git a/doc/tex/ex-client2.tex b/doc/tex/ex-client2.tex
index 37184c6ed6..c46413a4ae 100644
--- a/doc/tex/ex-client2.tex
+++ b/doc/tex/ex-client2.tex
@@ -14,7 +14,6 @@
  */
 
 #define MAX_BUF 1024
-#define CRLFILE "crl.pem"
 #define CAFILE "ca.pem"
 #define SA struct sockaddr
 #define MSG "GET / HTTP/1.0\r\n\r\n"
@@ -71,7 +70,7 @@ int main()
    /* X509 stuff */
    gnutls_certificate_allocate_credentials(&xcred);
 
-   /* set's the trusted cas file
+   /* sets the trusted cas file
     */
    gnutls_certificate_set_x509_trust_file(xcred, CAFILE, GNUTLS_X509_FMT_PEM);
 
diff --git a/doc/tex/ex-serv-export.tex b/doc/tex/ex-serv-export.tex
index 10dddc0783..c34b612dda 100644
--- a/doc/tex/ex-serv-export.tex
+++ b/doc/tex/ex-serv-export.tex
@@ -71,7 +71,7 @@ gnutls_dh_params dh_params;
  */
 gnutls_rsa_params rsa_params;
 
-static int generate_dh_params(void)
+int generate_dh_params(void)
 {
    /* Generate Diffie Hellman parameters - for use with DHE
     * kx algorithms. These should be discarded and regenerated
diff --git a/doc/tex/ex-serv-pgp.tex b/doc/tex/ex-serv-pgp.tex
index d4db2dc902..c9792a930f 100644
--- a/doc/tex/ex-serv-pgp.tex
+++ b/doc/tex/ex-serv-pgp.tex
@@ -30,45 +30,12 @@
 
 /* These are global */
 gnutls_certificate_credentials cred;
-
-gnutls_session initialize_tls_session()
-{
-   gnutls_session session;
-   const int cert_type_priority[2] = { GNUTLS_CRT_OPENPGP, 0 };
-
-   gnutls_init(&session, GNUTLS_SERVER);
-
-   /* avoid calling all the priority functions, since the defaults
-    * are adequate.
-    */
-   gnutls_set_default_priority( session);
-   gnutls_certificate_type_set_priority(session, cert_type_priority);
-
-   gnutls_credentials_set(session, GNUTLS_CRD_CERTIFICATE, cred);
-
-   /* request client certificate.
-    */
-   gnutls_certificate_server_set_request( session, GNUTLS_CERT_REQUEST);
-
-   gnutls_dh_set_prime_bits( session, DH_BITS);
-
-   return session;
-}
-
+const int cert_type_priority[2] = { GNUTLS_CRT_OPENPGP, 0 };
 gnutls_dh_params dh_params;
 
-static int generate_dh_params(void) {
-
-   /* Generate Diffie Hellman parameters - for use with DHE
-    * kx algorithms. These should be discarded and regenerated
-    * once a day, once a week or once a month. Depends on the
-    * security requirements.
-    */
-   gnutls_dh_params_init( &dh_params);
-   gnutls_dh_params_generate2( dh_params, DH_BITS);
-
-   return 0;
-}
+/* Defined in a previous example */
+extern int generate_dh_params( void);
+extern gnutls_session initialize_tls_session( void);
 
 int main()
 {
@@ -120,6 +87,7 @@ int main()
    client_len = sizeof(sa_cli);
    for (;;) {
       session = initialize_tls_session();
+      gnutls_certificate_type_set_priority(session, cert_type_priority);
 
       sd = accept(listen_sd, (SA *) & sa_cli, &client_len);
 
diff --git a/doc/tex/examples.tex b/doc/tex/examples.tex
index 2e9fc22fde..a6f24ec513 100644
--- a/doc/tex/examples.tex
+++ b/doc/tex/examples.tex
@@ -16,21 +16,22 @@ are used in most of the other examples below, without redefining them.
 \input{ex-client2}
 
 \subsection{Obtaining session information}
-The following function prints information about the current \tls{} session.
-This function should be called after a successful
-\printfunc{gnutls_handshake}{gnutls\_handshake}
+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 \printfunc{gnutls_handshake}{gnutls\_handshake}
 
 \input{ex-session-info}
 
 \subsection{Verifying peer's certificate}
-A TLS connection is not secure just after the handshake has finished.
-It must be considered secure, after the peer's certificate and identity have been
-verified. That is, you usually have to verify not only the signature in peer's 
-certificate, but also the hostname in the certificate, expiration dates etc. 
-After this step you should treat the connection as being a secure one.
-
-\par
-The following function is an example on how to verify a certificate.
+A \tls{} session is not secure just after the handshake procedure has finished.
+It must be considered secure, only after the peer's certificate and identity have been
+verified. That is, you have to verify the signature in peer's 
+certificate, the hostname in the certificate, and expiration dates.
+Just after this step you should treat the connection as being a secure one.
+The following function is a simple example on how to verify a single certificate.
+Real world programs should be able to handle certificate chains as well.
 
 \input{ex-rfc2818}
 
@@ -46,42 +47,57 @@ to assist in this purpose.
 
 \subsection{Client with Resume capability example}
 \label{resume-example}
-This is a modification of the simple client above. Here we added support 
-for session resumption.
+This is a modification of the simple client example. Here we demonstrate
+the use of session resumption. The client tries to connect once using
+\tls{}, close the connection and then try to establish a new connection
+using the previously negotiated data.
 \input{ex-client-resume}
 
 \subsection{Simple client example with SRP authentication}
 The following client
-is a very simple SRP-TLS client which connects to a server 
-and authenticates using {\it username} and {\it password}.
-
+is a very simple SRP \tls{} client which connects to a server 
+and authenticates using a {\it username} and a {\it password}. The
+server may authenticate itself using a certificate, and in that case it
+has to be verified.
 \input{ex-client-srp}
 
 \section{Server examples}
 This section contains examples of \tls{} and \ssl{} servers, using \gnutls{}.
 
 \subsection{Echo Server with X.509 authentication}
-This example is a server which supports {\bf X.509} authentication.
+This example is a very simple echo server which supports {\bf X.509} authentication,
+using the RSA ciphersuites.
 \input{ex-serv1}
 
 \subsection{Echo Server with X.509 authentication II}
 The following example is a server which supports {\bf X.509} authentication.
-This server also supports export-grade cipher suites and session resuming.
+This server supports the export-grade cipher suites, the DHE ciphersuites
+and session resuming.
 \input{ex-serv-export}
 
 \subsection{Echo Server with OpenPGP\index{OpenPGP!Server} authentication}
-The following example is a server which supports {\bf OpenPGP} key authentication.
+The following example is an echo server which supports {\bf OpenPGP} key 
+authentication. You can easily combine this functionality --that is have
+a server that supports both X.509 and OpenPGP certificates-- but we
+separated them to keep these examples as simple as possible.
 \input{ex-serv-pgp}
 
-\subsection{A callback which\index{OpenPGP!Key retrieval} retrieves OpenPGP keys}
-The following example is a callback function which retrieves {\bf OpenPGP} keys from
-a public key server.
-\input{ex-pgp-keyserver}
 
 \subsection{Echo Server with SRP authentication}
-This is a server which supports {\bf SRP} authentication.
+This is a server which supports {\bf SRP} authentication. It is also
+possible to combine this functionality with a certificate server. Here it
+is separate for simplicity.
 \input{ex-serv-srp}
 
+\section{Miscellaneous examples}
+
+\subsection{A callback which\index{OpenPGP!Key retrieval} retrieves OpenPGP keys}
+The following example is a callback function which retrieves {\bf OpenPGP} keys from
+a public key server. This is useful when a client connected to an OpenPGP \tls{} server
+and sent its key fingerprint instead of the whole key. With this callback the \tls{}
+server can retrieve the key from a public key server.
+\input{ex-pgp-keyserver}
+
 \subsection{Checking for an alert}
 This is a function that checks if an alert has been received
 in the current session.