EJBCA - Open Source PKI Certificate Authority
Search ejbca.org for:

Verification tool

Verification of a running responder can be done by using EJBCA's clientToolBox. See EJBCA clientToolBox for instructions how to build and use it.

To get all available OCSP commands please type: $TOOLBOX_HOME/ejbcaClientToolBox.sh OCSP

Chain validation

When returning status of a certificate whose status is requested in an OCSP request, the status of the CA certificate of this certificate is also validated.

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 configurations in the $EJBCA_HOME/conf/ocsp.properties file or in the Internal Key Binding in the GUI, will have 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 any way.
  • 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'

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 are set to ARCHIVED in the database (CertificateData table) by the CRL creation job. This ARCHIVED status does not (from EJBCA 3.9.4) affect the response sent by the OCSP responder. The algorithm is:

  • If status is CERT_REVOKED the certificate is revoked and reason and date is picked up.
  • If status is CERT_ARCHIVED and reason is _NOT_ REMOVEFROMCRL or NOT_REVOKED the certificate is revoked and reason and date is 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 RFC 6960.

Multiple responder 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.

There can exist multiple CA certificates with the same DN. The OCSP standard includes IssuerNameHash and IssuerKeyHash in the request, meaning that the OCSP protocol, and the responder, can handle key roll-over on the CA without issues.

Using the OCSP API

The best way to learn the API is by looking at the source code, since it is included. 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 and it is in the class org.ejbca.ui.cli.Ocsp.

OCSP extensions

The standard allows the usage of extensions in OCSP requests and responses.

Nonce

Nonce is the only standard extensions defined. The purpose of the nonce is that a client can verify that a response really is in response to the specific requests, and not a replayed response. Is is recommended that if the OCSP requests contains the nonce extension, the OCSP response also contains the nonce.
EJBCA included the nonce from the client requests in the server response if the requests contains a nonce.

Custom extensions

You can implement custom OCSP extensions in EJBCA by implementing a simple Java class and including it in the application servers class-path. The easiest way to do that is to put your java file in an ejbca-custom directory, so it will be included in the ejbca.ear file. See EJBCA User Guide and look in conf/custom.properties for more information about using an ejbca-custom directory. To use your custom OCSP extension you have to define a few properties in conf/ocsp.properties:

  • ocsp.extensionoid - the OID defining your extension.
  • ocsp.extensionclass - the fully qualified class name implementing your extension, i.e. org.ejbca.core.protocol.ocsp.extension.unid.OCSPUnidExtension.
To specify that an extension always be used in the reply regardless of what's specified in the request, preface the relevant ocsp.extensionoid-value with an asterisk (e.g. *2.16.578.1.16.3.2)

Fnr-Unid Mapping Extension

Note
If you don't know what a Unid-Fnr mapping is, you are probably not interested in this part.

The Unid functionality is described in a separate document.

CertHash OCSP Extension

The CertHash functionality is described in a separate document.

Using HTTP GET and RFC5019

For HTTP get requests according to RFC5019 we can set HTTP headers in the response to allow caching proxies to cache responses. By default these properties are set not to allow caching, which is the default behavior. To enable caching in HTTP proxies you can tune a few properties in conf/ocsp.properties or in the an OcspKeyBinding.

  • ocsp.untilNextUpdate - number of seconds a response will be valid. This sets the nextUpdate field in the OCSP response.
  • ocsp.maxAge - how long a response will be cached, in seconds. Should be less than untilNextUpdate. This adds RFC5019 cache headers.

You can also specify different nextUpdate values depending on which certificate profiles the certificate was issued by. This only works when you have published the certificate information using EJBCA 3.9.0 or later, where the certificateProfileId column in the CertificateData table is populated. You can find the certificateProfileId in the AdminGUI.

  • ocsp.<certificateProfileId>.untilNextUpdate - number of seconds a response will be valid for certificates issued with the specified certificate profile.
  • ocsp.<certificateProfileId>.maxAge - how long a response will be cached for certificates issued with the specified certificate profile. Should be less than untilNextUpdate.
If no specific certificateProfileId is specified the default values from ocsp.maxAge and ocsp.untilNextUpdate are used. Properties from an OcspKeyBinding will override the defaults, but never certificateProfileId specific settings.

However, in case of certificate status unknown, EJBCA attempts to avoid the caching of an OSCP GET response by setting the HTTP header "Cache-Control" to "no-cache, must-revalidate" (non-configurable)

OCSP stress testing

Using the EJBCA client toolbox you can easily stress test your CAs and OCSP responders.

To stress test you can first issue a large number of certificates from the CA using the web-service stress test, and after this stress test the OCSP responder with a random selection of all the certificates issued. 

