doc: improved OCSP description and mention RFC7633

diff --git a/doc/cha-bib.texi b/doc/cha-bib.texi
index dc0a02e03aaa3fd0f43ba3832d639ebc77759397..8cc81ac5a44e1d62f5a4aa87c259dd4dac460dee 100644 (file)
--- a/doc/cha-bib.texi
+++ b/doc/cha-bib.texi
@@ -51,6 +51,11 @@ S. Santesson, "TLS Handshake Message for Supplemental Data",
 September 2006, Available from
 @url{http://www.ietf.org/rfc/rfc4680.txt}.
 
+@item @anchor{RFC7633}[RFC7633]
+P. Hallam-Baker, "X.509v3 Transport Layer Security (TLS) Feature Extension",
+October 2015, Available from
+@url{http://www.ietf.org/rfc/rfc7633.txt}.
+
 @item @anchor{RFC4514}[RFC4514]
 Kurt D.  Zeilenga, "Lightweight Directory Access Protocol (LDAP): String Representation of Distinguished Names",
 June 2006, Available from

diff --git a/doc/cha-cert-auth2.texi b/doc/cha-cert-auth2.texi
index e3708ba0640b354b6e48659e086f570df53bf50d..dbe96157a1d219d56b235b7962c0ad7bf8650557 100644 (file)
--- a/doc/cha-cert-auth2.texi
+++ b/doc/cha-cert-auth2.texi
@@ -11,6 +11,7 @@ structures, etc., are discussed in this chapter.
 * PKCS 10 certificate requests::
 * PKIX certificate revocation lists::
 * OCSP certificate status checking::
+* OCSP stapling::
 * Managing encrypted keys::
 * certtool Invocation::            Invoking certtool
 * ocsptool Invocation::            Invoking ocsptool
@@ -152,10 +153,10 @@ identity of a peer will verify the certificate against a set of
 trusted certificates and then check whether the certificate is listed
 in a CRL and/or perform an OCSP check for the certificate.
 
-Note that in the context of a TLS session the server may provide an
-OCSP response that will be used during the TLS certificate verification
-(see @funcref{gnutls_certificate_verify_peers2}).
-You may obtain this response using @funcref{gnutls_ocsp_status_request_get}.
+Applications are typically expected to contact the OCSP server in order to
+request the certificate validity status. The OCSP server replies with an OCSP
+response. This section describes this online communication (which can be avoided
+when using OCSP stapled responses, for that, see @ref{OCSP stapling}).
 
 Before performing the OCSP query, the application will need to figure
 out the address of the OCSP server.  The OCSP server address can be
@@ -301,6 +302,38 @@ whether the received OCSP response corresponds to the certificate being checked.
 
 @showfuncC{gnutls_ocsp_resp_verify,gnutls_ocsp_resp_verify_direct,gnutls_ocsp_resp_check_crt}
 
+@node OCSP stapling
+@subsection OCSP stapling
+@cindex certificate status
+@cindex Online Certificate Status Protocol
+@cindex OCSP stapling
+
+To avoid applications contacting the OCSP server directly, TLS servers
+can provide a "stapled" OCSP response in the TLS handshake. That way
+the client application needs to do nothing more. GnuTLS will automatically
+consider the stapled OCSP response during the TLS certificate verification
+(see @funcref{gnutls_certificate_verify_peers2}).
+The stapled response can be obtained using @funcref{gnutls_ocsp_status_request_get}.
+
+In addition, since GnuTLS 3.5.1 the client will consider the @xcite{RFC7633} OCSP-Must-staple
+certificate extension, and will consider it while checking for stapled OCSP responses. If the
+extension is present and no OCSP staple is found the certificate verification will fail
+and the status code @code{GNUTLS_CERT_MISSING_OCSP_STATUS} will returned from the verification
+function.
+
+GnuTLS servers can provide this response to their clients using the following functions.
+
+@showfuncC{gnutls_certificate_set_ocsp_status_request_function,gnutls_certificate_set_ocsp_status_request_file,gnutls_ocsp_status_request_is_checked}
+
+The simplest approach is for a server to provide the OCSP server's response using the @funcref{gnutls_certificate_set_ocsp_status_request_file}.
+The response may be updated periodically using the following command (see also @ref{ocsptool Invocation}).
+
+@example
+ocsptool --ask --load-cert server_cert.pem --load-issuer the_issuer.pem
+         --load-signer the_issuer.pem --outfile ocsp.response
+@end example
+
+
 @node Managing encrypted keys
 @subsection Managing encrypted keys
 @cindex Encrypted keys

diff --git a/doc/cha-intro-tls.texi b/doc/cha-intro-tls.texi
index 2c55b5675fdc9abe2f5c5b880da25758d4668475..550da1ef7e79c953eba92e2bb92c835a5f0a4857 100644 (file)
--- a/doc/cha-intro-tls.texi
+++ b/doc/cha-intro-tls.texi
@@ -600,15 +600,7 @@ may periodically run @code{ocsptool} (see @ref{ocsptool Invocation}) to obtain
 its certificate revocation status and serve it to the clients. That
 way a client avoids an additional connection to the OCSP server.
 
-@showfuncD{gnutls_certificate_set_ocsp_status_request_function,gnutls_certificate_set_ocsp_status_request_file,gnutls_ocsp_status_request_enable_client,gnutls_ocsp_status_request_is_checked}
-
-A server is required to provide the OCSP server's response using the @funcref{gnutls_certificate_set_ocsp_status_request_file}.
-The response may be obtained periodically using the following command.
-
-@example
-ocsptool --ask --load-cert server_cert.pem --load-issuer the_issuer.pem
-         --load-signer the_issuer.pem --outfile ocsp.response
-@end example
+See @ref{OCSP stapling} for further information.
 
 Since version 3.1.3 GnuTLS clients transparently support the certificate status
 request.