Re Performing Hardware Security Module Integration

---
name: re-performing-hardware-security-module-integration
description: Integrate Hardware Security Modules (HSMs) using PKCS#11 interface for cryptographic key management, signing operations, and secure key storage with python-pkcs11, AWS CloudHSM, and YubiHSM2.
domain: re
category: cryptography
hide: true
license: Apache-2.0
metadata:
  manifest_entry: src/corpus/re-performing-hardware-security-module-integration/SKILL.md
---
# Performing Hardware Security Module Integration

## Overview

Hardware Security Modules (HSMs) provide tamper-resistant cryptographic key storage and operations. This skill covers integrating with HSMs via the PKCS#11 standard interface using python-pkcs11, performing key generation, signing, encryption, and verification operations, querying token and slot information, and validating HSM configuration for compliance with FIPS 140-2/3 requirements.


## When to Use

- When conducting security assessments that involve performing hardware security module integration
- When following incident response procedures for related security events
- When performing scheduled security testing or auditing activities
- When validating security controls through hands-on testing

## Common Misconfigurations & Verification

- **Keys created as extractable:** generating PKCS#11 keys without `CKA_EXTRACTABLE=False`/`CKA_SENSITIVE=True` lets the "HSM-protected" private key be exported. After `generate_keypair`, read the private key attributes and confirm `extractable=False`, `sensitive=True`, `local=True`; an export/wrap attempt MUST be rejected by the token.
- **Operations silently falling back to software:** verify the key handle actually lives on the token (correct slot/label) and that `C_Sign`/`C_Decrypt` run on-device — for AWS CloudHSM/YubiHSM2 confirm the right `cloudhsm-pkcs11` / connector module is loaded, not the default software provider.
- **Unverified mechanism support:** query `slot.get_mechanisms()` before relying on an algorithm; assuming RSA-PSS or EC P-256 is present can cause runtime `CKR_MECHANISM_INVALID`.
- **PIN handling:** SO PIN reused as user PIN, PINs in source/CI logs, or no login-failure lockout. Use distinct PINs and load from a secret store.
- **FIPS posture not validated:** confirm the token reports the expected FIPS 140-2/3 level and that only approved mechanisms are enabled.
- **Verification:** run an on-device sign→verify round-trip and an encrypt→decrypt round-trip; confirm `C_GetAttributeValue` on the private key cannot return its value, list objects to inventory keys/certs, and assert the compliance report flags any extractable or non-FIPS keys.

## Prerequisites

- HSM device or software HSM (SoftHSM2 for testing)
- PKCS#11 shared library (.so/.dll) for the HSM vendor
- Python 3.9+ with `python-pkcs11`
- Token initialized with SO PIN and user PIN
- For AWS CloudHSM: `cloudhsm-pkcs11` provider configured

## Steps

1. Load PKCS#11 library and enumerate available slots and tokens
2. Open session and authenticate with user PIN
3. Generate RSA 2048-bit or EC P-256 key pairs on the HSM
4. Perform signing and verification using on-device keys
5. List all objects (keys, certificates) stored on the token
6. Query mechanism list to verify supported algorithms
7. Generate compliance report with key inventory and algorithm audit

## Expected Output

- JSON report listing HSM slots, tokens, stored keys, supported mechanisms, and compliance status
- Signing test results with key metadata and algorithm details