Document the new verification functions

1 files changed, 22 insertions, 20 deletions

diff --git a/doc/cha-gtls-app.texi b/doc/cha-gtls-app.texi
index 48b3a23221..9e09088d91 100644
--- a/doc/cha-gtls-app.texi
+++ b/doc/cha-gtls-app.texi
@@ -574,23 +574,25 @@ the following functions, applicable to X.509 and OpenPGP certificates.
 
 @showfuncC{gnutls_certificate_set_x509_system_trust,gnutls_certificate_set_x509_trust_file,gnutls_certificate_set_openpgp_keyring_file}
 
-The peer's certificate is not automatically verified and one 
-must call @funcref{gnutls_certificate_verify_peers3}
-after a successful handshake to verify the certificate's signature and the owner 
-of the certificate. The verification status returned can be printed using
-@funcref{gnutls_certificate_verification_status_print}.
-
-Alternatively the verification can occur during the handshake
-by using @funcref{gnutls_certificate_set_verify_function}.
-
-The functions above provide a brief verification output. If a
+The peer's certificate will be automatically verified if
+@funcref{gnutls_session_auto_verify_cert} is called prior to handshake.
+
+Alternatively, one must set a callback function during the handshake
+using @funcref{gnutls_certificate_set_verify_function}, which
+will verify the peer's certificate once received. The verification
+should happen using @funcref{gnutls_certificate_verify_peers3} within
+the callback. It will verify the certificate's signature and the owner 
+of the certificate. That will provide a brief verification output. If a
 detailed output is required one should call @funcref{gnutls_certificate_get_peers}
 to obtain the raw certificate of the peer and verify it using the
 functions discussed in @ref{X.509 certificates}.
 
-@showfuncdesc{gnutls_certificate_verify_peers3}
+In both the automatic and the manual cases, the verification status returned
+can be printed using @funcref{gnutls_certificate_verification_status_print}.
 
-@showfuncdesc{gnutls_certificate_set_verify_function}
+@showfuncdesc{gnutls_session_auto_verify_cert}
+
+@showfuncB{gnutls_certificate_verify_peers3,gnutls_certificate_set_verify_function}
 
 
 @node SRP credentials
@@ -839,15 +841,15 @@ exchange.
 
 @showfuncdesc{gnutls_handshake_set_timeout}
 
-The handshake process doesn't ensure the verification
-of the peer's identity. When certificates are in use,
-this can be done, either after the handshake is complete, or during 
-the handshake if @funcref{gnutls_certificate_set_verify_function}
-has been used. In both cases the @funcref{gnutls_certificate_verify_peers2} function can be
-used to verify the peer's certificate (see @ref{Certificate authentication}
-for more information).
+In GnuTLS 3.5.0 and later it is recommended to use @funcref{gnutls_session_auto_verify_cert}
+for the handshake process to ensure the verification of the peer's identity.
+
+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}
+for more information.
 
-@showfuncA{gnutls_certificate_verify_peers2}
+@showfuncB{gnutls_session_auto_verify_cert,gnutls_certificate_verify_peers2}
 
 @node Data transfer and termination
 @section Data transfer and termination