doc: few improvements over certificate validation text

Signed-off-by: Nikos Mavrogiannopoulos <nmav@gnutls.org>

3 files changed, 29 insertions, 10 deletions

diff --git a/doc/cha-cert-auth.texi b/doc/cha-cert-auth.texi
index d48e1bb814..0a9da1c9f8 100644
--- a/doc/cha-cert-auth.texi
+++ b/doc/cha-cert-auth.texi
@@ -5,7 +5,7 @@
 The most known authentication method of @acronym{TLS} are certificates.
 The PKIX @xcite{PKIX} public key infrastructure is daily used by anyone
 using a browser today. @acronym{GnuTLS} provides a simple API to 
-use the @acronym{X.509} certificates @xcite{PKIX}.
+verify the @acronym{X.509} certificates as in @xcite{PKIX}.
 
 The key exchange algorithms supported by certificate authentication are
 shown in @ref{tab:key-exchange}.
diff --git a/doc/cha-gtls-app.texi b/doc/cha-gtls-app.texi
index 0f89e8f41a..0e1e04df3e 100644
--- a/doc/cha-gtls-app.texi
+++ b/doc/cha-gtls-app.texi
@@ -976,13 +976,16 @@ exchange.
 
 In GnuTLS 3.5.0 and later it is recommended to use @funcref{gnutls_session_set_verify_cert}
 for the handshake process to ensure the verification of the peer's identity.
+That will verify the peer's certificate, against the trusted CA store while
+accounting for stapled OCSP responses during the handshake; any error will
+be returned as a handshake error.
 
-In older GnuTLS versions it is required to manually verify the peer's certificate
-during the handshake by using @funcref{gnutls_certificate_set_verify_function}, and
-@funcref{gnutls_certificate_verify_peers2}. See @ref{Certificate authentication}
+In older GnuTLS versions it is required to verify the peer's certificate
+during the handshake by setting a callback with @funcref{gnutls_certificate_set_verify_function},
+and then using @funcref{gnutls_certificate_verify_peers3} from it. See @ref{Certificate authentication}
 for more information.
 
-@showfuncB{gnutls_session_set_verify_cert,gnutls_certificate_verify_peers2}
+@showfuncB{gnutls_session_set_verify_cert,gnutls_certificate_verify_peers3}
 
 @node Data transfer and termination
 @section Data transfer and termination
diff --git a/lib/cert-session.c b/lib/cert-session.c
index f858308664..772d1417d9 100644
--- a/lib/cert-session.c
+++ b/lib/cert-session.c
@@ -587,18 +587,18 @@ _gnutls_x509_cert_verify_peers(gnutls_session_t session,
  * The default verification flags used by this function can be overridden
  * using gnutls_certificate_set_verify_flags().
  *
- * This function will take into account the OCSP Certificate Status TLS extension,
+ * This function will take into account the stapled OCSP responses sent by the server,
  * as well as the following X.509 certificate extensions: Name Constraints,
  * Key Usage, and Basic Constraints (pathlen).
  * 
- * To avoid denial of service attacks some
- * default upper limits regarding the certificate key size and chain
- * size are set. To override them use gnutls_certificate_set_verify_limits().
- *
  * Note that you must also check the peer's name in order to check if
  * the verified certificate belongs to the actual peer, see gnutls_x509_crt_check_hostname(),
  * or use gnutls_certificate_verify_peers3().
  *
+ * To avoid denial of service attacks some
+ * default upper limits regarding the certificate key size and chain
+ * size are set. To override them use gnutls_certificate_set_verify_limits().
+ *
  * Returns: %GNUTLS_E_SUCCESS (0) when the validation is performed, or a negative error code otherwise.
  * A successful error code means that the @status parameter must be checked to obtain the validation status.
  **/
@@ -624,6 +624,10 @@ gnutls_certificate_verify_peers2(gnutls_session_t session,
  * using gnutls_certificate_set_verify_flags(). See the documentation
  * of gnutls_certificate_verify_peers2() for details in the verification process.
  *
+ * This function will take into account the stapled OCSP responses sent by the server,
+ * as well as the following X.509 certificate extensions: Name Constraints,
+ * Key Usage, and Basic Constraints (pathlen).
+ * 
  * If the @hostname provided is non-NULL then this function will compare
  * the hostname in the certificate against it. The comparison will follow
  * the RFC6125 recommendations. If names do not match the
@@ -632,6 +636,10 @@ gnutls_certificate_verify_peers2(gnutls_session_t session,
  * In order to verify the purpose of the end-certificate (by checking the extended
  * key usage), use gnutls_certificate_verify_peers().
  *
+ * To avoid denial of service attacks some
+ * default upper limits regarding the certificate key size and chain
+ * size are set. To override them use gnutls_certificate_set_verify_limits().
+ *
  * Returns: %GNUTLS_E_SUCCESS (0) when the validation is performed, or a negative error code otherwise.
  * A successful error code means that the @status parameter must be checked to obtain the validation status.
  *
@@ -667,6 +675,10 @@ gnutls_typed_vdata_st data;
  * using gnutls_certificate_set_verify_flags(). See the documentation
  * of gnutls_certificate_verify_peers2() for details in the verification process.
  *
+ * This function will take into account the stapled OCSP responses sent by the server,
+ * as well as the following X.509 certificate extensions: Name Constraints,
+ * Key Usage, and Basic Constraints (pathlen).
+ * 
  * The acceptable @data types are %GNUTLS_DT_DNS_HOSTNAME, %GNUTLS_DT_RFC822NAME and %GNUTLS_DT_KEY_PURPOSE_OID.
  * The former two accept as data a null-terminated hostname or email address, and the latter a null-terminated
  * object identifier (e.g., %GNUTLS_KP_TLS_WWW_SERVER).
@@ -679,6 +691,10 @@ gnutls_typed_vdata_st data;
  * or be marked for any purpose, otherwise verification status will have the
  * %GNUTLS_CERT_SIGNER_CONSTRAINTS_FAILURE flag set.
  *
+ * To avoid denial of service attacks some
+ * default upper limits regarding the certificate key size and chain
+ * size are set. To override them use gnutls_certificate_set_verify_limits().
+ *
  * Returns: %GNUTLS_E_SUCCESS (0) when the validation is performed, or a negative error code otherwise.
  * A successful error code means that the @status parameter must be checked to obtain the validation status.
  *