---
name: encrypt-sensitive-data
description: Encrypts sensitive data at rest, in transit, and per-field using AEAD-only ciphers (AES-256-GCM or ChaCha20-Poly1305 — never ECB, never unauthenticated CBC, never raw RSA) — envelope encryption where a KMS-held KEK wraps a per-record/per-tenant DEK, per-column field encryption for PII with deterministic-vs-randomized chosen per query need, strict unique-nonce/IV discipline (random 96-bit or counter, NEVER reused under one key), AAD binding ciphertext to its context (tenant/row id), versioned keys + rotation that re-wraps DEKs without re-encrypting data, TLS 1.2+/1.3 with mTLS and modern cipher suites, and — critically — passwords are HASHED with argon2id/bcrypt, NOT encrypted. Distinct from secrets-management (stores the app secrets/keys this skill consumes) and map-privacy-data-gdpr (the legal PII/erasure obligations encryption helps satisfy).
when_to_use: You must protect sensitive data — encrypting PII/PHI/card data at rest, a per-column/field-level encryption scheme, envelope encryption with a KMS (AWS KMS/GCP KMS/Vault Transit), key rotation, choosing a cipher/mode/nonce strategy, enforcing TLS/mTLS, or hashing passwords. Distinct from secrets-management (storing and injecting the KEKs/API keys/credentials — that skill provisions the keys; this one uses them to encrypt data) and map-privacy-data-gdpr (the legal classification/erasure/residency duties that encryption and crypto-shredding help you meet).
---

## When to Use

Reach for this skill when the task is making sensitive *data* cryptographically protected — at rest, in transit, or field-by-field:

