HSM Setup

HSM Setup

This page describes recommended HSM (Hardware Security Module) setup and configuration patterns for protecting code signing keys. It covers both on‑prem HSMs (PKCS#11) and cloud KMS options (AWS KMS / CloudHSM, Azure Key Vault, GCP KMS), plus examples for a local developer/testing setup using SoftHSM.

Goals

• Keep private keys inside a tamper‑resistant boundary (HSM or KMS).
• Minimize key export and ensure keys are used only for signing operations.
• Provide high availability, audit logging, and strong access controls.

HSM vs Cloud KMS (when to use which)

• On‑prem HSM (PKCS#11): Choose when strict physical control, regulatory requirements, or offline operation are required. Good for highly regulated industries.
• Cloud KMS / CloudHSM: Good for SaaS or hybrid deployments where you want managed availability and simpler ops. Ensure you configure strict IAM and network isolation.

Compliance & Recommendations

• Prefer FIPS‑certified HSMs (FIPS 140‑2 Level 2+ or equivalent) for production code signing keys.
• Use HSMs that support remote attestation and strong audit logging.
• Plan for certificate validity rules (note: public code signing certs now have max 460-day validity for new certs).

PKCS#11 Basics

Most on‑prem HSMs expose a PKCS#11 interface used by client libraries and agents. Typical steps:

1. Install the HSM vendor’s PKCS#11 library on the agent host.
2. Configure the agent or signing service to point at the PKCS#11 module or remote provider.
3. Create keys inside the HSM (do not import/export private keys unless vendor supports secure wrapping).
4. Assign access controls to key objects (roles, PINs, policies).

Example: SoftHSM (local dev/testing)

SoftHSM provides a PKCS#11 software implementation useful for development.

Install (Ubuntu example):

sudo apt-get install softhsm2 opensc

Initialize a token and create a key:

softhsm2-util --init-token --slot 0 --label "dev-token"
pkcs11-tool --module /usr/lib/softhsm/libsofthsm2.so -l --pin <PIN> --keypairgen --key-type rsa:3072 --id 01 --label "signing-key"

Configure your app/agent to use /usr/lib/softhsm/libsofthsm2.so as the PKCS#11 module.

PKCS#11 URI (example)

A PKCS#11 URI for the key might look like:

pkcs11:token=dev-token;id=%01;object=signing-key;type=private

HSM Deployment & Network Considerations

• Place HSM management interfaces on an administrative network; only allow necessary hosts to access the PKCS#11 endpoint.
• For remote HSMs (CloudHSM or vendor appliances), use private connections (VPC peering, VPN, ExpressRoute) and strict firewall rules.
• Ensure time sync (NTP) across services to avoid timestamp verification issues.

Key Management & Lifecycle

• Generate keys inside HSM whenever possible.
• Enforce RBAC for key use (separate admin and signing roles).
• Rotate keys and certificates on a regular schedule; automate renewals where possible.
• Use separate keys for dev/staging/production.

Integrating with QCecuring Platform

• Agents: Use mTLS agents that proxy PKCS#11 operations or expose a remote keystore to CI/CD systems.
• API: When using cloud KMS, bind KMS keys to platform service roles and restrict usage to signing operations.
• Timestamps: Configure workers to request RFC 3161 timestamps when needed and store timestamp tokens alongside signatures.

Troubleshooting & Diagnostics

• Health checks: Use HSM vendor health endpoints or /actuator/health/hsm (example platform endpoint) to verify connectivity.
• Common tools:
  • pkcs11-tool (OpenSC) — list slots, objects, and test key operations.
  • softhsm2-util — manage SoftHSM tokens for dev.
• Check logs for errors such as PIN/credential failures, module load issues, or network timeouts.

Helpful commands

# List PKCS#11 slots
pkcs11-tool --module /usr/lib/softhsm/libsofthsm2.so -L

# List objects on a token
pkcs11-tool --module /usr/lib/softhsm/libsofthsm2.so -l --pin <PIN> -O

# Test a signing operation (if key supports sign)
pkcs11-tool --module /usr/lib/softhsm/libsofthsm2.so -l --pin <PIN> --sign --mechanism RSA-PKCS --input data.bin --output sig.bin

Vendor Notes

• Follow vendor-specific administration guides for Thales, Utimaco, or other HSM vendors. They provide detailed steps for provisioning, HSM clustering, backups, and hardware maintenance.
• When using cloud KMS (AWS KMS / CloudHSM, Azure Key Vault, or GCP KMS), follow the provider’s best practices for IAM, key policies, and network security.

Checklist (Quick)

• Generate or import key material inside a secure HSM/KMS
• Configure PKCS#11 module or Cloud KMS integration for the signing agent
• Configure RBAC and approver groups if using quorum approvals
• Validate signing end-to-end (digest generation → sign → attach → verify)
• Enable monitoring and alerting for HSM health and performance

---

See also: Install → On‑Premises, Key Management, Signing Workflows.