SKCE Install

Introduction

There are two paths to install the StrongKey CryptoEngine: Manual and Automated. This section of the wiki describes the automated installation using the install-skce.sh script. The installation script will deploy and configure all the software necessary to run SKCE. Be aware that the script modifies system files such as iptables and inittab. While it is possible to install the SKCE on your personal computer, it is highly recommended to perform this installation in a virtual environment or workstation/server dedicated to the SKCE.

Prerequisites

A fully qualified domain name (FQDN) for a hostname with either DNS or local hostfile entry in /etc/hosts that can resolve the hostname. It is very important to have a hostname that is at least TLD+1 (i.e. acme.com, example.org, etc) otherwise FIDO functionality may not work.

The installation process has been tested on CentOS 6.7 and should work for all version of CentOS 6. The installation script is untested on CentOS 5, CentOS 7, and other flavours of Linux but may work with slight modifications.

It is recommended to have at least 10GB of available disk space and 4GB of memory.

Step 1: Download StrongKey CryptoEngine 2.0 (SKCE 2.0)

Make sure you have the following set up and/or ready to run before you begin:

Download the binary distribution file skce-v2.0-build-N.zip (where N is the latest build) from Sourceforge.

Extract the distribution in the directory of your choice.
> unzip skce-v2.0-build-N.zip

Download the following binaries and copy them to the extracted directory:

glassfish-4.1.zip
https://glassfish.java.net/download.html

jce_policy-8.zip
http://www.oracle.com/technetwork/java/javase/downloads/jce8-download-2133166.html

jdk-8u121-linux-x64.tar.gz
http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html

OpenDJ-3.0.0.zip
https://backstage.forgerock.com/#!/downloads/enterprise/OpenDJ

mariadb-10.1.22-linux-x86_64.tar.gz
https://downloads.mariadb.org/mariadb/10.1.22/

mariadb-java-client-1.5.8.jar
https://downloads.mariadb.org/connector-java/1.5.8/

SKCE has been tested with these versions of the above software. SKCE should work with any new minor versions released, but the installation script must be modified to accommodate the new filenames. After downloading and placing the files, your installation directory should look similar to this:


If any downloaded software does not match the version listed above, modify the install-skce.sh installation script and update the version numbers inside in the Current Versions section.


Modify the Basic Configuration section of install-skce.sh. This section contains information about default passwords for created users, system resource allocation, and other miscellaneous configurations. The default configuration should work on systems with at least 4 GB available. The only configuration that must be modified is the servers list. Change it to the hostname of the appliance. Also If this is a cluster install, uncomment and modify the other server hostnames as well.

Step 2: Running the Installation Script

The installation script must be run as root. The script will create a strongauth user account with the home directory of /usr/local/strongauth. All software required for the SKCE will be deployed to the /usr/local/strongauth directory and be run by strongauth.

NOTE: While the installation script allows for changing the default /strongauth home directory, the software has not be updated to recognize a non-default directory.

Execute the install-skce.sh script.
> ./install-skce.sh

If the script indicates a problem such as missing files, correct the error and re-run the script.

When the script finishes, all software will have been installed and a strongauth user will have been created. Log out of root and log in to the strongauth user for the next steps. The default password for the strongauth user is “ShaZam123”.

Step 3: Activate SKCE 2.0 for Cryptographic Operations

The cryptographic services on StrongKey CryptoEngine are controlled by three Key Custodians. Whenever the Glassfish application server is restarted, the Key Custodians must activate the SKCE by providing their credentials before all of the cryptographic operations will work. This document describes a step-by-step procedure of generating the Key Custodian credentials and how to activate SKCE using those credentials. If this is a cluster install run this ONLY on one of the machines in the cluster. For all other machines refer to Step 4.

Step 3a. Setup Key Custodians

SKCE uses three Key Custodians to activate cryptographic operations on SKCE:

  1. Security Officer
  2. Key Custodian 1
  3. Key Custodian 2

