OCSP Responder Management
The following covers all aspects of managing an OCSP Responder, whether situated locally on the same machine as the CA or remotely on a VA.
For an in-depth description of how EJBCA handles OCSP, see the OCSP Overview. For more information about OCSP Responders, see the OCSP Responder Overview.
Building and Configuring the OCSP Responder
Using the UI on a Remote VA
The OCSP responder has the same UI as the CA, so you can manage all your Crypto Tokens and Key Bindings using the CA UI (or the CLI see below).
In an OCSP responder, you normally only use a few functions of the CA UI, although all of them are available. The important functions for an OCSP responder are:
Crypto Tokens
Internal Key Bindings
Prerequisites for CA UI access:
Available TLS keystores as p12/tomcat.jks and p12/truststore.jks (copies from the EJBCA CA), to be deployed with deploy-keystore and web-configure (may require configuration of keystore password in conf/web.properties).
An imported Management CA certificate (the certificate of the CA that issues administrator certificates).
Configured Administrators with access rules.
If you only want to set up a super administrator, the initial super administrator access rule is automatically set up during the initial startup (see database tables AdminGroupData and AccessRulesData). You can run the following commands to import a Management CA certificate and add a SuperAdmin, that has a certificate with "CN=SuperAdmin" issued from this CA (this will create a record in the database table AdminEntityData).
bin/ejbca.sh ca importcacert ManagementCA /home/user/adminca1.pembin/ejbca.sh roles addmember "Super Administrator Role" ManagementCA WITH_COMMONNAME TYPE_EQUALCASE SuperAdminIf you do not want to import the administrator certificate into EJBCA, you can configure web.reqcertindb=false in conf/web.properties.
Otherwise, the administrator certificate must be present in the database (can be imported using the CLI).
Setting up the OCSP Responder Keys
If working on a remote VA, make sure to import the CA that is meant to be the OCSP responder from the EJBCA CA.
The keys used to sign the OCSP response are referenced through Crypto Tokens (that could be either soft or HSM/PKCS#11 based). There should be one key for each CA, and one OCSP signing certificate must be issued from each CA the responder answers for.
The certificate profile could be the same for all issued OCSP signing certificates.
To issue an OCSP signer certificate from EJBCA, define a new certificate profile and clone the built-in certificate profile 'OCSPSIGNER'. This certificate profile is like a normal profile, with the following key usages:
- Key Usage: Digital Signature- Extended Key Usage: OCSPSignerConfigure the newly created certificate profile to use the OCSP publisher defined above. You also need to create a new End Entity Profile to use the new Certificate Profile. You should then create a user for each CA using this certificate profile. Use the token type User generated.
The OCSP responders certificate(s) AND the CA certificate(s) need to be published from the CA to the OCSP responder. For the CA you do this by setting the CRL publisher to the OCSP publisher.
Populating the OCSP Database on a Remote VA
By design, a standalone VA is designed to be stateful as a connection to the CA can't be presumed, and such a connection can't be relied upon to be constant. For that reason the VA's database is populated with certificate information, allowing it to function independently of the CA. This can be done in several ways. While we strongly recommend using the EJBCA Peer Publisher as the most secure and easy way, we provide options for populating the VA from a CRL produced by a non-EJBCA CA, or producing your own custom publisher and writing straight to the EJBCA database as well.
Using a Publisher on the CA
We currently provide two publishers, the EJBCA Peer Publisher which publishes certificates synchronously over TLS, and the Legacy VA Publisher which uses direct database publishing.
Using the EJBCA Peer Publisher
ENTERPRISE This is an EJBCA Enterprise feature.
Follow the steps to set up a new OCSP Signer using an EJBCA Peer System:
These instructions assume that there already is a Peer System connecting the CA and the VA machines, that the connection is already tested, and that there is already a remote identity representing the CA among the "Incoming Connections" in the VA's Peer Systems. For information on setting up Peer Systems, see Peer Systems.
Go to the CA UI of the VA → Crypto Tokens and create a new Crypto Token (unless you want to reuse an existing).
Go to the CA UI of the VA → Crypto Tokens → Your created Crypto Token and generate a new key pair.
Go to the CA UI of the VA → OCSP Responders and create a new OCSP Responder that references the Crypto Token and key pair.
Go to the CA UI of the VA → Peer Systems → Click on Modify Role for the peer connector representing the CA and set access rules for the newly created OCSP Responder ("view only" or "Renew certificate").
Go to the Ra UI of the CA → Enroll → Make new request, create an End Entity (use "Postpone" option for "Key-pair generation") for issuing the OCSP signing certificate (use an OCSP Signer certificate profile).
Go to the CA UI of the CA → Peer Systems → Click Manage for the peer connector representing the VA → Remote Key Bindings, fill in the credentials for the OCSP signing End Entity in the newly created OCSP Responder and click Issue Signing Certificate.
Go to the CA UI of the VA> OCSP Responders and verify that the OCSP key binding has a certificate and has been activated.
Using the Legacy VA Publisher
ENTERPRISE This is an EJBCA Enterprise feature.
Follow the steps to set up a new OCSP Signer using a VA Publisher:
Go to the CA UI of the VA → Crypto Tokens and create a new Crypto Token (unless you want to reuse an existing).
Go to the CA UI of the VA → Crypto Tokens → Your created Crypto Token and generate a new key pair.
Go to the CA UI of the VA → OCSP Responders and create a new OCSP Responder the references the Crypto Token and key pair.
Go to the CA UI of the VA → Internal Key Bindings and create a Certificate Signing Request for your new OCSP Responder. Save this file.
Go to the RA Web of CA → Enroll → Use Username → Use the credentials for issuing an OCSP signing certificate and upload the CSR.
...(CA publishes new OCSP signing certificate to the VA instance)...
Go to the CA UI of the VA → Internal Key Bindings and click Update for your new OCSP Responder. This will find the published certificate by matching the key pair with the certificate.
Go to the CA UI of the VA → Internal Key Bindings and click Enable for your new OCSP Responder to start processing OCSP responses with it.
Using the CRL Download Service
To configure a Service that automatically downloads and populates the mentioned fields from a CRL, do the following:
Select CA UI → Certification Authorities → Import CA certificate for the CA that you want to serve OCSP responses for.
Select CA UI → Certification Authorities → Edit CA for the imported CA → Configure an external CDP where the CA makes its CRLs available (must begin with "http://").
Select CA UI → Services and Add a new Service "CRLDownloadService".
Select CA UI → Services and 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 than this limit.
Period: How often the Service should check if a new CRL needs to be downloaded.
Active: Select to activate the service.
The next time the service is executed, there will be log entries showing if the CRL download and processing were successful. After the first execution of the service, you should be able to download the CRL from the VA's RA Web pages.
Next, set up an OCSP Responder ing 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.
Using a Custom Implementation
When running the OCSP responder answering queries from CAs in an EJBCA installation, populate the database using the External OCSP Publisher. For more information, see Building and Configuring the OCSP Responder.
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:
|
Field |
Description |
|
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. |
|
revocationDate |
Date (in milliseconds since epoch) that the certificate was revoked on. Or 0 by default if not revoked. |
|
revocationReason |
Revocation reason. If from RevokedCertInfo.NOT_REVOKED etc. |
|
certificateProfileId |
Used if you configure things like ocsp.999.untilNextUpdate in ocsp.properties. |
|
expireDate |
Date (in milliseconds since epoch) that the certificate expires. |
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.
Setting the Default Responder
The default responder is the valid CA or OCSP Responder set to sign responses to requests that come in for unknown issuers.
Setting the Default Responder from the GUI
You can choose the default responder from the list menu in the OCSP Responder page in the GUI, which will show all valid CAs and responders. It will also provide the option to choose none and allow retaining an old but unmatched value imported via migration from configurations earlier than version 6.2.4
Setting the Default Responder from the CLI
The default responder can also be chosen from the CLI with the following command.
bin/ejbca.sh ocsp setdefaultresponder <DN>To see a list of valid responders, run the command with the --help switch. This will also show the currently chosen responder.
Setting Responder ID Type for CAs
Local CA's will automatically answer OCSP responses for themselves unless an OCSP Responder has been set up for them. This setting defines the general responder ID type for CA's acting as their own responders. Just like for an OCSP Responder, the responder ID type is either a Name (SubjectDN of the signing certificate used for response) or Keyhash (SHA-1 digest of the public key of the signing certificate used for response).
Enable OCSP Signing Cache Update
Controls if the OCSP signing cache update is enabled or not. The default is that the cache update is disabled (Enable OCSP signing cache update is cleared).
Prior to EJBCA 7.4.1, the cache update was enabled by default, and searching for missing entries for unknown CAs in the cache was always performed. Note that it only comes to effect when new CAs are created or already existing CAs are renewed. If the old behavior is needed, the Enable OCSP signing cache update option must be selected to enable OCSP signing cache update.
Enable OCSP Cache Headers for Unauthorized Responses
By default, responses with the status Unauthorized do not include any cache headers. By enabling this option, unauthorized responses will contain a no-cache header.
Checking the Status of the OCSP Responder using the EJBCA Client Toolbox
Verification of a running responder can be done using the EJBCA Client Toolbox.
To list all available OCSP commands, run the following:
$TOOLBOX_HOME/ejbcaClientToolBox.sh OCSPUsing 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 OCSP Responder.
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 CA UI.
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 OCSP Responder will override the defaults, but never certificateProfileId specific settings.
However, in case of certificate status unknown, EJBCA attempts to avoid the caching of an OCSP GET response by setting the HTTP header "Cache-Control" to "no-cache, must-revalidate" (non-configurable).
OCSP Stress Testing
You can stress test your CAs and OCSP responders using the EJBCA Client Toolbox.
To stress test, issue a large number of certificates from the CA using the web-service stress test, and then 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 standalone tool for monitoring OCSP databases. The tool is based on Java SE JPA and can be configured in:
dist/ejbca-db-cli/META-INF/persistence.xml.Log4J is used for reporting and can be configured in:
dist/ejbca-db-cli/log4j.xml.Once built, run the command with:
./run.sh ocspmonThe tool operates using Certificate Profile IDs that are the internal representations of different Certificate Profiles in EJBCA. When running the tool, it outputs all the existing IDs in each OCSP. These IDs are also shown in the CA UI for each CertificateProfile.
The following inconsistencies are detected:
Missing information about certificates in the OCSP database. (ERROR)
Additional information about certificates in the OCSP database. (ERROR)
Information about certificates in the OCSP database that has been tampered with. (ERROR)
If there are any extra certificate profiles in use on the OCSP besides those being checked. (WARN)
Every detected inconsistency will also be reported in a summarizing final ERROR message and if there are too many errors, this final message will be truncated.
Instead of going through every single CertificateData row in a database, it is recommended to use indexes like the following example for both the CA database and each OCSP responder:
create index certificatedata_idx7 on CertificateData(certificateProfileId);Signature Token Activation (Upgrades only)
If you are upgrading from an earlier EJBCA 5.0.x version, the activation password is required for migrating the OCSP signing key-stores. When activating you are prompted for a password and this password will then be used for all token passwords not configured.
To activate:
$TOOLBOX_HOME/ejbcaClientToolBox.sh OCSPActivateAfter migrating the key-stores and certificates to Crypto Tokens and OCSP Responders, you must use the EJB CLI for activating your Crypto Tokens.
Example: Set up a Responder
For instructions on how to set up a responder using the command line interface, see Setting up a Responder Using the CLI.