primekey/ejbca-ce repository overview

*** This repository is deprecated - please use keyfactor/ejbca-ce⁠ going forward ***

⁠EJBCA Community Edition

EJBCA® is a PKI Certificate Authority software. Robust, flexible, high performance, scalable, platform independent, and component based, EJBCA can be used stand-alone or integrated with other applications as a component of your service. See https://www.ejbca.org/⁠ for a full list of features and capabilities.

EJBCA is developed and commercially supported by Keyfactor⁠. EJBCA Community Edition is the LGPL licensed subset of EJBCA Enterprise⁠.

An EJBCA instance can be deployed to do one or more or of the following, from the very small to the very very large:

⁠Certificate Authority (CA)

A Certificate Authority (CA) issues fully customizable X.509 certificates for devices, humans and anything in between.

These certificates can be used to provide security, prove identity, secure communication (e.g. TLS/DTLS) or prove authenticity of your manufactured IoT device.

Standardized protocols for issuance, revocation and other common tasks in the PKI world allows for smooth integration and a high level of automation.

⁠Validation Authority (VA)

A Validation Authority (VA) can answer the question if a certificate is still valid.

Commonly the Online Certificate Status Protocol (OCSP) is used for online checking or by serving Certificate Revocation Lists (CRL) in environments with sporadic online presence or air-gaps.

⁠Registration Authority (RA)

A Registration Authority (RA) is a self service portal where certificate management can be delegated, partially or in full, to authorized team members in an organization.

⁠Minimum System Requirements

To run the EJBCA container a system should fulfill these minimum requirements:

• at least two CPU cores
• at least 1GB or RAM

⁠Usage

The container's behaviour can be customized by overriding environment variables.

Starting the container without setting any environment variables will

• Use the bundled H2 database that is persisted on graceful stop.
• Generate a Management CA on first run with an empty database and output the enrollment information for the first administrator to the console.
• Generate a TLS server side certificate from the Management CA on first startup for the instance's assigned hostname.
• Log sufficient and necessary information for most common setups to console.
• Accept plain HTTP connections of port 8080 and TLS connections on port 8443 with optional acceptance of client TLS certificates from any CA known to the application on startup.

⁠Quick start - ephemeral test instance

Start of ephemeral instance where anyone with unauthenticated network access to the instance can manage the system:

docker run -it --rm -p 80:8080 -p 443:8443 -h mycahostname -e TLS_SETUP_ENABLED="simple" primekey/ejbca-ce

Once the system is fully started, go to https://mycahostname:443/ejbca/adminweb/ to access the EJBCA Admin GUI where the instance can be managed. In the menu of the EJBCA Admin GUI you will find a link to additional Documentation.

TLS_SETUP_ENABLED="simple" is not recommended except for ephemeral tests without public network access.

When you stop the container all data will be gone. (Skip the --rm flag to persist data in the containers file system or use DATABASE_JDBC_URL described below to persist data in an external database.)

⁠Quick start - classic workflow

Start of ephemeral instance with client certificate authenticated access to management of the instance:

docker run -it --rm -p 80:8080 -p 443:8443 -h mycahostname primekey/ejbca-ce

In the console output, you will find instructions for how to enroll for the initial SuperAdmin client certificate keystore that needs to be imported to your browser.

Once the system is fully started, go to https://mycahostname:443/ejbca/adminweb/ to access the EJBCA Admin GUI where the instance can be managed. In the menu of the Admin GUI you will find a link to additional Documentation.

When you stop the container all data will be gone. (Skip the --rm flag to persist data in the containers file system or use DATABASE_JDBC_URL described below to persist data in an external database.)

⁠Additional examples

More complex deployment examples are available on Github⁠.

⁠Using an external database

EJBCA uses a shared database model for clustering where all EJBCA nodes have a consistent view of the data. Hence, clustering EJBCA will require the use of an external SQL database. MariaDB with Galera clustering is an open source example of such database that can be both highly available and consistent with synchronous multi-master replication.

DATABASE_JDBC_URL: The JDBC drivers for MariaDB/MySQL and Postgres are also bundled with the container and works out of the box by specifying the corresponding JDBC URL. For historical reasons the MariaDB JDBC URL begins with jdbc:mysql:.