Setting up key custodians for SKCE can be done by running a script provided along with the distribution you downloaded for SKCE. Through out the whole process, it is highly recommended to watch the Glassfish server logs. So, we will maintain two terminal windows as we do the steps.

NOTE: In production environments, the key custodian credentials are stored in USB flash drives and are handed over to real administrators who would further be responsible for the key custodianship. But for demonstration purposes, we will generate the credentials onto a directory called ‘keystores’ on the local file system.

Open a terminal window; let us call this window1. Change directory to Glassfish logs directory.
> cd /usr/local/strongauth/glassfish4/glassfish/domains/domain1/logs

Window1: tail the glassfish logs and leave the window open as we work with SKCE to observe the logs information. Keep this window open through out the steps.
> tail -f server.log

Open another terminal window; let us call this window2. Change directory to /usr/local/strongauth/.
> cd /usr/local/strongauth/

Window2 : Change directory to /usr/local/strongauth/bin/.
> cd /usr/local/strongauth/bin/

Window2 : Run Primary-SKCE-KeyCustodian-Setup-Wizard.sh using the command below and press Enter.
> ./Primary-SKCE-KeyCustodian-Setup-Wizard.sh

The script will open up a wizard to generate key custodian credentials for SKCE. As you progress through the steps, make sure to watch the logs that are scrolling on window1.

The first screen of the wizard will look like the image below.

Clicking Next will take you to the screen where the cryptographic module information is provided. Since this is a demonstration version of SKCE, it uses a software-based cryptographic module which is a local keystore that will be generated by this wizard. In a production environment, it is HIGHLY RECOMMENDED not to use a software-based cryptographic module.

Please select Software-based Module (SunJCE) as the Type of cryptographic module and click Next.

The next page in the wizard generates the Security Officer’s credentials. Please enter a password and repeat the same to confirm. Additionally, using the Browse button to point Target Location to the /keystores directory created a few steps ago. The wizard should look like the image below.

Once all fields are completed, click Create. The wizard creates and stores the credential files in /usr/local/strongauth/skce/keystores/.

A prompt appears: ‘Remove the flash-drive AFTER clicking Next to continue.’ Working in a production environment, these credentials would be stored in flash drives that are handed over to real administrators; in the demo scenario, this message can be ignored.

Click OK to continue.

The output on the wizard should look like the bottom pane in the image below.

Click Next to advance to Key Custodian #1’s credentials.

Choose and confirm another password for Key Custodian #1 (KC1).

For Target Location, Browse to the /keystores directory, then click Create.

The successful output of credential creation should look like the bottom pane in the image below.

Click Next to advance to Key Custodian #2’s credentials.

Choose and confirm another password for Key Custodian #2 (KC2).

For Target Location, Browse to the /keystores directory, then click Create.

The successful output of credential creation should look like the bottom pane in the image below.

Click Next.

Clicking Finish to complete credentials generation.  The /usr/local/strongauth/skce/keystores directory should have all the credential key store files.

Key Custodian setup for SKCE is complete.

Restart Glassfish to pick up new property changes created by the wizard:
> sudo service glassfishd restart

The default strongauth password is ShaZam123.

Leave window1 and window2 open for the next steps.

Step 3b: Activate SKCE for Cryptographic Operations

Now that the key custodians have been setup, SKCE must be activated to perform cryptographic operations using KC credentials.

Switch to window2Change directory to /usr/local/strongauth/bin.
> cd /usr/local/strongauth/bin

Run the SKCE-ConsoleTool.sh shell script in the /usr/local/strongauth/bin directory:
> ./SKCE-ConsoleTool.sh

The script will open up a graphical user interface; a wizard to activate SKCE using all the three key custodian credentials; Security Officer, Key Custodian #1, and Key Custodian #2. Throughout this process, make sure to keep an eye on the logs that are scrolling on window1.

The first screen of the wizard will look like the image below.

