Online Certificate Status Protocol Module

Respond with the revocation status of a certificate.

What does it do?

Based on configuration of the backend modules, an Online Certificate Status Protocol response is returned for the given certificate as per RFC6960.

Module Integration

The mod_ocsp module is a frontend module and will not do anything useful until mod_ocsp has been combined with one or more backend modules listed below. The mod_ocsp module uses the following hook to check the certificate status against the certificate revocation list, and suitable backend modules must be configured to implement each hook as needed.

All frontend modules run within a standard Apache httpd request, and standard httpd functionality applies in all cases.

Get CA Certificate Hook

This hook returns CA certificates for the given CA.

mod_ca_engine Returns CA certificates that would sign certificate sign requests by an HSM such as a smartcard.
mod_ca_simple Returns CA certificates that would sign certificate sign requests by a certificate and key specified on disk.

Certificate Status Hook

This hook returns the certificate status for the given certificate.

mod_ca_crl Check the certificate status against the certificate sign request from disk.

Examples

Basic Example

The simplest case: return the certificate revocation list to anybody who wants one.


# backend configuration:
<IfModule mod_ca_crl.c>
  # return this crl
  CACRLCertificateRevocationList /etc/pki/tls/ca-crl.pem
</IfModule>

# frontend configuration:
<IfModule mod_ocsp.c>
  <Location /ocsp>
    SetHandler ocsp
    OcspSigningCertificate /etc/pki/tls/ocsp.cert
    OcspSigningKey /etc/pki/tls/ocsp.key
  </Location>
</IfModule>

Handler Reference

The following parameters to the SetHandler directive are supported.

ocsp Handler

After calling the certificate status hook return the OCSP response.

SetHandler ocsp

Directive Reference

OcspSigningCertificate Directive

Description Set to the name of the signing certificate.
Syntax OcspSigningCertificate filename
Default none
Context server config, virtual host, directory, .htaccess
Status Frontend
Module mod_ocsp
Compatibility Introduced in mod_ocsp 0.2.0 and works with Apache HTTP Server 2.4.0 and later

Set to the name of the signing certificate.

OcspSigningKey Directive

Description Set to the name of the signing key.
Syntax OcspSigningKey filename
Default none
Context server config, virtual host, directory, .htaccess
Status Frontend
Module mod_ocsp
Compatibility Introduced in mod_ocsp 0.2.0 and works with Apache HTTP Server 2.4.0 and later

Set to the name of the signing key.

OcspOtherCertificates Directive

Description Set to the name of a file containing other certificates to add to the response.
Syntax OcspOtherCertificates filename
Default none
Context server config, virtual host, directory, .htaccess
Status Frontend
Module mod_ocsp
Compatibility Introduced in mod_ocsp 0.2.0 and works with Apache HTTP Server 2.4.0 and later

Set to the name of a file containing other certificates to add to the response.

OcspSize Directive

Description Set to the maximum size of the OCSP request from the client.
Syntax OcspSize bytes
Default OcspSize 131072
Context server config, virtual host, directory, .htaccess
Status Frontend
Module mod_scep
Compatibility Introduced in mod_ocsp 0.2.0 and works with Apache HTTP Server 2.4.0 and later

Set to the maximum size of the OCSP request from the client. This value cannot be smaller than 4096 bytes.

OcspLocation Directive

Description Set the URL location of the WADL returned by the OPTIONS method.
Syntax OcspLocation url
Default OcspLocation [current-URL]
Context server config, virtual host, directory, .htaccess
Status Frontend
Module mod_ocsp
Compatibility Introduced in mod_ocsp 0.2.0 and works with Apache HTTP Server 2.4.0 and later

Set the URL location of the WADL returned by the OPTIONS method.

OcspNextUpdate Directive

Description Set to the number of seconds until the next update.
Syntax OcspNextUpdate seconds
Default OcspNextUpdate 0
Context server config, virtual host, directory, .htaccess
Status Frontend
Module mod_ocsp
Compatibility Introduced in mod_ocsp 0.2.0 and works with Apache HTTP Server 2.4.0 and later

