Integrate enclaive vHSM with Utimaco HSM
Learn how to install and configure enclaive vHSM with Utimaco HSM
Prerequisites
Download and install Utimaco Security Server software.
Update the
cs_pkcs11_R3.cfgconfiguration file.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
To integrate enclaive vHSM with Utimac HSM you need to perform these steps:
Install enclaive vHSM in a Docker container
Create the vhsm group :
groupadd vhsmCreate the vhsm User :
useradd --gid vhsm vhsmPull the latest image:
docker pull harbor.enclaive.cloud/vhsm/vhsm-utimaco:latestSet the enterprise license key that you received as an environment variable:
export ENCLAIVE_LICENCE=<licence-key>Download and install the vHSM CLI to interact with enclaive vHSM:
wget https://vhsm.enclaive.cloud/static/vhsmCreate a directory for the vHSM configuration file, data, and certificates
# mkdir /etc/vhsm
# mkdir /opt/utimacoConfigure 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:
# Configure Seal with Utimaco SecurityServer
seal "pkcs11" {
lib = "/opt/utimaco/lib/libcs_pkcs11_R3.so"
slot = "<slot_no.>"
pin = "<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.json3. 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 false4. 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=<slot_no> loginuser=<slot_PIN> 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 false7. Log in to vHSM using the initial Root token that you saved: vhsm login <initial_root_token_value>
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 falseTest 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/secret5. 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_secretEnable 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:
# Configure Seal with Utimaco SecurityServer
seal "pkcs11" {
lib = "/opt/utimaco/lib/libcs_pkcs11_R3.so"
slot = "<slot_no.>"
pin = "<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 <name_of_the_container>
3. Log in to vHSM using the initial Root token that you saved. vhsm login <initial_root_token_value>
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
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/orders7. 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 18. 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=
19. Decode to get the original value: base64 --decode <<< NDExMSAxMTExIDExMTEgMTExMQo=
root@enclaive ~ % base64 --decode <<< NDEzMSAxMTEzIDEzMTEgMTEzMQo=
4111 1111 1111 1111Last updated
Was this helpful?