$TOOLBOX_HOME/ejbcaClientToolBox.sh EjbcaWsRaCli stress ...
$TOOLBOX_HOME/ejbcaClientToolBox.sh OCSP stress ...

Monitoring OCSP databases

EJBCA Database CLI contains a tool for monitoring OCSP databases. This tool is stand-alone and based on Java SE JPA that can be configured in 

dist/ejbca-db-cli/META-INF/persistence.xml.

Log4J is used for reporting an can be configured in 

dist/ejbca-db-cli/log4j.xml.

Once built, run the command with 

./run.sh ocspmon

The tool operates using Certificate Profile IDs that are the internal representations of different Certificate Profiles in EJBCA. When you run the tool it will output all the existing IDs in each OCSP. These IDs is also shown in the AdminGUI for each CertificateProfile.

Inconsistencies that will be detected are:

  1. Missing info about certificates in the OCSP database. (ERROR)
  2. Additional info about certificates in the OCSP database. (ERROR)
  3. Info about certificates in the OCSP database that has been tampered with. (ERROR)
  4. If there are any extra certificates profiles in use on the OCSP besides those that we are trying to check. (WARN)
Every detected inconsistency will also be reported in a summarizing final ERROR-message. If there are two many errors, this final message will be truncated.

Since going through every single CertificateData row in a database is heavy work, it's highly recommended to use indexes such as 

create index certificatedata_idx7 on CertificateData(certificateProfileId);

for your both the CA database and each OCSP responder.

Populating the OCSP responder database using a custom implementation

When running the OCSP responder answering queries from CAs in an EJBCA installation, populating the database is easy. Simply use the 'External OCSP Publisher'. Documentation how to configure this is located in the 'OCSP Installation' guide.

When using other CA software than EJBCA you can populate the database based on data from that system. The only thing needed is to insert data in the CertificateData table on the external OCSP responder.

The values used by the OCSP responder are:

  • issuerDN
  • serialNumber
  • status
  • revocationDate
  • revocationReason
  • certificateProfileId

Specification of the fields:

  • issuerDN must be of "EJBCA normalized" form, as returned by org.cesecore.util.CertTools.getIssuerDN(cert).
  • serialNumber is BigInteger.toString().
  • Status is from CertificateDataBean.CERT_REVOKED etc.
  • certificateProfileId can be basically anything and is used if you configure things like 'ocsp.999.untilNextUpdate' in ocsp.properties.

CA certificates and OCSP signer certificates must also be in the database. For these certificates the fingerprint, subjectDN and base64Cert fields must also be included.

Populating the OCSP responder database using the CRL download service

In EJBCA 6.2.0+ you can configure a Service that automatically downloads and populates the mentioned fields from a CRL.

  • Admin GUI -> Certification Authorities -> "Import CA certificate..." for the CA that you want to serve OCSP responses for.
  • Admin GUI -> Certification Authorities -> "Edit CA" for the imported CA -> Configure an external CDP where the CA makes its CRLs available (must begin with "http://")
  • Admin GUI -> Services -> Add a new Service "CRLDownloadService"
  • Admin GUI -> Services -> Edit "CRLDownloadService" ->
    Select Worker: CRL Downloader
    CAs to Check: select the imported CA (or select ANY to process all external X509 CAs with a configured external CDP)
    Ignore nextUpdate and always download the CRL: select this option to force a download of the CRL whenever the service is executed instead of only downloading the CRL when the last known CRL indicates that a new one will be available.
    Maximum allowed size to download (bytes): The Service will refuse to process CRLs that are larger then this limit.
    Period: How often the Service should check if a new CRL needs to be downloaded.
    Active: Check to activate the service.
    Save
The next time the service is executed, there will be log entries showing if the CRL download and processing was successful. After the first execution of the service you should be able to download the CRL from the VA's Public Web pages.

Next step is to setup an OcspKeyBinding as described for the case where direct database publishing is used. The only difference is that there is no way for the VA to know if a certificate has ever been issued, so it makes sense to respond OCSP status "good" for unknown certificates.

If the downloaded CRL from the external CDP contains the Freshest CRL extension, the service will try to download and process any such URL that uses "http" as protocol.

Signature token activation (Upgrades only)

If you are upgrading from an earlier (EJBCA 5.0.x) version of EJBCA, the activation password is required for migrating the OCSP signing key-stores. When activating you are prompted for a password. This password will then be used for all token password not configured.

Activate like this: 

$TOOLBOX_HOME/ejbcaClientToolBox.sh OCSPActivate

After migrating the key-stores and certificates to Crypto Tokens and OcspKeyBindings, you must use the EJB CLI for activating your Crypto Tokens.

Copyright © EJBCA team. EJBCA® is a registered trademark of PrimeKey Solutions AB. All rights reserved.