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

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

1. Install enclaive vHSM

2. Configure enclaive vHSM

Install enclaive vHSM in a Docker container

1. Create the vhsm group : groupadd vhsm

2. Create the vhsm User : useradd --gid vhsm vhsm

3. Login to the enclaive repository and enter user and password: docker login harbor.enclaive.cloud

The output is similar to:

Username: <username>
Password: <password>
Login Succeeded 

1. Pull the latest image: docker pull harbor.enclaive.cloud/vhsm/vhsm-utimaco:latest

2. Set the enterprise license key that you received as an environment variable: export ENCLAIVE_LICENCE=<licence-key>

3. Download and install the vHSM CLI to interact with enclaive vHSM: wget https://vhsm.enclaive.cloud/static/vhsm

4. Create a directory for the vHSM configuration file, data, and certificates

# mkdir /etc/vhsm 
# mkdir /etc/vhsm/data
# mkdir /etc/vhsm/certs  

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.json 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" 
}
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
   }me code

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.3.2-0 heads/main-0-g1b8bb7c 2024-10-10T01:15:29+00:00
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