# Documentation of algorithms/key lengths/ciphers

- **Pattern:** `ab-001431` (`finserv-encryption.pci-alignment.encryption-documentation`)
- **Severity:** low
- **Lifecycle:** active
- **Last modified:** 2026-04-18
- **Canonical URL:** https://auditbuffet.com/patterns/ab-001431
- **License:** CC-BY-4.0 — attribute to AuditBuffet Pattern Catalog (https://auditbuffet.com/patterns/ab-001431)

## Why it matters

PCI-DSS 4.0 Req-12.3 requires organizations to document their cryptographic inventory — which algorithms are in use, where, and with what key lengths. NIST SC-13 requires documentation of approved cryptographic modules. Without this documentation, compliance auditors (QSAs, FFIEC examiners) cannot verify that encryption meets the required standards, and internal teams cannot make informed decisions when upgrading or rotating algorithms. A `SECURITY.md` that says "we encrypt sensitive data" without naming the algorithm or key length cannot satisfy either framework. Documentation gaps also create drift risk: without a written spec, different developers may implement different algorithms across services.

## Severity rationale

Low because missing documentation is an audit and governance failure rather than an active exploit path, but it blocks PCI-DSS QSA approval and creates conditions for algorithm drift.

## Remediation

Create `SECURITY.md` in the repo root (or a dedicated `docs/encryption.md`) and document at least three encryption aspects: algorithm name, key length, and cipher suite or mode. Template:

```markdown
# Encryption Overview

## Data at Rest
- Algorithm: AES-256-GCM
- Key length: 256 bits
- Mode: GCM (authenticated encryption, provides integrity + confidentiality)
- Key storage: AWS KMS (key ID documented in `docs/kms-inventory.md`)

## Data in Transit
- Protocol: TLS 1.3 (minimum TLS 1.2)
- Cipher suites: TLS_AES_256_GCM_SHA384, ECDHE-RSA-AES256-GCM-SHA384
- Certificate authority: Let's Encrypt (auto-renewed)
- HSTS: Enabled (max-age=63072000)

## Password Hashing
- Algorithm: Argon2id (NIST SP 800-63B-4)
- Parameters: m=65536, t=3, p=4

## Last updated: 2026-04-01
```

Link this document from the deployment checklist so it's reviewed before each production release.

## Detection

- **ID:** `encryption-documentation`
- **Severity:** `low`
- **What to look for:** Count all documentation files that reference encryption (SECURITY.md, README, architecture docs, code comments). Enumerate the specific algorithms, key lengths, and cipher suites documented. Quote the actual algorithm names and key lengths found. Verify at least 3 encryption aspects are documented: algorithm, key length, and cipher suite.
- **Pass criteria:** At least 1 documentation file exists listing at least 3 encryption aspects: algorithm name, key length, and cipher suite. Report the count even on pass (e.g., "SECURITY.md documents 4 aspects: AES-256-GCM, 256-bit keys, TLS 1.3, TLS_AES_256_GCM_SHA384").
- **Fail criteria:** No documentation of encryption approach (0 files reference encryption), or fewer than 3 encryption aspects documented.
- **Skip (N/A) when:** Very early-stage projects (pre-alpha) that have not yet implemented encryption — cite the actual development stage found.
- **Detail on fail:** `"0 documentation files reference encryption — algorithm and key length choices undocumented"` or `"SECURITY.md mentions 'AES encryption' but only 1 of 3 required aspects specified (missing key length and cipher suite)"`
- **Remediation:**
  - Create a SECURITY.md or encryption.md file:
    ```markdown
    # Encryption Overview

    ## Data at Rest
    - Algorithm: AES-256-GCM
    - Key length: 256 bits
    - Key storage: AWS KMS
    - Key rotation: Automatic (annually)

    ## Data in Transit
    - Protocol: TLS 1.3
    - Minimum TLS: TLS 1.2
    - Cipher suites: TLS13:TLS_AES_256_GCM_SHA384:ECDHE-RSA-AES256-GCM-SHA384
    - Certificate validation: Enabled

    ## Hashing (Passwords/Auth)
    - Algorithm: Argon2id / bcrypt
    - Parameters: [specific config]
    ```

## External references

- nist SC-13
- pci-dss Req-12.3
- external FFIEC-IT-Handbook-IS-Crypto — https://ithandbook.ffiec.gov/it-booklets/information-security.aspx

Taxons: regulatory-conformance, cryptography-and-secrets

HTML version: https://auditbuffet.com/patterns/ab-001431