Deploying KeyMaster pre-6.2.0

This page will take you through the process of deploying versions of KeyMaster older than 6.2.0.

Prerequisites

You need to have the following already installed:

  • A Java application server

  • Java 6 or .NET framework 3.5

  • Single Sign-on (SSO) system with which to integrate KeyMaster

It will also be necessary to synchronise the system clocks of the Java application server and Liberator servers if this is not done automatically by your system. Instructions on how to do this are below.

To ease log-file analysis across servers, time zones, and daylight savings transitions, we recommend that you set the system clocks of all hosts in a Caplin stack to UTC.

Synchronising the Servers

Make sure that the clock on the server running the Liberator is synchronised with the clock on the server where KeyMaster Signature Generator is running. If the clocks on these two servers are set to different times, the Liberator may falsely decide that a user credentials token has expired.

If the clocks are not correctly synchronised, then you will see the following message in the Liberator log file:

NOTIFY: Signature expired for key_id [key id] - [timestamp] denying login

Installation

A summary of the required steps are:

1. Generate keys

KeyMaster uses three encryption key files: a public key file, a private key file, and a DER public key file (which is a binary version of the public key). These key files must be generated before KeyMaster authentication can be used.

This installation guide assumes the names of the encryption key files are the same as the ones defined in the example version of keygen.props (a properties file within the KeyMaster deployment package), namely privatekey.store, publickey.store and publickey.der.

Follow these steps to generate the keys:

  1. Make sure you have the following JAR files. These should be present in the \lib directory of your KeyMaster installation:

    • The Bouncy Castle encryption JAR (bcprov-jdk<version>.jar).

      The version of the Bouncy Castle encryption JAR file must match the version of Bouncy Castle used to create the keystore. KeyMaster supplies the version bcprov-jdk14-125.jar which is compatible with Caplin Trader 1 and 2. However, the version bcprov-jdk14-1.46.jar is required for Caplin Trader 3.

    • The KeyMaster JAR containing all the classes KeyMaster needs to execute (keymaster.jar).

  2. KeyMaster uses a properties file keygen.props that is used to initialise and configure the Key Generator. There is an example keygen.props file in <Your_KeyMaster_dir>. You can use this file for your KeyMaster installation, if it is suitable for your needs. Alternatively you can create your own version of this file.

  3. Please check whether your KeyMaster installation directory contains existing key files that have the same name as the key files that we are going create.

    So to clarify, if you are going to use the example keygen.props properties file provided with the install kit, then you should check your KeyMaster installation directory for files called privatekey.store, publickey.store and publickey.der. If any or all of these files already exist, you will need to delete, move or rename them.

    Do not use any keys that are supplied with KeyMaster. Generate your own keys for production environments (see next step)

  4. Now run the Key Generator. This is the Java class com.caplin.keymaster.keygenerator.KeyGenerator, which is included in /lib/keymaster.jar.

    The Key Generator requires two command line arguments:

    • The name of the properties file that will be used to create the keys

    • An identifier for the key

    The identifier can be set to any string value. The same identifier must be passed as the property encrypting.generator.key.identifier to KeyMaster.getKeyMaster(props). Remember the value that you have chosen. You will need this for the next stage.

<Your_KeyMaster_dir> should now contain the newly generated key files: privatekey.store, publickey.store and publickey.der.

In the case that a key file with the same name as that specified in keygen.props already exists in <Your_KeyMaster_dir>, Key Generator will overwrite the old key file and will display a message similar to this:

Adding the private key replaced the existing key for the same server:
com.caplin.keymaster.encrypted.PrivateKeyStoreElement@d1fa5
Retrieved a KeyStoreElement containing a public key from input key store
for name keyid1
Adding the public key replaced the existing key for the same server:
com.caplin.keymaster.encrypted.PublicKeyStoreElement@134e4fb"

2. Single Sign-on set up

KeyMaster must be deployed behind a single sign-on system (SSO) in order to securely generate log-in tokens that contain credentials belonging to authorised users. The SSO system is responsible for authenticating a user and passing the username on to the KeyMaster.

If you do not already have an existing SSO system in place, you will need to set one up:

Follow your Java web container documentation for detailed procedures on how to set up an SSO.

3. Deploy the Java servlet

You need to create a KeyMaster servlet. To assist you, there is a servlet in KeyMaster<version> that you can use as an example. This is JndiKeyMasterServlet.java. This can later be adapted and modified as you require.

It is strongly recommended that you use the JndiKeyMasterServlet implementation as a basis for your own Single Sign-on (SSO) integration. You should write your own implementation based on the example provided for the JndiKeyMasterServlet.

Follow the steps below:

  1. First follow this guide to make server configurations for the Java servlet before deploying.

  2. Now deploy your KeyMaster servlet (based on the JndiKeyMasterServlet.java example) in a WAR file on to your server. The bouncy castle encryption JAR (bcprov-jdk<version>.jar) must also be included in the WAR if you intend to implement the bouncy castle encryption algorithm.

Do not use the KeyMaster.war file in the installation package as your servlet. It is important to base your servlet on the JndiKeyMasterServlet.java example, and then deploy this to your web server in a WAR file.

Once you have deployed your servlet to the application server and installed your credentials; installed and configured the server; and configured KeyMaster to work with the server; the run-time module of KeyMaster will be able to generate user credentials tokens for the server to pass back to requesting clients (see next section). The servlet will return a token for StreamLink to log in to the Liberator.

Validate the deployment of the Java servlet

Once you have deployed and configured the Java servlet, we will want to validate that it has been deployed successfully.

  1. Go to the URL of your KeyMaster servlet in a browser. If the servlet has been configured as outlined in KeyMaster servlets, then the URL will be <server url>/<war name>/servlet/StandardKeyMaster.

  2. You should be prompted to log in. Log in with the user that you added to the role configured in the security-constraint in the Server configuration guide.

  3. Once you have logged in, you should see the KeyMaster token in your web browser:

    credentials=ok
username=admin
token=hf46Rt6wNOwAryZji9Eeu5ADkbSzLxoq93yUsf5w3da56atw0vB/gEQOpBi/O5xSgxI3Ixw7QA3kz6oVkmdpa2XbQCxCZa/HebBu1sSnEMm+dmJrceg6cvVVxqL2FCDZFceUfd2ThWunecU4VwbNXT2puDNsDX4dvFuyip2qwDY=~20140411112017~0~~~admin

4. User Setup

Before you can set up KeyMaster, you need to set up users to use the system. Details of how to set up user authentication and permissioning are here.

Next steps

Now see the Hardening KeyMaster security guide for information on making KeyMaster production ready.