updated documentation

4 files changed, 24 insertions, 42 deletions

diff --git a/doc/tex/certificate.tex b/doc/tex/certificate.tex
index 7ea2b532ee..2cf9614d57 100644
--- a/doc/tex/certificate.tex
+++ b/doc/tex/certificate.tex
@@ -126,3 +126,4 @@ it was created by the key itself.
 Validity means if the signatures on the key are valid and the key was not 
 changed by somebody or corrupted during transport.
 
+
diff --git a/doc/tex/ex-rfc2818.tex b/doc/tex/ex-rfc2818.tex
index b22895c06a..a8cd459abf 100644
--- a/doc/tex/ex-rfc2818.tex
+++ b/doc/tex/ex-rfc2818.tex
@@ -10,7 +10,12 @@
  */
 void verify_certificate( gnutls_session session, const char* hostname)
 {
-   int status = gnutls_certificate_verify_peers(session);
+   int status;
+
+   /* This verification function uses the trusted CAs in the credentials
+    * structure. So you must have installed one or more CAs.
+    */
+   status = gnutls_certificate_verify_peers(session);
 
    if (status == GNUTLS_E_NO_CERTIFICATE_FOUND) {
       printf("No certificate was sent");
@@ -43,7 +48,7 @@ void verify_certificate( gnutls_session session, const char* hostname)
          return;
       }
       if ( !gnutls_x509_check_certificates_hostname( &cert_list[0], hostname)) {
-         printf("The certificate does not matches hostname\n");
+         printf("The certificate does not match hostname\n");
          return;
       }
    }
diff --git a/doc/tex/ex3.tex b/doc/tex/ex3.tex
index c678e4a85d..a8d6ca2a28 100644
--- a/doc/tex/ex3.tex
+++ b/doc/tex/ex3.tex
@@ -22,7 +22,6 @@ int print_info(gnutls_session session)
 {
    const char *tmp;
    gnutls_credentials_type cred;
-   int status;
    gnutls_kx_algorithm kx;
 
    /* print the key exchange's algorithm name
@@ -43,30 +42,7 @@ int print_info(gnutls_session session)
       break;
 
    case GNUTLS_CRD_CERTIFICATE:        /* certificate authentication */
-
-      /* try to verify the peer's certificate (if any)
-       */
-      status = gnutls_certificate_verify_peers(session);
-
-      if (status < 0) {
-         if (status == GNUTLS_E_NO_CERTIFICATE_FOUND)
-            printf("- Peer did not send any X509 Certificate.\n");
-         else
-            printf("- Could not verify certificate\n");
-      } else {
-
-         if (status & GNUTLS_CERT_INVALID)
-            printf("- Peer's certificate is invalid\n");
-         if (status & GNUTLS_CERT_CORRUPTED)
-            printf("- Peer's certificate is corrupted.\n");
-         if (status & GNUTLS_CERT_REVOKED)
-            printf("- Peer's certificate is revoked\n");
-         if (status & GNUTLS_CERT_NOT_TRUSTED)
-            printf("- Peer's certificate is not trusted\n");
-         else
-            printf("- Peer's certificate is trusted\n");
-      }
-
+      
       /* Check if we have been using ephemeral Diffie Hellman.
        */
       if (kx == GNUTLS_KX_DHE_RSA || kx == GNUTLS_KX_DHE_DSS) {
diff --git a/doc/tex/examples.tex b/doc/tex/examples.tex
index cc0c88e07d..2b2ac721d1 100644
--- a/doc/tex/examples.tex
+++ b/doc/tex/examples.tex
@@ -12,27 +12,27 @@ is a very simple \tls{} client, it does not support session resuming nor
 any other fancy features.
 \input{ex2}
 
-\subsection{Getting peer's information}
-\par The above example was the simplest form of a client, it didn't even check
-the result of the peer's certificate verification function. The lack of
-this check may result to an unauthenticated connection.
-The following function does check the peer's
-X.509 certificate, and prints some information about the current session.
+\subsection{Verifying peer's certificate}
+\par A TLS connection is not secure just after the handshake has finished.
+It must be considered secure, after the peer's identity has been
+verified. That is, you usually have to verify not only the 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.
+
+\input{ex-rfc2818}
+
+\subsection{Parsing peer's certificate, and obtaining session information}
+The following function reads the peer's certificate,
+and prints some information about the certificate and the current session.
 \par
 This function should be called after a successful
 \printfunc{gnutls_handshake}{gnutls\_handshake}
 
 \input{ex3}
 
-\subsection{Verifying peer's hostname in a certificate}
-\par HTTPS clients have to verify not only the peer's certificate,
-but also the hostname in this certificate. That is to know that
-they actually connected to the right site.
-
-\par
-The following function is an example on how to fully verify a certificate.
-
-\input{ex-rfc2818}
 
 \subsection{Client with Resume capability example}
 \label{resume-example}