4.2.4 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 gnutls_certificate_verify_peers2). To disable the automatic OCSP verification the flag GNUTLS_VERIFY_DISABLE_CRL_CHECKS should be specified to gnutls_certificate_set_verify_flags.

Since GnuTLS 3.5.1 the client certificate verification will consider the [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 GNUTLS_CERT_MISSING_OCSP_STATUS will returned from the verification function.

Under TLS 1.2 only one stapled response can be sent by a server, the OCSP response associated with the end-certificate. Under TLS 1.3 a server can send multiple OCSP responses, typically one for each certificate in the certificate chain. The following functions can be used by a client application to retrieve the OCSP responses as sent by the server.

int gnutls_ocsp_status_request_get (gnutls_session_t session, gnutls_datum_t * response)

int gnutls_ocsp_status_request_get2 (gnutls_session_t session, unsigned idx, gnutls_datum_t * response)

GnuTLS servers can provide OCSP responses to their clients using the following functions.

void gnutls_certificate_set_retrieve_function3 (gnutls_certificate_credentials_t cred, gnutls_certificate_retrieve_function3 * func)

int gnutls_certificate_set_ocsp_status_request_file2 (gnutls_certificate_credentials_t sc, const char * response_file, unsigned idx, gnutls_x509_crt_fmt_t fmt)

unsigned gnutls_ocsp_status_request_is_checked (gnutls_session_t session, unsigned int flags)

A server is expected to provide the relevant certificate’s OCSP responses using gnutls_certificate_set_ocsp_status_request_file2, and ensure a periodic reload/renew of the credentials. An estimation of the OCSP responses expiration can be obtained using the gnutls_certificate_get_ocsp_expiration function.

Function: time_t gnutls_certificate_get_ocsp_expiration (gnutls_certificate_credentials_t sc, unsigned idx, int oidx, unsigned flags)

sc: is a credentials structure.

idx: is a certificate chain index as returned by gnutls_certificate_set_key() and friends

oidx: is an OCSP response index

flags: should be zero

This function returns the validity of the loaded OCSP responses, to provide information on when to reload/refresh them.

Note that the credentials structure should be read-only when in use, thus when reloading, either the credentials structure must not be in use by any sessions, or a new credentials structure should be allocated for new sessions.

When oidx is (-1) then the minimum refresh time for all responses is returned. Otherwise the index specifies the response corresponding to the odix certificate in the certificate chain.

Returns: On success, the expiration time of the OCSP response. Otherwise (time_t)(-1) on error, or (time_t)-2 on out of bounds.

Since: 3.6.3

Prior to GnuTLS 3.6.4, the functions gnutls_certificate_set_ocsp_status_request_function2 gnutls_certificate_set_ocsp_status_request_file were provided to set OCSP responses. These functions are still functional, but cannot be used to set multiple OCSP responses as allowed by TLS1.3.

The responses can be updated periodically using the ’ocsptool’ command (see also ocsptool Invocation).

ocsptool --ask --load-cert server_cert.pem --load-issuer the_issuer.pem
         --load-signer the_issuer.pem --outfile ocsp.resp

In order to allow multiple OCSP responses to be concatenated, GnuTLS supports PEM-encoded OCSP responses. These can be generated using ’ocsptool’ with the ’–no-outder’ parameter.