- "Encrypt SSNs / card numbers / health records / PII columns in the database"
- "Set up envelope encryption with AWS KMS / GCP KMS / Vault Transit (DEK + KEK)"
- "Rotate our encryption keys" / "we need versioned keys without re-encrypting everything"
- "Which cipher/mode — is AES-CBC okay? do we need a separate MAC? what nonce?"
- "Enforce TLS 1.3 / mutual TLS between services with modern cipher suites"
- "Are we storing passwords correctly?" (hash, don't encrypt)
- "Make a user's data unrecoverable on account deletion" (crypto-shredding)

NOT this skill:
- Storing/injecting the KEKs, API keys, DB creds, and `.env` material this skill *consumes* → secrets-management (it provisions and rotates the secrets; this skill encrypts data *with* them)
- The legal side — what counts as PII/PHI, lawful basis, right-to-erasure, data residency → map-privacy-data-gdpr (this skill is the *technical control*, e.g. crypto-shredding, that satisfies those duties)
- TLS *termination/cert issuance* at the edge proxy, ACME, SNI routing → configure-dns-tls and configure-reverse-proxy-lb (this skill covers the cipher-suite/mTLS *policy*, not cert plumbing)
- Browser security response headers (HSTS, CSP) → configure-security-headers-csp (HSTS *enforces* HTTPS; this skill is the transport crypto itself)
- Login sessions, JWT signing/verification, token rotation → auth-jwt-session (signatures/JWE are adjacent but that owns session lifecycle)
- Identifying the threats/attacker model that justify these controls → threat-model-stride
- A broad security pass over a diff → security-review (this skill is the deep crypto specialist it defers to)

## Steps

1. **Classify data first, then pick the protection tier — encryption is not the answer to everything.** Three distinct goals need three different tools:

   | Goal | Use | NEVER |
   |---|---|---|
   | Verify a credential later (passwords) | **slow password hash** (argon2id) — one-way | encrypt; never decrypt a password |
   | Protect data you must read back (PII, PHI, PAN, tokens) | **AEAD encryption** + KMS envelope | reversible "encoding", base64, ROT |
   | Integrity/origin without secrecy | HMAC-SHA-256 / signature | "encrypt to authenticate" |
   | Index/search without revealing value | HMAC-based blind index or deterministic enc | plaintext index column |

   Encrypting a password is a **bug**, not a feature: anything reversible means an attacker (or insider) with the key gets every plaintext password.

2. **Use AEAD ciphers only. Banned modes are non-negotiable.** Authenticated Encryption with Associated Data gives confidentiality *and* tamper-detection in one primitive:

   | Use this | Why |
   |---|---|
   | **AES-256-GCM** | hardware-accelerated (AES-NI), NIST-approved, ubiquitous KMS support |
   | **ChaCha20-Poly1305** | faster on CPUs without AES-NI (mobile/ARM), constant-time by design |
   | **AES-256-GCM-SIV / XChaCha20-Poly1305** | nonce-misuse-resistant / 192-bit nonce — prefer when you can't guarantee unique 96-bit nonces |

   | Banned | Why it's broken |
   |---|---|
   | **ECB** | identical plaintext blocks → identical ciphertext (the "ECB penguin"); leaks structure |
   | **CBC/CTR without a MAC** | unauthenticated → padding-oracle (CBC) & bit-flipping attacks; ciphertext is malleable |
   | **Raw RSA / RSA-PKCS#1v1.5 enc** | use RSA-OAEP, or better ECIES/hybrid; never "RSA the whole payload" |
   | DES/3DES/RC4/MD5/SHA-1 | broken/deprecated |

   Don't hand-roll "AES + separate HMAC" (encrypt-then-MAC) unless you must — get the construction order wrong and you reintroduce the oracle. Use a vetted library: **libsodium** (`crypto_aead_*` / `secretbox`), **Go** `crypto/cipher` GCM or `nacl/secretbox`, **Python** `cryptography` `AESGCM`/`ChaCha20Poly1305` (not the low-level `Cipher` API), **Java** `javax.crypto` GCM or Google **Tink**, **Rust** `aes-gcm`/`chacha20poly1305` RustCrypto crates, **Node** `crypto.createCipheriv('aes-256-gcm', …)` + `getAuthTag()`. **Tink/libsodium are the senior default** — they pick safe modes and manage nonces for you.

3. **Nonce/IV discipline: unique per (key, message), forever. This is the #1 way AEAD fails.** GCM with a **repeated nonce under the same key is catastrophic** — it leaks the XOR of plaintexts *and* the authentication key (forgery). Rules:
   - 96-bit (12-byte) nonce for GCM. Either **random** from a CSPRNG (`os.urandom`/`crypto.randomBytes`/`getrandom`) or a **monotonic counter** — never both, never `0`, never a timestamp, never reuse.
   - Random 96-bit nonces are safe only up to **~2³² messages per key** (birthday bound). High-volume? Rotate the DEK sooner, or use **XChaCha20-Poly1305 (192-bit nonce)** / **AES-GCM-SIV** which tolerate accidental reuse.
   - **Store the nonce alongside the ciphertext** (it's not secret) — typical record = `version ‖ nonce ‖ ciphertext ‖ tag`.
   - Don't derive the nonce from the plaintext or a non-unique field. Don't reuse one nonce across a re-encrypt.

4. **Bind ciphertext to its context with AAD (Associated Data).** AEAD lets you authenticate (not encrypt) extra context — pass the **row id / tenant id / column name / key version** as AAD. This stops an attacker from copying a valid ciphertext from row A into row B (ciphertext substitution): decryption of B fails because the AAD no longer matches. AAD must be reconstructible at decrypt time from the record's own metadata.

5. **Envelope encryption: a KMS-held KEK wraps per-record/per-tenant DEKs. Never encrypt bulk data directly with the KMS key.** The pattern that scales and rotates cleanly:

   ```
   1. KMS.GenerateDataKey(KeyId=KEK, KeySpec=AES_256)
        → returns { Plaintext DEK, Encrypted DEK (wrapped by KEK) }
   2. Encrypt your data locally with the plaintext DEK (AES-256-GCM, fresh nonce)
   3. Store: encrypted_dek ‖ key_version ‖ nonce ‖ ciphertext ‖ tag
   4. ZERO the plaintext DEK from memory immediately after use
   5. Decrypt: KMS.Decrypt(encrypted_dek) → plaintext DEK → local AEAD decrypt
   ```

   - **KEK** lives in **AWS KMS / GCP KMS / Azure Key Vault / Vault Transit / an HSM** and *never leaves it* — KMS does the wrap/unwrap, your app never sees KEK bytes. **DEK** is short-lived in app memory, zeroed after use.
   - Granularity: **per-tenant or per-record DEK** for crypto-shredding (delete the DEK → that data is gone). Per-row is most flexible; cache the unwrapped DEK briefly (e.g. LRU with TTL) to avoid a KMS call per row.
   - Tools: AWS **KMS** + the **AWS Encryption SDK** (handles the envelope + nonce for you), GCP **KMS**, HashiCorp **Vault Transit** (`vault write transit/encrypt/...` — Vault holds the key, returns ciphertext), or **Tink**'s `KmsEnvelopeAead`. Prefer these over rolling your own envelope.

6. **Per-field/column encryption for PII — choose deterministic vs randomized by query need.** Application-layer (encrypt before the DB sees it) beats trusting only DB-native TDE, because TDE protects the *disk file*, not a SQL-injection or a DBA reading rows.

   | Mode | Same plaintext → | Lets you | Cost |
   |---|---|---|---|
   | **Randomized** (fresh nonce) | different ciphertext | only decrypt-then-use | leaks nothing; **default for PII** |
   | **Deterministic** (synthetic IV / SIV) | same ciphertext | equality lookup, joins, unique constraint | leaks equality (which rows share a value) |

   For *searchable* encryption use a **blind index**: store `HMAC-SHA256(key, normalize(value))` in a separate indexed column and query by that, keeping the value column randomized-encrypted. Don't reach for order-preserving/fully-homomorphic encryption (leaky / impractical) unless you truly understand the tradeoff. Postgres `pgcrypto` is fine for small cases but does *application-visible* keys in SQL logs — prefer encrypting in the app. **Don't encrypt a column you need range-query or `LIKE` on** without redesigning the access pattern first.

7. **Passwords: hash with a memory-hard KDF, salted and parameterized — never encrypt, never plain SHA-256.** Use:

   | Algorithm | Params (2025 baseline) |
   |---|---|
   | **argon2id** (first choice) | m=19–64 MiB, t=2–3, p=1; OWASP min m=19 MiB,t=2,p=1 |
   | **scrypt** | N=2^17, r=8, p=1 (or N=2^15 for lighter) |
   | **bcrypt** (legacy/compat) | cost ≥ 12; **pre-hash with SHA-256 + base64** if password may exceed 72 bytes (bcrypt silently truncates) |

   - A **per-password random salt** is mandatory (the libraries generate and embed it in the encoded hash — `$argon2id$v=19$m=...`). No global "pepper-as-salt".
   - **Pepper** (optional, defense-in-depth) = a secret key *not* in the DB; either HMAC the password before hashing or keep it in a KMS/HSM. Store the pepper in secrets-management, never beside the hash.
   - **Never** use fast hashes (MD5, SHA-1, SHA-256, SHA-512) bare for passwords — GPUs do billions/sec. **Never** encrypt passwords (reversible = breach of all of them).
   - Verify in **constant time** (the KDF's `verify`/`checkpw` does this); re-hash on login if cost params have since increased.

8. **TLS in transit: 1.2 minimum, 1.3 preferred; modern cipher suites; mTLS for service-to-service.**
   - **Versions:** disable SSLv3/TLS 1.0/1.1 entirely. Allow **TLS 1.2 + 1.3**; prefer 1.3 (1-RTT, AEAD-only, forward-secret by construction).
   - **TLS 1.2 cipher suites** (AEAD + ECDHE forward secrecy only): `ECDHE-ECDSA-AES128-GCM-SHA256`, `ECDHE-RSA-AES256-GCM-SHA384`, `ECDHE-*-CHACHA20-POLY1305`. **No** CBC suites, no static RSA key exchange, no `NULL`/`RC4`/`3DES`/`EXPORT`. TLS 1.3 only offers AEAD suites, so the choice is made for you.
   - Mozilla SSL Config "**Intermediate**" is the safe default; "Modern" = TLS 1.3-only. Verify with **`testssl.sh`** or SSL Labs (target **A/A+**). Enable **HSTS** at the edge (handoff to configure-security-headers-csp).
   - **mTLS** for internal/service-to-service: both sides present certs; pin to your CA, short-lived certs (SPIFFE/SVID, Istio, Linkerd, or a service-mesh issuer). Validate the **full chain + SAN**, not just "a cert was presented."
   - **Never disable cert verification** (`verify=False`, `rejectUnauthorized:false`, `InsecureSkipVerify:true`) outside a throwaway test — it silently turns TLS into plaintext-to-anyone.

9. **Key rotation with versioned keys — rotate the KEK cheaply, re-wrap DEKs, lazy-re-encrypt data.** Store a **`key_version`** with every ciphertext so multiple key generations coexist:
   - **KEK rotation** (cheapest, do on schedule, e.g. annually or per policy): KMS rotates the KEK; you **re-wrap each DEK** (decrypt-unwrap with old, wrap with new). Bulk data is *untouched* — that's the whole point of envelope encryption.
   - **DEK rotation:** generate a new DEK, **re-encrypt the affected records lazily** (on next write, or a background backfill) and bump `key_version`. Keep old key versions readable until backfill completes, then retire.
   - **On compromise:** rotate immediately and force re-encryption; **crypto-shred** by destroying a DEK to make its data permanently unrecoverable (the GDPR-erasure trick — handoff to map-privacy-data-gdpr).
   - Decrypt path must **dispatch on the stored `key_version`**; never assume "current key." Keep a registry of retired versions for audit.

10. **Operational hygiene — the parts that get forgotten.** Generate all keys/nonces/salts from a **CSPRNG** (`os.urandom`, `crypto.randomBytes`, `getrandom(2)`, `SecureRandom`) — never `Math.random`/`rand()`/`mt19937`. **Zero plaintext keys** from memory after use where the language allows (Go `defer` wipe, Rust `zeroize`, libsodium `sodium_memzero`). Don't log plaintext, keys, or full ciphertext. Encrypt **backups and replicas** too (same KMS). Use **constant-time comparison** for MACs/tags/tokens (`hmac.compare_digest`, `crypto.timingSafeEqual`, `subtle.ConstantTimeCompare`) — `==` leaks via timing. Run a **`security-review`** over the crypto diff before shipping.

## Common Errors

- **Encrypting passwords instead of hashing.** Reversible = one key compromise dumps every password. Fix: argon2id/bcrypt, one-way (step 7).
- **Plain/fast hash for passwords** (`SHA256(password)`, unsalted MD5). GPUs crack billions/sec; rainbow tables for unsalted. Fix: memory-hard KDF with per-password salt.
- **ECB mode / unauthenticated CBC.** ECB leaks structure; CBC-without-MAC → padding oracle, malleable ciphertext. Fix: AEAD (AES-GCM/ChaCha20-Poly1305) only.
- **Nonce/IV reuse under one key (GCM).** Catastrophic — leaks plaintext XOR *and* the auth key (forgeries). Fix: unique nonce per message; XChaCha20/GCM-SIV if you can't guarantee it (step 3).
- **Hardcoded / static IV** (`iv = new byte[12]` all zeros). Same as reuse. Fix: fresh CSPRNG nonce per encryption, stored with ciphertext.
- **Encrypting bulk data directly with the KMS/KEK.** Throughput and cost explode; no clean rotation. Fix: envelope — KEK wraps per-record DEK (step 5).
- **No AAD binding.** Valid ciphertext copy-pasted between rows/tenants decrypts fine. Fix: pass row/tenant/version as AAD (step 4).
- **No key version on ciphertext.** Rotation becomes a flag-day re-encrypt-everything. Fix: store `key_version`, dispatch decryption on it (step 9).
- **Plaintext DEK left in memory / logged.** Heap dump or log leak = game over. Fix: zero after use; never log keys/plaintext/tags.
- **`Math.random()` / `rand()` for keys, nonces, or salts.** Predictable → forgeable. Fix: CSPRNG only.
- **Disabling TLS verification** (`verify=False`, `InsecureSkipVerify`, `rejectUnauthorized:false`). Silent MITM. Fix: validate chain + SAN; only bypass in isolated tests.
- **Weak TLS** (TLS 1.0/1.1, CBC suites, static RSA, RC4/3DES). Fix: TLS 1.2+/1.3, AEAD+ECDHE suites; verify with testssl.sh.
- **`==` on MACs/tags/tokens.** Timing side-channel. Fix: constant-time comparison.
- **Roll-your-own crypto / `Cipher` low-level API.** Easy to misorder encrypt-then-MAC, mishandle padding. Fix: libsodium / Tink / AWS Encryption SDK.
- **Deterministic encryption on high-cardinality PII you didn't mean to.** Leaks equality patterns. Fix: randomized by default; deterministic/blind-index only where a query needs it (step 6).

## Verify

1. **No banned modes/algorithms:** grep the diff for `ECB`, `AES/CBC` without an accompanying MAC, `DES`, `RC4`, `MD5`/`SHA1` on secrets, raw RSA encrypt — zero hits. All symmetric encryption is AES-GCM / ChaCha20-Poly1305 (AEAD).
2. **Passwords are hashed, not encrypted:** grep finds argon2id/bcrypt/scrypt on the password path and **no** encrypt/decrypt of passwords; salts are per-password (encoded in the hash); cost params meet the step-7 baseline.
3. **Nonce uniqueness:** confirm every encryption draws a fresh CSPRNG nonce (or a guaranteed-unique counter); no static/zero IV; nonce stored with ciphertext. For high volume, DEK rotation or a nonce-misuse-resistant mode is in place.
4. **Envelope encryption holds:** bulk data is encrypted with a DEK, the DEK is wrapped by a KMS-held KEK that never leaves KMS, plaintext DEK is zeroed after use, and a `key_version` is stored per record.
5. **AAD binds context:** moving a valid ciphertext from one row/tenant to another **fails** decryption (AAD mismatch).
6. **Rotation works without re-encrypting everything:** rotating the KEK re-wraps DEKs only; old `key_version` ciphertext still decrypts; a DEK-destroy crypto-shreds its records (they become permanently undecryptable).
7. **TLS posture:** `testssl.sh <host>` / SSL Labs returns **A/A+** — TLS 1.2+ only, AEAD+forward-secret suites, no CBC/RC4/3DES; mTLS validates the full chain + SAN; no `verify=False`/`InsecureSkipVerify` in non-test code.
8. **Randomness + timing:** all keys/nonces/salts come from a CSPRNG (no `Math.random`/`rand`); MAC/tag/token comparisons are constant-time.
9. **Tamper detection:** flipping one ciphertext byte makes decryption **fail** (auth tag rejects it) rather than returning garbage plaintext.

Done = sensitive data is encrypted with AEAD under unique nonces, bulk data uses KMS envelope encryption with versioned, rotatable keys and context-binding AAD, passwords are hashed with argon2id/bcrypt (never encrypted), PII fields are randomized-encrypted (deterministic/blind-index only where a query demands it), transport is TLS 1.2+/1.3 with modern suites and mTLS where needed, and all keys/nonces/salts come from a CSPRNG with constant-time tag checks — all proven by checks 1–9, with `security-review` run over the crypto diff.