AWS KMS + HashiCorp Vault + HSM PKCS#11: Enterprise Key Management Integration Guide

Vault Transit Engine with AWS KMS

Vault’s Transit secrets engine provides encryption-as-a-service. Applications send plaintext to Vault, get ciphertext back — without ever handling encryption keys directly.

Setup

# Enable transit secrets engine
vault secrets enable transit

# Create an encryption key
vault write -f transit/keys/payment-data \
  type=aes256-gcm96 \
  auto_rotate_period=90d

# Create a key backed by AWS KMS (Vault Enterprise)
vault write transit/keys/regulated-data \
  type=managed_key \
  managed_key_name=aws-kms-key \
  managed_key_id=arn:aws:kms:us-east-1:123456789012:key/example-key-id

Application Usage

# Encrypt data
vault write transit/encrypt/payment-data \
  plaintext=$(echo -n "4111-1111-1111-1111" | base64)

# Response:
# ciphertext: vault:v1:8SDd3WHDOjf7mq69CyCqYjBXAiQQAVZRkFM13ok481zoCmHnSeDX9vyf7w==

# Decrypt data
vault write transit/decrypt/payment-data \
  ciphertext="vault:v1:8SDd3WHDOjf7mq69CyCqYjBXAiQQAVZRkFM13ok481zoCmHnSeDX9vyf7w=="

# Response:
# plaintext: NDExMS0xMTExLTExMTEtMTExMQ==  (base64 of "4111-1111-1111-1111")

Key Rotation (Zero-Downtime)

# Rotate the encryption key (new version created)
vault write -f transit/keys/payment-data/rotate

# Old ciphertext still decrypts (Vault keeps all key versions)
# New encryptions use the latest version

# Rewrap existing ciphertext with the new key version (batch operation)
vault write transit/rewrap/payment-data \
  ciphertext="vault:v1:old-ciphertext-here"
# Returns: vault:v2:new-ciphertext-with-latest-key

Vault PKI Secrets Engine with HSM-Protected Keys

For issuing certificates where the CA private key must be HSM-protected:

# Enable PKI secrets engine
vault secrets enable -path=pki_root pki
vault secrets tune -max-lease-ttl=87600h pki_root

# Generate root CA with HSM-backed key (Enterprise)
vault write pki_root/root/generate/kms \
  managed_key_name=hsm-root-ca-key \
  common_name="Enterprise Root CA" \
  ttl=87600h \
  key_type=rsa \
  key_bits=4096

# Enable intermediate PKI
vault secrets enable -path=pki_int pki
vault secrets tune -max-lease-ttl=43800h pki_int

# Generate intermediate CSR
vault write pki_int/intermediate/generate/internal \
  common_name="Enterprise Issuing CA" \
  key_type=rsa \
  key_bits=4096

# Sign intermediate with root
vault write pki_root/root/sign-intermediate \
  csr=@pki_int_csr.pem \
  format=pem_bundle \
  ttl=43800h

# Configure roles for certificate issuance
vault write pki_int/roles/server-cert \
  allowed_domains="example.com,internal.example.com" \
  allow_subdomains=true \
  max_ttl=8760h \
  key_type=ecdsa \
  key_bits=256 \
  require_cn=false

Issuing Certificates

# Issue a certificate (short-lived, automated)
vault write pki_int/issue/server-cert \
  common_name="api.internal.example.com" \
  alt_names="api-v2.internal.example.com" \
  ttl=720h

# Response includes:
# - certificate (PEM)
# - issuing_ca (PEM)
# - private_key (PEM)
# - serial_number
# - expiration

AWS KMS Custom Key Store (CloudHSM-Backed)

For organizations that need AWS KMS convenience with HSM-level key protection:

# Create a CloudHSM cluster
aws cloudhsmv2 create-cluster \
  --hsm-type hsm1.medium \
  --subnet-ids subnet-abc123 subnet-def456

# Create a custom key store backed by CloudHSM
aws kms create-custom-key-store \
  --custom-key-store-name "production-hsm-keystore" \
  --cloud-hsm-cluster-id cluster-abc123 \
  --key-store-password "HSM_kmsuser_password" \
  --trust-anchor-certificate file://customerCA.crt

# Connect the custom key store
aws kms connect-custom-key-store \
  --custom-key-store-id cks-abc123

# Create a KMS key in the custom key store (HSM-backed)
aws kms create-key \
  --origin AWS_CLOUDHSM \
  --custom-key-store-id cks-abc123 \
  --description "HSM-backed encryption key for regulated data"

This gives you:

• AWS KMS API for all operations (familiar to developers)
• CloudHSM hardware protection (FIPS 140-2 Level 3)
• Keys never leave the HSM in plaintext
• Full AWS service integration (S3, EBS, RDS use this key transparently)

PKCS#11 Deep Dive

PKCS#11 (Cryptoki) is the standard API for applications to communicate with cryptographic tokens (HSMs, smart cards). Understanding it is essential for any HSM integration.

Key Concepts

Common PKCS#11 Operations

# List available slots
pkcs11-tool --module /path/to/libpkcs11.so --list-slots

# List objects (keys, certs) on the token
pkcs11-tool --module /path/to/libpkcs11.so --login --pin $PIN --list-objects

# Generate an AES-256 key on the HSM
pkcs11-tool --module /path/to/libpkcs11.so --login --pin $PIN \
  --keygen --key-type AES:32 --label "app-encryption-key" --id 01

# Generate an RSA-4096 key pair on the HSM
pkcs11-tool --module /path/to/libpkcs11.so --login --pin $PIN \
  --keypairgen --key-type RSA:4096 --label "ca-signing-key" --id 02

# Sign data with an HSM-stored key
pkcs11-tool --module /path/to/libpkcs11.so --login --pin $PIN \
  --sign --mechanism SHA256-RSA-PKCS --id 02 --input-file data.bin

PKCS#11 Library Paths by Vendor

Production Architecture Example

Deployment Checklist