From: Nikos Mavrogiannopoulos <nmav@gnutls.org>
Date: Fri, 25 May 2012 20:25:51 +0000 (+0200)
Subject: updated doc
X-Git-Tag: gnutls_3_0_21~112
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=d869e863c32d685d7e795616db4e6e6bf4fa1d22;p=thirdparty%2Fgnutls.git

updated doc
---

diff --git a/doc/cha-cert-auth.texi b/doc/cha-cert-auth.texi
index 1ee95bf1df..946674c48e 100644
--- a/doc/cha-cert-auth.texi
+++ b/doc/cha-cert-auth.texi
@@ -243,7 +243,8 @@ provided.
 The verification function will verify a given certificate chain against a list of certificate
 authorities and certificate revocation lists, and output
 a bit-wise OR of elements of the @code{gnutls_@-certificate_@-status_t} 
-enumeration shown in @ref{gnutls_certificate_status_t}. 
+enumeration shown in @ref{gnutls_certificate_status_t}. The @code{GNUTLS_@-CERT_@-INVALID} flag
+is always set on a verification error and more detailed flags will also be set when appropriate.
 
 @showenumdesc{gnutls_certificate_status_t,The @code{gnutls_@-certificate_@-status_t} enumeration.}
 
@@ -263,7 +264,8 @@ authority list may also be set using:
 
 Then it is not required to setup a trusted list as above.
 The function @funcref{gnutls_certificate_verify_peers2} 
-may then be used to verify the peer's certificate chain.
+may then be used to verify the peer's certificate chain. The flags
+are set similarly to the verification functions in the previous section.
 
 There is also the possibility to pass some input to the verification
 functions in the form of flags. For @funcref{gnutls_x509_trust_list_verify_crt} the
diff --git a/doc/cha-gtls-app.texi b/doc/cha-gtls-app.texi
index 605c3ca356..512f2b0ed3 100644
--- a/doc/cha-gtls-app.texi
+++ b/doc/cha-gtls-app.texi
@@ -22,6 +22,7 @@
 @menu
 * General idea::
 * Error handling::
+* Common types::
 * Debugging and auditing::
 * Thread safety::
 * Callback functions::
@@ -94,6 +95,32 @@ a function, these error codes will be documented in the function's
 reference.  See @ref{Error codes}, for a description of the available 
 error codes.
 
+@node Common types
+@subsection Common types
+
+Several functions in @acronym{GnuTLS} use @code{gnutls_datum_t} which is
+convenient way to combine a pointer to data and data's size. Its definition is
+shown below.
+@verbatim
+  typedef struct
+  {
+    unsigned char *data;
+    unsigned int size;
+  } gnutls_datum_t;
+@end verbatim
+
+Other functions that require data for scattered read use a structure similar
+to @code{struct iovec} typically used by @funcintref{readv}. It is shown
+below.
+@verbatim
+  typedef struct
+  {
+    void *iov_base;             /* Starting address */
+    size_t iov_len;             /* Number of bytes to transfer */
+  } giovec_t;
+@end verbatim
+
+
 @node Debugging and auditing
 @subsection Debugging and auditing
 
diff --git a/doc/cha-shared-key.texi b/doc/cha-shared-key.texi
index c9605de2b1..1d3186a6c1 100644
--- a/doc/cha-shared-key.texi
+++ b/doc/cha-shared-key.texi
@@ -132,7 +132,8 @@ with the peer. Moreover it is useful when complete anonymity is required.
 Unless in one of the above cases, do not use anonymous authentication.  
 
 The available key exchange algorithms for anonymous authentication are
-shown below.
+shown below, but note that few public servers support them. They typically
+have to be explicitly enabled.
 
 @table @code
 
diff --git a/doc/examples/ex-client-x509.c b/doc/examples/ex-client-x509.c
index ab46118fbc..2a78e2da17 100644
--- a/doc/examples/ex-client-x509.c
+++ b/doc/examples/ex-client-x509.c
@@ -159,9 +159,6 @@ _verify_certificate_callback (gnutls_session_t session)
       return GNUTLS_E_CERTIFICATE_ERROR;
     }
 
-  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");
 
@@ -174,6 +171,12 @@ _verify_certificate_callback (gnutls_session_t session)
   if (status & GNUTLS_CERT_NOT_ACTIVATED)
     printf ("The certificate is not yet activated\n");
 
+  if (status & GNUTLS_CERT_INVALID)
+    {
+      printf ("The certificate is not trusted.\n");
+      return GNUTLS_E_CERTIFICATE_ERROR;
+    }
+
   /* 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.
@@ -194,9 +197,6 @@ _verify_certificate_callback (gnutls_session_t session)
       return GNUTLS_E_CERTIFICATE_ERROR;
     }
 
-  /* 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");