HSM / KMS provider abstraction

A partir da v3.0, a chave master do CipherVault (KEK que envelopa DEKs de Fortress, EaaS, Tokenization, Dynamic Secrets cache, etc.) é gerenciada por uma abstração de provider. Você escolhe onde a KEK vive: na própria máquina, em AWS KMS, ou em um HSM PKCS#11.

Providers suportados

Provider	Onde a KEK vive	Quando usar
local	Derivada de MASTER_KEY env var (PBKDF2-SHA256)	Dev, PoC, single-tenant pequeno
aws-kms	AWS KMS (chave AWS-managed ou CMK custom)	Produção SaaS / cloud-native
pkcs11	HSM PKCS#11 (Thales Luna, AWS CloudHSM, SafeNet)	Compliance rigoroso (PCI HSM, BACEN)

Configuração

Via env vars no backend:

local (default)

CV_HSM_PROVIDER=local
MASTER_KEY=<32 bytes random base64>

Comportamento idêntico à v2 — KEK derivada de MASTER_KEY via PBKDF2. Backup do MASTER_KEY é responsabilidade sua.

aws-kms

CV_HSM_PROVIDER=aws-kms
CV_HSM_AWS_KMS_KEY_ID=arn:aws:kms:sa-east-1:169984788045:key/abc-123
AWS_REGION=sa-east-1
# Credenciais via IAM role (preferido) ou access key padrão

Cada operação de Encrypt/Decrypt vai para AWS KMS API. SDK AWS é lazy-loaded — apenas instalado quando esse provider é selecionado.

Permissões IAM necessárias na role do CV:

{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Action": [
      "kms:Encrypt",
      "kms:Decrypt",
      "kms:GenerateDataKey",
      "kms:DescribeKey"
    ],
    "Resource": "arn:aws:kms:sa-east-1:169984788045:key/abc-123"
  }]
}

pkcs11 (real desde v4.5)

CV_HSM_PROVIDER=pkcs11
CV_HSM_PKCS11_LIBRARY=/opt/cloudhsm/lib/libCryptoki2_64.so
CV_HSM_PKCS11_SLOT=0
CV_HSM_PKCS11_PIN_FILE=/etc/cv/hsm-pin
CV_HSM_PKCS11_KEY_LABEL=ciphervault-master-key

Suportado: AWS CloudHSM, Thales Luna Network HSM, SafeNet, SoftHSM v2 (dev/CI), YubiHSM (low-cost prod).

A chave nunca sai do HSM — o backend chama operações PKCS#11 via pkcs11js:

• CKM_AES_KEY_WRAP — wrapping de DEK no HSM
• C_Encrypt / C_Decrypt — operações simétricas
• C_Sign / C_Verify — assinatura (v4.5+, antes só encrypt/decrypt)
• Rotação de KEK in-place suportada

CI matrix (no produto): SoftHSM v2 sempre, CloudHSM + YubiHSM opt-in. Detalhes em docs/HSM.md do repo do produto (compat matrix por vendor + benchmarks).

Auto-unseal HSM (v4.5+)

Estilo HashiCorp Vault. KEK fica encrypted-at-rest na DB do CV; descriptografada via HSM no boot do backend (sem operador digitando passphrase manual). Ativa via:

CV_HSM_AUTO_UNSEAL=true
CV_HSM_UNSEAL_KEY_LABEL=ciphervault-unseal-key

Sem auto-unseal, backend exige passphrase no startup ou env var MASTER_KEY (modo local).

Health check

GET /health/hsm

Retorna o estado do provider configurado:

{
  "provider": "aws-kms",
  "healthy": true,
  "key_arn": "arn:aws:kms:sa-east-1:169984788045:key/abc-123",
  "latency_ms": 32
}

Em provider pkcs11:

{
  "provider": "pkcs11",
  "healthy": true,
  "library": "/opt/cloudhsm/lib/libCryptoki2_64.so",
  "slot": 0,
  "label": "ciphervault-master-key",
  "latency_ms": 8
}

healthy: false indica que o provider está respondendo erro — alerte em SIEM e dashboard. Operações dependentes (criar Fortress, rotacionar DEK, etc.) começam a falhar.

Migração entre providers

Não suportada in-place — exige rotação completa de master key:

1. Configure novo provider em ambiente staging
2. Faça master_key_rotate (re-encripta fortress_shards.wrapped_key, DEKs do EaaS, etc.) via Approvals (required_approvals: 3, ver Approvals)
3. Apenas após sucesso completo, mude env var em produção

Performance

Provider	Latência típica encrypt/decrypt
local	< 1ms
aws-kms	30–80ms (sa-east-1 ↔ KMS)
pkcs11 (CloudHSM)	5–15ms (mesmo VPC)
pkcs11 (Luna network)	3–10ms

DEK plaintext tem cache 60s no CV — operações usam KEK apenas em escrita ou expirações de cache.

Custos AWS KMS

• $1.00/mês por CMK
• $0.03 por 10.000 requests (Encrypt/Decrypt/GenerateDataKey)

Para tenant pequeno-médio, custo típico: ~$2–5/mês. Empresas com milhões de operações: orçar por uso.

Boas práticas

• Produção: aws-kms ou pkcs11 — nunca local em produção
• CMK custom em aws-kms — não reutilize aws/kms default; CMK custom permite controle de policy IAM separado
• Backup do trust path — em PKCS#11, o token PIN deve estar em arquivo 0600 com backup offline
• Health check em monitoring — alerte em < 95% healthy nos últimos 5min
• Audit cruzado — combine logs do CV com CloudTrail (KMS) ou SIEM do HSM
• Não compartilhe CMK entre tenants — em multi-tenant, cada tenant tem sua CMK ou label PKCS#11 dedicado