KeyMaster
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 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 generateToken
method call. You might also need to write a custom credentials provider for
your StreamLink application.