[toc]

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](http://ejbca.org/installation.html#Ubuntu%20quick%20start) 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):

```
? root
$ apt-get install unzip
```

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

```
? 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 appropriate JDBC drivers for it:

```
? root
$ apt-get install libmysql-java
```

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:

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

```
# /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
```

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:

```
? root
mysql> create database ejbca;
mysql> grant all privileges on ejbca.* to 'ejbca'@'localhost' identified by '{{ejbca_mysql_password}}';
mysql> flush privileges;
```

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
```
? 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.

Setting-up JBoss AS
===================

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 ([attachment:4]). 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/ejbca
```

Set-up the file permissions for the init script:

```
? root
$ chown root.root /etc/init.d/ejbca
$ chmod 755 /etc/init.d/ejbca
```

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

```
# /etc/init.d/ejbca
----BEGIN----p
--- # Provides: jboss
+++ # Provides: ejbca
-----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 [attachment:5] file for details on what the parameters do and what parameters are available):

```
# /etc/jboss/ejbca.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/ejbca.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](http://community.jboss.org/wiki/SecureJBoss) 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:

```
-t nat -A PREROUTING -p tcp -m tcp --dport 80 -j REDIRECT --to-ports 8080
-t nat -A PREROUTING -p tcp -m tcp --dport 443 -j REDIRECT --to-ports 8443
```

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:

```
? 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 CA part. OCSP will be deployed on a separate server.
ejbca.productionmode=ca

# Specify the password which will be used for protecting the keystore where the
# CA's private key and certificate will be stored.
ca.keystorepass={{keystore_password}}

# Specify the configuration of JBoss AS that should be used.
jboss.config=ejbca

# Make the healthchecker a bit more strict than the default. It will trigger an
# alarm once this much of free memory is left (in megabytes).
healthcheck.amountfreemem=32

# Make the healthcheck actually perform signing operation to make sure it's
# working properly.
healthcheck.catokensigntest=true
-----END-----
```

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:

```
# /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/ejbca?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=ejbca
database.password={{ejbca_mysql_password}}
-----END-----
```

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:

```
# /opt/ejbca/conf/install.properties
----BEGIN----
# Name of the temporary CA used for initial configuration and access (before the
# proper CA hierarchy is in place).
ca.name=ExampleTempAdminCA

# Distinguished name of the temporary admin CA
ca.dn=CN=ExampleTempAdminCA,O=Example Inc.,C=RS

# Software tokens should have this set to null
ca.tokenpassword=null

# Type of the temporary admin CA private key. (default value listed)
ca.keytype=RSA

# RSA key size for the temporary admin CA.
ca.keyspec=4096

# Default signing algorithm for the temporary admin CA.
ca.signaturealgorithm=SHA256WithRSA

# Validity period for the temporary admin CA in days.
ca.validity=30

# Policy for the temporary admin CA.
ca.policy=null
-----END-----
```

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:

```
# /opt/ejbca/conf/web.properties
----BEGIN----
# Password for the Java truststore used by EJBCA.
java.trustpassword={{ejbca_truststore_password}}

# Common and distinguished name for the temporary super-administrator.
superadmin.cn=TempSuperAdmin
superadmin.dn=CN=${superadmin.cn}

# Password for the temporary super-administrator's p12 keystore.
superadmin.password={{temporary_superadmin_password}}

# Specify that the temporary super-administrator's p12 keystore should be
# generated a part of a 'batch' operation. (otherwise it's useful for storing it
# on a smart-card through the EJBCA public web interface)
superadmin.batch=true

# Password for protecting the keystore containing the application server's
# private key and certificate.
httpsserver.password={{ejbca_https_keystore_password}}

# Hostname which will be used for accessing the CA (must be resolvable from
# client stations accessing the web interface).
httpsserver.hostname=ca.example.com

# Distinguished name for the application server.
httpsserver.dn=CN=${httpsserver.hostname},O=Example Inc.,C=RS

# Specify external port visible to users of EJBCA.
httpserver.external.privhttps=443

