AWS CloudHSM Integration Guide

Overview

This guide configures AWS CloudHSM so the CBOM Secure HSM Sensor can discover cryptographic material in your CloudHSM cluster:

  • Symmetric keys (AES, 3DES) managed within HSM partitions
  • Asymmetric key pairs (RSA, EC) stored on the HSM
  • X.509 certificates and associated metadata
  • Key attributes such as key type, length, label, ID, and usage flags

It covers creating and initializing a cluster, provisioning a read-only Crypto User (CU), configuring the CloudHSM client daemon, and wiring the sensor configuration.

Prerequisites

  1. An AWS account with permissions to manage CloudHSM (e.g. AWSCloudHSMFullAccess).
  2. A VPC with at least one private subnet in the target region.
  3. The AWS CLI installed and configured.
  4. The CloudHSM Client SDK 5 (cloudhsm-cli) installed on the sensor host.
  5. Crypto Officer (CO) credentials for an existing cluster, or you will initialize one here.
  6. The sensor host can reach the cluster on port 2223 (HSM ENI) and 2224 (client daemon).

Step-by-Step Guide

Step 1: Create and Initialize a CloudHSM Cluster 

aws cloudhsmv2 create-cluster \ 
  --hsm-type hsm1.medium \ 
  --subnet-ids subnet-0abc12345def67890 
aws cloudhsmv2 create-hsm \ 
  --cluster-id cluster-0123456789abcdef0 \ 
  --availability-zone us-east-1a

Download the cluster CSR from the console, sign it with your CA (or a self-signed issuing cert for lab use), then upload and initialize: 

openssl req -new -x509 -days 3652 -key customerCA.key \ 
  -out customerCA.crt -subj "/CN=CustomerCA" 

openssl x509 -req -days 3652 \ 
  -in cluster-0123456789abcdef0_ClusterCsr.csr \ 
  -CA customerCA.crt -CAkey customerCA.key -CAcreateserial \ 
  -out cluster-0123456789abcdef0_CustomerHsmCertificate.crt

Step 2: Configure the CloudHSM Client Daemon 

# Amazon Linux 2 / RHEL 
sudo yum install -y cloudhsm-client 
# Ubuntu / Debian 
sudo apt-get install -y cloudhsm-client 

sudo /opt/cloudhsm/bin/configure-client -a  
sudo cp customerCA.crt /opt/cloudhsm/etc/customerCA.crt 

sudo systemctl enable cloudhsm-client 
sudo systemctl start cloudhsm-client 
ls -lh /opt/cloudhsm/lib/libcloudhsm_pkcs11.so

Step 3: Create a Dedicated Crypto User (CU)

Authenticate as Crypto Officer, then create a read-only Crypto User for the sensor. Do not use CO credentials for the sensor. 

/opt/cloudhsm/bin/cloudhsm-cli interactive 
aws-cloudhsm> login --username admin --role crypto-officer 
aws-cloudhsm> user create --username cbom-sensor --role crypto-user 
aws-cloudhsm> user list 
aws-cloudhsm> logout

Note: A Crypto User can enumerate and use keys shared with it but cannot create, delete, or wrap other users’ keys — satisfying the sensor’s read-only requirement.

Step 4: Enumerate Slots 

pkcs11-tool --module /opt/cloudhsm/lib/libcloudhsm_pkcs11.so --list-slots

Step 5: Configure the CBOM Secure Sensor 

sensors:
  - name: Discover_HSM
    type: hsm_pkcs11
    enabled: true
    schedule: "0 2 * * *"     # daily at 02:00 UTC 
    connection: 
     hsm_provider: aws_cloudhsm 
     pkcs11_library: /opt/cloudhsm/lib/libcloudhsm_pkcs11.so 
     cluster_id: cluster-0123456789abcdef0 
     hsm_ip: 10.0.1.42                 # HSM ENI IP 
     slot: 0 
    credentials: 
     username: cbom-sensor 
     password: "${CBOM_CLOUDHSM_CU_PASSWORD}"        # from secrets manager 
     role: crypto-user 
    discovery: 
     include_key_types: [AES, RSA, EC, DES3] 
     include_certificates: true 
     include_secret_keys: true 
     include_private_keys: true        # metadata only; material never extracted 
    output: 
     tags: { environment: production, region: us-east-1 } 
     notify_on_expiry_days: 30

Step 6: Validate 

cbom sensor run --name Discover_HSM --dry-run 
cbom sensor run --name Discover_HSM

Confirm output such as Discovered 14 key objects (AES: 8, RSA: 4, EC: 2) and 3 certificate objects, then verify assets under Assets → HSM filtered by region.

Common Errors

CKR_TOKEN_NOT_PRESENT

Cause: The client daemon cannot reach the appliance, or the slot number is wrong.

Resolution: Verify connectivity (telnet 192.168.10.50 2348), confirm proteccio-client is running, and re-check the slot index with –list-slots.

CKR_PIN_INCORRECT

Cause: The Operator PIN (or CBOM_HSM_PIN) does not match the initialized PIN.

Resolution: Reset the Operator PIN in the console (Reset PIN), update the variable, and retry.

CKR_LIBRARY_LOAD_FAILED / cannot open shared object file

Cause: The Proteccio client package is not installed, or the library is at a non-standard path.

Resolution: Install the client package and confirm /usr/lib/pkcs11/libnethsm.so; update library_path if it differs.

Security Recommendations

  • Use a dedicated Operator account, never the Security Officer credential.
  • Keep include_sensitive_attributes: false so the sensor never requests CKA_VALUE.
  • Store the Operator PIN in a secrets manager; never hard-code or commit it.
  • Restrict SSH access to the sensor host and monitor logins.
  • Rotate the Operator PIN periodically and enable mutual TLS on the Proteccio client.

Conclusion

With the Proteccio client installed, a dedicated CBOM_Discovery slot, and a read-only Cryptographic Operator, the HSM Sensor enumerates cryptographic assets over PKCS#11 on a schedule, providing continuous visibility into key types, certificate lifetimes, and algorithm usage with no key material ever exposed.