Installation Instructions

The following describes how to install EJBCA on the most well-supported application server JBoss AS. EJBCA can also be run on Glassfish and Weblogic, but your mileage may vary (see details below).

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.

  • JBoss Application Server 7.1.x or later or JBoss EAP 7 or later. WildFly 9 or later.

    • The currently recommended Application Servers are WildFly 10, or JBoss EAP 7 (download WildFly or download JBoss EAP).

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

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, not published in LDAP. 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 REAL CAs using the Admin GUI.
    Use your preferred certificate profiles etc. These certificates can be published in LDAP. For configuration information, refer to doc/howto/HOWTO-multiplecas.txt.

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

  • Hypersonic 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.

  • Hypersonic 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.