# Specify desired language for the web frontend.
web.availablelanguages=EN

# Error message which should be shown to end users in case of an error.
web.errorpage.notification=An exceptions has occurred while trying to process your request. Please contact the administrators and provide the information presented within this page.
-----END-----
```

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:

```
# /opt/ejbca/conf/mail.properties
----BEGIN----
# Log-in credentials for sending email notifications from EJBCA.
mail.user=ejbca@example.com
mail.password={{ejbca_mail_password}}

# Mail server used for sending out email notifications.
mail.smtp.host=mail.example.com

# Specify whether the mail server requires the authentication or not.
mail.smtp.auth=true

# Specify whether STARTTLS should be used or not.
mail.smtp.starttls.enable=true

# Email address used for sending the emails.
mail.from=ejbca-noreply@example.com
-----END-----
```

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

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

Installing EJBCA
================

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

```
? ejbca
$ cd /opt/ejbca/
$ ant bootstrap
```

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:

```
? root
$ service ejbca start
```

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

```
? ejbca
$ tail -f /opt/jboss/server/ejbca/log/server.log
```

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

```
2011-03-28 22:22:40,743 INFO  [org.jboss.bootstrap.microcontainer.ServerImpl] (main) JBoss (Microcontainer) [5.1.0.GA (build: SVNTag=JBoss_5_1_0_GA date=200905221053)] Started in 4m:59s:229ms
```

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

```
? ejbca
$ cd /opt/ejbca/
$ ant install
```

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:

```
? root
$ service ejbca stop
```

Finalise the deployment with:

```
? ejbca
$ cd /opt/ejbca/
$ ant deploy
```

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

```
? root
$ update-rc.d ejbca defaults
$ service ejbca start
```

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:

```
# /opt/ejbca/p12/superadmin.p12
```

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:

```
@ http://ca.example.com/ejbca/
```

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:

```
Signing Algorithm: SHA256WithRSA
RSA key size: 4096
Description: Root CA for Example Inc.
Validity (*y *mo *d) or end date of the certificate: 20y
Subject DN: CN=Example Root CA,O=Example Inc.,C=RS
Use Issuing Distribution Point on CRLs: On
Default CRL Dist. Point: http://crl.example.com/rootca.crl
CRL Expire Period (*y *mo *d *h *m): 1y
CRL Overlap Time (*y *mo *d *h *m): 2d
```

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:

```
Available bit lengths: 4096 bits
Validity: 15y
Allow validity override: Off
CRL Distribution Points: On
Use CA defined CRL Dist. Point: On
Available CAs: Example Root CA
```

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:

```
Signing Algorithm: SHA256WithRSA
RSA key size: 4096
Description: Example's CA in charge of issuing certificates for individuals within the organisation.
Validity (*y *mo *d) or end date of the certificat: 15y
Subject DN: CN=Example Person CA,O=Example Inc.,C=RS
Signed By: Example Root CA
Certificate Profile: Example Sub-CA
Use Issuing Distribution Point on CRLs: On
Default CRL Dist. Point: http://crl.example.com/personca.crl
CRL Expire Period (*y *mo *d *h *m): 14d
CRL Overlap Time (*y *mo *d *h *m): 12h
Default OCSP Service Locator: http://ocsp.example.com/ejbca/publicweb/status/ocsp
```

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:

```
Signing Algorithm: SHA256WithRSA
RSA key size: 4096
Description: Example's CA in charge of issuing certificates for servers within the organisation.
Validity (*y *mo *d) or end date of the certificat: 15y
Subject DN: CN=Example Server CA,O=Example Inc.,C=RS
Signed By: Example Root CA
Certificate Profile: Example Sub-CA
Use Issuing Distribution Point on CRLs: On
Default CRL Dist. Point: http://crl.example.com/serverca.crl
CRL Expire Period (*y *mo *d *h *m): 14d
CRL Overlap Time (*y *mo *d *h *m): 12h
Default OCSP Service Locator: http://ocsp.example.com/ejbca/publicweb/status/ocsp
```

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:

```
Available bit lengths: 1024, 2048, 4096
Validity (*y *mo *d) or end date of the certificate: 1y
Key Usage: Digital Signature, Non-repudiation
Extended Key Usage: Client Authentication, Email Protection
CRL Distribution Points: On
Use CA defined CRL Dist. Point: On
Authority Information Access: On
Use CA defined OCSP locator: On
Available CAs: Example Person CA
```

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:

```
Available bit lengths: 1024, 2048, 4096
Validity (*y *mo *d) or end date of the certificate: 1y
Key Usage: Key encipherment, Data encipherment
Extended Key Usage: Email Protection
CRL Distribution Points: On
Use CA defined CRL Dist. Point: On
Authority Information Access: On
Use CA defined OCSP locator: On
Available CAs: Example Person CA
```

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:

```
Available bit lengths: 1024, 2048, 4096
CRL Distribution Points: On
Use CA defined CRL Dist. Point: On
Authority Information Access: On
Use CA defined OCSP locator: On
Available CAs: Example Server CA
```

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:

```
E-mail Domain: example.com
O, Organization: Example Inc.
C, Country (ISO 3166): RS
RFC 822 Name (e-mail address) Required: On
Default Certificate Profile: Example Person Signing
Available Certificate Profiles: Example Person Signing, Example Person Encryption
Default CA: Example Person CA
Available CAs: Example Person CA
Default Token: P12 file
Number of allowed requests: 2
Number of allowed requests use: On
Key Recoverable Use: On
```

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:

```
Batch generation (clear text pwd storage) use: On
E-mail Domain: example.com
O, Organization: Example Inc.
C, Country (ISO 3166): RS
RFC 822 Name (e-mail address) Required: On
Default Certificate Profile: Example Server
Available Certificate Profiles: Example Server
Default CA: Example Server CA
Available CAs: Example Server CA
Default Token: PEM file
```

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:

```
Username: {{admin_username}}
Password: {{admin_password}}
Confirm Password: {{admin_password}}
Email: {{admin_mail}} @ example.com
CN, Common name: {{admin_name}} {{admin_surname}}
UID, Unique Identifier: {{user_id}}
O, Organization: Example Inc.
C, Country (ISO 3166): RS
Use data from E-mail address field: On
Certificate Profile: Example Person Signing
CA: Example Person CA
Token: P12 file
Number of allowed requests: 2
Key Recoverable: Off
```

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:

```
CA: Example Person CA
Match with: Certificate serial number (recommended)
Match type: Equals, case sens.
Match value: {{certificate_serial}}
```

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:

```
Username: ca.example.com_ejbca
Password: {{ca_keystore_password}}
Confirm Password: {{ca_keystore_password}}
Batch generation (clear text pwd storage): On
E-mail address: ejbca@example.com
CN, Common name: Example CA Server
O, Organization: Example Inc.
C, Country (ISO 3166): RS
DNS Name: ca.example.com
Use data from E-mail address field: On
Certificate Profile: Example Server
CA: Example Server CA
Token: JKS file
```

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:

```
# /opt/ejbca/bin/batchtool.properties
----BEGIN----
keys.spec=4096
-----END-----
```

The keystore can now be generated with the following commands:

```
? ejbca
$ cd /opt/ejbca/
$ bin/ejbca.sh batch
```

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:

```
? ejbca
----BEGIN----$
cd /opt/ejbca/
bin/ejbca.sh ca getrootcert 'Example Root CA' rootca.der -der
bin/ejbca.sh ca getrootcert 'Example Person CA' personca.pem
openssl x509 -in personca.pem -out personca.der -outform DER
keytool -importcert -alias examplerootca -file rootca.der -keystore p12/truststore_new.jks
keytool -importcert -alias examplepersonca -file personca.der -keystore p12/truststore_new.jks
-----END-----$
```

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:

```
? root
$ service ejbca stop
```

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

```
? ejbca
$ cd /opt/ejbca/p12/
$ cp ca.example.com_ejbca.jks /opt/jboss/server/ejbca/conf/keystore/keystore.jks
$ cp truststore_new.jks /opt/jboss/server/ejbca/conf/keystore/truststore.jks
```

Once this is done, EJBCA can be started again:

```
? root
$ service ejbca start
```

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:

```
? ejbca
$ cd /opt/ejbca/p12/
$ mv ca.example.com_ejbca.jks tomcat.jks
$ mv truststore_new.jks truststore.jks
```

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:

```
Select Worker: Publish Queue Process Service
Select Interval: Periodical Interval
Period: 1 minutes
Select Action: No Action
Active: On
Pin to Specific Node(s): ca.example.com
Description: Publish certificates and CRL's from the publisher queue.
```

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:

```
Select Worker: CRL Updater
CAs to Check: Example Root CA, Example Person CA, Example Server CA
Select Interval: Periodical Interval
Period: 5 minutes
Select Action: No Action
Active: On
Pin to Specific Node(s): ca.example.com
Description: Updates the CRL's if necessary. Checks are made every 5 minutes.
```

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.

Troubleshooting
===============

**Running batch generations results in status FAILED**

When running the `bin/ejbca.sh batch` command, you may notice the output will mention `status FAILED`. For example:

```
ejbca@ca:/opt/ejbca$ bin/ejbca.sh batch
Use 'batch --help' for additional options.
Generating keys in directory /opt/ejbca_4_0_5/p12.
Generating for end entities with status NEW.
Batch generating 1 users.
Generating keys for ca.example.com_ejbca.
Created Keystore for 'ca.example.com_ejbca'.
New user generated successfully - ca.example.com_ejbca.
1 new users generated successfully - :ca.example.com_ejbca.
Generating for end entities with status FAILED.
Batch generating 0 users.
```

The troublesome line is `Generating for end entities with status FAILED.` - in the above example this is in fact *not* an error. It is actually stating that it has tried batch generation for EJBCA end entities which are already in status FAILED (of which there were none, as can be seend in `Batch generating 0 users` line.

**I get `You are not authorized to view this page` when accessing EJBCA administrator page after replacing `truststore.jks` with `truststore_new.jks`**

There is a couple of issues that can result in such an error. Make sure that:

1. You have imported the new super-administrator P12 into browser.

2. You have restarted the web browser (to clear caching of credentials).

3. Make sure the JBoss has been restarted so it can start using the `truststore.jks`.

4. Make sure you have set-up the new administrator correctly before replacing the `truststore.jks`.

5. If you keep getting the error, and it is not related to TLS, check the JBoss server logs to see what identity EJBCA sees when you try to access the administration pages.

It might be useful to also list the current admins registered via `bin/ejbca.sh` CLI.

**Batch generation fails during `ant install`**

This issue is possibly related to password length specified for the JBoss truststore/keystore in `web.properties` file. Make sure all keystore passwords at least 6 characters long (this is Java requirement).

**Running `ant install` fails**

Make sure that EJBCA has deployed before running the command. Also make sure that you have restarted JBoss after running `ant bootstrap`.

**Instructions do not work when deploying on JBoss 6, JBoss 7, Wildfly and/or EJBCA 6**

The guide was written quite some time ago, and has been tested against specific combination of JBoss + EJBCA. Anything else may or may not work, and there's very little I can do about it without spending way too much time on it.

**I'm trying to add custom field/extension and am having issues**

See the [EJBCA admin guide](https://www.ejbca.org/docs/adminguide.html#Custom%20DN%20and%20altName%20oids) or post question to [EJBCA development list](https://lists.sourceforge.net/lists/listinfo/ejbca-develop)

**I want to use different FQDN for accessing the CA. Should I reissue the superadmin certificate as well?**

You just need to issue a new CA web server certificate with proper FQDN specified in it. The old super-admin certificate is not tied in any way to FQDN, so no need to reissue that one.

**Running `service ejbca start` results in errors**

When running `service ejbca start`, you encountered the following errors:

```
[root@ejbca ~]# service ejbca start
/etc/init.d/jboss: line 172: log_daemon_msg: command not found
/etc/init.d/jboss: line 139: start-stop-daemon: command not found
/etc/init.d/jboss: line 173: log_end_msg: command not found
```

You are most likely either not using Debian Squeeze or Debian Wheezy, or quite possibly you are not running Debian at all. The init script is specifically written for Debiaj Squeeze/Wheezy.

**CRL updater service did not generate a new CRL even though I have revoked a certificate**

The CRL updater service does not generate a new CRL for each revocation. It actually checks (based on CA's CRL settings) if old CRL has expired and if new one should be generated based on provided CRL overlap etc.

Generating CRL for each revocation would be wasteful (1000 revoked certificates could result in 1000 CRLs), and you most likely want to use OCSP instead.

If you really want to, you could create a new custom publisher that would call the `bin/ejbca.sh ca createcrl` command.

**I changed password on `tomcat.jks` using `keytool` and now JBoss won't start**

When changing the password for `tomcat.jks`, you need to keep in mind that there are two passwords involved with the file - one is the password used for keystore itself, while the other is password used for protecting the private key within the keystore. Have a look at keytool's `-keypasswd` option to change the internal, private key password.

**I get a lot of errors about missing symbols and files while running ant bootstrap**

There is a high chance you have been using wrong user account to run some applications. Most likely you have been running a bunch of commands as `root` instead of `ejbca`. Fix your file permissions and try again.

In particular:

- `/opt/ejbca/` should be owned by `ejbca:ejbca`.

**How do I set-up mail server for sending and receiving notifications?**

This is a bit out-of-scope of this guide, but I could recommend having a look at [ISPmail tutorial](https://workaround.org/ispmail).

**I need to use a custom extended key usage**

Have a look at `extendedkeyusage.properties`.

**Runnin `service ejbca start` does not start JBoss, but running `service ejbca restart` produces `no such file or directory` error

If you are running on slightly different (Ubuntu) distro, or maybe using 64-bit installation, you may encounter error similar to:

```
root@ubuntu:~# service ejbca restart
 * Restarting daemon ejbca
