# Integrate enclaive vHSM with Utimaco HSM ### Prerequisites 1. Download and install Utimaco Security Server software. 2. Update the `cs_pkcs11_R3.cfg` configuration file. 3. Create a Security Officer (SO) User and initialize a slot. For more information about downloading, installing, Utimaco Secirity Server Software, see the [Utimaco integration guide](https://utimaco.com/integration-guides/enclaive-vhsm-utimaco-utrust-general-purpose-hsm) To integrate enclaive vHSM with Utimac HSM you need to perform these steps: 1. [Install enclaive vHSM](#install-enclaive-vhsm-in-a-docker-container) 2. [Configure enclaive vHSM ](#configure-enclaive-vhsm-to-run-with-utimaco-hsm) 3. [Test the integration](#test-vhsm-integration-with-utimaco-hsm) 4. [Enable entropy augmentation](#enable-entropy-augmentation) ### Install enclaive vHSM in a Docker container 1. Create the *vhsm* group : `groupadd vhsm` 2. Create the *vhsm* User : `useradd --gid vhsm vhsm` 3. Pull the latest image: `docker pull harbor.enclaive.cloud/vhsm/vhsm-utimaco:latest` 4. Set the enterprise license key that you received as an environment variable: `export ENCLAIVE_LICENCE=` 5. Download and install the vHSM CLI to interact with enclaive vHSM: `wget https://vhsm.enclaive.cloud/static/vhsm` 6. Create a directory for the vHSM configuration file, data, and certificates ``` # mkdir /etc/vhsm # mkdir /opt/utimaco ``` ### Configure enclaive vHSM to run with Utimaco HSM To configure the vHSM, you need to set up vHSM first. Outside of development mode, vHSM servers are configured using a persistent storage method. 1\. Create a `/etc/vhsm/config` file and add the following contents: {% hint style="info" %} **Note**: Ensure that the slot number and slot PIN are per your Utimaco setup. {% endhint %} ``` # Configure Seal with Utimaco SecurityServer seal "pkcs11" { lib = "/opt/utimaco/lib/libcs_pkcs11_R3.so" slot = "" pin = "" key_label = "hsm_demo" hmac_key_label = "demo" generate_key = "true" r3_config = "/opt/utimaco/cs_pkcs11_r3.cfg" } ui = true disable_mlock = true # Configure the storage backend storage "file" { path = "/etc/vhsm/data" } listener "tcp" { address = "0.0.0.0:8200" tls_disable = true } ``` 2\. Start the enclave vHSM server to run with Utimaco HSM. ``` docker run --cap-add=IPC_LOCK -p 8200:8200 \ -e ENCLAIVE_LICENSE=$ENCLAIVE_LICENSE \ harbor.enclaive.cloud/enclaive-dev/vhsm:latest \ server -config /etc/vhsm/config.json ``` 3\. Check the status of vHSM server: `vhsm status` The output is similar to: ``` vhsm status Key Value --- ----- Seal Type pkcs11 Initialized false Sealed true Total Shares 0 Threshold 0 Version 1.3.2-0 heads/main-0-g1b8bb7c 2024-10-10T01:15:29+00:00 Build Date n/a Storage Type file HA Enabled false ``` 4\. Initialize vHSM to use the HSM initial token value: `vhsm operator init` The output is similar to: ``` [root@enclaive bin]# vault operator init Recovery Key 1: ovZbTXwkQnatlgla7KD5fcZW4rSv4WJkf8ogwR2KoN0 Recovery Key 2: RxZhmLQ24XGWbhwhr2OiP6VcOVhKWSNzY+63EVM6cVTH Recovery Key 3: m0xO/kpDG+OneZylWx8o6gyFZ6acl6eeNnrsYyTWk+ls1 Recovery Key 4: qL45SP/uKTspXdeExFgx0P22rjy5eHncvIY0Y1B9UC83 Recovery Key 5: twdDxXfjKXEgkIO+vJ6sB+794bHVqzWh3QTVLSzpYfg Initial Root Token: hvs.KxttXNOYSLu16KGEd1cyKpm5 Success! Vault is initialized Recovery key initialized with 5 key shares and a key threshold of 3. Please securely distribute the key shares printed above. ``` 5\. Verify that the keys got generated into the HSM: `p11tool2 slot= loginuser= listobjects` The output is similar to: ``` root@enclaive ~]# p11tool2 slot=26 loginuser=12345678 listobjects CKO_SECRET_KEY: + 1.1 CKA_KEY_TYPE = CKK_AES CKA_UNIQUE_ID = 6AA56EFD-DA57-4488-926C-9D54B554B055 CKA_SENSITIVE = CK_TRUE CKA_EXTRACTABLE = CK_FALSE CKA_LABEL = hsm_demo CKA_ID = 0x32333333 34313737 3138 | 2333417718 | + 1.2 CKA_KEY_TYPE = CKK_GENERIC_SECRET CKA_UNIQUE_ID = A82D49E9-44EB-462C-8216-4F78BB8B9646 CKA_SENSITIVE = CK_TRUE CKA_EXTRACTABLE = CK_FALSE CKA_LABEL = demo CKA_ID = 0x32333530 36323337 3632 | 2350623762 | ``` 6\. Check the status of vHSM again to verify that it is initialized and unsealed: `vhsm status` The output is similar to: ``` Key Value --- ----- Seal Type shamir Initialized true Sealed false Total Shares 1 Threshold 1 Version 1.4.3-1 Build Date n/a Storage Type inmem Cluster Name vault-cluster-58e9dc60 Cluster ID 1abf9eb1-3ae1-1652-7058-e9d73b08d105 HA Enabled false ``` 7\. Log in to vHSM using the initial Root token that you saved: `vhsm login ` The output is similar to: ``` root@enclaive ~ % vhsm login Token (will be hidden): Success! You are now authenticated. The token information displayed below is already stored in the token helper. You do NOT need to run "vhsm login" again. Future vHSM requests will automatically use this token. Key Value --- ----- token hvs.hidxumzILZ6yk044XQC07bxS token_accessor E5leo0H9hmyinJ0n8eqfTtH5 token_duration ∞ token_renewable false token_policies ["root"] identity_policies [] policies ["root"] Cluster ID 1abf9eb1-3ae1-1652-7058-e9d73b08d105 HA Enabled false ``` ## Test vHSM Integration with Utimaco HSM After configuring vHSM with Utimaco HSM you can test the integration by viewing the secrets, enabling the Secrets Engine, seal wrapping the secret data, and retrieving the secret data. 1\. View the current secrets and the default locations: `vhsm secrets list` ``` root@enclaive ~ % vhsm secrets list Path Type Accessor Description ---- ---- -------- ----------- cubbyhole/ cubbyhole cubbyhole_ae9dbaf0 per-token private secret storage identity/ identity identity_55ca36ed identity store secret/ kv kv_a9126082 key/value secret storage sys/ system system_620d7ac5 system endpoints used for control, policy and debugging ``` 2\. Enable the KV engine: `vhsm secrets enable -version=1 kv` ``` root@enclaive ~ % vhsm secrets enable -version=1 kv Success! Enabled the kv secrets engine at: kv/ ``` 3\. View the details of the Secrets Engine that you enabled: `vhsm secrets list -detailed` ``` root@enclaive ~ % vhsm secrets list -detailed Path Plugin Accessor Description Default TTL Max TTL Force No Cache Replication Seal Wrap External ---- ------ -------- ----------- ------------ ------- --------------- ------------ ---------- -------- cubbyhole/ cubbyhole cubbyhole_c249bae per-token private secret storage n/a n/a false local false n/a map[] v1.4.3+builtin.vault n/a n/a identity/ identity identity_4e8eed82 identity store system system false replicated false n/a map[] v1.4.3+builtin.vault n/a n/a secret/ kv kv_e2b17a6d key/value secret storage system system false replicated false false map[version:2] v1.5.0+builtin.vault supported n/a sys/ system system_324f2e96 system endpoints used for control, n/a n/a false replicated true false policy and debugging map[] v1.4.3+builtin.vault n/a n/a ``` 4.To test the seal wrap feature, add secret data to the key/value storage of vHSM: `vhsm kv put kv /opt/vhsm/secret key=test_secret` ``` root@enclaive ~ % vhsm kv put kv/opt/vhsm/secret key=test_secret Success! Data written to: kv/opt/vhsm/secret ``` 5\. Retrieve the secret data from vHSM storage: `vhsm kv get kv /opt/vhsm/secret` ``` root@enclaive ~ % vhsm kv get kv/opt/vhsm/secret === Data === Key Value --- ----- key test_secret ``` ### Enable Entropy Augmentation Entropy augmentation allows Vault Enterprise to supplement its system entropy with entropy from an external cryptography module. Designed to operate in environments where alignment with cryptographic regulations like NIST SP800-90B is required or when augmented entropy from external sources such as hardware true random number generators (TRNGs) augmented entropy replaces system entropy when performing random number operations on critical security parameters (CSPs). \ 1\. Update the `/etc/vhsm/config` file and add the following contents: {% hint style="info" %} **Note**: Ensure that the slot number and slot PIN are per your Utimaco setup. {% endhint %} ``` # Configure Seal with Utimaco SecurityServer seal "pkcs11" { lib = "/opt/utimaco/lib/libcs_pkcs11_R3.so" slot = "" pin = "" key_label = "hsm_demo" hmac_key_label = "demo" generate_key = "true" r3_config = "/opt/utimaco/cs_pkcs11_r3.cfg } ui = true disable_mlock = true # Configure the storage backend storage "file" { path = "/etc/vhsm/data" } listener "tcp" { address = "0.0.0.0:8200" tls_disable = true } # vHSM configuration to use Utimaco PKCS#11 for entropy augmentation entropy "seal" { mode = "augmentation" } ``` \ 2\. Restart the vHSM service: `docker restart ` 3\. Log in to vHSM using the initial Root token that you saved. `vhsm login ` 4\. Execute the following command to enable transit secrets engine with external entropy source using the \` -external-entropy-access\` flag: `vhsm secrets enable -external-entropy-access transit` ``` [root@enclaive ~]# vhsm secrets enable -external-entropy-access transit Success! Enabled the transit secrets engine at: transit/ ``` 5\. List the enabled secrets engine with -detailed flag: `vhsm secrets list -detailed` ``` [root@enclaive ~]# vhsm secrets list -detailed Path Plugin Accessor Default TTL Max TTL Force No Cache Replication Seal Wrap External Entropy Options Version Running Version SHA256 Deprecation Status UUID Running ---- ------ -------- ------------ ------- --------------- ------------ --------- ------------------ cubbyhole/ cubbyhole cubbyhole_13b27c27 n/a n/a false local false false map[] per-token private secret storage n/a 89cf788b-bc6d-40cb-513d-786ece92afd3 n/a v1.4.3+builtin.vault n/a identity/ identity identity_8f414177 n/a n/a false replicated false false map[] identity store system system system 2bca948c-f41b-0602-5893-3fb4bd40faa5 n/a v1.4.3+builtin.vault n/a secret/ kv kv_768a1b40 n/a n/a false replicated false false map[version:1] key/value secret storage n/a 6818492d-20e5-97bf-1a35-0e2d522d1479 n/a v0.14.2+builtin supported n/a sys/ system system_3b8d717be n/a n/a false replicated false false map[] system endpoints used for control, policy and debugging 925f31a3-74da-9266-e91b-245b94872ba6 n/a v1.4.3+builtin.vault n/a transit/ transit transit_d9b2c2a9 n/a n/a false replicated false true map[] n/a system system system 6818492d-20e5-97bf-1a35-0e2ba6fd9e24 n/a v1.4.3+builtin.vault n/a ``` {% hint style="info" %} **Note**: The External Entropy Access is set to true for transit. {% endhint %} 6\. You can start using the transit secrets engine to encrypt your sensitive data which leverages the HSM as its external entropy source. Now create a new encryption key named, "orders". `vhsm write -f transit/keys/order` ``` [root@enclaive ~]# vhsm write -f transit/keys/orders Success! Data written to: transit/keys/orders ``` 7\. Send a base64-encoded string to be encrypted by vHSM: `vhsm write transit/encrypt/orders plaintext=$(base64 <<< “4111 1111 1111 1111”)` ``` root@enclaive ~ % vhsm write transit/encrypt/orders plaintext=$(base64 <<< "4111 1111 1111 1111") Key Value --- ----- ciphertext vault:v1:mBBYBUoICZ/gXgK9k9yPmWA+2b6upmZMlWqQEytiLyGa6aGbqpn0HfQxpi89aJ key_version 1 ``` 8\. Verify that you can decrypt: `vhsm write transit/decrypt/orders`\ `ciphertext=vault:v1:mBBYBUoICZ/igXKgkb9YPmWA+2b6upmZM1WqQEyiiyGa6aq6bpqn0Hfqxpi89aJ` ``` root@enclaive ~ % vhsm write transit/decrypt/orders \ ciphertext=vault:v1:mBBYBUoICZ/gXgK9k9yPmWA+2b6upmZMlWqQEytiLyGa6aGbqpn0HfQxpi89aJ Key Value --- ----- plaintext NDE xMSAxMTE xIDE xMTEgMTE xMQo= 1 ``` 9\. Decode to get the original value: `base64 --decode <<< NDExMSAxMTExIDExMTEgMTExMQo=` ``` root@enclaive ~ % base64 --decode <<< NDEzMSAxMTEzIDEzMTEgMTEzMQo= 4111 1111 1111 1111 ``` --- # Agent Instructions: 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.enclaive.cloud/virtual-hsm/integrations/integration-with-utimaco-securityserver/integrate-enclaive-vhsm-with-utimaco-hsm.md?ask= ``` 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.