• jdbc:h2:/mnt/persistent/ejbcadb;DB_CLOSE_DELAY=-1 will use the bundled H2 database that is persisted when the container is gracefully stopped. This is the default value.
• jdbc:h2:mem:ejbcadb;DB_CLOSE_DELAY=-1 will use the bundled H2 database where nothing is persisted when the container is stopped.
• jdbc:mysql://database:3306/ejbca?characterEncoding=UTF-8 will connect to an MariaDB/MySQL instance with a database named ejbca at the host database
• jdbc:postgresql://database/ejbca will connect to a Postgres instance with a database named ejbca at the host database

DATABASE_USER: The username part of the credentials to access the external database. Not required for use of the H2 database. DATABASE_PASSWORD: The password part of the credentials to access the external database. Not required for use of the H2 database.

⁠Using the container behind a proxy

Configuring the container as a proxy back-end will disable legacy installation workflow or any local TLS server side certificate generation. The Admin UI will be open to anyone will network access until configured otherwise.

Running the container behind a front-end proxy (like Nginx or Apache Httpd) that terminates TLS connections is currently the expected setup for any kind of production-like deployment.

When binding a proxy back-end protocol port to

• an IP that can later be exposed outside the container (e.g. "0.0.0.0") care needs to be taken to ensure that no traffic can reach the bound port directly.
• a local IP (e.g. "127.0.0.1") it is expected that a side-car deployment in the same Kubernetes Pod will be used and forward requests inside the Pod.

PROXY_AJP_BIND: Run container with an AJP proxy port :8009 bound to the IP address in this variable.

PROXY_HTTP_BIND: Run container with two HTTP back-end proxy ports :8081 and :8082 configured bound to the IP address in this variable. Port 8082 will accepts the SSL_CLIENT_CERT HTTP header.

TLS_SETUP_ENABLED: No proxy back-end setup, but still disable container internal TLS setup by setting this to "false". The applications Admin UI will grant full access to anyone that is able to connect. Currently EJBCA's Admin GUI is not very functional in this setup without a URL-content rewriting proxy in front. By setting this to "simple", you will end up with a Management CA and server side TLS certificate, but anyone can manage the system over HTTPS. Such unauthenticated access is allowed with a PublicAccessAuthenticationToken configured in Admin GUI → Roles → Super Administrator Role → Members.

⁠Sending email

When using email notifications EJBCA by default uses a service in the application server java:/EjbcaMail. Such a mail service is pre-configured in the application servers' standalone.xml, with environment variables for SMTP host and port.

SMTP_DESTINATION: The hostname/IP of the SMTP server that should be used for sending email, default localhost (there is no SMTP server in the container though).

SMTP_DESTINATION_PORT: the SMTP port to use on the host, default 25.

You can set the variables with an argument with a '-e' argument on the command line, see Quick Start for example usage.

⁠Other Environment Variables

There are other environment variables that you can set. You can list them all by running this on a running container (container_name):

docker exec -it container_name printenv

for example you can enable DEBUG logging with '-e LOG_LEVEL_APP=DEBUG'.

⁠Overriding properties

The ejbca.ear file in the container is built with enabled what is called allow.external-dynamic.configuration=true, this means that it looks for configuration properties, in order of priority:

• Java system property (java -Dfoo.prop=bar)
• {application server home directory}/conf
• /etc/cesecore/conf/ or /etc/ejbca/conf (depending on which specific config file)
• configuration files built into the ejbca.ear file

⁠Changing ports for static link in Public Web

If you want to run EJBCA on a different HTTPS port than the default (443), for example:

docker run -it --rm -p 80:8080 -p 9443:8443 -h mycahostname primekey/ejbca-ce

Everything works as expected but there is one link from the Public Web, https://locahost:9443⁠, that has a static configuration of the port s the link does not work. You can fix this with the above property override.

1. In the machine where docker is running, create a directory and create a file web.properites

2. Add this content to the file:

   httpserver.external.privhttps=9443

3. Run the container with

   docker run -it --rm -p 8080:8080 -p 9443:8443 -h mycahostname -v $PWD/config/web.properties:/opt/primekey/ejbca/conf/web.properties primekey/ejbca-ce

Now you can browse to https://localhost:8443⁠ and see that the link Miscellaneous -> Administration is: https://localhost:9443/ejbca/adminweb/⁠