CRL Generation

Certificates that have been revoked before their expiration date are stored in a Certificate Revocation List (CRL), kept by the CA. The CRL is usually published at a regular interval, for example, every 24 hours. Entities in the network validate issued certificates with the CRL or using an OCSP check every time a certification is used.

The CA administrator can also decide to manually publish a new CRL immediately after a certificate has been revoked.

The following sections cover how to manage CRLs in EJBCA.

A new CA should always issue an (empty) CRL and this is done when the CA is created.
Expired certificates are normally removed from CRLs following RFC 5280. This behavior is configurable using the Keep Expired Certificates on CRL setting, see CA Fields.

Generating a CRL

Manually generate CRL

To create or download a CRL, select the CA Structure & CRLs menu option. The CA Structure & CRLs page displays sections for each CA and sub CA created.

To generate and publish a new CRL immediately, click Create CRL.
To download a CRL, click the Download link at the end of the created CRL.

To generate a CRL using the EJBCA command line interface, run the following command:

BASH

bin/ejbca.sh ca createcrl <CA name>

For more information on how to configure CRL periods, CRL Distribution Points and CRL Issuers, see CA Fields and Managing Certificate Profiles.

Automatically generate CRL

Use one of the following ways to make EJBCA automatically create updated CRLs:

Using the CRL Update Service Worker

In the Admin GUI, go to Edit Services and add a new service. Edit the service and select the CRL Updater worker and the interval to use. Make sure to set the service to Active.

This service checks, at the selected interval, if it is required to regenerate the current CRL (due to being expired or within the expiration threshold), and generates a new CRL if needed.

For more information on the CRL Updater service, see Services.

Generate CRL upon revocation

If this option in the CA CRL settings is checked, the next CRL or delta CRL is generated immediately, see CA FIelds.

Using Unix Cron

CRLs can also be generated by having a cron job or equivalent call bin/ejbca.sh ca createcrl. The createcrl command checks all active CAs and if an update of their CRLs is required.

To force CRL generation for a CA, use bin/ejbca.sh ca createcrl caname.

An example crontab entry:

BASH

PATH=$PATH:/usr/java/jdk1.6.0_24/bin
@daily cd /home/ejbca;/home/ejbca/bin/ejbca.sh ca createcrl;

where /usr/java/jdk1.6.0_24/bin is the path to where java can be found and /home/ejbca is where ejbca is installed.

The following displays a sample crontab to be installed with crontab -e:

BASH

SHELL=/bin/sh
PATH=/usr/local/sbin:/usr/local/bin:/sbin:/bin:/usr/sbin:/usr/bin
CLASSPATH=$CLASSPATH:/root/ejbca
APPSRV_HOME=/usr/local/jboss
#m h dom mon dow command
00 0 * * * cd /root/ejbca;./bin/ejbca.sh ca createcrl

Delta CRLs

EJBCA can issue delta CRLs. In the CA configuration, set Delta CRL Period to the amount of time your delta CRLs will be valid if delta CRLs are issued. The command line interface and CRL Updater Service will generate delta CRLs if Delta CRL Period is larger than 0.

If a certificate is on hold (i.e. revoked with reason code certificateHold) on a base CRL, and then released from hold, it will appear on subsequent delta CRLs with reason code removeFromCRL in accordance with RFC 5280, section 5.2.4. The revocationDate of such a CRL entry will be the date when the certificate was released from hold.

Note that after changing the revocation reason for the previously revoked certificate or certificates, the revocation reason change will not end up in the next Delta CRL if the revocation is backdated beyond the previous full CRL. For more information, see Allow Changing Revocation Reason in CA Fields and Allow Backdated Revocation in Certificate Profile Fields.

CRL Invalidity Date

The CRL Invalidity Date extension provides the date on which it is known or suspected that the private key was compromised or that the certificate otherwise became invalid, see RFC 5280, section 5.3.2.

In EJBCA, the CRL Invalidity Date extension can only be specified using the REST API and it is disabled by default.

To enable CRL Invalidity Date, edit the corresponding CA and enable the CA setting Allow invalidity date. For more information, see Allow invalidity date in CA Fields.

To specify the invalidity date, use the REST endpoint /v1/certificate/.../revoke parameter invalidity_date. The following displays an example using cURL:

BASH

curl -X PUT "https://localhost:8443/ejbca/ejbca-rest-api/v1/certificate/CN%3DManagementCA/1234abcd/revoke?invalidity_date=2023-02-01T15%3A49%3A37Z" -H  "accept: application/json"

Retrieving CRLs

EJBCA stores all generated CRLs, unless you manually remove them from the database.

You can retrieve CRLs (either the latest CRL or a CRL with a specific CRL number) using the command line interface or the RA Web:

To retrieve CRLs using the command line interface:

CODE

bin/ejbca.sh ca getcrl --help

To retrieve CRLs using the RA Web, select RA Web>CA Certificates and CRLs and use the additional parameter crlnumber=<crl number>.

CRL Generation Efficiency

In order to generate a CRL, index the following database queries to be efficient:

CODE

SELECT MAX(a.crlNumber) FROM CRLData a WHERE a.issuerDN=:issuerDN AND a.deltaCRLIndicator=-1 (or >0)
SELECT a FROM CRLData a WHERE a.issuerDN=:issuerDN AND a.crlNumber=:crlNumber
SELECT a FROM CerttificateData a WHERE a.issuerDN=:issuerDN AND a.status=:status
SELECT a FROM NoConflictCertificateData a WHERE a.issuerDN=:issuerDN AND a.status=:status

Ensuring that these queries are efficient over time, with a growing database, implies adding indexes to your database, as laid out on the file doc/sql-scripts/create-index-ejbca.sql. In particular:

crldata_idx3
crldata_idx4
certificatedata_idx6

Large CRLs

It is not possible to name a maximum size of CRLs, since this depends on the system used and that there are users generating CRLs with millions of entries. In general, generating large CRLs requires:

Good database indexes to look up all revoked certificates.
Enough RAM allocated to JBoss to construct the CRL.
Depending on exactly how large it is, some timeout tweaking may be needed as well, if it takes a long time to generate CRLs.
Database tuning may be needed to run very large queries and for storing the resulting CRL, that can be hundreds of MB, in the database (an example is the max_allowed_packet setting in MariaDB/MySQL).

To generate really large CRLs, you can use a dedicated node for CRL generation to not affect issuance nodes while a large CRL is being generated.

To test large CRLs, you can use the clientToolBox Web Service stress test Revoke mode to revoke certificates issued, allowing you to quickly generate hundreds of thousands of revoked certificates. The revoked certificates can be issued from a dedicated test CA, enabling the database to be cleaned easily (although backup/restore before and after the test is most effective). The test allows you to generate a hundred thousand entries first, create a CRL, then generate 2 hundred, 5 hundred, 1 million and at the same time keep an overview of how the time to generate the CRL increases and the size of the generated CRL.

To view command usage instructions, run:

CODE

./ejbcaClientToolBox.sh EjbcaWsRaCli stress

If run with the mode REVOKE, certificates will be issued and then revoked, producing revoked certificate entries that will be on the next CRL generated.