> For the complete documentation index, see [llms.txt](https://docs.keeper.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.keeper.io/keeperpam/secrets-manager/integrations/entrust-hsm.md).

# Entrust HSM Encryption

<figure><img src="/files/ULS6vy5bX8lKkFab02Rl" alt=""><figcaption></figcaption></figure>

Keeper Secrets Manager integrates with Entrust HSM in order to provide encryption for Keeper Secrets Manager configuration files. With this integration, you can protect connection details on your machine while taking advantage of Keeper's zero-knowledge encryption of all you secret credentials.

## Features

* Encrypt and Decrypt your KSM configuration files with Entrust HSM
* Protect against unauthorized access to your Secrets Manager connections
* Requires only minor change to code for immediate protection. Works with all KSM Python SDK functionality

## Prerequisites

* Supports the [Python Secrets Manager SDK](/keeperpam/secrets-manager/developer-sdk-library/python-sdk.md)
* Requires Python 3.9.2+
* The Python module needs to be built as a nShield native application using `nfpython` modules from the SDK ISO image (Entrust nShield Security World 12.80 or later)
* Virtualenv is recommended

{% hint style="warning" %}
**v1.1.0 Python version requirement:** The umbrella `keeper-secrets-manager-storage` package requires Python 3.9.2+. The Entrust nShield SDK ships Python 3.8.5, which is **incompatible with v1.1.0**.

You have two options:

* **Stay on v1.0.x** with the bundled Entrust Python 3.8.5: pin with `pip3 install "keeper-secrets-manager-storage<1.1.0"`.
* **Upgrade to v1.1.0** using a separately installed Python 3.9.2+ interpreter (Linux or Windows) for your venv, then install `nfpython*.whl` into that venv. Contact Entrust Support for guidance on using nShield Python 3 support with a non-bundled Python interpreter.
  {% endhint %}

## Setup

### 1. Create and Configure Virtualenv

This step is optional, but recommended for development

{% tabs %}
{% tab title="Linux" %}
Create a virtualenv environment to work in

`/opt/nfast/python3/bin/python3 -m venv --copies venv`

Activate the virtualenv environment before starting development

`. venv/bin/activate`
{% endtab %}

{% tab title="Windows" %}
Create a virtualenv environment to work in

`c:\Program Files\nCipher\nfast\python3\python --copies -m venv venv`

Activate the virtualenv environment before starting development

`venv\Scripts\activate.ps1`
{% endtab %}
{% endtabs %}

### 2. Install KSM Storage and nfpython Modules

The Secrets Manager HSM modules are located in the Keeper Secrets Manager storage module which can be installed using pip

```
pip3 install keeper-secrets-manager-storage
```

The nfpython package also needs to be installed in order to utilize the Entrust HSM. This package is installed as part of the nShield package with your Entrust installation.

In Linux:

```
pip install /opt/nfast/python3/additional-packages/nfpython*.whl 
```

In Windows:

```
pip install c:\Program Files\nCipher\nfast\python3\additional-packages\nfpython*.whl
```

### 3. Add Entrust HSM Storage to Your Code

Use the `HsmNfastKeyValueStorage` as your Secrets Manager storage in the `SecretsManager` constructor.

The `HsmNfastKeyValueStorage` requires the method and identity ("simple" and "ksmkey" respectively in this example).

{% hint style="info" %}
**Upgrading from v1.0.x?** v1.1.0 includes these behavioral changes:

* `decrypt_config()` now defaults to `autosave=False` — call `decrypt_config(autosave=True)` to preserve the previous behavior.
* Corrupt or empty decrypt output now raises `"is not a valid encrypted config file"` instead of leaking `JSONDecodeError`.
* Non-UTF8 bytes that are not a valid encrypted blob also raise the same error.
* Encrypt and decrypt failures now raise exceptions instead of silently corrupting storage state.
* Config writes are now atomic (write-then-rename), so a failed write no longer truncates the existing config to zero bytes.
* `delete_all()` now removes the encrypted config file from disk instead of writing an empty encrypted blob.
* `HsmNfastKeyValueStorage` is now thread-safe for concurrent reads and writes.
  {% endhint %}

{% code title="entrust\_hsm\_example.py" %}

```python
from keeper_secrets_manager_core import SecretsManager
from keeper_secrets_manager_hsm.storage_hsm_nfast import HsmNfastKeyValueStorage

config=HsmNfastKeyValueStorage('simple', 'ksmkey', 'client-config.json')

secrets_manager = SecretsManager(config=config, verify_ssl_certs=True)

all_records = secrets_manager.get_secrets()

```

{% endcode %}

{% hint style="success" %}
You're all set and ready to use Secrets Manager with Entrust NShield HSM
{% endhint %}

## Using Secrets Manager with Entrust HSM

Once setup, the Secrets Manager Entrust integration supports all Secrets Manager SDK functionality. Your code will need to be able to access the nShield HSM in order to manage the decryption of the configuration file when run.

{% hint style="info" %}
Check out the [KSM SDKs documentation](/keeperpam/secrets-manager/developer-sdk-library.md) for more examples and functionality
{% endhint %}

### Create an Encryption Key for Testing

In order to test encryption with the Entrust nShield HSM, use the following command:

Replace "ksmkey" in these examples with the identity in your HSM.

in Linux:

```bash
/opt/nfast/bin/generatekey -b simple protect=module type=AES size=256 ident=ksmkey
```

in Windows:

{% code overflow="wrap" %}

```bash
c:\Program Files\nCipher\nfast\bin\generatekey -b simple protect=module type=AES size=256 ident=ksmkey
```

{% endcode %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.keeper.io/keeperpam/secrets-manager/integrations/entrust-hsm.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.