open-standards/openpay/compliance/hsm-kms-guidance.md

HSM / KMS Integration Guidance

This document gives operator-facing guidance for plugging an HSM or cloud KMS into an OpenPay deployment. The pattern follows the EvmSigner trait in op-rails-crypto (crates/op-rails-crypto/src/signer.rs): the OpenPay code builds an unsigned operation, hands it to an operator-supplied trait, and lets the operator's chosen backend perform the privileged cryptography.

The KeyProvider adapter trait

OpenPay does not ship a KeyProvider trait in the workspace because the Vault trait already abstracts the entire storage-side concern. Operators implementing a vault against a KMS or HSM should follow the same shape as EvmSigner:

// Pattern, not shipped code — operators add this to their own vault crate.
pub trait KeyProvider: Send + Sync {
    /// Encrypt a fresh DEK (data-encryption key) under the KEK.
    fn wrap_dek(&self, plaintext_dek: &[u8; 32]) -> Result<Vec<u8>>;

    /// Decrypt a previously wrapped DEK.
    fn unwrap_dek(&self, wrapped_dek: &[u8]) -> Result<[u8; 32]>;

    /// Rotate the KEK. Returns the new key version identifier.
    fn rotate_kek(&self) -> Result<KeyVersion>;

    /// Active KEK version, for emitting on audit log entries.
    fn active_kek_version(&self) -> Result<KeyVersion>;
}

The operator's vault impl then performs envelope encryption: generate a 32-byte DEK with getrandom, encrypt the PAN with AES-256-GCM-SIV under the DEK, call KeyProvider::wrap_dek to wrap the DEK under the KEK, store (wrapped_dek, ciphertext, nonce, kek_version) keyed by VaultRef. On detokenize, the reverse.

The four backends below all fit this shape.

AWS KMS

Setup

1. Create a customer-managed CMK in the AWS region hosting the vault. Use a symmetric SYMMETRIC_DEFAULT key for envelope encryption; multi-region keys are appropriate if the vault is multi-AZ.
2. Restrict the CMK key policy to the IAM role attached to the vault EC2 / ECS / EKS workload identity. Statement: kms:Encrypt, kms:Decrypt, kms:GenerateDataKey, kms:DescribeKey. Deny kms:ScheduleKeyDeletion and kms:DisableKey to non-break-glass roles.
3. Enable CloudTrail data events on the CMK. Ship the events to a separate AWS account (the log archive account in a Control Tower setup) so vault admins cannot tamper with their own audit trail.
4. The operator's KeyProvider impl uses the AWS SDK for Rust (aws-sdk-kms) and authenticates via IMDSv2 / IRSA / workload identity — never a long-lived access key.

Latency

• Encrypt / Decrypt over a 32-byte DEK: typically 5-15 ms intra-region, 95th percentile under 30 ms. AWS does not publish an SLA on KMS latency; budget 50 ms in your detokenize path.
• For high-throughput vaults, use the AWS KMS Data Key Caching pattern: cache unwrapped DEKs in memory for up to 60 seconds, bounded by an LRU cache of e.g. 1024 entries. This keeps amortised KMS cost at one call per minute per hot DEK.

Key rotation

• Enable AWS-managed annual KEK rotation (kms:EnableKeyRotation). AWS retains every prior key version internally; Decrypt automatically uses the right version. No application changes required.
• For forced rotation (suspected compromise), generate a new CMK, re-wrap every DEK by reading each ciphertext, decrypting under the old CMK, re-wrapping under the new CMK, writing back, and finally scheduling the old CMK for deletion (30-day window).

Audit log requirements

Each wrap_dek / unwrap_dek call must produce a CloudTrail entry containing the calling principal, the source IP (the vault host), the CMK ARN, the encryption context (operator should pass {"vault_ref": "<token>", "tenant": "<id>"} so the audit log identifies which PAN was touched), and the timestamp. Ship CloudTrail logs to S3 + CloudWatch Logs; retain for at least one year (PCI-DSS Req. 10.5.1).

GCP KMS (Cloud KMS)

Setup

1. Create a key ring in the region hosting the vault. Create a SOFTWARE or HSM protection-level key inside it. For PCI scope choose HSM (FIPS 140-2 Level 3).
2. Bind the vault workload's Google service account to roles/cloudkms.cryptoKeyEncrypterDecrypter on the key. Do not grant cloudkms.cryptoKeys.create or cloudkms.cryptoKeys.destroy to the workload.
3. Enable Cloud Audit Logs (Admin Activity and Data Access) on the key ring. Sink to a separate BigQuery dataset or Cloud Storage bucket in a different project.
4. Authenticate the vault workload via Workload Identity Federation (GKE) or the metadata server (GCE) — never a downloaded JSON key file.

Latency

• Encrypt / Decrypt: 10-30 ms typical, 100 ms 99th percentile. HSM-protected keys add ~10 ms vs software keys. Budget 100 ms in the detokenize path.
• Cloud KMS does not have a published data-key caching SDK pattern; implement caching identically to the AWS KMS guidance (LRU + 60-second TTL).

Key rotation

• Set rotationPeriod = 7776000s (90 days) on the key. Cloud KMS creates a new primary key version automatically; older versions remain decryptable until explicitly destroyed.
• For forced rotation, create a new key version manually (gcloud kms keys versions create), wait for it to become primary, and then run the re-wrap loop.

Audit log requirements

