vault_2.1.0+ent.hsm 1.19.3+ent.hsm
Auto Light Dark
Auto Light Dark
vault_2.1.0+ent.hsm 1.19.3+ent.hsm
Breadcrumbs

Optional Features

Enable Entropy Augmentation

Entropy augmentation allows Vault Enterprise to supplement its system entropy with entropy from an external cryptography module. It is 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), replaces system entropy when performing random number operations on critical security parameters (CSPs).

  1. Add the following to the /etc/vault/config.hcl file.

# 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"

# Vault configuration to use Utimaco PKCS#11 for entropy augmentation
entropy "seal" {
mode = "augmentation"
}

  1. Restart the Vault service.

# systemctl restart vault.service

  1. Log in to Vault using the Initial Root Token saved earlier.

# vault login <initial_root_token_value>

  1. Execute the following command to enable the transit secrets engine with an external entropy source using the -external-entropy-access flag.

# vault secrets enable -external-entropy-access transit
image-20260928-101255.png

Enable entropy augmentation

  1. List the enabled secrets engine with the -detailed flag.

# vault secrets list -detailed

Note that the External Entropy Access is set to true for transit/.

image-20260928-101441.png


List enable secret engine

  1. You can start using the transit secrets engine to encrypt your sensitive data. This engine leverages the HSM as its external entropy source. Now, create a new encryption key named "orders."

# vault write -f transit/keys/orders
image-20260928-101831.png


New encryption

  1. Send a base64-encoded string to be encrypted by Vault.

# vault write transit/encrypt/orders plaintext=$(base64 <<< "4111 1111 
1111 1111")
image-20260928-102107.png

Base64-encoded string

  1. Now, verify that you can decrypt.

# vault write transit/decrypt/orders ciphertext=vault:v1:<Ciphertext>
image-20260928-102736.png

Test decrypt operation

  1. Decode to get the original data.

# base64 --decode <<< <plaintext>
image-20260928-112023.png

Decode original data

Rotate Keys stored in the Utimaco HSM

  1. Stop HashiCorp Vault service and check the status of the service.

# systemctl stop vault.service
# systemctl status vault.service
image-20260928-112330.png


Stop vault service

  1. For rotating the keys, update the configuration file /etc/vault/config. hcl with a new key label and the old key label of the root key and hmac key in the seal “pkcs11” section, as shown below.

# vi /etc/vault/config.hcl
# PKCS#11 Seal, Utimaco HSM Integration
seal "pkcs11" {
lib = "/opt/utimaco/lib/libcs_pkcs11_R3.so"
slot = "<slot_no>"
pin = "<slot_PIN>"
default_key_label="hsm_demo"
key_label = "hsm_demo1"
default_hmac_key_label="demo"
hmac_key_label = "demo1"
generate_key = true
}

Do not delete the old keys from the HSM as the old keys will still be used to decrypt the old data. Here, default_key_label and default_hmac_key_label are old key labels. New keys will have the label values from key_label and hmac_key_label.

  1. Restart the Vault service.

# systemctl restart vault.service
# systemctl status vault.service
image-20260930-030534.png

Start vault service

  1. Verify that the keys got generated on the HSM.

# p11tool2 slot=<slot_no.> LoginUser=<slot_PIN> ListObjects
image-20260930-030915.png

List keys

  1. Log in to Vault using the Initial Root Token saved earlier.

# vault login <initial_root_token_value>

  1. Verify that you can list the secrets.

# vault secrets list -detailed
image-20260930-031627.png

List the secret keys

  1. Verify that you can retrieve the secret data.

# vault kv get kv/opt/vault/secret
image-20260930-031852.png

Retrieve secret data

Migrate from Shamir Seal to Utimaco PKCS11 Seal

You can migrate the existing Vault encrypted with the Shamir seal (the default software-based seal) to the Utimaco PKCS11 seal. For demonstration purposes, the end-to-end steps have been shown below, starting with initializing the Vault with a Shamir seal and then migrating it to the Utimaco PKCS11 seal.

Before verifying the migration from the Shamir seal to the Utimaco PKCS#11 seal, ensure that any existing Vault deployment, storage data, and previously created Vault PKCS#11 seal objects in the HSM are removed. This migration procedure assumes a clean environment with Vault initialized using the default Shamir seal. Reusing existing Vault seal objects may lead to unexpected results during migration verification.
sudo systemctl stop vault

sudo rm -rf /opt/vault/data/*
Also ensure that any previously created Vault seal objects (for example, hsm_demo, demo, hsm_demo1, or demo1) are removed from the HSM before starting the migration procedure.


  1. Add the contents shown below to /etc/vault/config.hcl. This config file will initialize the Vault with the Shamir seal.

# Configure the storage backend for Vault
storage "file" {
 path = "/opt/vault/data"
}
# Addresses and ports on which Vault will respond to requests
listener "tcp" {
 address = "0.0.0.0:8200"
 tls_disable = true
}
ui = true
license_path = "/etc/vault/license.hclic"
disable_mlock = true

  1. Initialize the Vault to use the Shamir seal and note the unseal keys and Initial Root Token value.

# systemctl restart vault.service
# systemctl status vault.service
# vault operator init
image-20260930-032754.png


Vault initialization

  1. Check the Vault status.

# vault status
image-20260930-032946.png

Vault status

  1. Execute the following command a number of threshold times (in this case, 3 times) to unseal the vault and provide a unique unseal key when prompted.

# vault operator unseal
image-20260930-033337.png

Vault operator unseal progress 1/3

image-20260930-033610.png


Vault operator unseal progress 2/3

image-20260930-033842.png


Vault operator unseal completed

  1. Check the Vault status again and verify that the Vault is unsealed now.

# vault status
image-20260930-034128.png


Vault unsealed

  1. Log in to Vault using the Initial Root Token saved above.

# vault login <initial_root_token_value>
image-20260930-034328.png

Vault login

  1. Enable the KV secret engine.

# vault secrets enable -version=1 kv
image-20260930-034525.png

Enable kv engine

  1. List the enabled Secrets Engines with details.

# vault secrets list -detailed
image-20260930-035423.png


Vault secret list detailed

  1. To test the seal wrap feature, write some secret data. Add data to the key/value storage area of Vault.

# vault kv put kv/opt/vault/secret key=test_secret
image-20260930-035558.png

Vault seal wrap

  1. Retrieve the secret data.

# vault kv get kv/opt/vault/secret
image-20260930-035937.png

Retrieve data

  1. Stop the Vault service and verify its status.

# systemctl stop vault
# systemctl status vault
image-20260930-040122.png

Vault service status

  1. Now edit /etc/vault/config.hcl and add the seal PKCS11 section as shown below with the Utimaco HSM information.

seal "pkcs11" {
 lib = "/opt/utimaco/lib/libcs_pkcs11_R3.so"
 slot = "<slot_no>"
 pin = "<slot_PIN>"
 key_label = "hsm_demo1"
 hmac_key_label = "demo1"
 generate_key = "true"
}
# Configure the storage backend for Vault
storage "file" {
 path = "/opt/vault/data"
}
# Addresses and ports on which Vault will respond to requests
listener "tcp" {
 address = "0.0.0.0:8200"
 tls_disable = true
}
ui = true
license_path = "/etc/vault/license.hclic"
disable_mlock = true

  1. Start the Vault service.

# systemctl start vault
# systemctl status vault
image-20260930-040650.png

Vault service status

  1. To migrate from the Shamir seal to the Utimaco PKCS11 seal, run the command below for the number of threshold times (in this case, 3 times). When prompted, provide the unseal key.

# vault operator unseal -migrate
image-20260930-041057.png


Vault seal migration progress 1/3

image-20260930-041228.png


Vault seal migration progress 2/3

image-20260930-041402.png


Vault seal migration completed

Once the required threshold of unseal keys is entered, unseal keys will be migrated to recovery keys.

  1. Verify that the keys were generated in the HSM.

# p11tool2 slot=<slot_no.> LoginUser=<slot_PIN> ListObjects
image-20260930-043008.png


  1. Monitor the log and wait until the migration process is completed. To verify that it has, look for a seal re-wrap completed message in the Vault status.

# systemctl status vault
image-20260930-102819.png


Vault service seal rewrap status

  1. Now you can retrieve the earlier secret data.

# vault kv get kv/opt/vault/secret
image-20260930-043917.png


Retrieve data

Verify PKI Secrets Engine with HSM-Backed Managed Key

  1. Edit the vault server configuration at /etc/vault/config.hcl to add Utimaco HSM PKCS#11 library for creating Utimaco HSM-Backed Managed Key.

# vi /etc/vault/config.hcl
kms_library "pkcs11" { name="utimaco" library = "/opt/utimaco/lib/libcs_pkcs11_R3.so" }

  1. Restart the vault service.

# systemctl restart vault
# systemctl status vault

  1. Log in to vault.

# vault login <initial_root_token_value>
image-20260930-062806.png


Vault login

  1. Each managed key requires the slot for key and a PIN to access and create the key on the HSM. Configure the managed key.

# vault write sys/managed-keys/pkcs11/learn-managed-key library=utimaco slot=<SLOT_NUMBER> pin=<USER_PIN> key_label=pki-key allow_store_key=true allow_generate_key=true mechanism=0x0001 key_bits=4096 any_mount=false
image-20260930-063218.png

Configure the managed key

  1. Read the key back.

# vault read /sys/managed-keys/pkcs11/learn-managed-key
image-20260930-063911.png


Key read

  1. Test endpoint to validate that we can access the managed key.

# vault write -force /sys/managed-keys/pkcs11/learn-managed-key/test/sign

The key has been generated in the HSM and used to sign and verify a dummy value.

image-20260930-091316.png

Sign managed key

  1. Enable the PKI secrets engine at the PKI path.

# vault secrets enable pki
image-20260930-051038.png

PKI enable

  1. Tune the secrets engine to use managed keys.

# vault secrets tune -allowed-managed-keys=learn-managed-key pki

You configured the managed key with any_mount=false in the previous step. This command grants access to the learn-managed-key to the PKI secrets engine's mount.

image-20260930-051518.png

Vault secrets tune

  1. Generate the root certificate.

# vault write -field=certificate pki/root/generate/kms managed_key_name=learn-managed-key common_name=root.myco.com ttl=8760h

  1. Configure the CA and CRL URLs.

# vault write pki/config/urls issuing_certificates="$VAULT_ADDR/v1/pki/ca" crl_distribution_points="$VAULT_ADDR/v1/pki/crl"
image-20260930-091711.png


Configure CA & CRL

  1. Test that you can issue a certificate with your managed key backed root CA by configuring and using a role.

# vault write pki/roles/example-dot-com allowed_domains="example.com" allow_subdomains=true max_ttl="720h"
image-20260930-091447.png


Issue certificate with managed key 1

image-20260930-091525.png


Issue certificate with managed key 2

  1. Request a new certificate for the test.example.com domain based on the exampledot-com role.

# vault write -format=json pki/issue/example-dot-com common_name="test.example.com" ttl="24h"
image-20260930-092023.png


Generate a new certificate

image-20260930-092228.png


Generate a new certificate

image-20260930-092303.png


Generate a new certificate

In a similar way you can issue more certificates signed by CA according to your requirement.

This completes the integration of HashiCorp Vault with Utimaco u.trust GP HSM.