<!-- Copyright (c) 2026 defconxt. All rights reserved. -->
<!-- Licensed under AGPL-3.0 — see LICENSE file for details. -->
---
name: implementing-hardware-security-modules
description: >-
  Deploy and integrate Hardware Security Modules (HSMs) for cryptographic key
  protection including PKCS#11 interface configuration, cloud HSM services
  (AWS CloudHSM, Azure Dedicated HSM, GCP Cloud HSM), key ceremony procedures,
  and FIPS 140-2/140-3 compliance validation.
domain: cybersecurity
subdomain: cryptography
tags:
  - hsm
  - pkcs11
  - fips-140
  - aws-cloudhsm
  - key-ceremony
  - hardware-crypto
  - key-protection
  - tamper-resistant
version: "1.0"
author: defconxt
license: AGPL-3.0
metadata:
  mitre-attack: ["T1552"]
---

# Implementing Hardware Security Modules

## Overview

HSMs provide tamper-resistant hardware for cryptographic key storage and
operations. Keys generated inside an HSM never leave the hardware boundary,
eliminating key extraction attacks. This skill covers HSM selection, PKCS#11
integration, cloud HSM deployment, and key ceremony procedures.

## Prerequisites

| Requirement | Install |
|---|---|
| OpenSC (PKCS#11) | `apt install opensc` |
| p11-kit | `apt install p11-kit` |
| pkcs11-tool | Included in OpenSC |
| AWS CloudHSM client | AWS documentation |
| Python 3.10+ | For agent tooling |
| SoftHSM2 (testing) | `apt install softhsm2` |

## Key Concepts

### HSM Comparison

| Feature | SoftHSM2 (Dev) | AWS CloudHSM | Azure Dedicated HSM | YubiHSM 2 |
|---|---|---|---|---|
| FIPS 140-2 | None | Level 3 | Level 3 | Level 3 |
| PKCS#11 | Yes | Yes | Yes | Yes |
| Cost | Free | ~$1.50/hr | ~$4,800/mo | ~$650 one-time |
| Use case | Development | Production cloud | Production cloud | Small-scale |

### SoftHSM2 (Development/Testing)

```bash
# Initialize a SoftHSM2 token
softhsm2-util --init-token --slot 0 --label "dev-token" \
  --pin 1234 --so-pin 5678

# List available tokens
softhsm2-util --show-slots

# Generate an RSA key pair
pkcs11-tool --module /usr/lib/softhsm/libsofthsm2.so \
  --login --pin 1234 --keypairgen --key-type rsa:2048 \
  --id 01 --label "signing-key"

# List objects in the token
pkcs11-tool --module /usr/lib/softhsm/libsofthsm2.so \
  --login --pin 1234 --list-objects

# Sign data with HSM-stored key
pkcs11-tool --module /usr/lib/softhsm/libsofthsm2.so \
  --login --pin 1234 --sign --mechanism SHA256-RSA-PKCS \
  --id 01 --input-file data.bin --output-file data.sig
```

### PKCS#11 Integration

```bash
# Test PKCS#11 module
p11-kit list-modules

# Use OpenSSL with PKCS#11 engine
openssl req -new -x509 -engine pkcs11 \
  -keyform engine -key "pkcs11:token=dev-token;id=%01" \
  -sha256 -out cert.pem -subj "/CN=HSM Test"

# Configure OpenSSL pkcs11 engine
export OPENSSL_CONF=openssl-pkcs11.cnf
# openssl-pkcs11.cnf:
# openssl_conf = openssl_init
# [openssl_init]
# engines = engine_section
# [engine_section]
# pkcs11 = pkcs11_section
# [pkcs11_section]
# engine_id = pkcs11
# MODULE_PATH = /usr/lib/softhsm/libsofthsm2.so
# PIN = 1234
```

### AWS CloudHSM

```bash
# Initialize CloudHSM cluster
aws cloudhsmv2 create-cluster --hsm-type hsm1.medium \
  --subnet-ids subnet-12345

# Create HSM in cluster
aws cloudhsmv2 create-hsm --cluster-id cluster-12345 \
  --availability-zone us-east-1a

# Configure client
sudo /opt/cloudhsm/bin/configure -a <hsm-ip>

# Key management via key_mgmt_util
/opt/cloudhsm/bin/key_mgmt_util
# loginHSM -u CU -s admin -p <password>
# genSymKey -t 31 -s 32 -l "aes-key"
# genRSAKeyPair -m 4096 -e 65537 -l "rsa-key"
```

### Key Ceremony Procedure

```
Key Ceremony Checklist:
├── 1. Preparation
│     ├── Secure room with CCTV, no wireless devices
│     ├── Two-person integrity (dual control)
│     ├── Notarized witness present
│     └── Hardware verified tamper-evident seals intact
├── 2. Generation
│     ├── Initialize HSM with factory reset
│     ├── Generate root CA key inside HSM
│     ├── Export public key only
│     └── Record key identifiers and metadata
├── 3. Backup
│     ├── Split key shares (M-of-N, e.g., 3-of-5)
│     ├── Store shares in separate physical safes
│     └── Record custodian assignments
├── 4. Verification
│     ├── Test sign/verify operation
│     ├── Verify key attributes and permissions
│     └── Confirm audit logs recorded
└── 5. Documentation
      ├── Sign ceremony log
      ├── Photograph sealed HSM
      └── Archive in secure storage
```

## Workflow

1. **Select** — Choose HSM based on FIPS level, budget, and deployment model
2. **Provision** — Initialize HSM, set PINs, configure network access
3. **Integrate** — Configure PKCS#11 for application and CA integration
4. **Ceremony** — Conduct formal key generation ceremony for root keys
5. **Operate** — Monitor HSM health, audit access logs, manage key lifecycle
6. **Test** — Validate failover, backup restoration, and key recovery

## Verification

| Check | Method |
|---|---|
| Token initialized | `pkcs11-tool --list-slots` shows active token |
| Key generated in HSM | Key attributes show `CKA_SENSITIVE=TRUE` |
| PKCS#11 functional | OpenSSL sign/verify via engine succeeds |
| FIPS validated | HSM certificate shows FIPS 140-2/3 Level 3 |
| Audit logging | HSM audit trail captures all operations |

## References

- [NIST FIPS 140-3](https://csrc.nist.gov/publications/detail/fips/140/3/final)
- [OASIS PKCS#11 Specification](https://www.oasis-open.org/committees/pkcs11/)
- [AWS CloudHSM User Guide](https://docs.aws.amazon.com/cloudhsm/latest/userguide/)
- [SoftHSM2 Documentation](https://www.opendnssec.org/softhsm/)