Cloud Audit Logs record both the call and the encryption context (Cloud KMS calls it additional authenticated data; pass the same {"vault_ref": ..., "tenant": ...} as for AWS). Retain for one year minimum; PCI-DSS Req. 10.5.1.

HashiCorp Vault (Transit secret engine)

Setup

1. Deploy HashiCorp Vault in HA mode (Raft storage backend, 5-node quorum). Enable the Transit secret engine at a mount path such as transit-openpay/.
2. Create a key with vault write -f transit-openpay/keys/openpay-cde type=aes256-gcm96 derived=true exportable=false. derived=true requires the caller to supply a per-VaultRef context (giving you per-token key derivation for free); exportable=false ensures the key never leaves the Vault server.
3. Create a policy granting update on transit-openpay/encrypt/openpay-cde and transit-openpay/decrypt/openpay-cde, and deny everything else.
4. Authenticate the OpenPay vault workload via the AppRole, Kubernetes, or AWS-IAM auth method. Lease TTL: 1 hour, renew before expiry. No root tokens in production.
5. Audit-log to a file device that ships to your SIEM. Enable the enable_response_wrapping audit option so token IDs are obfuscated in logs.

Latency

• transit/encrypt / transit/decrypt over 32 bytes: 2-8 ms typical against a same-VPC HashiCorp Vault cluster. Lower than cloud KMS because there is no AWS / GCP control-plane hop.
• Budget 25 ms in the detokenize path.

Key rotation

• vault write -f transit-openpay/keys/openpay-cde/rotate creates a new key version. All future encrypts use the new version; decrypts of older ciphertexts continue to work because the ciphertext header carries the version number.
• For forced rotation, also run vault write transit-openpay/keys/openpay-cde/rewrap to mass-re-encrypt all data under the new version (HashiCorp Vault has a built-in rewrap API).

Audit log requirements

The Transit engine logs every encrypt / decrypt with the AppRole identity, source IP, request ID, and the context (derived=true makes this mandatory). Ship audit logs to a write-once store (S3 + Object Lock, or a dedicated log-archive instance). Retain one year minimum.

Fortanix DSM (Data Security Manager)

Setup

1. Provision a Fortanix DSM cluster — SaaS or self-hosted. SaaS is FIPS 140-2 Level 3 certified; self-hosted on Intel SGX is FIPS 140-2 Level 3 (HSM mode).
2. Create an App (service identity) for the OpenPay vault workload. Use App API key or certificate authentication; do not use username + password.
3. Inside the App's group, create an AES-256 Security Object with operations ENCRYPT, DECRYPT, WRAPKEY, UNWRAPKEY allowed and EXPORT denied.
4. Configure quorum approvals if your operational model requires two-person control for KEK rotation or deletion.
5. The Fortanix REST API or its PKCS#11 / KMIP interfaces all map to the KeyProvider shape above; choose REST for cross-cloud portability, PKCS#11 for legacy compatibility.

Latency

• REST API to Fortanix SaaS: 20-50 ms typical (single-region), 100 ms 99th. Self-hosted on-prem on SGX: 5-15 ms.
• Budget 100 ms in the detokenize path for SaaS, 25 ms for self-hosted.

Key rotation

• DSM supports key versioning and automatic rotation policies. Set rotation_policy.interval_days = 90 on the Security Object.
• Forced rotation: create a new key version manually, run the operator's re-wrap job. DSM keeps old versions decryptable per the Key state lifecycle (Active → Suspended → Deactivated → Destroyed).

Audit log requirements

DSM emits an audit log entry for every Security Object operation, including the calling App, source IP, operation, and Security Object UUID. Forward logs via syslog to your SIEM; DSM supports CEF and JSON formats. Retain one year minimum.

Cross-provider comparison

Provider	FIPS level	Typical latency	Caching pattern	Rotation cadence	Auth
AWS KMS	140-2 L3 (HSM-backed CMKs)	5-15 ms	LRU + 60 s TTL	Annual auto, manual on-demand	IAM role
GCP KMS	140-2 L3 (HSM tier)	10-30 ms	LRU + 60 s TTL	90-day auto	Workload Identity
HashiCorp Vault Transit	140-2 L1 (default) / L2 (with HSM auto-unseal)	2-8 ms	not needed (already fast)	Manual, mass-rewrap supported	AppRole / Kubernetes / IAM
Fortanix DSM	140-2 L3 (SGX)	20-50 ms (SaaS) / 5-15 ms (self-hosted)	LRU + 60 s TTL	90-day auto, quorum-gated manual	API key / cert

Common pitfalls

• Caching unwrapped DEKs beyond their TTL. PCI-DSS Req. 3.7.1 expects DEKs to live no longer than necessary. Bound the cache at 60 seconds.
• Pinning the wrong KEK version into ciphertext metadata. Always record kek_version alongside the wrapped DEK; mass-rewrap operations need it.
• Logging encryption context that contains the PAN. The encryption context becomes part of CloudTrail / Cloud Audit / Vault audit logs, which are not CDE-scoped storage. Pass only VaultRef and tenant_id, never PAN-derived material.
• Using a single KMS key for multiple tenants. If you operate a multi-tenant vault, derive per-tenant DEKs via the KMS Derive operation (AWS KMS supports this via key context; HashiCorp Vault Transit supports it via derived=true).
• Treating the KMS as the CDE boundary. The KMS holds the KEK, not the PAN. The CDE is wherever the plaintext PAN lives, which is the vault process during the brief window between unwrap_dek and AES decryption + the subsequent acquirer post.