NPKD Installation

The following covers information on prerequisites, configuring and installation of a NPKD system and information on application server configuration.

Prerequisites

It is recommended to run NPKD on the following platform:

Linux-based operating system. NPKD is tested with CentOS 7.
OpenJDK 8, 11, or 17.
MariaDB
Wildfly 10, 14, or 24. The installation instructions cover versions 10 and 14 only.
Apache Ant 1.10 or later.
OPTIONAL EJBCA ClientToolBox to interact with the HSM.

Operating System Accounts

Throughout the installation, the following operating system accounts will be assumed to be available and with log-in capabilities:

root, This operating system account can be used for direct log-in into the servers at all times.
primekey, Must have sudo-privileges to install software and start services.

All commands in this NPKD Installation guide are expected to be run as primekey user unless specifically stated otherwise.

Primary Environment

Create the /opt/primekey folder by running the following command:
BASH
```
sudo mkdir /opt/primekey
```

Set up the user and group ownership:

BASH

sudo chown primekey.primekey /opt/primekey

Set-up the file permissions:
BASH
```
chmod 755 /opt/primekey
```
Unpack Wildfly into the directory /opt/primekey/

Create a symbolic link to the Wildfly directory:

BASH

unzip -q <WILDFLY RELEASE>.zip -d /opt/primekey/
ln -snf /opt/primekey/<WILDFLY RELEASE> /opt/primekey/wildfly

Unpack NPKD into the /opt/primekey directory and create a symbolic link:

BASH

unzip -q <NPKD RELEASE>.zip -d /opt/primekey/
ln -snf /opt/primekey/<NPKD RELEASE> /opt/primekey/npkd

Configure NPKD according to your specifications by editing the properties files under /opt/primekey/npkd/conf.
Define environment variables by adding the following lines at the end of /home/primekey/.bashrc (if the file does not already exist, create it).
BASH
```
# PrimeKey PKI Platform environment variables.
ANT_HOME="/opt/primekey/ant"
ANT_OPTS="-Xmx512m"
JAVA_HOME="/usr/lib/jvm/java"
#APPSRV_HOME="/opt/primekey/wildfly"

PATH="$ANT_HOME/bin:$JAVA_HOME/bin:$PATH"
export PATH ANT_HOME ANT_OPTS JAVA_HOME
```
Ensure that Java SDK is installed and that the JAVA_HOME environment variable is correctly defined in the .bashrc file located in primekey users home folder.
Reload environment:
BASH
```
source /home/primekey/.bashrc
```

Configure Wildfly as a Service

Perform the following steps in order to add the Wildfly NPKD instance as a service:

If you plan on running multiple Wildfly instances on the same machine (perhaps on different port offsets), you should give the service a different name here, such as wildfly-npkd

Create the file /etc/systemd/system/wildfly.service containing the following start script:

BASH

[Unit]

Description=Wildfly service

After=network.target mysql.service 

[Service]
PIDFile=/var/run/wildfly.pid
User=primekey
Group=primekey
ExecStart=/opt/primekey/wildfly/bin/standalone.sh
ExecStop=/bin/kill -HUP $MAINPID
Type=idle
TimeoutStartSec=600
TimeoutStopSec=600
 
[Install]
WantedBy=default.target

Reload the systemctl daemon:
BASH
```
sudo systemctl daemon-reload
```
Add Wildfly startup to allow start-up on boot:
BASH
```
sudo systemctl enable wildfly
```
Start Wildfly:
BASH
```
sudo systemctl start wildfly
```
Check if Wildfly started without any errors:
BASH
```
sudo systemctl status wildfly
```

Database Setup

For MariaDB, set binlog_format to "row" under the section mysqld. Edit /etc/my.cnf.d/server.cnf:
BASH
```
sudo vi /etc/my.cnf.d/server.cnf
```
Modify or add the following option under [mysqls]:
TEXT
```
[mysqld] 
binlog_format=row
```
Restart MariaDB:
BASH
```
sudo systemctl restart mariadb.service
```
Make MariaDB run at startup:
BASH
```
sudo systemctl enable mariadb
```

Hardening of MariaDB

Do basic hardening and set MariaDB root password:

BASH

mysql_secure_installation

When prompted to enter the current password for root, click Enter.
Press [ Y ] to set the root password.
Enter MariaDB Primary environment DataBase root password.
Press [ Y ] to remove the default anonymous user.
Press [ Y ] to disallow root login remotely.
Press [ Y ] to remove test database and access to it.
Press [ Y ] to reload privilege tables.

Create the Database

Connect to mysql database using mysql client, with root db user:
BASH
```
mysql -u root -p
```

Create the NPKD database and a user and grant it privileges for NPKD database as root:

Run as DB Root User

SQL

create database <DB_NAME> character set utf8 collate utf8_general_ci;
create user npkd_user@localhost identified by '<DB_USER_PASSWORD>';
grant all privileges on <DB_NAME>.* to <DB_USER_NAME>@<HOST>;

