documentation changes.

8 files changed, 41 insertions, 50 deletions

diff --git a/doc/cha-auth.texi b/doc/cha-auth.texi
index c7d4dfe05c..78bcfc386b 100644
--- a/doc/cha-auth.texi
+++ b/doc/cha-auth.texi
@@ -397,7 +397,7 @@ with the credential types is shown in @ref{tab:key-exchange-cred}.
 
 @item @code{KX_SRP_RSA}, @code{KX_SRP_DSS}
 @tab @code{CRD_SRP}
-@tab @code{CRD_CERTIFICATE}
+@tab @code{CRD_CERTIFICATE}, @code{CRD_SRP}
 
 @item @code{KX_SRP}
 @tab @code{CRD_SRP}
diff --git a/doc/cha-cert-auth.texi b/doc/cha-cert-auth.texi
index 1d5357a0fa..aeef0619a7 100644
--- a/doc/cha-cert-auth.texi
+++ b/doc/cha-cert-auth.texi
@@ -775,19 +775,17 @@ certificate chain, and get a @code{GNUTLS_CERT_INSECURE_ALGORITHM}
 validation error (see @ref{Verifying X.509 certificate paths}), it means
 that somewhere in the certificate chain there is a certificate signed
 using @code{RSA-MD2} or @code{RSA-MD5}.  These two digital signature
-algorithms are considered broken, so GnuTLS fail when attempting to
-verify the certificate.  In some situations, it may be useful to be
+algorithms are considered broken, so GnuTLS fails verifying
+the certificate.  In some situations, it may be useful to be
 able to verify the certificate chain anyway, assuming an attacker did
 not utilize the fact that these signatures algorithms are broken.
 This section will give help on how to achieve that.
 
-First, it is important to know that you do not have to enable any of
+It is important to know that you do not have to enable any of
 the flags discussed here to be able to use trusted root CA
-certificates signed using @code{RSA-MD2} or @code{RSA-MD5}.  The only
-attack today is that it is possible to generate certificates with
-colliding signatures (collision resistance); you cannot generate a
-certificate that has the same signature as an already existing
-signature (2nd preimage resistance).
+certificates self-signed using @code{RSA-MD2} or @code{RSA-MD5}. The
+certificates in the trusted list are considered trusted irrespective
+of the signature.
 
 If you are using @funcref{gnutls_certificate_verify_peers2} to verify the
 certificate chain, you can call
@@ -816,9 +814,8 @@ user when verification failure occur for this reason.  The simplest is
 to not use the flags by default, and only fall back to using them
 after warning the user.  If you wish to inspect the certificate chain
 yourself, you can use @funcref{gnutls_certificate_get_peers} to extract
-the raw server's certificate chain, then use
-@funcref{gnutls_x509_crt_import} to parse each of the certificates, and
-then use @funcref{gnutls_x509_crt_get_signature_algorithm} to find out the
+the raw server's certificate chain, @funcref{gnutls_x509_crt_list_import} to parse each of the certificates, and
+then @funcref{gnutls_x509_crt_get_signature_algorithm} to find out the
 signing algorithm used for each certificate.  If any of the
 intermediary certificates are using @code{GNUTLS_SIGN_RSA_MD2} or
 @code{GNUTLS_SIGN_RSA_MD5}, you could present a warning.
diff --git a/doc/cha-gtls-app.texi b/doc/cha-gtls-app.texi
index 814d722a60..3d115bbf01 100644
--- a/doc/cha-gtls-app.texi
+++ b/doc/cha-gtls-app.texi
@@ -214,6 +214,7 @@ functions resemble the POSIX @code{recv} and @code{send}
 functions.
 
 @showfuncdesc{gnutls_record_send}
+
 @showfuncdesc{gnutls_record_recv}
 
 In DTLS it is adviceable to use the extended receive
@@ -225,8 +226,7 @@ messages may arrive out of order.
 
 A helper function is available to check whether data
 to be read are pending in a @acronym{GnuTLS} session.
-This is the equivalent in POSIX systems to using @code{select} 
-for data waiting to be read by @code{recv}.
+This is the equivalent of @code{select} in @acronym{POSIX} systems.
 
 @showfuncdesc{gnutls_record_check_pending}
 
@@ -496,8 +496,8 @@ redefining them.
 @subsection Simple 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 
-@ref{Simple client example with X.509 certificate support} above.
+server. This is the @acronym{DTLS} equivalent to the example
+in @ref{Simple client example with X.509 certificate support}.
 
 @verbatiminclude examples/ex-client-udp.c
 
diff --git a/doc/cha-intro-tls.texi b/doc/cha-intro-tls.texi
index f71b305202..ab117ba508 100644
--- a/doc/cha-intro-tls.texi
+++ b/doc/cha-intro-tls.texi
@@ -584,14 +584,10 @@ Changing this default behavior would prevent interoperability against
 the majority of deployed servers out there.  We will reconsider this
 default behavior in the future when more servers have been upgraded.
 Note that it is easy to configure clients to always require the safe