Ensure that the Webservice URL points to your machine’s hostname where SKCE is installed, including the port on which it is running. Leave the rest of the settings as is.

For each of the Key Custodians, including the Security Officer, follow these steps:

1. Select the Key Custodian Role from the drop-down. (order does not matter)

2. Browse to and select the right Keystore file. All three files can be found in the /usr/local/strongauth/skce/keystores directory.

  • For the Security Officer, it is skce-securityofficer.jceks
  • For Key Custodian #1, it is skce-keycustodian1.jceks
  • For Key Custodian #2, it is skce-keycustodian2.jceks

3. In the Keystore password field, enter the relevant password.
4. Click Verify. Ensure the message in the lower pane says, ‘Password has been successfully verified.’
5. Click Submit.  Ensure the message in the lower pane says, ‘Successfully set pin for [role] [code]‘.

Once all the three Key Custodians have submitted their credentials, click Exit to close the wizard.

The cryptographic module of StrongKey CryptoEngine is active and SKCE is ready to perform cryptographic operations.

Step 3c: Create Signing Key for the SKCE Domain

Switch to window2. Change directory to /usr/local/strongauth/bin.
> cd /usr/local/strongauth/bin

Run the New-SKCE-Domain-Setup.sh shell script in the /usr/local/strongauth/bin directory:
> ./New-SKCE-Domain-Setup.sh

The script will launch a wizard to generate a signing key for the SKCE domain. Be sure to keep track of the logs scrolling on window1.

The first screen of the wizard will look like the image below.

Click Next. Since this is a demonstration version of SKCE, it uses a software-based cryptographic module which is a local key store generated by this wizard. In a production environment, it is HIGHLY RECOMMENDED not to use software-based cryptographic modules.

Please select Software-based Module (SunJCE) as the Type of cryptographic module and click Next.

Click Next. The Set applicationID panel displays. In the Application ID field, provide the URL to the list of facets allowed to access FIDO registration and authentication services on this domain. If you are not using FIDO, use the following as your applicationID.

https://<FQDN of primary host>:8181/app.json

Click Next. Enter a Common Name for the signing key. The example below uses strongauth with the domain ID of 1. The common name and the SAKA domain is just for information purposes in the signing key and does not impact any functionality.

Leave the Certificate Location with the default, which is /usr/local/strongauth/skce/etc.

Click Create to generate the signing key and place it in the certificate location.

A successful creation message looks like this:

Click Next when finished.

Click Finish to complete the signing key generation. The /usr/local/strongauth/skce/keystores directory should have the signing key file added.

Step 4: Setting Up Key Custodians on All Secondary SKCEs

On every secondary SKCE, the Key Custodians are not regenerated but copied over from the primary as generated in Step 3a. Securely copy the /keystores directory to this
node from the node first upgraded
; you may use SCP or SFTP to perform this task:

shell> scp ­-r strongauth@<fqdn­node­first­upgraded>:skce/keystores .

Also edit the /usr/local/strongauth/skce/etc/skce/skce-configuration.properties file and copy over the skse.cfg.property.dsig.signingdn property from the primary SKCE’s property file.

Restart Glassfish to pick up new property changes created by the wizard.
shell > sudo service glassfishd restart
The default strongauth password is ShaZam123.

Follow Step 3b to set PINs for all the Key Custodians.

Repeat this process on all the secondary SKCE’s.

Step 5: Test SKCE 2.0 using the sample SKCE client program

StrongKey has put up a sample client application called skceclient to test the StrongKey CryptoEngine 2.0 functionality. The sample client is a command line interface (CLI)-based client written in Java programming language; tested on JDK 8.
Skceclient tests file encryption and decryption, cloud operations, LDAP/AD-based user authentications/authorizations, FIDO-based user registrations/authentications, etc.

Test SKCE v2.0 build 148 with a sample client program

NOTE: A full JDK installation (JDK 8 or above) is needed; just the JRE is not sufficient.