This section describes how to install and configure jPOS Template to work with the Futurex Excrypt HSM. Before starting this section, download jPOS Template from the GitHub repository.

Within a jPOS project, add a reference to the Excrypt JAR.

None

dependencies {*
   *
   *
   compile files('your/path/to/jpos-excrypt-1.0.5-SNAPSHOT.jar')
}

Run gradle installResources to add the following QBean configuration samples to the project:

None

-- dist
  -- deploy
    -- 90_excrypt_ping.xml
  -- deploy-cli
    -- 20_excrypt.xml

Change the configuration values in 20_excrypt.xml as needed.

Excrypt Adapter

The ExcryptAdapter class encapsulates all the Excrypt command set implementation. It implements the SMAdapter interface so it can be configured and deployed as any other jPOS SMAdapter implementation. Example (20_excrypt.xml):

Xml

<ssm name="excrypt" class="org.jpos.q2.security.SMAdaptor" logger="Q2">
      <attr name="impl">org.jpos.security.excrypt.ExcryptAdapter</attr>
      <property name="host" value="hsm.example.com" />
      <property name="port" value="6000" />
      <property name="pkcs12" value="cfg/certificate.p12" />
      <property name="passphrase" value="your_passphrase" />
</ssm>

Configuration

Property	Description
host	Excrypt host (for example, hsm.example.com)
port	Excrypt port (i.e. 6000)
pkcs12	Path to the PKCS #12 file (i.e. cfg/certificate.p12)
passphrase	Passphrase for the PKCS #12 file

Accessing the adapter

The Excrypt adapter instance can be pulled off the name registrar by doing the following:

Java

ExcryptAdapter excrypt = NameRegistrar.get("excrypt");
// or
SMAdapter adapter = NameRegistrar.get("excrypt"); // Recommended

By doing the latter, the code produced will not have a direct dependency to the Excrypt implementation and will, potentially, work with any other underlying SMAdapter implementation (i.e. JCESecurityModule).

Environment provider

The Excrypt library provides a custom environment provider that helps secure configuration values.

Example

In cfg/default.yml:

YAML

example:
   config: hsm::ujNsgPW1x8edx2yUqp5kOoLxtmzjXgQytO9FRslJWSs0hQTlPIVrf1DNpXF9Hpd

When loading up the example.config value, the system will decrypt value on the fly using the HSM. The encrypted value is calculated using the ENCRYPT CLI command (see Validate and test) If you would like to make the configuration values more secure, you can store the values in cfg/default.yml:

YAML

EXCRYPT_HOST: hsm.example.com
EXCRYPT_PORT: 9100
EXCRYPT_PKCS12: ../../../application-certificate.p12
EXCRYPT_PASSPHRASE: obf::[obfuscated_pkcs12_passphrase]
hsm:
   service: excrypt
   key: obf::[obfuscated_key]

Note that sensitive configuration values have been obfuscated using jPOS’ obf CLI command. This practice is recommended and will help avoid leaking configuration values to occasional viewers. For more information on the configuration sub-system and the obf environment provider, see the jPOS Programmer’s Guide, section 3.3.

Then you can modify the values in 20_excrypt.yml:

Xml

<ssm name="excrypt" class="org.jpos.q2.security.SMAdaptor" logger="Q2">
      <attr name="impl">org.jpos.security.excrypt.ExcryptAdapter</attr>
      <property name="host" value="${EXCRYPT_HOST}" />
      <property name="port" value="${EXCRYPT_PORT}" />
      <property name="pkcs12" value="${EXCRYPT_PKCS12}" />
      <property name="passphrase" value="${EXCRYPT_PASSPHRASE}" />
</ssm>

Overview

Certificate Authority

Certificate management

Certificate validation

Code signing

Credential management

Data protection

Database

Digital signing

DNS

Firewall

Generic

IT automation and orchestration

Key management

Payment

Privileged access management

Secrets management

TLS offloading

VPN

Installation of jPOS

Excrypt Adapter

Configuration

Accessing the adapter

Environment provider

Example

​Excrypt Adapter

​Configuration

​Accessing the adapter

​Environment provider

​Example

Excrypt Adapter

Configuration

Accessing the adapter

Environment provider

Example