BYOK: HSM Keys and HSM-based Key Wrapping

Workspace ONE UEM natively supports Hardware Security Module (HSM)-based private keys. To import an RSA private key from an HSM into Workspace ONE UEM, the key material must be wrapped using the public wrapping key downloaded from the Workspace ONE UEM console during key upload.

For HSM-based keys, two wrapping methods are supported:

• HSM wrapping (Recommended): Perform the wrapping operation inside your HSM. This method ensures that the private key never leaves the hardware boundary in cleartext, providing end-to-end key protection during transfer. This requires the HSM to support importing a public key and wrapping the private key prior to export.

• Software wrapping: Wrap the key outside the HSM using a provided Python script. This method is only for environments where the HSM does not support key wrapping before export. This approach is not recommended because the key leaves the HSM unencrypted during the manual wrapping process. If you must use this method, perform the wrapping in a secure environment and securely delete the unencrypted key immediately afterward.

Wrap Keys Inside an HSM

Use this procedure to wrap your private key securely within your HSM. Your HSM must support importing a public key and wrapping a private key prior to export.

Procedure

1. Download the public key (.bin file) from the Workspace ONE UEM console.
2. Convert the public key from DER format to PEM format by using a tool such as OpenSSL.
3. Import the PEM-formatted key into your HSM with the required path, label, key type, and any required HSM-specific attributes.
4. Wrap your private key inside the HSM by using the imported Workspace ONE UEM public wrapping key.
5. Export the wrapped key material from the HSM to a file, and then transfer the file securely by using a tool such as WinSCP or scp.
6. Upload the wrapped key material to the Workspace ONE UEM console within the 24-hour expiration period after downloading the public wrapping key.

CloudHSM Example

The KMS public key is imported into CloudHSM with wrap=true, and the wrap operation runs entirely inside the cluster.

# 1. Convert KMS public key from DER to PEM
openssl rsa -pubin -inform DER \
  -in cloudhsm-wrap_WrappingPublicKey.bin \
  -outform PEM \
  -out kms-wrapping-public.pem

# 2. Import the KMS public key into CloudHSM
/opt/cloudhsm/bin/cloudhsm-cli key import pem \
  --path kms-wrapping-public.pem \
  --label kms-wrapping-key \
  --key-type-class rsa-public \
  --attributes wrap=true

# 3. Wrap the HSM-resident private key.
# Note: the wrapping method must be rsa-oaep because KMS import supports this algorithm only.
/opt/cloudhsm/bin/cloudhsm-cli key wrap rsa-oaep \
  --payload-filter attr.label=rsa_byok_4096 \
  --wrapping-filter attr.label=kms-wrapping-key \
  --hash-function sha256 \
  --mgf mgf1-sha256 \
  --path cloudhsm-wrap_EncryptedKeyMaterial.bin

# 4. Copy output to local machine for KMS import
scp -i "byok-ec2-key.pem" \
  ec2-user@<EC2-IP>:~/byok-wrap/cloudhsm-wrap_EncryptedKeyMaterial.bin \
  ./cloudhsm-wrap_EncryptedKeyMaterial.bin

The wrap=true attribute lets CloudHSM use the imported public key as a wrapping key, even though the key was created outside the HSM.