Cheat sheet · Security
Encryption and secrets
The problem
A notes app keeps people's private notes. We find every place where a stolen copy is readable: the network, the disk, the backups and the config file, and close them one by one.
What you learn
- What a TLS handshake checks and why certificates must renew themselves
- Encryption at rest, and why a key next to the data protects nothing
- Envelope encryption: a data key per record, a master key that never leaves the KMS
- Secrets in a secrets manager with short leases, and key rotation without re-encrypting everything
Diagram as code
The lesson's final design as text: paste it into Jira, GitLab, GitHub, Notion or your docs, where Mermaid renders by itself. There are D2 and PlantUML (Confluence, IntelliJ) versions too.
Mermaid: flowchart
flowchart LR
n_app(["Phone app"])
n_api["Notes API"]
n_db[("Database")]
n_attacker(("Attacker"))
n_backup[("Backups")]
n_kms>"KMS"]
n_secrets>"Secrets manager"]
n_app --> n_api
n_api --> n_db
n_db --> n_backup
n_backup --x|"lost"| n_attacker
n_api --x|"lost"| n_attacker
n_api --> n_kms
n_api -.->|"retry"| n_secretsMermaid: request sequence
sequenceDiagram
participant n_app as Phone app
participant n_api as Notes API
participant n_ca as Certificate authority
participant n_backup as Backups
actor n_attacker as Attacker
participant n_db as Database
participant n_kms as KMS
participant n_secrets as Secrets manager
Note over n_app,n_api: Notes travel in plain text
n_app->>n_api: POST /notes HTTP/1.1
n_api-->>n_app: HTTP/1.1 201 Created
Note over n_app,n_api: TLS handshake: a shared key and a proof of identity
n_app->>n_api: ClientHello
n_api-->>n_app: ServerHello + Certificate
Note over n_app,n_api: The certificate expired at midnight
n_app->>n_api: ClientHello
n_api-->>n_app: ServerHello + Certificate
Note over n_api,n_ca: Certificates renew themselves
n_api->>n_ca: POST /acme/new-order HTTP/1.1
n_ca-->>n_api: HTTP/1.1 201 Created
Note over n_backup,n_attacker: A backup leaks, and it is plain text
n_backup->>n_attacker: $ strings notes-2026-11-01.bak #124; grep -i door
Note over n_api,n_db: Encrypt the notes before saving them
n_api->>n_db: INSERT INTO notes (id, owner, text_enc, nonce)
n_db-->>n_api: INSERT 0 1
Note over n_api,n_attacker: The key sits next to the data
n_api->>n_attacker: config/prod.json (from a leaked image)
Note over n_api,n_kms: Envelope encryption with a KMS
n_api->>n_kms: POST /v1/keys/notes-master:generateDataKey HTTP/1.1
n_kms-->>n_api: HTTP/1.1 200 OK
Note over n_api,n_secrets: No secrets in code: a secrets manager
n_api->>n_secrets: GET /v1/secret/notes-db HTTP/1.1
n_secrets-->>n_api: HTTP/1.1 200 OK
Note over n_api,n_kms: Rotation without re-encrypting the data
n_api->>n_kms: POST /v1/keys/notes-master:reEncrypt HTTP/1.1
n_kms-->>n_api: HTTP/1.1 200 OKD2
direction: right
n_app: "Phone app" {
shape: rectangle
}
n_api: "Notes API" {
shape: rectangle
}
n_db: "Database" {
shape: cylinder
}
n_attacker: "Attacker" {
shape: person
}
n_backup: "Backups" {
shape: stored_data
}
n_kms: "KMS" {
shape: cloud
}
n_secrets: "Secrets manager" {
shape: cloud
}
n_app -> n_api
n_api -> n_db
n_db -> n_backup
n_backup -> n_attacker: "lost" {
style.stroke-width: 4
target-arrowhead.shape: cross
}
n_api -> n_attacker: "lost" {
style.stroke-width: 4
target-arrowhead.shape: cross
}
n_api -> n_kms
n_api -> n_secrets: "retry" {
style.stroke-dash: 3
}PlantUML: request sequence
@startuml
participant "Phone app" as n_app
participant "Notes API" as n_api
boundary "Certificate authority" as n_ca
database "Backups" as n_backup
actor "Attacker" as n_attacker
database "Database" as n_db
boundary "KMS" as n_kms
boundary "Secrets manager" as n_secrets
note over n_app, n_api : Notes travel in plain text
n_app -> n_api : POST /notes HTTP/1.1
n_api --> n_app : HTTP/1.1 201 Created
note over n_app, n_api : TLS handshake: a shared key and a proof of identity
n_app -> n_api : ClientHello
n_api --> n_app : ServerHello + Certificate
note over n_app, n_api : The certificate expired at midnight
n_app -> n_api : ClientHello
n_api --> n_app : ServerHello + Certificate
note over n_api, n_ca : Certificates renew themselves
n_api -> n_ca : POST /acme/new-order HTTP/1.1
n_ca --> n_api : HTTP/1.1 201 Created
note over n_backup, n_attacker : A backup leaks, and it is plain text
n_backup -> n_attacker : [duplicate] $ strings notes-2026-11-01.bak | grep -i door
note over n_api, n_db : Encrypt the notes before saving them
n_api -> n_db : INSERT INTO notes (id, owner, text_enc, nonce)
n_db --> n_api : INSERT 0 1
note over n_api, n_attacker : The key sits next to the data
n_api -> n_attacker : [duplicate] config/prod.json (from a leaked image)
note over n_api, n_kms : Envelope encryption with a KMS
n_api -> n_kms : POST /v1/keys/notes-master:generateDataKey HTTP/1.1
n_kms --> n_api : HTTP/1.1 200 OK
note over n_api, n_secrets : No secrets in code: a secrets manager
n_api -> n_secrets : GET /v1/secret/notes-db HTTP/1.1
n_secrets --> n_api : HTTP/1.1 200 OK
note over n_api, n_kms : Rotation without re-encrypting the data
n_api -> n_kms : POST /v1/keys/notes-master:reEncrypt HTTP/1.1
n_kms --> n_api : HTTP/1.1 200 OK
@endumlPlantUML: components
@startuml
left to right direction
agent "Phone app" as n_app
component "Notes API" as n_api
database "Database" as n_db
actor "Attacker" as n_attacker
storage "Backups" as n_backup
cloud "KMS" as n_kms
cloud "Secrets manager" as n_secrets
n_app --> n_api
n_api --> n_db
n_db --> n_backup
n_backup -[#c62828,dashed]-> n_attacker : lost
n_api -[#c62828,dashed]-> n_attacker : lost
n_api --> n_kms
n_api ..> n_secrets : retry
@endumlRecap
Find every place a copy of the data lives, then close each one.
1) TLS on every connection, with certificates that renew themselves and an alert before expiry. 2) Encrypt at rest, including backups. 3) Envelope encryption: data keys per record, the master key only in the KMS. 4) Secrets in a secrets manager with short leases, never in code. 5) Rotate by re-wrapping keys, not by re-encrypting data.
Numbers: at the start and at the end
| Metric | Start | End |
|---|---|---|
| Readable copies | 4 | 0 |
| Response p95 | 120 ms | 158 ms |
| Failed requests | 0% | 0% |
Steps
- Problem Notes travel in plain text
The app sends notes over plain HTTP.
- Fix TLS handshake: a shared key and a proof of identity
Before any data, the app and the server agree on a fresh key: each sends the public half of a
key_share, and both compute the same secret. - Problem The certificate expired at midnight
Someone renewed the certificate by hand once a year.
- Fix Certificates renew themselves
The server now asks the CA for a new certificate on its own, with the ACME protocol.
- Problem A backup leaks, and it is plain text
Nightly backups go to a storage bucket.
- Fix Encrypt the notes before saving them
The API now encrypts the note with AES-256-GCM before the
INSERT. - Problem The key sits next to the data
A container image with the config file was pushed to a public registry by mistake.
- Fix Envelope encryption with a KMS
The master key now lives in a KMS and never leaves it.
- Fix No secrets in code: a secrets manager
The database password moves out of the config file.
- Case Rotation without re-encrypting the data
Every year the KMS makes a new master key version, and old versions stay to decrypt old data.
- Recap Recap
Find every place a copy of the data lives, then close each one.
Terms
- TLS
- The protocol that encrypts a connection: in the handshake both sides agree on a shared key and the server proves its identity with a certificate. Certificates must renew themselves or they expire at midnight.
- Encryption at rest
- Data is encrypted before it is written, so disks and backups hold only ciphertext. If the key sits next to the data, this protects nothing.
- Envelope encryption (KMS)
- Each record is encrypted with its own data key, and the data key is wrapped by a master key that never leaves the KMS. Only the wrapped key is stored, and rotation re-wraps keys instead of re-encrypting data.