Secrets and Cryptography

Where secrets belong

A secret is anything whose disclosure grants access: API keys, database passwords, signing keys, OAuth client secrets, and private keys. The failure mode is almost never a broken cipher, it is a secret in the wrong place. Cryptographic Failures is A04:2025.

# .gitignore is a reminder, not a control
.env
.env.*
!.env.example
*.pem
*.key

Ship a committed .env.example with placeholder values so the required names are documented without the values.

Preventing and handling leaks

Detection has to be automatic, because humans miss it.

# Scan history, not just the working tree
gitleaks detect --source . --redact
trufflehog git file://. --only-verified
# Block commits before they happen
pre-commit install     # with a gitleaks or detect-secrets hook configured

A leaked secret is compromised, permanently. Rotate it. Do not "remove it in the next commit" and move on. Rewriting history does not help, because the object may already be cloned, cached by the host, or indexed. The order is: rotate, revoke the old value, then check access logs for use of it, then clean history.

Crypto do and do not

Use a vetted high-level library. The list below is the short version of current guidance, and every "do not" row is something that has caused real breaches.

# Python, cryptography: AES-GCM done correctly
import os
from cryptography.hazmat.primitives.ciphers.aead import AESGCM

key = AESGCM.generate_key(bit_length=256)     # store in a KMS, not in code
aead = AESGCM(key)
nonce = os.urandom(12)                        # fresh 96-bit nonce PER message
ct = aead.encrypt(nonce, plaintext, associated_data=b"v1:user:42")
pt = aead.decrypt(nonce, ct, associated_data=b"v1:user:42")

// Node, AES-256-GCM with the auth tag kept
import crypto from 'node:crypto'
const iv = crypto.randomBytes(12)
const c = crypto.createCipheriv('aes-256-gcm', key, iv)
const ct = Buffer.concat([c.update(pt), c.final()])
const tag = c.getAuthTag()          // store iv + tag + ct together

The nonce is not a secret, so store it alongside the ciphertext. It must be unique per key, which is a different requirement from being secret.

Constant-time comparison

Comparing a submitted token or MAC with == returns as soon as bytes differ, which leaks how many leading bytes matched. Use the platform's constant-time function.

import hmac
hmac.compare_digest(provided, expected)          # Python

crypto.timingSafeEqual(Buffer.from(a), Buffer.from(b))   // Node, equal lengths

subtle.ConstantTimeCompare([]byte(a), []byte(b)) == 1    // Go

java.security.MessageDigest.isEqual(a, b);               // Java

timingSafeEqual throws when the lengths differ, so compare fixed-length digests, or hash both sides first.

Data in transit and at rest

In transit. TLS everywhere, including internal service-to-service calls.

Strict-Transport-Security: max-age=63072000; includeSubDomains; preload

- Redirect all HTTP to HTTPS, then let HSTS remove the redirect from the picture. - Verify certificates. Disabling verification, in any client, is not a workaround. - TLS 1.2 as the floor, TLS 1.3 preferred, and no compression. - preload submits to the browser preload list. It is effectively hard to reverse, so do not add it until every subdomain is HTTPS-only.

At rest. Encrypt with a managed key where the platform offers it, and be honest about what it protects. Full-disk and volume encryption defends against a stolen disk, not against a SQL injection that reads the table.

Hashing something is not encrypting it and encrypting something is not hashing it. Use a hash when you never need the original back, and an AEAD cipher when you do.

Key management

The key is now the secret, so the same rules apply to it, with extra care.

stored value:  v2:<key-id>:<base64 nonce>:<base64 ciphertext+tag>

Encoding the version and the key id in the stored value is what makes rotation a background job rather than an outage.

Recognizing it in review

grep -rniE "aws_secret|api[_-]?key\s*=\s*[\"'][A-Za-z0-9/+]{16,}" .
grep -rniE "BEGIN (RSA |EC |OPENSSH )?PRIVATE KEY" .
grep -rniE "\bMD5\b|\bSHA1\b|ECB|DES\b|RC4" src/
grep -rniE "Math\.random|random\.randint.*token|rand\(\)" src/
grep -rniE "verify=False|rejectUnauthorized: *false|InsecureSkipVerify" src/

Checklist:

- No secret is in the repository, in a client bundle, in an image layer, or in a log. Secret scanning runs in CI. - Every credential is least privilege, and short-lived where the platform allows it. - Encryption is AEAD, and the nonce is fresh per message. - No MD5, SHA-1, ECB, DES, or RC4 in any security-relevant path. - Randomness for tokens, ids, nonces, and salts comes from a CSPRNG. - Every secret or MAC comparison is constant time. - Certificate verification is enabled in every client, with no verify=False. - HSTS is set with a long max-age, and preload only when every subdomain is ready. - Keys live in a KMS or secret manager, are separated by purpose, are versioned in the stored format, and have a tested rotation runbook. - No custom cryptographic construction exists anywhere in the codebase.

Further reading: the OWASP Cryptographic Storage Cheat Sheet, Secrets Management Cheat Sheet, and Transport Layer Security Cheat Sheet.