-renegotiation extension from servers (see below on the
-@code{%SAFE_RENEGOTIATION} priority string).
+renegotiation extension from servers.
 
 To modify the default behavior, we have introduced some new priority
-strings.  The priority strings can be used by applications
-(@funcref{gnutls_priority_set}) and end users (e.g., @code{--priority}
-parameter to @code{gnutls-cli} and @code{gnutls-serv}).
-
+strings (see @ref{Priority Strings}).  
 The @code{%UNSAFE_RENEGOTIATION} priority string permits
 (re-)handshakes even when the safe renegotiation extension was not
 negotiated. The default behavior is @code{%PARTIAL_RENEGOTIATION} that will
@@ -629,7 +625,7 @@ can be used both by clients and servers.
 @section Selecting cryptographic key sizes
 @cindex Key sizes
 
-In TLS, since a lot of algorithms are involved, it is not easy to set
+Because many algorithms are involved in TLS, it is not easy to set
 a consistent security level.  For this reason in @ref{tab:key-sizes} we
 present some correspondence between key sizes of symmetric algorithms
 and public key algorithms based on @xcite{ECRYPT}. 
@@ -685,7 +681,7 @@ parameter with actual bit sizes of parameters for DH, RSA, SRP and ECC algorithm
 A mapping to @code{gnutls_sec_param_t} value is given for each security parameter, on
 the next column, and finally a brief description of the level.
 
-Note however that the values suggested here are nothing more than an
+Note, however, that the values suggested here are nothing more than an
 educated guess that is valid today. There are no guarantees that an
 algorithm will remain unbreakable or that these values will remain
 constant in time. There could be scientific breakthroughs that cannot
diff --git a/doc/examples/ex-cert-select-pkcs11.c b/doc/examples/ex-cert-select-pkcs11.c
index 492cd5a8bf..bd7851c0be 100644
--- a/doc/examples/ex-cert-select-pkcs11.c
+++ b/doc/examples/ex-cert-select-pkcs11.c
@@ -4,8 +4,6 @@
 #include <config.h>
 #endif
 
-#include <getpass.h>
-
 #include <stdio.h>
 #include <stdlib.h>
 #include <string.h>
@@ -19,6 +17,7 @@
 #include <sys/types.h>
 #include <sys/stat.h>
 #include <fcntl.h>
+#include <getpass.h> /* for getpass() */
 
 /* A TLS client that loads the certificate and key.
  */
