OCSP User Guide
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:
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
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:
- The client was not authorized to request an Fnr.
- There was no Unid Fnr mapping available.
- 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.
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:
- Missing info about certificates in the OCSP database. (ERROR)
- Additional info about certificates in the OCSP database. (ERROR)
- Info about certificates in the OCSP database that has been tampered with. (ERROR)
- If there are any extra certificates profiles in use on the OCSP besides those that we are trying to check. (WARN)
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.