Installing KeyMaster

These are the installation instructions for KeyMaster version 6.2.0 onwards. For older versions of KeyMaster, see here.

This page will take you through the process of installing KeyMaster. You may already have KeyMaster installed as part of your Caplin Platform. If so, you do not need to follow the below steps as they are intended for users who do not have KeyMaster on their current systems.

Prerequisites

You need to have the following already installed:

  • An Application Server

  • Java 7 or .NET framework 3.5

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

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

Synchronising the server clocks

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 and it is likely to reject all user credentials tokens for this reason.

If the clocks are not correctly synchronised 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

  2. Single Sign-on set up

  3. Deploy Java servlet

  4. User setup

1. Generate keys

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

You can easily generate a private key in PEM format, with the corresponding public key in DER format, using the following OpenSSL commands. OpenSSL is open source software. Documentation detailing how to use the OpenSSL command line tool is available on the OpenSSL web site at https://www.openssl.org/docs.

This command generates a 2048 RSA private key in OpenSSL PEM format.

openssl genrsa -out privatekey_openssl.pem
KeyMaster .Net uses private keys in OpenSSL PEM format as generated above, whilst KeyMaster Java uses private keys in PKCS#8 PEM format.

To convert the OpenSSL private key file to PKCS#8 PEM format, suitable for the KeyMaster Java, use the following command:

For Java only:

openssl pkcs8 -topk8 -inform PEM -outform PEM -in privatekey_openssl.pem -out privatekey.pem -nocrypt

To create a public key in DER format for use by the Liberator, use the following command:

openssl rsa -in privatekey_openssl.pem -pubout -outform DER -out publickey.der

Example Session:

>openssl genrsa -out privatekey_openssl.pem
Generating RSA private key, 512 bit long modulus
......++++++++++++
..........++++++++++++
e is 65537 (0x10001)

>openssl pkcs8 -topk8 -inform PEM -outform PEM -in privatekey_openssl.pem -out privatekey.pem -nocrypt

>openssl rsa -in privatekey_openssl.pem -pubout -outform DER -out publickey.der
writing RSA key

>ls
privatekey.pem  privatekey_openssl.pem  publickey.der

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

3. Deploy the Java servlet

The Java version of KeyMaster contains an example servlet call StandardKeyMasterServlet (included in the kit in source form and as a deployable war file), this can be used as is, or as the basis for you own customized servlet.

Deploy your servlet:

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

  2. Now deploy your KeyMaster servlet in a WAR file on to your server.

Once you have deployed your servlet into 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
This example is for a user-role '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.

..Finished!

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