The following covers general concepts of EJBCA's OCSP responder. For instructions of how to set it up, see OCSP Responder Management and OCSP Responders.

Introduction

OCSP (Online Certificate Status Protocol) is used by PKI-clients to verify the validity of certificates in real-time. This is done by sending a request for the status of a specific certificate to an OCSP responder. The responder may or may not be the same as the CA. The OCSP responder sends a signed reply, containing the requested status information back to the client. The client uses this status information to determine whether the certificate is valid for use or revoked. OCSP is defined in two RFCs:

  • RFC 6960 - the base OCSP specification and how OCSP messages are sent using HTTP POST
  • RFC 5019 - lightweight OCSP profiles, how messages are sent using HTTP GET and cache headers allowing OCSP responses to be cached in web caches and CDNs

The OCSP servlet receives OCSP request over http(s) and sends back a status response signed by the CA.

The OCSP service receives requests on http://localhost:8080/ejbca/publicweb/status/ocsp. If a short URL with out path, http://hostname.tld/ is desired for an OCSP responder URL rewriting can be done, for example in a front-end (caching) web server or load balancer. See the EJBCA Integration documentation for a few such examples.

As long as the OCSP service has not been deactivated the OCSP service can process requests for certificates signed by a CA running in EJBCA, or an external CA. OCSP Key Bindings are configured to process OCSP requests for desired CAs. For a CA to be valid as an OCSP responder it must have the KeyUsage 'Digital Signature' in the certificate profile used to create the CA. This KeyUsage must be included if the CA is to sign OCSP responses. The default certificate profiles for CAs include the key usage 'Digital Signature'.

To generate an OCSP request using OpenSSL (works with both internal and external OCSP responders):

openssl ocsp -issuer Test-CA.pem -CAfile Test-CA-chain.pem -cert CertificateToCheck.pem -req_text -url http://localhost:8080/ejbca/publicweb/status/ocsp
BASH

To issue GET requests for testing, the following methodology can be used (replace with your own data):

# After generating the End User certificate, generate the OCSP Request:
openssl ocsp -noverify -no_nonce -respout ocsp.resp -reqout ocsp.req -issuer ManagementCA.cacert.pem -cert ee_cert.pem -url "http://ejbca-domain-name:8080/ejbca/publicweb/status/ocsp" -header "HOST=ejbca-domain-name" -text
# Encode the OCSP Request for a GET URL: 
openssl enc -in ocsp.req -out ocsp.req.b64 -a
# Perform the GET Request using curl. Append the data from 'ocsp.req.b64' to the end of URL, and ensure any whitespace is removed:
curl --verbose --url http://ejbca-domain-name:8080/ejbca/publicweb/status/ocsp/MEkwRzBFMEMwQTAJBgUrDgMCGgUABBT1x9iHOmegR7sYp5Fzdo/u3FMBRgQUH1DTnzl9lscAe3WBTUPCWR+xwpQCCDlpiyU2q5Rb --output response.txt
# Decode the OCSP response:
openssl ocsp -CAfile full-chain.pem -respin response.txt -text
BASH

If Firefox is to request and accept OCSP responses from a CA not in the default trust store, it must be configured to trust this CA:

  1. In Advanced > Certificates > View Certificates > Authorities, import and select the CA certificate, and checking the appropriate Trust options.
  2. If Query OCSP responder servers to confirm the current validity of certificates in Advanced > Certificates is selected, and certificates include an OCSP Service URL (AIA extension), Firefox will query the OCSP server when for example double-clicking on a certificate in the certificate manager.

An appropriate URL for validation is: http://hostname:8080/ejbca/publicweb/status/ocsp and doc/samples contains a sample on how to check revocation with OCSP using the new APIs as of JDK 1.5.

OCSP Service Locator URI 

Software, such as web browsers, usually figure out which OCSP URL to use when validating a specific certificate by looking at the AIA (Authority Information Access) certificate extension in the certificate to be validated. The AIA extension can hold an OCSP Service Locator URI, pointing to the OCSP responder that can answer authoritatively if the certificate is revoked or not (see RFC 6960 for details). The OCSP Service Locator URI can be configured in Certificate Profiles for certificates issued by EJBCA.

Revoked CA Certificates

When the first entry in the CA certificate chain matching an OCSP request is revoked with one of the reason codes "keyCompromise", "cACompromise", "aACompromise" or "unspecified", the status of the requested certificate will be returned as revoked with reason "cACompromise". This is in accordance with RFC6960, section 2.7.

This means that you can instantly block the use of leaf certificates by revoking the issuer of these certificates using, for example, the "cACompromise" reason code, even if the CA certificate is still considered valid according to a CRL at the client.

This also applies if you revoke a cross-signed CA certificate for one of these reasons or import such a CA revocation status update to you VAs. It is still recommended that you revoke the individual certificates, to ensure that they appear in fallback CRLs.

