Installation Instructions

The following describes how to install EJBCA on the most well-supported application server JBoss AS.

For information on quickly getting started with EJBCA, see Quick Start Guide.

Prerequisites

EJBCA uses strong crypto and keystore passwords longer than 7 characters. If you use Oracle JDK This requires you to install the Unlimited Strength Jurisdiction Policy Files for JDK, available for download together with the JDK download at the Oracle website. The text Using exportable cryptography will be shown on the first page in the Admin GUI if you fail to install the package. For more information, refer to the Oracle documentation on the JCE.

This is not needed when using OpenJDK.

The following needs to be built and run:

  • JDK 8, OpenJDK or Oracle JDK. If available OpenJDK is recommended.

  • Only if using OracleJDK - Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files for your JDK.

  • WildFly 10 or later or JBoss EAP 7 or later.

  • Apache Ant 1.8 or later to build (available as a standard package in Linux, or download). Note that javascript support may be needed in ant for some components.

Windows/Unix: When we describe command line commands below we use Unix notation, e.g. ejbca.sh for the executable command files. The same command files are available for windows as cmd-files, e.g. ejbca.cmd.

If you are unsure what version of EJBCA you are running, type ant ejbcaversion in the EJBCA_HOME directory.

Note that EJBCA currently (up to and including EJBCA 7.0) does not support Java 11. If running on a platform that comes with Java 11 by default, such as Ubuntu 18.04, switch to using Java 8 by running the following:

> sudo update-java-alternatives --set java-1.8.0-openjdk-amd64

Configure

Configuration Files

The configuration of EJBCA that cannot be configured in the Admin GUI is located in properties files in the conf directory. All properties are documented in sample files and to configure an option you copy the sample file, for example, copy conf/ejbca.properties.sample to conf/ejbca.properties and configure conf/ejbca.properties. You should at least familiarize yourself with the options in conf/install.properties, conf/ejbca.properties and conf/cesecore.properties. Most options, except those in install.properties can be changed after installation.

EJBCA Configuration

Copy conf/install.properties.sample to conf/install.properties, conf/ejbca.properties.sample to conf/ejbca.properties and conf/cesecore.properties.sample to conf/cesecore.properties. Customize if needed. The default values work fine for a test installation.

You must configure appserver.home in ejbca.properties to point to your application server directory. You find examples of how to do this in ejbca.properties.sample.

This makes libraries from the application server available to EJBCA during the build.

If you are only testing EJBCA at this stage and is not setting up a production environment, you can skip the rest of this step. There are default configuration options, that should work in a test environment, for everything.

  • If needed, customize the CA properties in conf/ejbca.properties. For production use you need to do this, don't forget to edit passwords to be secure and secret. Keep conf/ejbca.properties as secret as possible. DO NOT forget the passwords, if you need to re-install the software sometime.

  • To use a hard ca token from start, change ca.tokentype, ca.tokenpassword and ca.tokenproperties in install.properties. You also need to add the appropriate values to the ca.tokenproperties file for the HSM. Read the HSM documentation for the right values.

  • To put the initial superadmin certificate on a smartcard, set superadmin.batch=false in web.properties.
    Enroll from the Public Web after the installation is complete, as you would with any other smartcard user.
    Username is superadmin and password is superadmin.password from web.properties.

  • If you are deploying on JBoss EAP you probably want to look at the property jboss.config as well, since production may be the default server to start on JBoss EAP (depends on your configuration).

Do the same with other configuration files that you might want to customize. The default values are generally sufficient, and most options are documented in the sample files.

  • If needed, customize the database in conf/database.properties. Most straightforward is to keep the default values, using the JBoss embedded HSQLDB. For production use, you should use a real database instead of the embedded one.

Configure Application Servers

Due to differences between different application servers, configure your application server with certain settings, and EJBCA with server-specific settings. For more information, see Application Servers.

Finalizing the Installation

Once you have installed according to the instructions for your application server EJBCA will, during the ant runinstall step have generated an administrator keystore

  • p12/superadmin.p12

Imported this keystore in your web browser, this is your administration certificate. The password for the keystore is prompted for during installation, or set by you in install.properties. The default password is ejbca. Other administrators with specific privileges can be created later on.

Go to https://localhost:8443/ejbca/ to access the Admin GUI, or http://localhost:8080/ejbca for the public web pages.

Optional

Instead of creating an initial Admin CA and issuing administrator certificates from that, you can install using administrator certificates from an already existing external CA. For more information, see Administrators Issued by External CAs.

If you create other CAs that you want to add as acceptable CAs in the server TLS configuration, or if you renew the CA certificate, you can install any CA certificate in the server TLS configuration afterwards with the following command:

ant -Dca.name="My CA Name" javatruststore

What this does in the background is that it adds the CA certificate to p12/truststore.jks and copies this file to APPSRV_HOME/standalone/configuration/keystore, where the TLS keystores are located.

You must stop and start JBoss after doing this.

Considerations

When everything is prepared, there are a few things to configure before starting your applications and running everything in a production environment.

In a production environment you should use something like the following structure:

  1. Go through the install process creating a ManagementCA.
    Use a simple DN. This CA should only be used to issue the administrator certificates. If you want to use an HSM for this CA, refer to the documentation in the configuration file conf/ejbca.properties.sample.

  2. Once installed, create all your Organization CAs using the Admin GUI.
    Use your preferred certificate profiles etc.

In a production environment, it is required to use something else than the default H2 database provided with JBoss/WildFly, for the following reasons:

  • H2 database is in-memory and will over time consume more memory. If a large number of certificates is issued, it will become an issue after a while.

  • H2 does not support full SQL, in particular, ALTER statements. When a new version of EJBCA is released we cannot create scripts that update the database if some tables have changed. This will complicate upgrades.

For information about installing JDBC drivers for other databases, refer to doc/howto/HOWTO-database.txt in the distribution.