Set to the number of seconds until the next update. Defaults to zero (to disable).

OcspNoCertificates Directive

Description Set to 'on' to suppress the sending of certificates in the response.
Syntax OcspNoCertificates flag
Default OcspNoCertificates off
Context server config, virtual host, directory, .htaccess
Status Frontend
Module mod_ocsp
Compatibility Introduced in mod_ocsp 0.2.0 and works with Apache HTTP Server 2.4.0 and later

Set to 'on' to suppress the sending of certificates in the response. Defaults to 'off'.

OcspIdentifyByKeyID Directive

Description Set to 'on' to identify the signer certificate by key ID.
Syntax OcspIdentifyByKeyID flag
Default OcspIdentifyByKeyID off
Context server config, virtual host, directory, .htaccess
Status Frontend
Module mod_ocsp
Compatibility Introduced in mod_ocsp 0.2.0 and works with Apache HTTP Server 2.4.0 and later

Set to 'on' to identify the signer certificate by key ID. Defaults to 'off' for subject name.

OcspOverrideReason Directive

Description Mark all certificates as revoked, giving this reason.
Syntax OcspOverrideReason string
Default none
Context server config, virtual host, directory, .htaccess
Status Frontend
Module mod_ocsp
Compatibility Introduced in mod_ocsp 0.2.0 and works with Apache HTTP Server 2.4.0 and later

Mark all certificates as revoked, giving this reason.

Reasons must be one of:

  • unspecified
  • keyCompromise
  • CACompromise
  • affiliationChanged
  • superseded
  • cessationOfOperation
  • certificateHold
  • removeFromCRL

OcspOverrideRevocationTime Directive

Description If all certificates are revoked, add this revocation time.
Syntax OcspOverrideRevocationTime YYYYMMDDHHMMSSZ
Default None
Context server config, virtual host, directory, .htaccess
Status Frontend
Module mod_ocsp
Compatibility Introduced in mod_ocsp 0.2.0 and works with Apache HTTP Server 2.4.0 and later

If all certificates are revoked, add this revocation time, formatted as per http://tools.ietf.org/html/rfc2459#section-4.1.2.5.2 (YYYYMMDDHHMMSSZ)

OcspOverrideInvalidityDate Directive

Description If all certificates are revoked, add this invalidity date.
Syntax OcspOverrideInvalidityDate YYYYMMDDHHMMSSZ
Default None
Context server config, virtual host, directory, .htaccess
Status Frontend
Module mod_ocsp
Compatibility Introduced in mod_ocsp 0.2.0 and works with Apache HTTP Server 2.4.0 and later

If all certificates are revoked, add this invalidity date, formatted as per http://tools.ietf.org/html/rfc2459#section-4.1.2.5.2 (YYYYMMDDHHMMSSZ)

OcspOverrideHoldInstruction Directive

Description If all certificates are revoked, add this hold instruction.
Syntax OcspOverrideHoldInstruction string
Default none
Context server config, virtual host, directory, .htaccess
Status Frontend
Module mod_ocsp
Compatibility Introduced in mod_ocsp 0.2.0 and works with Apache HTTP Server 2.4.0 and later

If all certificates are revoked, add this hold instruction, formatted as an OID.

Instructions must be one of:

  • holdInstructionCallIssuer
  • holdInstructionReject

OcspFreshness Directive

Description The max-age of the certificate revocation list will be divided by this factor.
Syntax OcspFreshness factor [max-seconds]
Default OcspFreshness 2 86400
Context server config, virtual host, directory, .htaccess
Status Frontend
Module mod_ocsp
Compatibility Introduced in mod_ocsp 0.2.0 and works with Apache HTTP Server 2.4.0 and later

The age of the certificate revocation list will be divided by this factor when added as a max-age, set to zero to disable. Defaults to "2". An optional maximum value can be specified, defaults to one day.