PKI and HSM in a SME – 2/4 – Installing EJBCA

1. Writing conventions

• %VARIABLE% is whatever you need it to be: a user, a password, etc.
• A command line starting with $ means it should be run as standard user.
  A command line starting with # means it should be run as superuser or via sudo.

2. Requirements

3. Setup environment

It is (of course) absolutly not recommanded to run EJBCA as root (and not by a sudoer either).

My advice will be to create a Linux user for EJBCA to run on it. Let’s call him %user%. Let’s create him:
# adduser %user%
His home folder will then be located at /home/%user%/
From now on, all commands with $ will be runned by %user%.

4. Download and extract EJBCA

You can download EJBCA from SourceForge (sic) here: https://sourceforge.net/projects/ejbca/files/latest/download

Be careful: if you use wget to download it directly from SF, you have to rename your downloaded file.
Below code is a sample, please always download lastest EJBCA version:
$ cd


$ wget -O ejbca_ce_6_10_1_2.zip https://downloads.sourceforge.net/project/ejbca/ejbca6/ejbca_6_10_0/ejbca_ce_6_10_1_2.zip?r=https%3A%2F%2Fsourceforge.net%2Fprojects%2Fejbca%2Ffiles%2Fejbca6%2Fejbca_6_10_0%2Fejbca_ce_6_10_1_2.zip%2Fdownload%3Fuse_mirror%3Dfreefr&ts=1535615539&use_mirror=freefr


You can check file integrity by comparing checksums and the ones given on EJBCA Official Website

Then extract the downloaded package:
$ unzip ejbca_ce_%version%.zip


5. Database creation

Before doing anything, please secure your MariaDB instance by running
# mysql_secure_installation

EJBCA requires its on database and credentials to access. Login to MariaDB:
$ mysql -uroot -p
Then create the database with:
MariaDB [(none)]> CREATE DATABASE %dbname% CHARACTER SET utf8 COLLATE utf8_general_ci;

Finally, create MariaDB user and grant access to the database:
MariaDB [(none)]> GRANT ALL PRIVILEGES ON %dbname%.* TO '%dbuser%'@'localhost' IDENTIFIED BY '%dbpassword%';

6. EJBCA installation script settings

We are going to edit the main EJBCA installation script to fit our system and our needs.
Edit the file ~/ejbca_%version%/bin/extra/ejbca-setup.sh

At the beginning of the file, change the lines corresponding to database settings:

database_host="localhost"
database_name="%dbname%"
database_driver="org.mariadb.jdbc.Driver"
database_url="jdbc:mysql://${database_host}:3306/${database_name}?characterEncoding=UTF-8"
database_username="%dbuser%"<
database_password="%dbpassword%"

You can also change few things considering the Management Certificate Authority. It is the Certificate Authority delivering certificates to EJBCA RA team, admins and superadmins.
Please check for allowed characters and fields in DN before modifying this, or setup will fail.

BASE_DN="OU=%unit%,O=%org%,L=%loc%,C=%country in 2 letter format%"
ca_name="%managementcaname%"
ca_dn="CN=%managementcaname%,${BASE_DN}"

Finally, you can also change the SuperAdmin CN (Common Name), it will be the first generated certificate of the Management Certificate Authority during setup:

superadmin_cn="God"

7. Start EJBCA setup (and take a coffee )

You can start setup by running:
$ ./ejbca_ce_%version%/bin/extra/ejbca-setup.sh


The script will automagically download and install WildFly 10 (application server), and its MariaDB database connector.

Once setup is done, get the ~/ejbca/p12/superadmin.p12 and import it in your web browser using the password provided at the end of the script and open the EJBCA Administration homepage at https://%yourdomainname%:8443/ejbca/adminweb/
This file is a TLS Client certificate allowing you to log in as the SuperAdmin of EJBCA.
yourlocalmachine $ scp %user%@%ejbcamachine%:ejbca-custom/p12/superadmin.p12 ./


8. EJBCA instance structure overview

Your ~ folder should be pretty populated now, let’s review its (interesting) content!

~
├── Download
│   └── [...]
├── ejbca -> ~/ejbca_ce_6_10_1_2/
├── ejbca_ce_6_10_1_2
│   ├── conf
│   ├── modules
│   ├── src
│   └── [...]
├── ejbca-custom
│   ├── conf
│   └── p12
├── wildfly -> wildfly-10.1.0.Final
├── wildfly-10.1.0.Final
│   ├── bin
│   ├── standalone
│   └── [...]
└── [...]

The ~/Download folder can be safely removed, it contained downloads of Wildfly and Java MariaDB connector.

~/ejbca is a symlink to current active EJBCA instance, in this example ~/ejbca_ce_6_10_1_2. It contains few interesting things, but mostly **nothing** should be modified in this. There’s a better place, which is…

~/ejbca-custom is a very interesting folder. It will contain all YOUR custom configuration. We will see that if you want to modify a file (for example a config file), you need to copy it in the ~/ejbca-custom folder, keeping the same path tree. Update command will overwrite ~/ejbca with ~/ejbca-custom content.
Two things to note then:

• Never **EVER** modify anything in ~/ejbca.
• Be careful on updates, some things may have been modified in the source code making your changes broken at least, destroying everything at most 🙂

~/wildfly is a symlink to ~/wildfly-10.1.0.Final: it is the Java Application server. EJBCA runs in it. For J2E lovers, this is a JBoss FLOSS continuation.

9. EJBCA: start, stop restart commands

For now, commands will be very rough, it’ll get better later with a systemd unit file.

To start EJBCA, run:
$ cd ~
$ nohup wildfly/bin/standalone.sh -b 0.0.0.0 > /dev/null 2> /dev/null &


To stop EJBCA, run:
$ cd ~
$ ./wildfly/bin/jboss-cli.sh --connect :shutdown


To reload EJBCA, run:
$ cd ~
$ ./wildfly/bin/jboss-cli.sh --connect :reload

10. EJBCA: Network ports used

EJBCA serves over various network port to work properly.

The only needed ports to open to the outside are:

• Port 8080/TCP is used as public HTTP service,
• Port 8442/TCP is used as public HTTPS service (used for example for enrollment),
• Port 8443/TCP is used as private HTTPS service (used with TLS Client certificate to administer EJBCA).

Do not worry, we’ll see in the next part how to use Apache2 as a proxy to standardize the ports to HTTP/80 and HTTPS/443.

EJBCA also some private ports, that you can either firewall or desactivate.

Up to this, all incoming ports are blocked, except:

• Port 22/TCP (for SSH access)
• Port 80/TCP (for HTTP, will be used in part 3)
• Port 443/TCP (for HTTPS, will be used in part 3)
• Port 8080/TCP (for testing purposes, will be deactivated in part 3)
• Port 8442/TCP (for testing purposes, will be deactivated in part 3)
• Port 8443/TCP (for testing purposes, will be deactivated in part 3)