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

Control tool

All control of a running responder is done with the EJBCA client toolbox. See EJBCA client toolbox for instructions how to build and use the client toolbox.

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

Signature token activation

If passwords are not configured for the tokens of the keys then you got to activate your responder. 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

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.

Multiple responder and CA certificates

The OCSP responder can have many responder certificates, each issued by one CA. 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, meaning that the OCSP protocol, and the responder, can handle key rollover on the CA without issues.

Using the API

The best way to learn the API is by looking at the source code, since it is included. The client API is 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.

Fnr-Unid mapping

For the Unid Lookup part, you must use https with a client certificate with the ocsp client. If you use http with a client certificate and the OCSP responder is set up to answer Lookup requests, the OCSP client will returns the Fnr. The Fnr will be returned if the certificate contains a Unid in the SN component of the SubjectDN, and the Unid has a valid mapping to an Fnr in the OCSP responders Fnr-Unid mapping database.

If the Fnr returned is null, there are several possible errors:

  1. The client was not authorized to request an Fnr.
  2. There was no Unid Fnr mapping available.
  3. There was no Unid in the certificate (serialNumber DN component).

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.OCSPUnidExtension.

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.

  • 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 using EJBCA 3.9.0 or later, where the certificateProfileId column in the CertificateData table is populated. You can find the certificateProfileId in the admin GUI.

  • 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.

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 webservice 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 ClientToolBox contains a tool for monitoring OCSP databases. This tool is stand-alone and based on Java SE JPA that can be configured in 

clientToolBox-dist/properties/META-INF/persistence.xml.

Log4J is used for reporting an can be configured in 

clientToolBox-dist/properties/log4j.xml.

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 Admin GUI 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

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.ejbca.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.

Copyright © 2001-2009 EJBCA team. All rights reserved.