wolfSSL supports the Online Certificate Status Protocol (OCSP) [https://tools.ietf.org/html/rfc2560] as a client and OCSP stapling version 1 [https://tools.ietf.org/html/rfc6066#section-8] and 2 [https://tools.ietf.org/html/rfc6961]. OCSP is a substitute for Certificate Revocation Lists (CRL). CRLs are a list of certificates that shouldn’t be temporarily or permanently trusted. A major setback for CRLs is the time it takes for these lists to propagate. It may take up to a week [https://tools.ietf.org/html/rfc5280#section-3.3] due to CRLs being issued periodically by Certificate Authorities (CA). OCSP allows clients to verify the validity of server certificates with an OCSP responder and know in real time whether to trust a certificate or not.
OCSP stapling is a TLS extension sent by a client that instructs the server that it would like to receive certificate status information. Stapling significantly cuts down on bandwidth and on round trips needed to set up a connection. When a TLS server receives the Certificate Status Request extension from a client, it will transmit the OCSP responders complete, DER-encoded OCSP response. This relieves the client from having to ask an OCSP responder about the certificate validity and saves the OCSP responder bandwidth coming from clients of a frequently visited server.
OCSP stapling version 1 is severely limited by being able to only transmit the status information of only one certificate. Many TLS servers opt to send intermediate certificates along with its own certificate in case clients do not know the intermediate certificate chain. OCSP stapling version 1 will only save the client the trouble of confirming the status of the server’s certificate, but not of checking the intermediate certificates. OCSP stapling version 2 defines a new extension that allows “servers […] to provide status information about not only the server’s own certificate but also the status of intermediate certificates in the chain” [https://tools.ietf.org/html/rfc6961].
To compile wolfSSL with OCSP support, use the following configure options:
OCSP: --enable-ocsp
OCSP stapling: --enable-ocspstapling
OCSP stapling v2: --enable-ocspstapling2
The following API are available in wolfSSL to enable OCSP usage:
int wolfSSL_CTX_EnableOCSP(WOLFSSL_CTX*, int options);
int wolfSSL_CTX_DisableOCSP(WOLFSSL_CTX*);
int wolfSSL_CTX_SetOCSP_OverrideURL(WOLFSSL_CTX*, const char*);
int wolfSSL_CTX_SetOCSP_Cb(WOLFSSL_CTX*,
CbOCSPIO, CbOCSPRespFree, void*);
int wolfSSL_CTX_EnableOCSPStapling(WOLFSSL_CTX*);
int wolfSSL_CTX_DisableOCSPStapling(WOLFSSL_CTX*);
int wolfSSL_CTX_EnableOCSPMustStaple(WOLFSSL_CTX*);
int wolfSSL_CTX_DisableOCSPMustStaple(WOLFSSL_CTX*);
The following flow is enough to use OCSP in wolfSSL:
wolfSSL_CTX_EnableOCSP(ctx, 0);
To use OCSP stapling:
wolfSSL_CTX_EnableOCSPStapling(ctx);
wolfSSL_UseOCSPStapling(ssl, WOLFSSL_CSR_OCSP, 0);
wolfSSL_CTX_EnableOCSP(ctx, 0);
To use OCSP stapling version 2:
wolfSSL_CTX_EnableOCSPStapling(ctx);
wolfSSL_UseOCSPStaplingV2(ssl, WOLFSSL_CSR2_OCSP*, 0);
wolfSSL_CTX_EnableOCSP(ctx, 0);
* To provide status request information for intermediate certificates use WOLFSSL_CSR2_OCSP_MULTI
To allow the server to provide OCSP stapling responses use:
wolfSSL_CTX_EnableOCSP(ctx, 0);
To provide a custom OCSP responder URL use:
wolfSSL_CTX_SetOCSP_OverrideURL(ctx, ocspUrl);
wolfSSL_CTX_EnableOCSP(ctx, WOLFSSL_OCSP_URL_OVERRIDE);
OCSP stapling version 2 can’t be used with TLS 1.3 as it has been deprecated [https://tools.ietf.org/html/rfc8446#section-4.4.2.1]. TLS 1.3 uses OCSP stapling version 1 but the certificate status is not a separate message. Instead it is included as an extension to the corresponding certificate.
If you have any questions or run into any issues, contact us at facts@wolfssl.com, or call us at +1 425 245 8247.