Expired Certificates

EJBCA keeps the status of expired certificates in the database, so the responder will answer queries also for expired certificates unless you remove them from the database. In the internal EJBCA database, the status of expired certificates is set to ARCHIVED in the database (CertificateData table) by the CRL creation job. The ARCHIVED status does not affect the response sent by the OCSP responder.

The algorithm is:

  • If status is CERT_REVOKED, the certificate is revoked, and reason and date are picked up.
  • If status is CERT_ARCHIVED and reason is NOT REMOVEFROMCRL or NOT_REVOKED, the certificate is revoked, and reason and date are picked up.
  • If status is CERT_ARCHIVED and reason is REMOVEFROMCRL or NOT_REVOKED, the certificate is NOT revoked.
  • If status is neither CERT_REVOKED or CERT_ARCHIVED, the certificate is NOT revoked.

The archive cutoff extension is used as defined in section 4.4.4 of the RFC 6960. For more information, see Archive Cutoff. 

Response Validity

The field nextUpdate can be included in OCSP responses (RFC6960) and is calculated based on the Response validity setting for the OCSP Key Binding.

A value of 0 means that there is always a newer response available, and the nextUpdate field is not included in OCSP responses.

If the nextUpdate is calculated to be after 99991231235959Z, it would be set to 99991231235959Z (last OCSP answer as defined in ETSI EN 319 411-2 and -1). This can be forced by configuring Response validity to for example, 315328464000 seconds (9999y).

Setting up an OCSP Responder on a Remote VA 

You can set up separated OCSP responders in EJBCA in order to isolate the CA from the Internet and still be able to answer OCSP requests. Additionally, you can set up firewalls so that only outgoing traffic is allowed from the CA, and nothing to the CA.

Separated OCSP responders are also recommended when you do not require high-performance clustering for the CA, but you do need high-performance for the OCSP responders. This is a common setup, if the CA only issues certificates once every year for one million users, this does not put much pressure on the CA, but the OCSP responders can be put under high load continuously.

For information on how to set up standalone, separated OCSP responders, see OCSP Responder Management.

Multiple Responders and CA Certificates

The OCSP responder can have many responder certificates, each issued by one CA and mapped by an OcspKeyBinding. This means that the responder can answer requests targeted at multiple CAs. There is no built-in limitation on the number of CAs that can be handled.

Selection of OCSP Signing Certificate from a Request

In the OCSP request as defined in RFC 6960, the hash of both the issuing CA's Subject DN and the public key are available:

CertID ::= SEQUENCE {
 hashAlgorithm AlgorithmIdentifier,
 issuerNameHash OCTET STRING, – Hash of issuer's DN
 issuerKeyHash OCTET STRING, – Hash of issuer's public key
 serialNumber CertificateSerialNumber }
CODE

EJBCA selects OcspKeyBinding based on the subject DN and public key of the CA certificate that issued an OCSP signing certificate. The issuing CA certificate is determined from the OCSP certificate chain and the construction of the chain is described below.

CA Key Renewal Considerations

EJBCA considers two X.509 CA certificates as the same CA if they share the same Subject DN and as different versions of the same CA if the public key is different. Since both subject and key pair is used in the request, you will need two OcspKeyBindings (one issued before key renewal and one after) to be able to serve OCSP requests where clients use CA certificate for both the old and new key pair in their requests.

EJBCA currently only allows you to issue an OCSP signing certificate from the latest version of the CA. Thus, before such a CA key renewal, you will need to issue OCSP signing certificates that will last for the lifetime of the CA certificate.

Certificate Chain Construction

EJBCA builds the chain for each OCSP signing certificate by looking for the latest CA certificate with a Subject DN equal to the Issuer DN of the OCSP signing certificate. Unless the found CA certificate is self-signed, the procedure is repeated until the full chain is built.

If the built chain is unable to verify the OCSP signing certificate (due to CA certificate key renewal), a different algorithm is used where EJBCA uses the internal CertificateData.cAFingerprint value to determine the exact certificate that has issued an OCSP signing certificate. Similar to the case where we build the chain using the Issuer DN of the OCSP signing certificate, the process is repeated until a full chain leading up to a self-signed CA is built.

OCSP Response Certificate Chain

For efficiency reasons, it is possible to configure EJBCA to either omit including the signing certificate or its certificate chain in the OCSP response. Setting the relevant configuration in the $EJBCA_HOME/conf/ocsp.properties file or in the Internal Key Binding in the GUI, has the following effect:

  • If ocsp.includesignercert=true and ocsp.includecertchain=true, the signing certificate and its chain, except for the signing certificate root CA certificate, will be included in the OCSP response. If the signing certificate IS the root CA certificate, then the root CA certificate will be included in the response anyway.

  • If ocsp.includesignercert=true and ocsp.includecertchain=false, only the signing certificate will be included in the OCSP response even if it was a root CA certificate.
  • If ocsp.includesignercert=false, neither the signing certificate nor the certificate chain will be included in the OCSP response regardless of the value of ocsp.includecertchain

