For the purpose of running the EJBCA as an OCSP responder, several software requirements need to be met. For the sake of this guide the EJBCA will be used coupled with MySQL database server and JBoss AS JEE5 application server. It will also be necessary to install the JDK on the target server.
The version of JBoss AS used in this guide is 5.1.0.GA. The version of EJBCA used is 4.0.5. The rest of the components come from the native package manager.
Since both the EJBCA and JBoss AS are distributed in form of a zip archive, it will also be necessary to install the unzip utility (by default it doesn't come with Debian Squeeze network installation):
? root
$ apt-get install unzip
Practically any proper JDK should suffice for the use with JBoss AS and EJBCA (although Oracle's JDK might yield some additional configuration steps which are not covered in this guide). Debian Squeeze comes with the OpenJDK package available in default repositories, which can be installed with (take notice that installing just the JRE is not sufficient):
? root
$ apt-get install openjdk-6-jdk
Additionally, it will also be necessary to install the Apache Ant build tool (which will be used for building the EJBCA):
? root
$ apt-get install ant
Since the EJBCA will be using MySQL JDBC connectors, it's also necessary to install the following package:
? root
$ apt-get install libmysql-java
Before proceeding with the installation of the actual OCSP, it is necessary to create two new certificate profiles, one for the OCSP responder, and one for the MySQL servers (since OCSP's database will be accessed from the CA, SSL will be used for increasing the security by at least providing encryption of traffic). The reason why MySQL servers need a separate certificate profile is due to issues with MySQL's SSL implementation when using the SHA256WithRSA signature algorithm. This problem is present at least in the MySQL server version 5.1 from Debian Squeeze.
Log-in onto EJBCA, and go to the Administration -> Edit Certificate Profiles page. Click on the Example Server certificate profile, provide the name Example MySQL Server in the text box, and click on the Use selected as template button. Afterwards select the newly-created Example MySQL Server profile from the list, and click on the Edit Certificate Profile button. Make the following change:
Signature Algorithm: SHA1WithRSA
The rest of the options should remain the same. Click on the Save button.
Select the Example Server certificate profile again, enter Example OCSP Signer in the text box, and click on the Use selected as template button. Select the newly-created certificate profile, and click on the Edit Certificate Profile button. Make the following changes:
Key Usage: Digital Signature
Extended Key Usage: OCSP Signer
Available CAs: Example Person CA, Example Server CA
Click on the Save button once the changes have been made.
In addition to certificate profiles, end entity profiles need to be updated as well. A separate end entity profile will be created for the OCSP responder as well.
First of all, update the Server end entity profile. Go to the Administration -> Edit End Entity Profiles page, select the Server profile, and click on the Edit End Entity Profile. Make the following change:
Available Certificate Profiles: Example MySQL Server, Example Server
Click on the Save button to apply the changes.
Create a separate end entity profile for the OCSP signers by going to the Administration -> Edit End Entity Profiles page, selecting the Server profile, entering OCSP Signer and clicking on the Use selected as template. Select the newly-created end entity profile and click on the Edit End Entity Profile button. Make the following changes:
Default Certificate Profile: Example OCSP Signer
Available Certificate Profiles: Example OCSP Signer
Available CAs: Example Root CA, Example Person CA, Example Server CA
Default Token: P12 file
Click on the Save button once the changes have been made.
Installation of the MySQL server on top of Debian Squeeze is a pretty much straightforward step, and it can be done with a simple:
? root
$ apt-get install mysql-server
It's a very good idea to make MySQL use UTF-8 all the time. This can save a lot of trouble if you end-up using non-latin characters in the database.
# /etc/mysql/conf.d/utf-8.cnf
----BEGIN----
[client]
default-character-set=utf8
[mysqld]
default-character-set=utf8
default-collation=utf8_unicode_ci
character-set-server=utf8
init-connect='SET NAMES utf8'
character-set-client = utf8
-----END-----
After this you need to restart the MySQL server to apply the changes:
? root
$ service mysql restart
MySQL doesn't employ any type of protection mechanism of data being transmitted over the network. While this is a tolerable insecurity in cases where the applications are accessing the database directly on the localhost, it tends to be unacceptable when connections are made from non-local network interface, especially in context of storing the required data for the OCSP responder. If the attacker was able to sniff the traffic in any way, he'd be able to obtain MySQL username, password, as well as insert invalid data in the OCSP responder, rendering it useless for verification purposes.
Luckily, MySQL supports use of X.509 certificates for both data encryption and server/client authentication and authorisation. Unfortunately, since EJBCA is not capable of using client-side certificates for authentication, we will fall back to using the SSL for data encryption and server verification.
Go to the Administration -> Add End Entity page and provide the following information:
End Entity Profile: Server
Username: ocsp.example.com_mysql
Password: {{ocsp_mysqlentity_pass}}
Confirm password: {{ocsp_mysqlentity_pass}}
E-mail address: ocsp@example.com
CN, Common name: Example OCSP MySQL Server
O, Organization: Example Inc.
C, Country (ISO 3166): RS
DNS Name: ocsp.example.com
Certificate Profile: Example MySQL Server
CA: Example Server CA
Token: PEM file
Replace the ocsp_mysqlentity_pass with desired password. Once the information is filled-in, click on the Add button. Now proceed to the Public Web -> Create Keystore page (it is highly recommended to access the page through the https and not through the http protocol) and provide the following information in the form:
Username: ocsp.example.com_mysql
Password: {{ocsp_mysqlentity_pass}}
Click on the Ok button. On the next screen select Key Length of 4096 bits and click on the Ok button. Wait until the private key and certificate get generated (it can take a while), then save the resulting PEM file in a convenient location. The resulting PEM file needs to be split into two files (this can be done on any client station with openssl utility available on it).
The first file, to which we'll refer to as key.pem needs to contain only the private key. The second file, cert.pem needs to contain only the end entity certificate (of the MySQL server itself). You can perform this split with any text editor of your choice. In addition, due to a weird feature/bug of MySQL, it is also necessary to convert the EJBCA-provided private key into different format with the following command:
$ openssl rsa -in original_key.pem -out key.pem
The resulting two files should be put in the following locations:
# /etc/mysql/cert.pem
# /etc/mysql/key.pem
In order for private key and certificate to be accessible, it is also necessary to set-up the file permissions:
? root
$ chown root.mysql /etc/mysql/key.pem
$ chown root.mysql /etc/mysql/cert.pem
$ chmod 640 /etc/mysql/key.pem
$ chmod 640 /etc/mysql/cert.pem
The next thing that needs to be done is to set-up the MySQL server to actually use the certificate. This can be done by creating the following configuration file:
# /etc/mysql/conf.d/ssl.cnf
----BEGIN----
[mysqld]
ssl-cert = /etc/mysql/cert.pem
ssl-key = /etc/mysql/key.pem
-----END-----
The OCSP responder will require a single database to store its data, as well as two users for updating the database. One user will be utilised on the local OCSP server by the local instance of EJBCA, while the other user is meant to be used for the CA performing the updates over the network. Create the database and grant appropriate privileges with:
? root
mysql> create database ocsp;
mysql> grant all privileges on ocsp.* to 'ocsp'@'localhost' identified by '{{ocsp_mysql_password}}';
mysql> grant all privileges on ocsp.* to 'ejbca'@'ca.example.com' identified by '{{ejbca_mysql_password}}' require ssl;
mysql> flush privileges;
Parmater ocsp_mysql_password should be replaced by the desired password for the local ocsp user. Parameter ejbca_mysql_password should be replaced by the desired password for the ejbca user which will be connecting from the certification authority server.
The final step includes setting-up the MySQL server to listen on all of the network interfaces. Create the following configuration file which will override the default settings:
# /etc/mysql/conf.d/bind.cnf
----BEGIN----
[mysqld]
bind-address = 0.0.0.0
-----END-----
Restart the MySQL server:
? root
$ service mysql restart
In order to increase the security of the system, two system accounts will be used for deployment of JBoss AS and EJBCA. The first account will be used in order to restrict the access to JBoss AS shared files and directories, while the second one will be used for running the JBoss AS instance on top of which EJBCA will be running.
Create the necessary accounts for JBoss AS and EJBCA
? root
$ adduser --system --shell /bin/bash --group jboss
$ adduser --system --shell /bin/bash --group ejbca
$ usermod -a -G jboss ejbca
This kind of separation will allow for shared JBoss AS files to be owned by the jboss user and jboss group, and with proper mask it will be possible to grant the ejbca user, which will be running the JBoss AS instance with EJBCA on top of it, sufficient privileges to access those shared files.
Unpack the JBoss AS and set-up the file permissions:
? root
$ unzip ~/packages/bin/jboss-5.1.0.GA.zip -d /opt/
$ chown -R jboss.jboss /opt/jboss-5.1.0.GA
$ chmod -R o= /opt/jboss-5.1.0.GA
When it's necessary to upgrade a system, it is often convenient when it's not required to change any of the installation paths. In order to achieve this with the EJBCA deployment, a symbolic link should be created to point at the currently active installation of JBoss AS:
? root
$ cd /opt/
$ ln -s jboss-5.1.0.GA jboss
Starting-up the EJBCA automatically during boot is a necessity in most environments. To achieve this a custom init script has been provided attached to this guide ( ). The script itself is basically a rewrite of the JBoss-provided run.sh script. The script should be copied over into location:
# /etc/init.d/ocsp
Set-up the file permissions for the init script:
? root
$ chown root.root /etc/init.d/ocsp
$ chmod 755 /etc/init.d/ocsp
Change the init script so that it provides the EJBCA service:
# /etc/init.d/ocsp
----BEGIN----p
--- # Provides: jboss
+++ # Provides: ocsp
-----END-----p
The script itself relies on having a separate configuration directory within the /etc tree. Set-up the configuration directory for JBoss AS instances with the following commands:
? root
$ mkdir /etc/jboss
$ chmod 750 /etc/jboss
Create a configuration file for the EJBCA JBoss AS instance (if you're interested, take a look at the attached file for details on what the parameters do and what parameters are available):
# /etc/jboss/ocsp.conf
----BEGIN----
user=ejbca
group=ejbca
javaHome=/usr/lib/jvm/java-6-openjdk/
javaOpts=(-XX:PermSize=96m -XX:MaxPermSize=128m -Xms128m -Xmx512m -Dsun.rmi.dgc.client.gcInterval=3600000 -Dsun.rmi.dgc.server.gcInterval=3600000)
jbossHome=/opt/jboss
jbossConf=ejbca
jbossBind=0.0.0.0
jbossClasspath=/usr/share/java/mysql.jar
-----END-----
Set-up the configuration file permissions:
? root
$ chmod 640 /etc/jboss/ocsp.conf
With JBoss AS it's possible to create multiple configurations which allow you to deploy different applications in each one of them. The configuration is selected during start-up. In order to differentiate the EJBCA configuration from the stock configurations, we will create a new one based on the default configuration:
? root
$ cd /opt/jboss/server/
$ cp -pr default ejbca
$ chown -R ejbca.ejbca ejbca
Finally, it's useful to take some security precautions with JBoss AS instance used for EJBCA by removing the unnecessary applications from its configuration. This can be done with:
? ejbca
$ rm -rf /opt/jboss/server/ejbca/deploy/ROOT.war/
$ rm -rf /opt/jboss/server/ejbca/deploy/jmx-console.war/
$ rm -rf /opt/jboss/server/ejbca/deploy/management/
If you do not require the administration console, you can also remove it with:
$ ejbca
$ rm -rf /opt/jboss/server/ejbca/deploy/admin-console.war/
If you do not remove the administration console, at least make sure you have properly secured it. Some of the techniques which can be used for securing the JBoss AS can be found on the Securing JBoss wiki page. This includes alternatives to removing the above applications.
By default the JBoss AS instance will be listening on port 8080 providing HTTP protocol. The standard port for this protocol is 80, but the unprivileged user which will be running the JBoss AS EJBCA instance cannot bind to ports lower than 1024. There's several ways to solve this problem, but as a convenient way to do so, a simple redirect of port 80 to port 8080 can be performed instead.
This can be done with the following iptables rule:
-t nat -A PREROUTING -p tcp -m tcp --dport 80 -j REDIRECT --to-ports 8080
This rule should be set-up to be loaded automatically upon each boot.
An alternative (and probably a saner approach) would be to use the Apache HTTP server to this purpose usind mod_jk. For the time being this type of configuration falls outside of scope of this guide.
Unpack the EJBCA installation files and set-up their permissions:
? root
$ unzip ~/packages/src/ejbca_4_0_5.zip -d /opt/
$ chown -R ejbca.ejbca /opt/ejbca_4_0_5/
$ chmod -R o= /opt/ejbca_4_0_5/
The same way as with JBoss AS, it is useful to have a more constant path to EJBCA, while still preserving the information about what version it is. To this end a symbolic link will be set-up in a similar way:
? root
$ cd /opt/
$ ln -s ejbca_4_0_5 ejbca
It is now necessary to set-up the configuration files for the EJBCA. The configuration file samples, with plenty of comments describing various options, can be found within the /opt/ejbca/conf/ directory. The sample configuration files are ending with sample. The configuration files described here will be relatively simple, but sufficient for test deployments.
First of all, set-up the EJBCA's main configuration file by populating it with the following options (short comments provided as a basic explanation):
# /opt/ejbca/conf/ejbca.properties
----BEGIN----
# Specify the root directory of the application server that's being used.
appserver.home=/opt/jboss
# Explicitly specify the application server being used. Useful if the root
# (home) directory of the application server doesn't use a standard name.
appserver.type=jboss
# Force deployment only of OCSP part.
ejbca.productionmode=ocsp
# Specify the configuration of JBoss AS that should be used.
jboss.config=ejbca
-----END-----
After that set-up the database configuration file:
# /opt/ejbca/conf/database.properties
----BEGIN----
# Specify desired type of database server.
database.name=mysql
# Specify the database connection URL. This property should be set according to
# the JDBC connector used (in this case the MySQL connector). See the MySQL JDBC
# for details on other options.
database.url=jdbc:mysql://127.0.0.1:3306/ocsp?characterEncoding=UTF-8
# Specify the class which should be used for the communication with the
# database. This class should correspond to the select database, and its name is
# dependant on the JDBC implementation for the given database server.
database.driver=com.mysql.jdbc.Driver
# Login credentials for the database which should store the CA information.
database.username=ocsp
database.password={{ocsp_mysql_password}}
-----END-----
The ocsp_mysql_password parameter should be replaced with the same password used during creation of ocsp user for the MySQL server.
Now set-up the configuration file for the OCSP responder itself:
# /opt/ejbca/conf/ocsp.properties
----BEGIN----
# Make sure that OCSP servlet is enabled
ocsp.enabled=true
# Default responder to use for signing when an appropriate signer cannot be found.
ocsp.defaultresponder=CN=Example Server CA,O=Example Inc.,C=RS
# Use the following signature algorithm for responses
ocsp.signaturealgorithm=SHA256WithRSA
# Default directory where the OCSP's keys and certificates are stored at
ocsp.keys.dir=/opt/jboss/server/ejbca/conf/keys
# Disable the configuration of SSL for the OCSP
j2ee.web-noconfigure=true
# Password for the keystores
ocsp.keys.storePassword={{ocsp_keystore_password}}
-----END-----
Select a keystore password as desired (this will be used later on for generating appropriate end entities for the OCSP responder, so make sure you pick a good-enough password).
Finally, make sure that permissions on configuration files are set-up properly (keeping them safe from prying eyes):
? root
$ chown ejbca.ejbca /opt/ejbca/conf/*.properties
$ chmod 640 /opt/ejbca/conf/*.properties
As for the rest of the configuration files, those will be left as is for the purpose of this guide (default values from sample configuration files will be used).
The installation itself is now a breeze with the following commands:
? ejbca
$ cd /opt/ejbca/
$ ant va-deploy
Go to the Administration -> Add End Entity page. Create the OCSP signer for the Example Person CA by filling-in the following information:
End Entity Profile: OCSP Signer
Username: ocsp.example.com_person
Password: {{ocsp_keystore_password}}
Confirm Password: {{ocsp_keystore_password}}
Batch generation (clear text pwd storage): On
E-mail address: ocsp@example.com
CN, Common name: Example Person CA OCSP Signer
O, Organization: Example Inc.
C, Country (ISO 3166): RS
Certificate Profile: Example OCSP Signer
CA: Example Person CA
Token: P12 file
Click on the Add button. Now create the OCSP signer for the Example Server CA by filling in the following information on the same page:
End Entity Profile: OCSP Signer
Username: ocsp.example.com_server
Password: {{ocsp_keystore_password}}
Confirm Password: {{ocsp_keystore_password}}
Batch generation (clear text pwd storage): On
E-mail address: ocsp@example.com
CN, Common name: Example Server CA OCSP Signer
O, Organization: Example Inc.
C, Country (ISO 3166): RS
Certificate Profile: Example OCSP Signer
CA: Example Server CA
Token: P12 file
It's now necessary to obtain the keystores for the OCSP signers. Since the batch-generation has been turned on, the faster way is to through the console. Log-in onto the ca.example.com server and enter the following commands:
? ejbca
$ bin/ejbca.sh batch
This will create the following files on the ca.example.com server:
# /opt/ejbca/p12/ocsp.example.com_person.p12
# /opt/ejbca/p12/ocsp.example.com_server.p12
These two files now need to be put into the following location on the OCSP server:
# /opt/jboss/server/ejbca/conf/keys/
Don't forget to create the above directory if it still doesn't exist. Also make sure the permissions have been set-up appropriately after the files are copied over:
? root
$ chown -R ejbca.ejbca /opt/jboss/server/ejbca/conf/keys/
$ chmod 750 /opt/jboss/server/ejbca/conf/keys/
$ chmod 640 /opt/jboss/server/ejbca/conf/keys/*.p12
You can now start the OCSP responder and set it up to start automatically during system boot:
? root
$ /etc/init.d/ocsp start
$ update-rc.d ocsp defaults
You can track the progress of OCSP start-up with the following command:
? ejbca
$ tail -f /opt/jboss/server/ejbca/log/server.log
Once it has fully started, you should see a line like this in the log files:
2011-11-05 23:39:48,125 INFO [org.jboss.bootstrap.microcontainer.ServerImpl] (main) JBoss (Microcontainer) [5.1.0.GA (build: SVNTag=JBoss_5_1_0_GA date=200905221053)] Started in 1m:9s:51ms
The final step includes setting-up the EJBCA CA to publish all the information about certificates to the OCSP responder's database.
First of all, since we'll be using SSL-protected connection to the OCSP database, it's necessary to import the certificates for the Example Root CA and Example Server CA into the global Java truststore. The certificates can be obtained from the Public Web -> Fetch CA & OCSP Certificates. The certificates should be put under names rootca.pem and serverca.pem on CA server within the directory:
# /root/certs/
Once the CA certificates have been put in place, you can import them with the following commands:
? root
$ keytool -importcert -alias examplerootca -file /root/certs/rootca.pem -keystore /usr/lib/jvm/java-6-openjdk/jre/lib/security/cacerts
$ keytool -importcert -alias exampleserverca -file /root/certs/serverca.pem -keystore /usr/lib/jvm/java-6-openjdk/jre/lib/security/cacerts
While importing you will be prompted for a password for the default Java truststore. The password is changeit (literally, don't change the actual password). Also, when importing the first certificate (the root one), you will be prompted to confirm that the Example Root CA is trusted. The Example Server CA will be imported without this verification since it has been issued by the Example Root CA (which was previously marked as trusted).
Next on is setting-up an OCSP datasource on the CA server itself. This will also yield a redeployment of the EJBCA application. Create the following configuration file:
# /opt/ejbca/conf/va-publisher.properties
----BEGIN----
ocsp-datasource.jndi-name=OcspDS
ocsp-database.url=jdbc:mysql://ocsp.example.com:3306/ocsp?characterEncoding=UTF-8&useSSL=true&requireSSL=true
ocsp-database.driver=com.mysql.jdbc.Driver
ocsp-database.username=ejbca
ocsp-database.password={{ejbca_mysql_password}}
-----END-----
Make sure you've set-up the permissions on this configuration file properly:
? root
$ chown ejbca.ejbca /opt/ejbca/conf/va-publisher.properties
$ chmod 640 /opt/ejbca/conf/va-publisher.properties
The parameter ejbca_mysql_password should be replaced with the password specified during creation and granting of privileges for user ejbca for the ocsp MySQL database on the OCSP server.
After this is done, it's necessary to redeploy the EJBCA on the CA server. EJBCA must be stopped prior to this with:
? root
$ service ejbca stop
Re-deploy EJBCA application:
? ejbca
$ cd /opt/ejbca/
$ ant deploy
Start EJBCA again:
? root
$ service ejbca start
It's now required to create a publisher that will use the configured data-source through the EJBCA's web interface. Go to the Administration -> Edit Publishers page, enter OCSP Publisher, and click on the Add button. Select the OCSP Publisher from the list, and click on the Edit Publisher button. Make the following changes:
Publisher Type: Validation Authority Publisher
Description: Publisher for the EJBCA validation authority.
Click on the Save and Test Connection. If no errors are reported, proceed to enable the publisher for certificate profiles on the Administration -> Edit Certificate Profiles page. Select the Example Server certificate profile and click on the Edit Certificate Profile button. Make the following change:
Publishers: OCSP Publisher
Click on the Save button to apply the change. Repeat the above procedure for all the other Example profiles, 'except' for the Example Sub-CA. Certificates handed-out through this profile are meant to be checked only through CRL's.
A small modification is now required to have the Publish Queue Process Service take care of the OCSP publisher as well. 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 OCSP 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.
Finally, it's necessary to perform one initial synchronization of the OCSP responder database. Dump the table containing certificate information on the CA server:
? root
$ mysqldump -uejbca -p ejbca CertificateData > sync.sql
Copy the resulting sync.sql file to the following location on the OCSP server:
# /root/sync.sql
Import the MySQL export on the OCSP server with:
? root
$ mysql -uocsp -p ocsp < sync.sql
If the synchronisation has passed without problems, remove the table dump from the OCSP server:
? root
$ rm /root/sync.sql
All the certificates issued from now on will be automatically published through the OCSP Publisher if the certificate profiles they belong to have the above publisher enabled.
This concludes the set-up of EJBCA as OCSP responder.
What do ----BEGIN---- -----END----- mean?
Those are just annotations used for denoting beginning of a block of commands/lines and end. Those should never be copied into file/terminal.
What does # /etc/init.d/ocsp in combination with BEGIN/END mean?
Edit file called /etc/init.d/ocsp, adding content specified between BEGIN and END.
How do I import certificates from offline CA/some other CA
EJBCA OCSP responder gains access to all certificates via the CertificateData table. All you need to do would be to have procedure to create dumps of offline/some other CA and to insert those certificates in the table. For formatting/data description see the table schema and existing entries.
I get error javax.ejb.EJBException: Signing CA '...' is not active when trying to issue OCSP certificate
For some reason your CA has not been activated. You have probably deviated from the CA set-up described in this guide. Just make sure the CA is activated (via administrator pages) before issuing the OCSP certificate.
How do I test OCSP responder?
This can be easily done with OpenSSL CLI call (just make sure to specify correct CA pem files and URL):
openssl ocsp -CAfile rootca.pem -issuer some_sub_ca.pem -cert end_entity_cert.pem -url http://ocsp.example.com/ocsp
Can I use separate certificate for built-in OCSP responder on CA EJBCA instance?
Not in EJBCA 4.0.x. However, this is easily doable in EJBCA 6, in part because the OCSP and CA functionality have been unified under same interface.
When issuing a server certificate all I can see is the EMPTY end entity profile
You have probably skipped a couple of steps while setting-up EJBCA as a CA (steps related to creating new certificate profiles and entity profiles). Go back to the CA and set-up those profiles.
When saving the OCSP publisher, I get Connection in init failed: Table 'ocsp.CertificateData' doesn't exist" error
The most likely issue is that you have either skipped deployment of EJBCA on OCSP side, or there have been errors while starting the OCSP responder. The table should be created automatically during the first start-up. Check the JBoss server logs for any errors.
Should I set-up OCSP responder on same server where I have set-up the CA?
No. The guide assumes you are using separate servers, and you will run into problems if you try to deploy them on the same server.
On what server should I run the commands - CA or OCSP?
This should be clearly specified within the guide. If not, let me know and I will fix it.
When saving and testing the OCSP publisher, I get Connection in init failed: Unable to get managed connection for OcspDS error
For some reason JBoss could not establish connection to the OCSP Database from the CA server.
Possible causes:
How can I test MySQL connection from CA to OCSP outside of JBoss/EJBCA?
The easiest way to do that would be to run the following commands as ejbca on the CA server:
mysql -h ocsp.example.com -uejbca -p ocsp