A Word of Warning

A lot of people have come to this page following the links on the EJBCA main website. You should be warned that although I've tried my best to make a straight-forward guide, if you are only beginning with the EJBCA deployment, make sure you've at least ran through several set-ups following the Quick Start Guide for Ubuntu (should work for Debian Squeeze as well). The entire installation below takes on a more serious deployment schema, and you might find yourself a little overwhelmed if this is your first time starting-out.

There are plans to write some troubleshooting guidelines related to installation described below, but it's currently not the first thing on the TODO list, unfortunately.

Software Requirements

For the purpose of running the EJBCA as certification authority, 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):

Installing Required Java Packages

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):

Additionally, it will also be necessary to install the Apache Ant build tool (which will be used for building the EJBCA):

Since the EJBCA will be using MySQL JDBC connectors, it's also necessary to install the appropriate JDBC drivers for it:

Setting-up MySQL Server

Installation of the MySQL server on top of Debian Squeeze is a pretty much straightforward step, and it can be done with a simple:

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 adding non-latin characters in subject DN's or anywhere else in the EJBCA front-end. Create the following configuration file:

After this you need to restart the MySQL server to apply the changes:

Once the MySQL server has been installed and set-up to use UTF-8, it is necessary to create the database that will store EJBCA data, as well as to create and grant appropriate permissions to the user which will be used for accessing the database:

Parameter ejbca_mysql_password should be replaced by the desired password for the ejbca user.

Setting-up System Accounts

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

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.

Setting-up JBoss AS

Unpack the JBoss AS and set-up the file permissions:

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:

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:

Set-up the file permissions for the init script:

Change the init script so that it provides the EJBCA service:

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:

Create a configuration file for the EJBCA JBoss AS instance (if you're interested, take a look at the attached jboss.conf file for details on what the parameters do and what parameters are available):

Set-up the configuration file permissions:

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:

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:

If you do not require the administration console, you can also remove it with:

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.

Tweaking the Firewall Rules

By default the JBoss AS instance will be listening on port 8080 for HTTP, and port 8443 for HTTPS protocol. The standard ports for these protocols are 80 and 443, respectively, 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 ports 80 and 443 to ports 8080 and 8443 can be performed instead.

This can be done with the following iptables rules:

These rules should be set-up to be loaded automatically upon each boot. Take note that these rules won't be useful in cases where you're accessing the URL's from localhost (you'll need to use 8080 and 8443 in URL's).

An alternative (and probably a much saner approach) would be to use the Apache HTTP server to this purpose usind mod_jk. For the time being this type of deployment falls outside of scope of this guide.

Preparing EJBCA Installation Files

Unpack the EJBCA installation files and set-up their permissions:

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:

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):

Don't forget to replace the keystore_password parameter with your own desired password (make sure the password is at least six characters long or you won't be getting any keystore at all due to built-in checks of Java utilities). This password will protect the private key and certificate used by the certification authority itself.

Set-up the database configuration file:

The ejbca_mysql_password parameter should be replaced with the same password used during creation of ejbca user on the MySQL database.

One of the most important configuration files is the install.properties, which specifies lots of useful information about the initial certification authority. This starting certification authority is used in order to provide secure access to the EJBCA prior to deployment of proper certification authority hierarchy. In some cases it can also be kept as permanent administrative CA. The file should contain the following information:

In order to access the EJBCA it's also necessary to set-up the properties for the actual web server which will be serving its public and administrative web interfaces. The file should have the following contents:

The password parameters should be replaced by desired passwords (make sure the keystore/truststore passwords are at least six characters long or you won't be getting any keystore/truststore at all due to built-in checks of Java utilities).

Finally, if there's a functioning mail server which can be used for sending outgoing e-mails from EJBCA itself, it is also useful to set-up the appropriate configuration file for it:

The ejbca_mail_password parameter should be replaced with the password used for the ejbca@example.com user on the mail server itself (in this case mail.example.com).

Finally, make sure that permissions on configuration files are set-up properly (keeping them safe from prying eyes):

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).

Installing EJBCA

The installation itself is more or less a straightforward process. For start bootstrap the EJBCA:

After the boostrap process finishes, it is necessary to actually run the JBoss AS EJBCA instance in order to get on with the next step:

You should wait until the instance finishes starting-up. You can check for its progress with a tail command:

Once the server has stared up, you'll see a line like this in the log file:

Once the instance is up and running, proceed with the installation of EJBCA (this will actually create the necessary private keys, certificates, truststores etc):

The install command might take a while. Once the command finishes, the JBoss AS EJBCA instance should be stopped before proceeding with the next step:

Finalise the deployment with:

Once the deployment has finished, start the JBoss AS EJBCA instance again, and let it start automatically on boot:

This concludes the basic installation of EJBCA itself. What's left is to perform configurations steps from within the administrative interface. This actually forms the meat and bones of the entire process. Everything up until now was simply a preparation.

Importing Temporary Super-Administrator Token