Audit and Transaction Logging

The following types of logs that can be generated by the OCSP responder:

  • OCSP service log
  • OCSP transaction log
  • OCSP audit log

OCSP Service Log

The OCSP service log uses Log4j to log to the WildFly/JBoss server log. The WildFly/JBoss server log is located in APPSRV_HOME/standalone/configuration/log/server.log by default and the logging can be configured using JBoss CLI.

OCSP Transaction Log

The OCSP transaction log can be used to log various information about OCSP requests. Transaction logging summarizes each OCSP request/responses, which can be used for charging clients if you are running a commercial OCSP service.

For instructions on how to configure the OCSP transaction log, see OCSP Responder Management.

OCSP Audit Log 

Do not confuse the OCSP audit log with the standard logging. OCSP operations are not logged in a standard PKI installation, but a specific audit log for the OCSP responder can be written to disk.

The OCSP audit log logs entire requests and responses. This can be useful when requests and responses are signed because the information can be used to verify requests and responses afterward.

Audit logging is configured in the same way as transaction logging, see OCSP Responder Management for more information.

Using the OCSP API

To learn the API, you can study the included source code. The client API is used in the class org.ejbca.core.protocol.ocsp.OCSPUnidClient. The EJBCA Client Toolbox can serve as a good sample for using the API, in the class org.ejbca.ui.cli.Ocsp.

Database Indexes

As your OCSP database grows with revoked, and active, certificates you will need database indexes to maintain good performance. Refer to the file doc/sql-scripts/create-index-ejbca.sql (section for certificate data) for indexes needed for CA and OCSP operations.

OCSP GET

The GET OCSP request is defined in RFC 6960 (and RFC2560) A.1 as: 

'GET {url}/{url-encoding of base-64 encoding of the DER encoding of the OCSPRequest}'.

A base64-encoded request can contain the reserved characters '+', '/' and '=', but will be handled correctly both in their %-escaped and original form by the responder, since it's unclear if they do conflict as defined in RFC 2396 2.2.

Not all web-product handles the encoded '/' (%2F) nicely. JBoss/Tomcat has to be started with -Dorg.apache.tomcat.util.buf.UDecoder.ALLOW_ENCODED_SLASH=true added to JAVA_OPT in JBOSS_HOME/bin/run.conf.

Responses with Longer Validity and Caching 

RFC 6960 (and RFC2560) defines thisUpdate, nextUpdate and producedAt. producedAt is always included in the response and is the time the response was created. thisUpdate and nextUpdate are enabled by configuring 'ocsp.untilNextUpdate' in ocsp.properties or in the OcspKeyBinding. thisUpdate will be the time a singleResponse is embedded in the main response and nextUpdate will be 'untilNextUpdate' seconds later than thisUpdate. This enables clients that support this feature to re-use a valid response and decrease to load on the OCSP responder.

RFC 5019 defines how to use HTTP cache headers as defined in RFC 2616 for OCSP HTTP GET requests. By using the headers Last-Modified, Expires, max-age and Date, less intelligent network components like HTTP caches can cache responses. This enables re-use of responses to decrease the load on the OCSP responder and can shorten response times by deploying cache closer to the actual OCSP consumers. HTTP cache headers are enabled by configuring 'ocsp.maxAge' in ocsp.properties or in the OcspKeyBinding.

When using RFC 5019 style HTTP headers, JBoss users should be aware that the Date header is overwritten with a cached value. Since generating the Date-string is computationally heavy for regular small GET requests, it is generated about once per second. Consequently, a response can sometimes have a Last-Modified value one second in the future from the actual Date.

A regular Apache HTTP server can be used for caching requests, load-balancing and dropping some unwanted requests:

<VirtualHost *:80>
        # Use as much memory as possible for the cache (in 1 kB blocks)
        # 1GB of memory at ~2kB/ocsp request would hold about 500000 different requests
        CacheEnable mem /
        MCacheSize 1048576
        MCacheMaxObjectCount 1000000
        MCacheMinObjectSize 1
        MCacheMaxObjectSize 4096

        # Using disk-cache will allow a much larger pool of cached entires and the operation system
        # will cache those files, but you are responsible for cleaning up old cache-entries using
        # the "htcacheclean" tool. A disk cache will also live through a server restart.
        # The user running apache has to have read/write access to "/var/cache/ocsp".
        #CacheEnable disk /
        #CacheRoot /var/cache/ocsp

        # Ignore requests for uncached responses.. this will protect the OCSP from
        # DOS attacks using "Cache-Control: no-cache" or "Pragma: no-cache"
        CacheIgnoreCacheControl On

        ProxyRequests Off

        <Location>
                # Everybody is welcome here..
                Allow from all
                Order allow,deny

                # ..or just those from networks that is supposed to use the service
                #Deny from all
                #Order deny,allow
                #allow from 127.
                #allow from 172.16.212.1

                ProxyPassReverse balancer://mycluster-kerb/
        </Location>

        # Proxy requests to OCSP instances (only one machine currently configured)
        <Proxy balancer://mycluster-kerb>
                # proxy_ajp has to be enabled for ajp-proxying
                BalancerMember ajp://127.0.0.1:8009/ejbca/publicweb/status/ocsp
                # proxy_http has to be enabled for http-proxying
                #BalancerMember http://ocsp2.domain.org:8080/ejbca/publicweb/status/ocsp
                #BalancerMember http://ocsp3.domain.org:8080/ejbca/publicweb/status/ocsp
        </Proxy>

        # We only want RFC 5019 compliant URLs to be forwarded to the OCSP, the rest
        # should get a "404 Not found" or "414 Request-URI Too Large."
        LimitRequestLine 257
        RewriteEngine On
        RewriteCond %{REQUEST_METHOD} get [NC]
        RewriteRule ^/([a-zA-Z0-9+=/]+)$ balancer://mycluster-kerb/$1 [P,L]

        # Possible values include: debug, info, notice, warn, error, crit,
        # alert, emerg.
        LogLevel debug
        CustomLog /var/log/apache2/access.log combined
        ErrorLog /var/log/apache2/error.log
</VirtualHost>
XML

Pre-Produced OCSP Responses

ENTERPRISE  This is an EJBCA Enterprise feature.

By default, EJBCA generates and signs OCSP responses for every request. Pre-produced OCSP responses allow responses to be pre-produced and persisted before they are requested. This allows for increased throughput on the OCSP responders since signing responses commonly becomes a bottleneck during peak loads. Serving a request with a pre-produced response naturally comes with the trade-off that the response isn't freshly generated. This means the status of the requested certificate may have changed after the response was generated. The fields producedAt and thisUpdate in the response will always show when the response was signed and at which time the status was known to be correct by the responder. Furthermore, the field nextUpdate displays the time at, or before which time, newer information will be available about the status of the certificate.

A persisted OCSP response will be served until the nextUpdate date has passed or until a newer response is generated by the responder. See Responses with Longer Validity and Caching for nextUpdate configuration instructions. No responses are persisted if nextUpdate is not configured. Responses can be kept up to date, by configuring the OCSP Response Pre-Signer service or enabling Store Responses On Demand, which will persist responses upon request.

In addition to reducing the load on responders, pre-produced OCSP responses can also be used to issue Final OCSP Responses before a CA expires in compliance with EN 319 411-2.

For more information on configuring Pre-produced OCSP responses, see OCSP Response Pre-Production.

OCSP High Availability (HA)

A typical configuration when using External OCSP responders uses two or more OCSP responder nodes. To assure that failure of one node does not affect other nodes, each OCSP responder node can maintain its own database. By using its own database you can assure high availability since the nodes are completely independent and you perform maintenance on one node, including the database, without affecting uptime of the OCSP service as a whole. Similarly, each OCSP responder node can use its own HSM.

OCSP responder nodes can also use a common HA database and an HA cluster of HSM if that suits your organization better.

Each OCSP responder node can produce transaction and audit logging, see Audit and Account Logging.

Usage Examples 

Adobe Reader 

A good example of using OCSP is to check digitally signed PDF documents using Adobe Reader.

To verify certificates in Adobe Reader, you must first add the CA certificate as trusted in Adobe Reader. You can do that in the menu Document > Trusted Identities. Choose Certificates in the list menu and click Add contacts to browse to the CA-certificate that you have downloaded in DER format (for example by choosing download to IE on the public EJBCA pages). The CA certificate must have been saved with a name ending with .cer. After adding the new contact, click Edit trust and check at least Signatures and as trusted root and Certified documents. Applies for both internal and external OCSP responders.

Certificates that have an OCSP service locator will be verified against the OCSP responder. You can configure this in the certificate profile used to issue certificates.

If you sign PDF documents with embedded OCSP responses, these responses must include a nextUpdate field, and the timestamp must be within the thisUpdate and nextUpdate period of the OCSP response.

OCSP Response Extensions

OCSP Extensions (except the nonce extension) are configured in the section shown below when editing an OCSP key binding.

OCSP extensions that do not require data from the request (like the nonce extension does) will be automatically returned if specified in the keybinding, whether or not they have been specified in the request from the client. 

For information on OCSP Response Extensions, see the following sections: