Breadcrumbs

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.

  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.

# vault operator init
image-20250903-034329.png


Vault Initialization

  1. Check the Vault status.

# vault status
image-20250903-034501.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-20250903-034646.png
image-20250903-034715.png

Vault Operator Unseal

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

# vault status
image-20250903-034915.png


Vault Status

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

# vault login <initial_root_token_vaule>
image-20250903-035044.png


Vault Login

  1. Enable the KV secret engine.

# vault secrets enable -version=1 kv
image-20250903-035216.png

Enable KV Engine

  1. List the enabled Secrets Engines with details.

# vault secrets list -detailed
image-20250903-035445.png


Vault List

  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-20250903-035609.png


Vault Seal Wrap

  1. Retrieve the secret data.

# vault kv get kv/opt/vault/secret
image-20250903-035733.png


Retrieve Data

  1. Stop the Vault service and verify its status.

# systemctl stop vault
# systemctl status vault
image-20250903-035922.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-20250903-040149.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-20250903-043252.png
image-20250903-043325.png


Vault Seal Migration

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-20250903-043512.png


List Keys

  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-20250903-043710.png


Vault Service Status

  1. Now you can retrieve the earlier secret data.

# vault kv get kv/opt/vault/secret
image-20250903-043826.png


Retrieve Data