design: scope the AWS KMS key provider (first cloud provider)

[jdatcmd]

Scopes AWS KMS as the first cloud key provider, per the roadmap's Tier 1 item. Planning doc only, no code.

Key design points

• Envelope inside the provider. Because the provider interface deals in raw key bytes (keyring_get_key/store_key), the KMS wrap/unwrap can happen inside get/store: KMS Encrypt on write, Decrypt on read. The CMK never leaves KMS, and this needs no TDEKeyringRoutine vtable change — refining the roadmap's earlier note.
• Wrapped-blob storage: a provider-owned local ciphertext file in the data directory (recommended v1; a stolen disk yields only KMS ciphertext), with AWS Secrets Manager backing as a managed option.
• Implementation: raw HTTPS + AWS SigV4 over the already-linked libcurl/OpenSSL, not the heavy AWS C++ SDK; mirrors the OpenBao provider.
• Auth: the standard AWS credential chain (env/profile, IMDSv2 instance role in v1; IRSA/STS and ECS task role in v2). The credential chain is the main effort and risk, not the crypto.
• No on-disk format change; purely additive alongside file/KMIP/OpenBao.
• Covers config/SQL surface, security properties, LocalStack testing (t/aws_kms.pl, env-gated), effort/risk, phasing, and open questions.

🤖 Generated with Claude Code

[jdatcmd]

Prototype update: the two riskiest pieces of this design are now de-risked with a standalone C prototype (libcurl + OpenSSL only, no AWS SDK).

• SigV4 signing reproduces botocore byte for byte for a fixed KMS Encrypt request: canonical request, payload hash, string to sign, the kDate/kRegion/kService/kSigning chain, and the final signature all match. An independent HMAC-SHA256 recomputation agrees.
• KMS Encrypt/Decrypt round trip against a mock KMS (moto) wraps a 32-byte key and unwraps it back to the original over HTTPS. This is the envelope operation the provider runs inside get/store.

I've pushed a "Prototype: SigV4 and the KMS round trip are de-risked" subsection to design/aws-kms-provider.md under Implementation approach recording this. It narrows the hand-roll-vs-aws-c-auth open question to credential resolution only; the KMS protocol and signing are cheap to hand-roll with the libraries already linked.

Still awaiting decisions on the open questions before implementing v1: (1) v1 storage local file vs Secrets Manager, (2) whether IRSA is needed day one for EKS, (3) hand-roll credentials vs link aws-c-auth.