NPKD Installation

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

Prerequisites

NPKD is recommended to run with the following applications:

  • Linux based operating system. NPKD is tested with RedHat Server 6.8.
  • OpenJDK 8. If the code base is to be compiled on the same machine, make sure to install OpenJDK development environment (java-1.8.0-openjdk-devel.x86_64 in RedHat Server)
  • MariaDB
  • JBoss EAP 6.4 or equivalent
  • Apache Ant 1.10 or later
  • If the code base is to be compiled on the same machine, Apache Maven 3.3.9 or later is needed
  • (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


  2. Set-up the user and group ownership:

    sudo chown primekey.primekey /opt/primekey


  3. Set-up the file permissions:

    chmod 755 /opt/primekey


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

  5. Create a symbolic link to the JBoss directory:

    unzip -q <JBOSS RELEASE>.zip -d /opt/primekey/
    ln -snf /opt/primekey/<JBOSS RELEASE> /opt/primekey/jboss


  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
  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/jboss"
    
    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.

  9. Reload environment:

    source /home/primekey/.bashrc

Configure JBoss as a Service

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

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

    [Unit]
    
    Description=JBoss service
    
    After=network.target mysql.service 
    
    [Service]
    PIDFile=/var/run/jboss.pid
    User=primekey
    Group=primekey
    ExecStart=/opt/primekey/jboss/bin/standalone.sh
    ExecStop=/bin/kill -HUP $MAINPID
    Type=idle
    TimeoutStartSec=600
    TimeoutStopSec=600
     
    [Install]
    WantedBy=default.target
  2. Reload the systemctl daemon:

    sudo systemctl daemon-reload
  3. Add JBoss startup to allow start-up on boot:

    sudo systemctl enable jboss
  4. Start JBoss:

    sudo systemctl start jboss
  5. Check if JBoss started without any errors:

    sudo systemctl status jboss

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
  2. Modify or add the following option under [mysqls]:

    [mysqld] 
    binlog_format=row
  3. Restart MariaDB:

    sudo systemctl restart mariadb.service
  4. Make MariaDB run at startup:

    sudo systemctl enable mariadb

Hardening of MariaDB

Do basic hardening and set MariaDB root password:

mysql_secure_installation
  1. When prompted to enter 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


  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>;
  3. Flush all privileges:

    Run as DB Root User

    flush privileges;
  4. Exit the MySQL client:

    Run as DB Root User

    exit

Create the NPKD Database Tables

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

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 revertion 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>"
  2. Convert the p12-file to a Base64 encoded file:

    cat /home/primekey/dbprotect.p12 | base64 | tr -d '\012' > /home/primekey/dbprotect.b64
  3. Edit the database protection property file:

    vi /opt/primekey/npkd/conf/databaseprotection.properties
  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>
  5. Save the changes and exit the file editor.

Keys in HSM

For the following instruction, 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>


    The monitor output should contain:

    Created certificate with entry <TLS KEY ALIAS>
  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>
  3. Send the CSR-file to the CA and receice a certificate.

  4. Install the certificate in the HSM:

    ./ejbcaClientToolBox.sh PKCS11HSMKeyTool installcert /opt/primekey/hsm_pkcs11.so SLOT_LABEL:<SLOT LABEL> <CERTIFICATE FILE>
  5. Edit the database protection property file:

    vi /opt/primekey/npkd/conf/databaseprotection.properties
  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>
  7. Save the changes and exit the file editor.

Set up JBoss

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