Since EJBCA is protecting the access to administration segment through client certificates, it is necessary to import the temporary super-administrator token into web browser. The token itself is stored within a PKCS#12 file. The file should be copied over from the EJBCA server onto workstation which will be used for further configuration from the following location on CA server:

In case of Firefox, this file can be imported by going to Edit -> Preferences -> Security -> Advanced -> Encryption -> Show Certificates dialogue. Within this dialogue select the Your Certificates tab, click on the Import... button, and navigate to the PKCS#12 file. The file is protected by the appropriate password specified in web.properties configuration file.

Once this has been completed, it should be possible to access the administration interface of the EJBCA through the following URL:

Enabling Key Recovery

An important aspect when generating private keys is their secrecy and safekeeping. In case of private keys which should be used for non-repudiation, these keys should not be backed-up.

On the other hand, in case of private keys which are used for encryption, it is essential to maintain copies of those keys. If the keys get lost, the data encrypted with them is rendered useless.

To this end it's possible to use the EJBCA itself. In order to allow key recovery, go to the Administration -> System Configuration page and turn on the Enable Key Recovery option. Click on the Save button.

Creating the Root CA

With basic installation done, it's time to set-up the certification authority hierarchy. The starting point is the root CA. Go to the Edit Certificate Authorities page and enter Example Root CA as the name of new certification authority, then click on Create... button. Make the following changes:

Once the information is filled-in, click on the Create button. Wait until the operation finishes (it can take a while depending on CPU speed and amount of available entropy). Once it's done a new certification authority will be available in the list of CA's.

Creating Sub-CA's

Before proceeding with creation of the rest of production CA hierarchy, it is useful to create a distinct certificate profile for sub-CA's (CA's that are not root). EJBCA does come with some pretty sane defaults, but it's still very helpful to create a distinct profile in order to be sure what has been used for each authority (in cases that the defaults change between versions).

Open the Edit Certificate Profiles page, select the SUBCA (FIXED) profile from the list, enter Example Sub-CA in the edit box, and click on the Use selected as template button. This will create a new certificate profile with properties copied from the SUBCA profile.

Select the newly created Example Sub-CA and click on the Edit Certificate Profile button. The following options for this profile should be changed:

Click on the Save button to commit the changes.

Once the certificate profile has been completed, it's time to move on to creation of the certification authorities which will be in charge of issuing certificates to end entities (people and servers). Open the Edit Certificate Authorities page, and enter Example Person CA in the text box, then click on the Create... button. Make the following changes on the page:

Once the information is in place, click on the Create button. After a while a new CA will be created and it will appear in the list of available certification authorities.

The next CA in line is the certification authority which will issue certificates for servers. Open the Edit Certificate Authorities page, and enter Example Server CA in the text box, then click on the Create... button. Make the following changes on the page:

Click on the Create button to finalise the creation of basic CA hierarchy.

Creating Certificate Profiles for End Entities

The same way certificate profiles were created for sub-CA's, it is also necessary to create certificate profiles for end entities. These profiles will be based off the default profiles provided by the EJBCA itself.

Go to the Edit Certificate Profiles page and select the ENDUSER (FIXED) profile. Enter the name for the new profile in the text box - Example Person Signing, then click on the Use selected as template button. Select the newly created Example Person Signing profile from the list, and click on the Edit Certificate Profile button. Make the following changes:

Once the information is filled-in, click on the Save button (make sure the Key encipherment is turned off, otherwise the mailing software will pick up the signing certificate for encryption as well).

Select the ENDUSER (FIXED) profile again, and enter Example Person Encryption as the name of the new profile. Click on the Use selected as template button. Select the newly created profile and click on the Edit Certificate Profile button. Make the following changes to the profile:

Click on the Save button to apply the changes.

The next profile will be created for purpose of being used by servers. Select the SERVER (FIXED) profile, enter Example Server as the profile name, and click on the Use selected as template. Select the newly created certificate profile and click on the Edit Certificate Profile button. Make the following changes to the profile:

Save the changes. This concludes the creation of basic certificate profiles.

Creating End Entity Profiles

While the certificate profiles basically define what a certificate can be used for, the end entity profiles define the contents of certificate profiles. Two distinct end entity profiles will be created - one for individuals within the organisation, and another one for servers.

Go to the Administration -> Edit End Entity Profiles page. Enter Person within the text field and click on the Add button. Select the newly created Person profile and click on the Edit End Entity Profile button. Add the following Subject DN Attributes:

• UID, Unique identifier
• O, Organization
• C, Country (ISO 3166)

Make all the three newly added attributes required and modifiable. Add the subject alternative name RFC 822 Name (e-mail address).

Change the fields of Person profile as follows:

Once the changes have been made, click on the Save button.

Next in line is the server end entity profile. Go back to the Administration -> Edit End Entity Profiles page and enter Server in the text box. Click on the Add button. Select the newly-created Server profile and click on the Edit End Entity Profile button. Add the following Subject DN Attributes and mark them all as required:

• O, Organization
• C, Country (ISO 3166)

Add the subject alternative name DNS Name. Add the subject alternative name RFC 822 Name (e-mail address). Change the fields of Server profile as follows:

Click on the Save button. All the basic necessary end entity profiles are now available.

Moving EJBCA to Production Hierarchy

It's time to replace the existing certificates used by the EJBCA web frontend with certificates issued by Example Server CA, as well as to switch to using Example Person CA's certificates for authenticating and authorising administrators.

Issuing New Super-administrator Key and Certificate

Go to the Administration -> Add End Entity page. Select the Person end entity profile. Fill in the following information:

Don't forget to replace all the parameters with desired information. Click on Add End Entity button. The key/certificate pair can now be obtained and imported into browser through the public web interface. Go to the Public Web -> Create Browser Certificate page and provide the credentials previously specified for the administrator end entity. Make sure that the Example Person Signing profile is selected, and click on the OK button. You will be provided with a p12 file which can be saved locally, then imported into the web-browser you'll be using for further administration (other parts of this book also deal with storing of private keys and certificates on smart-cards instead, as well as generating private keys independently of EJBCA itself). The file is protected with the same password as specified for the end entity.

Head back to the Administration -> Edit Administrator Privileges page. Click on the Add link and enter Super Administrators as a name. Click on the Administrators link next to the Super Administrators group and provide the following information:

The certificate_serial parameter should be replaced by the certificate serial number you've just issued. It can be obtained through the web browser, for example. Make sure the serial number specified doesn't contain colons (Mozilla Firefox displays the serial number with colons).

Click on the Add button, then click on the Edit Access Rules on the same page. Select role Super Administrators, and click on the Save button.

Preparing New Keystore for the EJBCA Web Server

It's time to create a new keystore and truststore for the EJBCA web server. Go to the Administration -> Add End Entity page and select the Server profile. Provide the following information:

The password provided should match the password specified in the web.properties configuration file for the ejbca_https_keystore_password parameter. Once done, click on the Add button.

Now login to the CA server itself and add the following line at the end of the file:

The keystore can now be generated with the following commands:

In addition to generating the keystore, it's also necessary to create a new truststore. The truststore identifies which certificates should be trusted for the purpose of accessing the EJBCA administration interface. This can be done with the following set of commands:

The password provided for the new truststore should be exactly the same as the one provided in the web.properties configuration file for the ejbca_truststore_password parameter (this must be at least characters due to constraints imposed by Java and its tools).

Before proceeding with deployment of new keystore and truststore, make sure to stop the EJBCA service:

The keystore and truststore can be deployed with the following commands:

Once this is done, EJBCA can be started again:

Once the EJBCA has started-up you can try accessing the certification authority using your new key/certificate pair (you might need to restart your browser or clear its authentication credentials to be able to do so). If all goes well, it's recommended to make the new keystore/truststore default for future calls to deploy within the EJBCA source directory:

The final step includes disabling the old temporary super-administrator group, as well as temporary certification authority. Go to the Administration -> Edit Administrator Privileges page and click on the delete link next to the Temporary Super Administrator Group.

Once this has been completed, go to the page Administration -> CA Activation, select the Make off-line radio-box and turn off the Monitored check-box next to the ExampleTempAdminCA. Click on the Apply button.

It is also a good idea to revoke the old certificates used for the initial configuration (for end entities superadmin and tomcat) through the Administration -> Search/Edit End Entities page. Go to that page, and search for entities with status Generated. Click on the checkboxes next to the superadmin and tomcat end entities, and click on the Revoke And Delete button.

Configuring the Publish Queue Process Service

While this service may not be of any use yet, it will be useful in some of the later guides where OCSP, CRL, and LDAP get introduced. Once we start publishing the certificates and CRL's to remote locations it will be necessary to somehow make sure that in case of failures the certificates and CRL's do get published once the technical issues are resolved.

Go to the Administration -> Edit Services page. Enter Publis Queue Process Service in the edit box, and click on hte Add button. Select the newly-created service, and click on the Edit Service button. Provide the following information for it:

Click on the Save button to apply the changes.

Configuring the CRL Updater

As a final step to installing the EJBCA, it is necessary to set-up the CRL updater. CRL updater is in charge of generating the CRL's and making sure that once they expire they get regenerated. It is executed periodically. It should be noted that the CRL updater does not actually put CRL's in the spot from which they will be obtained. It merely generates them on the CA itself. Other parts of this book deal with making CRL's publicly available to the rest of the environment on the predefined location.

Go to the Administration -> Edit Services page. Enter CRL Updater in the edit box, and click on the Add button. Select the newly-created service, and click on the Edit Service button. Provide the following information for it:

Once the information is filled-in, click on the Save button. This concludes the initial deployment, installation, and configuration of the EJBCA as certification authority. You should proceed onto chapters covering the deployment of OCSP responder and CRL distribution point.