mufassall

Cheat sheet · Security

Encryption and secrets

14 min · Intermediate · mufassall.dtwin.uz/en/l/encryption/

← Open the lesson

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
Final scene
35%

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_secrets

Mermaid: 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 OK

D2

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
@enduml

PlantUML: 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
@enduml

Recap

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

MetricStartEnd
Readable copies40
Response p95120 ms158 ms
Failed requests0%0%

Steps

  1. Problem Notes travel in plain text

    The app sends notes over plain HTTP.

  2. 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.

  3. Problem The certificate expired at midnight

    Someone renewed the certificate by hand once a year.

  4. Fix Certificates renew themselves

    The server now asks the CA for a new certificate on its own, with the ACME protocol.

  5. Problem A backup leaks, and it is plain text

    Nightly backups go to a storage bucket.

  6. Fix Encrypt the notes before saving them

    The API now encrypts the note with AES-256-GCM before the INSERT.

  7. Problem The key sits next to the data

    A container image with the config file was pushed to a public registry by mistake.

  8. Fix Envelope encryption with a KMS

    The master key now lives in a KMS and never leaves it.

  9. Fix No secrets in code: a secrets manager

    The database password moves out of the config file.

  10. 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.

  11. 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.