diff --git a/lib/gnutls_buffers.c b/lib/gnutls_buffers.c
index 38e9828122..4f946f4445 100644
--- a/lib/gnutls_buffers.c
+++ b/lib/gnutls_buffers.c
@@ -84,10 +84,12 @@ _gnutls_record_buffer_put (gnutls_session_t session,
  * gnutls_record_check_pending:
  * @session: is a #gnutls_session_t structure.
  *
- * This function checks if there are any data to receive in the gnutls
- * buffers.
+ * This function checks if there are unread data
+ * in the gnutls buffers. If the return value is
+ * non-zero the next call to gnutls_record_recv()
+ * is guarranteed not to block.
  *
- * Returns: The size of that data or 0.
+ * Returns: Returns the size of the data or zero.
  **/
 size_t
 gnutls_record_check_pending (gnutls_session_t session)
diff --git a/lib/gnutls_pubkey.c b/lib/gnutls_pubkey.c
index d672309969..baea500fa3 100644
--- a/lib/gnutls_pubkey.c
+++ b/lib/gnutls_pubkey.c
@@ -406,7 +406,7 @@ gnutls_pubkey_import_openpgp (gnutls_pubkey_t key,
  * certificate corresponds to the given public key.
  *
  * If the buffer provided is not long enough to hold the output, then
- * *output_data_size is updated and GNUTLS_E_SHORT_MEMORY_BUFFER will
+ * *output_data_size is updated and %GNUTLS_E_SHORT_MEMORY_BUFFER will
  * be returned.  The output will normally be a SHA-1 hash output,
  * which is 20 bytes.
  *
@@ -461,7 +461,7 @@ gnutls_pubkey_get_openpgp_key_id (gnutls_pubkey_t key, unsigned int flags,
  * This function will export the certificate to DER or PEM format.
  *
  * If the buffer provided is not long enough to hold the output, then
- * *output_data_size is updated and GNUTLS_E_SHORT_MEMORY_BUFFER will
+ * *output_data_size is updated and %GNUTLS_E_SHORT_MEMORY_BUFFER will
  * be returned.
  *
  * If the structure is PEM encoded, it will have a header
@@ -535,7 +535,7 @@ cleanup:
  * certificate corresponds to the given public key.
  *
  * If the buffer provided is not long enough to hold the output, then
- * *output_data_size is updated and GNUTLS_E_SHORT_MEMORY_BUFFER will
+ * *output_data_size is updated and %GNUTLS_E_SHORT_MEMORY_BUFFER will
  * be returned.  The output will normally be a SHA-1 hash output,
  * which is 20 bytes.
  *
@@ -1145,9 +1145,8 @@ gnutls_pubkey_import_dsa_raw (gnutls_pubkey_t key,
  * This function will verify the given signed data, using the
  * parameters from the certificate.
  *
- * Returns: In case of a verification failure
- *   %GNUTLS_E_PK_SIG_VERIFY_FAILED is returned, and a positive code
- *   on success.
+ * Returns: On success, %GNUTLS_E_SUCCESS (0) is returned, otherwise a
+ *   negative error value (%GNUTLS_E_PK_SIG_VERIFY_FAILED in verification failure).
  *
  * Since: 2.12.0
  **/
@@ -1185,9 +1184,8 @@ gnutls_pubkey_verify_data (gnutls_pubkey_t pubkey, unsigned int flags,
  * This function will verify the given signed data, using the
  * parameters from the certificate.
  *
- * Returns: In case of a verification failure
- *   %GNUTLS_E_PK_SIG_VERIFY_FAILED is returned, and a positive code
- *   on success.
+ * Returns: On success, %GNUTLS_E_SUCCESS (0) is returned, otherwise a
+ *   negative error value (%GNUTLS_E_PK_SIG_VERIFY_FAILED in verification failure).
  *
  * Since: 3.0.0
  **/
@@ -1227,8 +1225,8 @@ gnutls_pubkey_verify_data2 (gnutls_pubkey_t pubkey,
  * This function will verify the given signed digest, using the
  * parameters from the certificate.
  *
- * Returns: In case of a verification failure %GNUTLS_E_PK_SIG_VERIFY_FAILED 
- * is returned, and a positive code on success.
+ * Returns: On success, %GNUTLS_E_SUCCESS (0) is returned, otherwise a
+ *   negative error value (%GNUTLS_E_PK_SIG_VERIFY_FAILED in verification failure).
  *
  * Since: 2.12.0
  **/
@@ -1261,8 +1259,8 @@ gnutls_pubkey_verify_hash (gnutls_pubkey_t key, unsigned int flags,
  * This function will read the certifcate and the signed data to
  * determine the hash algorithm used to generate the signature.
  *
- * Returns: the 0 if the hash algorithm is found. A negative error code is
- * returned on error.
+ * Returns: On success, %GNUTLS_E_SUCCESS (0) is returned, otherwise a
+ *   negative error value.
  *
  * Since: 2.12.0
  **/
diff --git a/lib/gnutls_record.c b/lib/gnutls_record.c
index 72e3f76845..1cd87a4fd8 100644
--- a/lib/gnutls_record.c
+++ b/lib/gnutls_record.c
@@ -180,23 +180,22 @@ gnutls_transport_get_ptr2 (gnutls_session_t session,
  * have been initiated using gnutls_handshake().  @how should be one
  * of %GNUTLS_SHUT_RDWR, %GNUTLS_SHUT_WR.
  *
- * In case of %GNUTLS_SHUT_RDWR then the TLS connection gets
+ * In case of %GNUTLS_SHUT_RDWR the TLS session gets
  * terminated and further receives and sends will be disallowed.  If
- * the return value is zero you may continue using the connection.
- * %GNUTLS_SHUT_RDWR actually sends an alert containing a close
+ * the return value is zero you may continue using the underlying
+ * transport layer. %GNUTLS_SHUT_RDWR sends an alert containing a close
  * request and waits for the peer to reply with the same message.
  *
- * In case of %GNUTLS_SHUT_WR then the TLS connection gets terminated
+ * In case of %GNUTLS_SHUT_WR the TLS session gets terminated
  * and further sends will be disallowed. In order to reuse the
  * connection you should wait for an EOF from the peer.
  * %GNUTLS_SHUT_WR sends an alert containing a close request.
  *
  * Note that not all implementations will properly terminate a TLS
  * connection.  Some of them, usually for performance reasons, will
- * terminate only the underlying transport layer, thus causing a
- * transmission error to the peer.  This error cannot be
- * distinguished from a malicious party prematurely terminating the
- * session, thus this behavior is not recommended.
+ * terminate only the underlying transport layer, and thus not
+ * distinguishing between a malicious party prematurely terminating 
+ * the connection and normal termination. 
  *
  * This function may also return %GNUTLS_E_AGAIN or
  * %GNUTLS_E_INTERRUPTED; cf.  gnutls_record_get_direction().