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

  1. Create the /opt/primekey folder by running the following command: 

    sudo mkdir /opt/primekey
    BASH

     

  2. Set up the user and group ownership: 

    sudo chown primekey.primekey /opt/primekey
    BASH

     

  3. Set-up the file permissions:

    chmod 755 /opt/primekey
    BASH

     

  4. Unpack Wildfly into the directory /opt/primekey/

  5. Create a symbolic link to the Wildfly directory:

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

     

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

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

  7. Configure NPKD according to your specifications by editing the properties files under /opt/primekey/npkd/conf.

  8. Define environment variables by adding the following lines at the end of /home/primekey/.bashrc (if the file does not already exist, create it).

    # 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
    BASH

    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.

  9. Reload environment: 

    source /home/primekey/.bashrc
    BASH

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


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

    [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
    BASH

  2. Reload the systemctl daemon:

    sudo systemctl daemon-reload
    BASH

  3. Add Wildfly startup to allow start-up on boot:

    sudo systemctl enable wildfly
    BASH

  4. Start Wildfly:

    sudo systemctl start wildfly
    BASH

  5. Check if Wildfly started without any errors:

    sudo systemctl status wildfly
    BASH

Database Setup

  1. For MariaDB, set binlog_format to "row" under the section mysqld. Edit /etc/my.cnf.d/server.cnf:

    sudo vi /etc/my.cnf.d/server.cnf
    BASH

  2. Modify or add the following option under [mysqls]:

    [mysqld] 
binlog_format=row
    TEXT

  3. Restart MariaDB:

    sudo systemctl restart mariadb.service
    BASH

  4. Make MariaDB run at startup:

    sudo systemctl enable mariadb
    BASH

Hardening of MariaDB

Do basic hardening and set MariaDB root password:

mysql_secure_installation
BASH

  1. When prompted to enter the current password for root, click Enter.

  2. Press [ Y ] to set the root password.

  3. Enter MariaDB Primary environment DataBase root password.

  4. Press [ Y ] to remove the default anonymous user.

  5. Press [ Y ] to disallow root login remotely.

  6. Press [ Y ] to remove test database and access to it.

  7. Press [ Y ] to reload privilege tables.

Create the Database

  1. Connect to mysql database using mysql client, with root db user:

    mysql -u root -p
    BASH

     

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

    Run as DB Root User

    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>;
    SQL

  3. Flush all privileges:

    Run as DB Root User

    flush privileges;
    SQL

  4. Exit the MySQL client:

    Run as DB Root User

    exit
    SQL

Create the NPKD Database Tables

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

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):

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

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

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

    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>"
    BASH

  2. Convert the p12-file to a Base64 encoded file:

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

  3. Edit the database protection property file:

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

  4. Change the relevant parameters:

    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>
    TEXT

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

  1. Generate keys in the HSM:

    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>
    BASH


    The monitor output should contain:

    Created certificate with entry <TLS KEY ALIAS>
    XML

  2. Generate a certificate request for the database protection key:

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

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

  4. Install the certificate in the HSM:

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

  5. Edit the database protection property file:

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

  6. Change the relevant parameters:

    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>
    TEXT

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