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.
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
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
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.
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/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 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 wiki page. This includes alternatives to removing the above applications.
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.
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).
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.
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/
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.
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.
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.
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.
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:
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:
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.
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.
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.
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.
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.
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.
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:
You have imported the new super-administrator P12 into browser.
You have restarted the web browser (to clear caching of credentials).
Make sure the JBoss has been restarted so it can start using the truststore.jks.
Make sure you have set-up the new administrator correctly before replacing the truststore.jks.
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 or post question to EJBCA development list
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.
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:
/opt/jboss/server/ejbca/./opt/ejbca/p12/.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.