Integrate enclaive vHSM with Utimaco HSM

Learn how to install and configure 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

To integrate enclaive vHSM with Utimac HSM you need to perform these steps:

1. Install enclaive vHSM

2. Configure enclaive vHSM

3. Test the integration

4. 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=<licence-key>

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:

Note: Ensure that the slot number and slot PIN are per your Utimaco setup.

# 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.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=<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       false

7. 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           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:

Note: Ensure that the slot number and slot PIN are per your Utimaco setup.

# 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

Note: The External Entropy Access is set to true for transit.

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