This page will take you through the process of installing versions of KeyMaster older than 6.2.0.
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
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
Follow these steps to generate the keys:
Make sure you have the following JAR files. These should be present in the
\libdirectory of your KeyMaster installation:
The Bouncy Castle encryption 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.jarwhich is compatible with Caplin Trader 1 and 2. However, the version
bcprov-jdk14-1.46.jaris required for Caplin Trader 3.
The KeyMaster JAR containing all the classes KeyMaster needs to execute (
KeyMaster uses a properties file
keygen.propsthat is used to initialise and configure the Key Generator. There is an example
keygen.propsfile 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.
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.propsproperties file provided with the install kit, then you should check your KeyMaster installation directory for files called
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)
Now run the Key Generator. This is the Java class
com.caplin.keymaster.keygenerator.KeyGenerator, which is included in
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
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:
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
Follow the steps below:
First follow this guide to make server configurations for the Java servlet before deploying.
Now deploy your KeyMaster servlet (based on the
JndiKeyMasterServlet.javaexample) 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
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.
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.
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.
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.
Now see the Hardening KeyMaster security guide for information on making KeyMaster production ready.