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:
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.
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 as defined in RFC 2560 is not used.
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 request, meaning that the OCSP protocol, and the responder, can handle key roll-over 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
The Unid functionality is described in a separate document.
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 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 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
dist/clientToolBox/properties/META-INF/persistence.xml.
Log4J is used for reporting an can be configured in
dist/clientToolBox/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.
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.