> ## Documentation Index
> Fetch the complete documentation index at: https://docs.futurex.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation of jPOS

> How to install and configure jPOS Template to work with the Futurex Excrypt HSM.

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.**](https://github.com/jpos/jPOS-template)

**Step 1**

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

```none expandable lines wrap title="None" theme={null}
dependencies {*
   *
   *
   compile files('your/path/to/jpos-excrypt-1.0.5-SNAPSHOT.jar')
}
```

**Step 2**

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

```none expandable lines wrap title="None" theme={null}
-- dist
  -- deploy
    -- 90_excrypt_ping.xml
  -- deploy-cli
    -- 20_excrypt.xml
```

**Step 3**

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 expandable lines wrap title="Xml" theme={null}
<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

<table>
  <thead>
    <tr>
      <th>Property</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>host</td>
      <td>Excrypt host (for example, hsm.example.com)</td>
    </tr>

    <tr>
      <td>port</td>
      <td>Excrypt port (i.e. 6000)</td>
    </tr>

    <tr>
      <td>pkcs12</td>
      <td>Path to the PKCS #12 file (i.e. cfg/certificate.p12)</td>
    </tr>

    <tr>
      <td>passphrase</td>
      <td>Passphrase for the PKCS #12 file</td>
    </tr>
  </tbody>
</table>

# Accessing the adapter

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

```java expandable lines wrap title="Java" theme={null}
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 expandable lines wrap title="YAML" theme={null}
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**](https://docs.futurex.com/Integrations/HSM/Payment/jPOS/Post-integration_tasks/Validate_and_test.md))

If you would like to make the configuration values more secure, you can store the values in `cfg/default.yml`:

```yaml expandable lines wrap title="YAML" theme={null}
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]
>
> 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](https://jpos.org/doc/proguide-draft.pdf), section 3.3.

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

```xml expandable lines wrap title="Xml" theme={null}
<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>
```