HSM Channel Introduction

The hsmchannel component implements a ActiveSpaces Transactions Channel Framework client channel which provides access to Host Security Module (HSM) devices. HSM devices provide a rich set of cryptographic services to clients which access the device over TCP/IP network connections. The channel implements support for a specific subset of HSM requests and responses.

The hsmchannel component supports the following HSM devices:

  • Thales Host Security Module 8000

The hsmchannel component includes a set of classes which implement the basic constructs of a ActiveSpaces Transactions Channel Framework channel, such as Service and Endpoint. The component also includes a set of classes which encapsulate the HSM requests and responses supported by the channel.

For a more detailed description of the various classes implemented in the component, please see the enclosed source, javadoc, and example class descriptions.

HSM Channel Overview

The main control point of the component is the Service class, which manages the lifecycle of the Channel Framework service, and acts as a container for one or more Endpoint instances. Endpoint creation occurs via the Service, and allows for the configuration of one or more Sessions, or connections to HSM devices. The Endpoint may then be used to send requests to the connected HSM devices, and is used by the channel to deliver responses to the ActiveSpaces Transactions Channel Framework application handler.

The channel implements a priority-based Session selection facility. Applications may configure the priority of each Session defined for a specific Endpoint. The channel then uses the priority when selecting a Session to use to send requests to an HSM device. This facility allows applications to implement both load balancing across multiple HSM devices, and failover from a primary to a backup HSM device, in a manner which is transparent to the business logic of the application.

HSM Simulator

The channel implements an HSM simulator, intended to facilitate testing. The simulator provides a simple simulation of an HSM device, which accepts TCP client connections.

The simulator supports a limited set of HSM requests:

  • Key Generation
  • Key Translation
  • PIN Re-encryption

The simulator supports single, double and triple-length DES keys. It also provides a facility for instrumentation of correlated requests and responses, to facilitate testing. If no instrumented response for a given request is found, the simulator returns a default response, specific to the request being processed.

Operational control of the simulator is provided via an instance of com.kabira.examples.hsmchannel.hsm.simulator.Server. This class provides simulator server lifecycle operations, and the request/response instrumentation facility. This class also allows the setting of the listener port to be used by the simulator (the default is 9999).

Usage

The primary use hsmchannel is for applications to access HSM devices, rather than as a stand-alone application itself. However, the channel does contain two classes which demonstrate how the channel may be used by applications:

  • Main
  • Application

The Main class shows how the channel is used to establish connectivity with HSM devices, by creating a Service and an Endpoint with a set of configured Sessions. Main also illustrates how HSM requests may be sent to HSM devices via an Endpoint. Main uses an HSM simulator service to process HSM requests.

The channel's Application class is a ActiveSpaces Transactions Channel Framework application handler class which demonstrates how HSM responses may be consumed by an application.

Here is the Maven command used to execute the example:

mvn -Dcom.kabira.fluency.administrationPort=2000 \
      -Dcom.kabira.fluency.hostName=kabira-server.local \
      compile deploy:exec

NOTE: kabira-server.local only works on OS X. Other platforms may use a different name or have to specify an IP address.

Dependencies

See the Dependencies page for information on the channel's dependencies.

For each dependency listed in the Project Dependencies section of the Dependencies page, the channel's POM (or parent POM) defines a property specifying the version of the dependency used by the channel. These properties can be overridden if there is a need to change the dependency versions used by the channel. The names of these properties are of the form com.tibco.groupId.artifactId.version where groupId and artifactId are the group id and artifact id of the dependency. For example, the property named com.tibco.com.tibco.ast.version specifies the version of the dependency with the group id of com.tibco and the artifact id of ast.