Terraform: KMS Key + RDS Encryption

version mismatch.

TypeScript Implementation

import { KMSClient, GenerateDataKeyCommand, DecryptCommand } from "@aws-sdk/client-kms";
import { createCipheriv, createDecipheriv, randomBytes, createHmac } from "crypto";

const kms = new KMSClient({ region: "us-east-1" });
const ALGORITHM = "aes-256-gcm";
const KEY_VERSION = "v1";

interface EncryptedPayload {
  ciphertext: string;
  encryptedDataKey: string;
  nonce: string;
  keyVersion: string;
  authTag: string;
}

export async function encryptAtRest(plaintext: string): Promise<EncryptedPayload> {
  // 1. Request data key from KMS
  const dataKeyCmd = new GenerateDataKeyCommand({
    KeyId: "alias/my-db-encryption-key",
    KeySpec: "AES_256",
  });
  const dataKeyResp = await kms.send(dataKeyCmd);
  
  const plaintextDataKey = dataKeyResp.Plaintext as Uint8Array;
  const encryptedDataKey = Buffer.from(dataKeyResp.CiphertextBlob as Uint8Array).toString("base64");

  // 2. Generate nonce and encrypt locally
  const nonce = randomBytes(12);
  const cipher = createCipheriv(ALGORITHM, plaintextDataKey, nonce);
  let ciphertext = cipher.update(plaintext, "utf8", "base64");
  ciphertext += cipher.final("base64");
  const authTag = cipher.getAuthTag();

  // 3. Clear plaintext key from memory
  plaintextDataKey.fill(0);

  return {
    ciphertext,
    encryptedDataKey,
    nonce: Buffer.from(nonce).toString("hex"),
    keyVersion: KEY_VERSION,
    authTag: Buffer.from(authTag).toString("hex"),
  };
}

export async function decryptAtRest(payload: EncryptedPayload): Promise<string> {
  // 1. Decrypt data key via KMS
  const decryptCmd = new DecryptCommand({
    CiphertextBlob: Buffer.from(payload.encryptedDataKey, "base64"),
  });
  const decryptResp = await kms.send(decryptCmd);
  const plaintextDataKey = decryptResp.Plaintext as Uint8Array;

  try {
    // 2. Decrypt payload locally
    const nonce = Buffer.from(payload.nonce, "hex");
    const authTag = Buffer.from(payload.authTag, "hex");
    const decipher = createDecipheriv(ALGORITHM, plaintextDataKey, nonce);
    decipher.setAuthTag(authTag);
    
    let plaintext = decipher.update(payload.ciphertext, "base64", "utf8");
    plaintext += decipher.final("utf8");
    return plaintext;
  } finally {
    // 3. Clear plaintext key from memory
    plaintextDataKey.fill(0);
  }
}

// Deterministic encryption for indexed fields
export function encryptDeterministic(plaintext: string, dataKey: Uint8Array): string {
  const hmac = createHmac("sha256", dataKey);
  hmac.update(plaintext);
  return hmac.digest("base64");
}

Architecture Rationale

• Memory Clearing: plaintextDataKey.fill(0) prevents key material from lingering in V8 heap memory.
• Version Tagging: keyVersion enables seamless rotation without full-table re-encryption.
• Deterministic Path: encryptDeterministic uses HMAC over the plaintext with the data key, producing consistent outputs for exact-match queries while avoiding IV reuse vulnerabilities.
• KMS Boundary: Master keys never touch application memory. Audit trails are centralized. IAM policies control access.

Pitfall Guide

1. Assuming TDE Covers All Data Surfaces Transparent Data Encryption only protects the primary storage volume. Database logs, temporary tables, read replicas, backups, and snapshots often bypass TDE unless explicitly configured. Always verify encryption inheritance across storage classes and backup pipelines.

2. Storing Keys in Environment Variables or Config Files Static keys in .env, Kubernetes secrets, or application configs are the fastest path to credential leakage. Use a dedicated KMS with IAM-scoped access. Never embed key material in source control or container images.

3. Neglecting Key Rotation Policies Keys that never rotate become single points of failure. Enable automatic rotation (typically 365 days). Implement versioned ciphertext storage and fallback decryption logic. Test rotation in staging before production rollout.

