Installing KeyMaster

Note: 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 comes with a default set of digital encryption keys for encrypting credential tokens. These digital keys are not supported for production use.

To generate a set of keys for production use, run the script below (OpenSSL required):

#!/bin/bash

# Generate a new 2048-bit RSA private key in PKCS#1 format (required by KeyMaster .NET)
openssl genrsa -out privatekey_pkcs1.pem 2048

# Convert the PKCS#1 key file to PKCS#8 format (required by KeyMaster Java)
openssl pkcs8 -topk8 -inform PEM -outform PEM -in privatekey_pkcs1.pem -out privatekey_pkcs8.pem -nocrypt

# Export the public key in DER format (required by Liberator)
openssl rsa -in privatekey_pkcs1.pem -pubout -outform DER -out keymaster_public.der

To configure KeyMaster Java to use the new PKCS#8 private key, privatekey_pkcs8.pem, see KeyMaster Servlets.

To provide Liberator with the public key, keymaster_public.der, see Installing Liberator.

2. Set up single sign-on

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 here, the URL will be <server url>/<war name>/servlet/StandardKeyMaster. 
  2. 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 will see the KeyMaster token in your web browser.

    Example (for user role 'admin'):

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

4. Setup users

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.