Add.

2 files changed, 89 insertions, 6 deletions

diff --git a/doc/examples/ex-rfc2818.c b/doc/examples/ex-rfc2818.c
new file mode 100644
index 0000000000..577c22211c
--- /dev/null
+++ b/doc/examples/ex-rfc2818.c
@@ -0,0 +1,81 @@
+#include <gnutls/gnutls.h>
+#include <gnutls/x509.h>
+
+/* This function will try to verify the peer's certificate, and
+ * also check if the hostname matches, and the activation, expiration dates.
+ */
+void verify_certificate( gnutls_session session, const char* hostname)
+{
+   unsigned int status;
+   const gnutls_datum* cert_list;
+   int cert_list_size, ret;
+   gnutls_x509_crt cert;
+
+
+   /* This verification function uses the trusted CAs in the credentials
+    * structure. So you must have installed one or more CA certificates.
+    */
+   ret = gnutls_certificate_verify_peers2(session, &status);
+
+   if (ret < 0) {
+      printf("Error\n");
+      return;
+   }
+
+   if (status & GNUTLS_CERT_INVALID)
+      printf("The certificate is not trusted.\n");
+
+   if (status & GNUTLS_CERT_SIGNER_NOT_FOUND)
+      printf("The certificate hasn't got a known issuer.\n");
+
+   if (status & GNUTLS_CERT_REVOKED)
+     printf("The certificate has been revoked.\n");
+
+
+   /* Up to here the process is the same for X.509 certificates and
+    * OpenPGP keys. From now on X.509 certificates are assumed. This can
+    * be easily extended to work with openpgp keys as well.
+    */
+   if ( gnutls_certificate_type_get(session) != GNUTLS_CRT_X509)
+      return;
+
+   if ( gnutls_x509_crt_init( &cert) < 0) {
+      printf("error in initialization\n");
+      return;
+   }
+
+   cert_list = gnutls_certificate_get_peers( session, &cert_list_size);
+   if ( cert_list == NULL) {
+      printf("No certificate was found!\n");
+      return;
+   }
+
+   /* This is not a real world example, since we only check the first 
+    * certificate in the given chain.
+    */
+   if ( gnutls_x509_crt_import( cert, &cert_list[0], GNUTLS_X509_FMT_DER) < 0) {
+      printf("error parsing certificate\n");
+      return;
+   }
+
+   /* Beware here we do not check for errors.
+    */
+   if ( gnutls_x509_crt_get_expiration( cert) < time(0)) {
+      printf("The certificate has expired\n");
+      return;
+   }
+
+   if ( gnutls_x509_crt_get_activation_time( cert) > time(0)) {
+      printf("The certificate is not yet activated\n");
+      return;
+   }
+
+   if ( !gnutls_x509_crt_check_hostname( cert, hostname)) {
+      printf("The certificate's owner does not match hostname '%s'\n", hostname);
+      return;
+   }
+
+   gnutls_x509_crt_deinit( cert);
+
+   return;
+}
diff --git a/doc/gnutls.texi b/doc/gnutls.texi
index 6e527915be..b3079aa769 100644
--- a/doc/gnutls.texi
+++ b/doc/gnutls.texi
@@ -1615,8 +1615,8 @@ redefining them.
 @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
+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 @code{gnutls_handshake}.
 
@@ -1630,10 +1630,12 @@ 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
-an example on how to verify the peer's certificate chain.  This is an
-advanced case. Things in a TLS session may be simplified by using
-@code{gnutls_certificate_verify_peers2}.
+treat the connection as being a secure one.
+
+@verbatiminclude examples/ex-rfc2818.c
+
+An other example is listed below which provides a more detailed
+verification output.
 
 @verbatiminclude examples/ex-verify.c