4. Over-Encrypting or Under-Encrypting Encrypting entire tables degrades query performance and complicates indexing. Encrypting only high-sensitivity fields reduces blast radius. Define a data classification matrix: PII, credentials, and financial data require application-level encryption; operational data can rely on volume encryption.

5. Overly Permissive KMS IAM Policies Granting kms:Decrypt to broad roles violates least privilege. Scope policies to specific key ARNs, required IAM roles, and VPC endpoints. Enable KMS key policies that restrict cross-account usage and require multi-factor authentication for administrative actions.

6. Ignoring Query and Index Implications Randomized encryption breaks B-tree indexes. Exact-match queries require deterministic encryption or encrypted search patterns (e.g., blind indexing). Range queries on encrypted data require order-preserving encryption or application-layer filtering, both with known security trade-offs.

7. Skipping Restore and Decrypt Testing Encryption is useless if decryption fails during incident response. Regularly test key recovery, backup decryption, and cross-region restore workflows. Document key version mapping and maintain offline key escrow for disaster recovery.

Best Practices from Production

• Use envelope encryption for all production workloads.
• Cache data keys in memory with short TTLs; never persist plaintext keys.
• Implement deterministic encryption only for fields requiring exact-match queries.
• Enable KMS CloudTrail/audit logging and set up alerts for unauthorized decrypt attempts.
• Run quarterly decryption drills against production backups.

Production Bundle

Action Checklist

• Classify data by sensitivity and map encryption scope per field/table
• Provision customer-managed KMS key with automatic 365-day rotation
• Implement envelope encryption pattern with versioned ciphertext storage
• Scope IAM/KMS policies to least-privilege roles and specific key ARNs
• Replace randomized encryption with deterministic/HMAC for indexed fields
• Verify encryption inheritance for backups, snapshots, logs, and replicas
• Schedule quarterly decryption drills and key rotation validation tests

Decision Matrix

Configuration Template

# Terraform: KMS Key + RDS Encryption
resource "aws_kms_key" "db_encryption" {
  description             = "Customer-managed key for database encryption at rest"
  deletion_window_in_days = 30
  enable_key_rotation     = true
  policy = jsonencode({
    Version = "2012-10-17"
    Statement = [
      {
        Sid    = "AllowRootAccount"
        Effect = "Allow"
        Principal = { AWS = "arn:aws:iam::${data.aws_caller_identity.current.account_id}:root" }
        Action   = "kms:*"
        Resource = "*"
      },
      {
        Sid    = "AllowAppRole"
        Effect = "Allow"
        Principal = { AWS = aws_iam_role.app_role.arn }
        Action   = ["kms:GenerateDataKey", "kms:Decrypt"]
        Resource = "*"
      }
    ]
  })
}

resource "aws_kms_alias" "db_encryption_alias" {
  name          = "alias/my-db-encryption-key"
  target_key_id = aws_kms_key.db_encryption.key_id
}

resource "aws_db_instance" "encrypted" {
  engine               = "postgres"
  engine_version       = "15.4"
  instance_class       = "db.r6g.large"
  storage_encrypted    = true
  kms_key_id           = aws_kms_key.db_encryption.arn
  backup_retention_period = 7
  copy_tags_to_snapshot  = true
}

// Application encryption config
{
  "encryption": {
    "provider": "aws-kms",
    "keyAlias": "alias/my-db-encryption-key",
    "algorithm": "aes-256-gcm",
    "cacheTtlMinutes": 15,
    "deterministicFields": ["email", "account_id"],
    "versionTag": "v1",
    "memoryClear": true
  }
}

Quick Start Guide

1. Create a customer-managed KMS key with automatic rotation enabled. Note the key ARN or alias.
2. Enable storage encryption on your database instance using the KMS key. Verify backups and snapshots inherit encryption.
3. Add the TypeScript envelope encryption module to your data access layer. Replace direct string storage with encryptAtRest() and decryptAtRest() calls.
4. Configure deterministic encryption for fields requiring exact-match queries. Update database indexes to use the deterministic output.
5. Run a decrypt validation test against a production backup. Confirm key version mapping and memory clearing behavior.