KeyMaster.NET Overview

This document provides reference information about the KeyMaster.NET API. For an explanation of what Caplin KeyMaster is and how it can be used, see the Caplin KeyMaster Overview (supplied with this kit).

KeyMaster.NET is used to implement a Microsoft .NET application that generates KeyMaster user credentials tokens. The token generator application is typically deployed as an ASP.NET web page, and will work with client applications that use any of Caplin's StreamLink libraries to communicate with a Liberator (for example, StreamLink.NET, StreamLink for Silverlight, StreamLink for Browsers, or StreamLink for Java). An example ASP.NET page is provided in the KeyMaster.NET kit (see the folder Examples\ASPExample\).

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

• A main class Caplin.KeyMaster.KeyMaster
• Three interfaces (Caplin.KeyMaster.IAuthenticationParameters, Caplin.KeyMaster.Configuration.IKeyMasterConfiguration, Caplin.KeyMaster.Formatters.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 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.

Usage

A KeyMaster instance should be instantiated using a Caplin.KeyMaster.Configuration.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 MD5 hashing algorithm:

using System;
using System.Collections.Generic;
using System.Text;
using Caplin.KeyMaster;
using Caplin.KeyMaster.Configuration;

namespace KeyMasterSnippets
{
    class CreatingKeyMasterInstance
    {
        const string PEM_FILE_LOCATION = "c:\\myprivatekey.pem";

        IKeyMaster CreateKeyMasterInstance()
        {
            // 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 PEMKeyMasterConfiguration(PEM_FILE_LOCATION);

            // Create a keymaster instance.
            IKeyMaster keymaster = new KeyMaster(configuration);

            return keymaster;
        }
    }
}

Once instantiated, KeyMaster tokens can be retrieved using the Caplin.KeyMaster.Keymaster.GenerateToken method. The following example generates a token and returns it formatted using the Caplin.KeyMaster.Formatter.StandardFormatter formatter.

using System;
using System.Collections.Generic;
using System.Text;
using Caplin.KeyMaster;
using Caplin.KeyMaster.Formatters;

namespace KeyMasterSnippets
{
    class RetrievingATokenUsingTheStandardFormatter
    {
        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.NET can only be configured programmatically, it does not explicitly have any dependencies on external resources. The default configuration implementations Caplin.KeyMaster.Configuration.PEMKeyMasterConfiguration and Caplin.KeyMaster.Configuration.XMLKeyMasterConfiguration will load the private key from a file on disc. However, this behaviour can be altered using the Caplin.KeyMaster.Configuration.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 Caplin.KeyMaster.Formatters.StandardFormatter is suitable for use for StreamLink for Java, StreamLink.NET, and StreamLink for Silverlight, using the standard KeyMaster CredentialsProvider supplied with the APIs.

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