Packages
Package	Description
com.caplin.keymaster	The interfaces and classes that provide the main features of KeyMaster for Java
com.caplin.keymaster.permissioning	The Permissioning namespace contains interfaces and classes that are used to supply permissioning information to the `tokenauth` Liberator authentication module.

KeyMaster Java Overview

This document provides reference information about the KeyMaster Java API. For an explanation of what Caplin KeyMaster is and how it can be used, see the Caplin KeyMaster Overview.

KeyMaster Java is used to implement a Java application that generates KeyMaster user credentials tokens. The token generator application is typically deployed as a Java Servlet, and will work with client applications that use any of Caplin's StreamLink libraries to communicate with a Liberator. An example Servlet is provided in the KeyMaster Java kit (see the examples folder).

KeyMaster Java is supplied as a class library providing an API that allows easy integration into your existing Java infrastructure. The API consists of:

A main class KeyMaster
Three interfaces (IAuthenticationParameters, IKeyMasterConfiguration, IKeyMasterFormatter).
Some implementations of these interfaces.

Additionally, if you are using the tokenauth Liberator authentication module, your KeyMaster application must provide permissioning information to this module using interfaces and classes defined in the com.caplin.keymaster.Permissioning namespace.

Conventionally, access to the URI providing KeyMaster services would be protected behind a single sign-on (SSO) implementation, thus ensuring that only authenticated users are permitted access to the data provided by a Liberator.

Terminology

In the API definitions, "user credentials tokens" are referred to as "tokens", for brevity.

Key pair generation

KeyMaster authentication depends on the user credentials token being signed using public key cryptography; the KeyMaster token generator signs the token using a private key and the Liberator uses the corresponding public key to verify the signature and thus verify the authenticity of the token. Before KeyMaster can be used, a suitable public/private key pair must be generated..

The file containing the private key should be in PKCS#8 PEM format. You can also implement the IKeyMasterConfiguration interface to support loading the private key from a file in the format of your choice. The API includes an implementation of this interface that load the private key from a PKCS8 PEM file (PEMPKCS8KeyMasterConfiguration).

The corresponding public key must be in DER format.

You can easily generate a private key in PKCS#8 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 http://www.openssl.org/docs.

openssl genrsa -out privatekey_openssl.pem

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

To convert this to a standard PKCS#8 PEM file use the following command.

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

To create a public key in DER format from the private key.

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

The publickey.der file is used by the Liberator to verify the signature.

Example Servlets

The kit contains source for two example servlets, one configured using standard servlet parameters and the other using jndi parameters.

A war file containing the example, StandardKeyMasterServlet, servlet is also included in the deploy directory.

To run the StandardKeyMasterServlet example, first deploy the war to your webserver and then configure the parameters in the associated servlet web.xml.

Also configure the servlet to require user authentication via security constraints (example config for basic authentication is included in the web.xml).

The following servlet parameters can be specified in the web.xml:

`Parameter`	Type	Description
`caplin.keymaster.privatekey.filename`	Required	The location of the PEM PKCS#8 formatted private key file relative to the webapp.
`caplin.keymaster.hashing.algorithm`	Optional	Hashing algorithm name, see KeyMasterHashingAlgorithm for the possible values, default is SHA256
`caplin.keymaster.security.provider.class.name`	Optional	Class name of a security provider to add to those available.
`caplin.keymaster.security.provider.name`	Optional	Name of security provider to use for the token generation.
`caplin.keymaster.cors.allow.origin`	Optional	To allow cross origin requests (CORS) specify the allowed origin to be used in the 'Access-Control-Allow-Origin' response header (for example 'http://localhost:3000')

Once the servlet is configured and deployed you will be able to generate keymaster tokens in your browser by visiting the url:


   [your app server address]/keymaster/servlet/StandardKeyMaster

this should generate a response of the form:

credentials=ok
username=tomcat
token=gnZXNVZFsuimWUpSoRrI59iN+OcC1N4G3xAQu/Kgg1seLR1LqI4POssgTdzmG6/aEWPNZNldK+mIB9/c1Ynrb1R2g6SPFKA5BQSgFluZmj8EFapWlfUX6fBps+Qsx6r8aFk4N4+iRnRIEp31A3TweR1tPcmj4C9hNPuhkXmctt0kVpdWg6J6y96jGZqdqMGXt4XmFTZ1O6odQVAnuYPrc4K2HeSD5r/xzr2qq8F1EpalQL3Yj3db2MjjFj7Bgd2TUcX+quvOdb6MD71tdg7vRFgnoUxquVjX1Q5+qHeuaduqqIzEqAy+spYI7PrWAOcWq0XsGKLylOYBCY4C+WBBig==~20150415140752~1~~~tomcat

API Usage

A KeyMaster instance should be instantiated using a IKeyMasterConfiguration instance to specify the location of the private key and the hashing algorithm to use.

The follow example uses a PEM formatted private key and the default SHA256 hashing algorithm:

import com.caplin.keymaster.IKeyMaster;
import com.caplin.keymaster.IKeyMasterConfiguration;
import com.caplin.keymaster.KeyMaster;
import com.caplin.keymaster.KeyMasterHashingAlgorithm;
import com.caplin.keymaster.PEMPKCS8KeyMasterConfiguration;

public class CreatingKeyMasterInstance
{
        private static final String PEM_FILE_LOCATION = "c:\\private.pem";
        
        public IKeyMaster createKeyMasterInstance() throws Exception
        {
                // Create a KeyMaster configuration using a private key stored as a PEM format file.
                // This constructor may throw an exception; handling of it has been omitted for clarity.
                IKeyMasterConfiguration configuration = new PEMPKCS8KeyMasterConfiguration(PEM_FILE_LOCATION, KeyMasterHashingAlgorithm.SHA256, null);
                
                // Create a keymaster instance.
                IKeyMaster keymaster = new KeyMaster(configuration);
                
                return keymaster;
        }
}

Once instantiated, KeyMaster tokens can be retrieved using the com.caplin.keymaster.Keymaster.generateToken method.

The following example generates a token and returns it formatted using the StandardFormatter formatter.

import com.caplin.keymaster.AuthenticationParameters;
import com.caplin.keymaster.IAuthenticationParameters;
import com.caplin.keymaster.IKeyMaster;
import com.caplin.keymaster.IKeyMasterFormatter;
import com.caplin.keymaster.StandardFormatter;

public class RetrievingATokenUsingTheStandardFormatter
{
        public String retrieveToken(IKeyMaster keymaster, String liberatorUsername)
        {
                // Create a set of IAuthenticationParameters for this user.
                IAuthenticationParameters authParams = new AuthenticationParameters(liberatorUsername);
                
                // Create a new formatter instance (they can be reused).
                IKeyMasterFormatter formatter = new StandardFormatter();
                
                // Generate and return the KeyMaster token.
                return keymaster.generateToken(authParams, formatter);
        }
}

Configuration

As KeyMaster Java can only be configured programmatically, it does not explicitly have any dependencies on external resources. The default configuration implementations PEMPKCS8KeyMasterConfiguration will load the private key from a file on disc. However, this behaviour can be altered using the IKeyMasterConfiguration interface and implementing your own configuration mechanism.

Output formatters

KeyMaster tokens can be output in different formats, according to the needs of the client that requires the token. The StandardFormatter is suitable for use with StreamLink, using the standard KeyMaster CredentialsProvider supplied with the APIs.

Should your application require an alternate format, you can implement the IKeyMasterFormatter interface and supply an instance of it to the com.caplin.keymaster.KeyMaster.generateToken method call. You might also need to write a custom credentials provider for your StreamLink application.

Converting Private Keys From Previous Version of KeyMaster

The previous version of KeyMaster for Java stored private keys in a serialized map of values. To convert keys stored in this format to PKCS#8 PEM format files a utility is provided. This utility is contained in the lib/KeyMasterLegacy-[version] jar file.

To convert an old KeyMaster keystore file to a PKCS#8 PEM file run the following command:

java -jar KeyMasterLegacy-[version].jar privatekey.store private.pem