start-stop-daemon: unable to stat /usr/lib/jvm/java-6-openjdk//bin/java (No such
 file or directory)
   ...done.
```

The most likely issue is that Java in your case can be found under different path. Just fix the path (parameter `javaHome`) in file `/etc/jboss/ejbca.conf`.

**I can't get EJBCA to work with Oracle JDK**

The guide was written with OpenJDK in mind. Oracle JDK has both limitations (US export laws regarding cryptography) and differences compared to OpenJDK that may require additional steps. I suggest having a look at EJBCA documentation if you really insist using Oracle JDK.

**I had a lot of errors, how do I start from scratch?**

Well, best off would be to reinstall OS, but if you feel lazy the minimum you need to do is:

- Remove `/opt/jboss/server/ejbca/`.
- Remove `/opt/ejbca/p12/`.
- Drop the EJBCA database.

**Why do you create copy of `default` JBoss directory?**

I find it useful to keep the stock JBoss server configuration directories intact for comparison purpose (i.e. the `minimal`, `default`, and `all`).

**When running `ant install` I get `javax.naming.CommunicationException`**

First of all, try to identify if you have a line in output similar to following:

```
     [java] javax.naming.CommunicationException: Could not obtain connection to any of these urls: 127.0.0.1:1099 and discovery failed with error: javax.naming.CommunicationException: Receive timed out [Root exception is java.net.SocketTimeoutException: Receive timed out] [Root exception is javax.naming.CommunicationException: Failed to connect to server /127.0.0.1:1099 [Root exception is javax.naming.ServiceUnavailableException: Failed to connect to server /127.0.0.1:1099 [Root exception is java.net.ConnectException: Connection refused]]]
```

If so, there has been an error during JBoss start-up (most likely it did not start at all). Have a look at JBoss logs to identify the issue.

Or... You may have forgotten to start JBoss.