Flush all privileges:
Run as DB Root User

SQL
```
flush privileges;
```
Exit the MySQL client:
Run as DB Root User

SQL
```
exit
```

Create the NPKD Database Tables

BASH

mysql <DB_NAME> -u <DB_USER_NAME> -p < /opt/primekey/npkd/doc/sql-scripts/create-tables.sql

Install the HSM

Follow the HSM vendor's instructions to install the HSM and create a symbolic link to the PKCS11 library in /opt/primekey/hsm_pkcs11.so (not necessary but will simplify typing):

BASH

ln -snf <PKCS11 .so LIBRARY> /opt/primekey/hsm_pkcs11.so

If you will have both the TLS keys and the database protection keys in the HSM, make sure to have them on separate partitions since they have different purposes.

For the rest of the instructions, it is assumed that /opt/primekey/hsm_pkcs11.so exists

Set up Database Protection Key (optional)

Optionally, you may enable database protection. It works by storing a signature of each row in the database. Unauthorized addition or modification of data will cause a signature verification failure when database protection is enabled. It does not detect reversion of rows to an old version or deletion of rows (although the Audit Log records contain sequence numbers, which can be used to detect gaps in the sequence numbering).

Database protection is configured in the file NPKD_HOME/conf/databaseprotection.properties. The properties databaseprotection.enablesign and databaseprotection.enableverify control whether signing and verification should be done. If the file is missing, then database protection will be completely disabled.

Soft Keys in File

Create a p12-file using the JAVA keytool utility and enter the requested information:

BASH

cd /home/primekey
$JAVA_HOME/bin/keytool -genkeypair -alias <DB_PROTECTION_KEY_ALIAS> -keystore /home/primekey/dbprotect.p12 -storepass DBPROTECT_PASSWORD -validity 7280 -keyalg <KEY ALGORITHM, tex. RSA> -keysize <KEY SPECIFICATION, tex 2048> -storetype pkcs12 -dname "<SUBJECT DN>"

Convert the p12-file to a Base64 encoded file:

BASH

cat /home/primekey/dbprotect.p12 | base64 | tr -d '\012' > /home/primekey/dbprotect.b64

Edit the database protection property file:

BASH

vi /opt/primekey/npkd/conf/databaseprotection.properties

Change the relevant parameters:

TEXT

databaseprotection.keylabel.0 = <DB_PROTECTION_KEY_ALIAS>
databaseprotection.classname.0 = org.cesecore.keys.token.SoftCryptoToken
databaseprotection.properties.0 =
databaseprotection.data.0 = <THE ENTIRE TEXT IN THE dbprotect.b64 FILE>
databaseprotection.tokenpin.0 = <THE PASSWORD TO THE dbprotect.p12 FILE>

Save the changes and exit the file editor.

Keys in HSM

For the following instructions, the tool EJBCA ClientToolBox will be used and it is assumed that EJBCA ClientToolBox is installed under /opt/primekey/clientToolBox.

Generate keys in the HSM:

BASH

cd /opt/primekey/clientToolBox/
./ejbcaClientToolBox.sh PKCS11HSMKeyTool generate /opt/primekey/hsm_pkcs11.so <KEY_SPECIFICATIONS, tex. 2048> <DB_PROTECTION_KEY_ALIAS> SLOT_LABEL:<SLOT LABEL>

The monitor output should contain:

XML

Created certificate with entry <TLS KEY ALIAS>

Generate a certificate request for the database protection key:

BASH

./ejbcaClientToolBox.sh PKCS11HSMKeyTool certreq /opt/primekey/hsm_pkcs11.so SLOT_LABEL:<SLOT LABEL> <DB_PROTECTION_KEY_ALIAS>

Send the CSR-file to the CA and receive a certificate.

Install the certificate in the HSM:

BASH

./ejbcaClientToolBox.sh PKCS11HSMKeyTool installcert /opt/primekey/hsm_pkcs11.so SLOT_LABEL:<SLOT LABEL> <CERTIFICATE FILE>

Edit the database protection property file:

BASH

vi /opt/primekey/npkd/conf/databaseprotection.properties

Change the relevant parameters:

TEXT

databaseprotection.keylabel.0 = <DB_PROTECTION_KEY_ALIAS>
databaseprotection.classname.0 = org.cesecore.keys.token.PKCS11CryptoToken
databaseprotection.properties.0 = sharedLibrary=/opt/hsm_pkcs11.so, slotLabelType=SLOT_LABEL, slotLabelValue=<SLOT LABEL>
databaseprotection.data.0 =
databaseprotection.tokenpin.0 = <HSM PARTITION PIN>

Save the changes and exit the file editor.

Set up Wildfly

See instructions in one of the following sections, depending on what Wildfly server you are using.

NPKD Installation with Wildfly 10

NPKD Installation with Wildfly 14

NPKD Upgrade