Software Requirements[edit]

In order to publish the CRL's from an EJBCA CA server onto a web server, standard OpenSSH client and server SSH implementations will be used, coupled with some shell-scripting.

The OpenSSH server will be required on the web server side, while the OpenSSH client will be required on the client side. Chances are that both will be already available in both cases.

If not, the OpenSSH server can be installed under Debian with:

? root
$ apt-get install openssh-server

The OpenSSH client can be installed under Debian with:

? root
$ apt-get install openssh-client

Setting-up User Accounts[edit]

A separate account will be created on web server for the purpose of publishing the CRL's to it. On the CA server it will be necessary to use the ejbca user account which is also running the EJBCA JBoss AS instance.

Create a separate user on the web server:

? root
$ adduser --disabled-password crl

You can provide any information when the script asks you about name etc. An informal name would be a good idea (specifying the purpose of user account).

Prepare the necessary directories on the web server for the crl user:

? crl
$ mkdir ~/.ssh/
$ touch ~/.ssh/authorized_keys

Create an RSA ssh key on the CA server (the key 'must not' be protected by the password):

? ejbca
$ ssh-keygen -b 4096 -N * -f ~/.ssh/id_rsa

The corresponding public key on the CA server will be located in location:

# /home/ejbca/.ssh/id_rsa.pub

Copy the contents of public key file (there should be a single line) to the following file on the crl.example.com server:

# /home/crl/.ssh/authorized_keys

Log-in at least once as the ejbca user to the crl.example.com in order to have the host added to the list of known hosts:

? ejbca
$ ssh crl@crl.example.com date

This will also verify that your key is working as expected.

Setting-up Synchronisation Script[edit]

EJBCA supports several types of CRL publishers. Additional publishers can be written either as an extension to EJBCA, or as an external program. External program usage will be covered within this section.

The only requirement for the external program is that it accepts a single argument which represents a path to a temporary file containing the CRL in DER encoding. Selection of programming or scripting language in which the publisher program is implemented is entirely left to the system administrator deploying the system.

Attached to this page you should find a script called crlpublisher.sh which uses a number of configuration files for achieving the publication of CRL's to desired locations. The script is meant to allow future extensions in terms of using different publisher types (currently the only supported publisher type is scp).

Copy the provided script to the following location on the CA server:

# /usr/local/bin/crlpublisher.sh

Set-up the file permissions:

? root
$ chown root.ejbca /usr/local/bin/crlpublisher.sh
$ chmod 750 /usr/local/bin/crlpublisher.sh

Create the necessary directory for the configuration:

? root
$ mkdir /etc/crlpublisher/

Set-up a configuration file for the Example Root CA CRL publisher:

# /etc/crlpublisher/examplerootca.conf
----BEGIN----
publisher=scp
remoteUser=crl
remoteHost="crl.example.com"
remoteLocation="/var/www/crl.example.com/rootca.crl"
privateKey="/home/ejbca/.ssh/id_rsa"
issuerDn="CN=Example Root CA,O=Example Inc.,C=RS"
-----END-----

Set-up a configuration file for the Example Server CA CRL publisher:

# /etc/crlpublisher/exampleserverca.conf
----BEGIN----
publisher=scp
remoteUser=crl
remoteHost="crl.example.com"
remoteLocation="/var/www/crl.example.com/serverca.crl"
privateKey="/home/ejbca/.ssh/id_rsa"
issuerDn="CN=Example Server CA,O=Example Inc.,C=RS"
-----END-----

Set-up a configuration file for the Example Person CA CRL publisher:

# /etc/crlpublisher/examplepersonca.conf
----BEGIN----
publisher=scp
remoteUser=crl
remoteHost="crl.example.com"
remoteLocation="/var/www/crl.example.com/personca.crl"
privateKey="/home/ejbca/.ssh/id_rsa"
issuerDn="CN=Example Person CA,O=Example Inc.,C=RS"
-----END-----

Set-up the file permissions:

? root
$ chown -R root.ejbca /etc/crlpublisher/
$ chmod 750 /etc/crlpublisher/
$ chmod 640 /etc/crlpublisher/*

Setting-up Directory for Storing CRL's[edit]

In the end, the CRL's will need to be stored somewhere. The location should be readable by the web server used for serving them over the HTTP.

Create the directory for storing the CRL's on the crl.example.com server (if you haven't done so before):

? root
$ mkdir -p /var/www/crl.example.com/
$ chown crl.crl /var/www/crl.example.com/
$ chmod 755 /var/www/crl.example.com/

Configuring EJBCA CRL Publisher[edit]

With everything else set in place, it's time to set-up the CRL publisher on the EJBCA itself. Go to the Administration -> Edit Publishers page. Enter CRL Publisher in the text box, and click on the Add button. Select the newly-created publisher from the list, and click on the Edit Publisher button. Make the following changes:

Publisher Type: Custom Publisher
Class Path: org.ejbca.core.model.ca.publisher.GeneralPurposeCustomPublisher
Properties of Custom Publisher: crl.application /usr/local/bin/crlpublisher.sh
                                crl.failOnStandardError false
                                crl.failOnErrorCode true
Description: Publishes a CRL list to the target CRL distribution point using the crlpublisher.sh script.

Click on the Save and Test Connection button to apply the changes and test the connection (this won't do anything, actually).

What's left is to activate the CRL publisher for each certification authority that was created. Go to the Administration -> Edit Certificate Authorities and select the Example Root CA from the list. Click on the Edit CA button, and make the following change:

Publishers: CRL Publisher

Click on the Save button to apply the change. Repeat the procedure for Example Person CA and Example Server CA as well.

Now we should have the Publish Queue Process Service take care of the CRL publisher. Go to the Administration -> Edit Services page and select the Publish Queue Process Service from the list. Click on the Edit Service button. Make sure to mark the CRL Publisher in the Publishers to check list (in addition to any of the already selected publishers). Click on the Save button to apply the changes.

In the end it might be convenient to republish the CRL's straight away. This can be done either from the Administration -> Basic Functions page, clicking on every Create CRL button except the one for the temporary CA, or, through the command line on the ca.example.com server:

? ejbca
$ cd /opt/ejbca/bin/
$ ./ejbca.sh ca createcrl 'Example Root CA'
$ ./ejbca.sh ca createcrl 'Example Person CA'
$ ./ejbca.sh ca createcrl 'Example Server CA'

The important thing to note here is that during the installation and configuration of the CA itself we had already configured the publishing of CRL's every five minutes (through the CRL Updater service). Each time there is a change in CRL's (for example due to expired CRL, or due to revoked certificate), a new CRL gets issued, and it automatically gets published to the crl.example.com server.

Finally you can verify that the CRL's are available and accessible by downloading them from the following URL's:

@ http://crl.example.com/personca.crl
@ http://crl.example.com/rootca.crl
@ http://crl.example.com/serverca.crl

Troubleshooting[edit]

Can I use crlpublisher.sh for publishing certificates to local directory?

No, for this purpose you would need to write another, custom script. You might find it useful to use crlpublisher.sh to get some ideas on how to do it, though.

How can I test my SSH connection outside of JBoss/EJBCA?

Try running the following command as ejbca user on the CA server:

ssh -i ~/.ssh/id_rsa crl@crl.example.com date

Also, make sure that the privateKey is set correctly in all configuration files under the /etc/crlpublisher/ directory and that you can read all the configuration files as ejbca user.

Can I publish delta CRLs using crlpublisher.sh?

No, the script is not able to publish delta CRLs. You could create your own or extend the crlpublisher.sh to be able to handle delta CRLs.

Can I manually test if the crlpublisher.sh script is properly configured outside of JBoss/EJBCA?

You should be able to do this by running the following command as ejbca user on the CA server (make sure to specify correct path to CRL that you downloaded to a local file):

crlpublisher.sh /path/to/crl/file

If you are facing issues, most likely you have not specified the issuer DN correctly in one of the /etc/crlpublisher/ configuration files.

How can I determine issuer DN for the crlpublisher.sh configuration file?

You should be able to obtain the issuer DN in correct format with command:

openssl x509 -subject -noout -in ca_certificate.pem | sed -e "s#subject= /##;s#/#,#g"

Where does the crlpublisher.sh read the CRL from during publishing?

When EJBCA generates a CRL and needs to call crlpublisher.sh, it will output the generated CRL to a temporary file, and pass path to this file to the crlpublisher.sh script.