Crypto Primitive Selection

crypto-primitive-selection

Decision aid for cryptographic primitive choices. Use this skill when designing or reviewing systems that encrypt, authenticate, derive, or sign — and especially before writing any line of code that calls a low-level crypto API.

The skill does not pick a single product or library for you. It gives you a suggested default for the common case, a vetted alternatives menu with selection criteria, and a research path for when neither default nor menu fits your constraints.

Triggers

Primary phrases are matched automatically from the description. Alternate expressions:

• "choose AEAD" / "which AEAD"
• "which KDF" / "password hashing"
• "encrypt with AES" / "AES-CBC" / "AES-GCM"
• "should I use HMAC"
• "sign vs MAC"
• "openssl enc" (any context)
• "is HMAC-SHA1 OK"
• "is PBKDF2 enough"
• "applied crypto review"

When NOT to use this skill

• High-level protocol design (use a peer-reviewed protocol like TLS 1.3, Noise, or Signal — don't roll your own)
• Post-quantum migration planning (separate concern; consult NIST PQC selections)
• Network-layer threat modeling (handled by sdlc-complete/skills/security-assessment)

Catalog Format

Every primitive section follows the same three-part pattern:

1. Suggested default — the right answer for the common case, with rationale
2. Vetted alternatives menu — when to pick something else, with selection criteria
3. Research path — how to evaluate newer or domain-specific options when nothing in the menu fits

The skill never hard-picks a vendor product. It describes properties; you choose against your constraints.

Section 1: AEAD (Authenticated Encryption with Associated Data)

Use when: Encrypting data at rest or in flight where you also need to detect tampering. This is the default for ~95% of "encrypt this" tasks.

Suggested default

XChaCha20-Poly1305 via libsodium (crypto_secretstream_xchacha20poly1305_* for streams, crypto_aead_xchacha20poly1305_ietf_* for one-shot).

Rationale:

• 192-bit nonces — random nonce generation is misuse-resistant (no birthday bound concerns for the lifetime of any realistic key)
• Audited C implementation (libsodium has been independently audited; tracks Bernstein/Aumasson reference)
• Broad language bindings (Python, Rust, Go, Node, Ruby, .NET, Swift — all wrap the same C lib)
• No hardware dependency — runs at acceptable speed in software on every architecture
• Streaming API via secretstream handles multi-chunk encryption with replay/reorder/truncation protection

Vetted alternatives

Research path for newer/domain-specific options

When the default and menu don't fit:

1. CFRG drafts at datatracker.ietf.org/wg/cfrg/documents/ — the IRTF Crypto Forum vets new constructions before IETF/NIST adoption
2. NIST CAVP validation list (csrc.nist.gov/projects/cryptographic-algorithm-validation-program) — required if you need FIPS-validated software/hardware
3. NIST Lightweight Crypto winners (Ascon family, 2023) — prefer for tightly-constrained IoT
4. SoK papers — search for "Systematization of Knowledge: AEAD" on IACR ePrint; SoK papers summarize the landscape with attack tables
5. Rule out: anything labeled "experimental", "research preview", or with no public security analysis from a non-author. If the construction is one academic paper old, it's not production-ready.

Anti-patterns (BLOCK on these)

• CBC, CTR, OFB, CFB without a separate MAC. Unauthenticated. Bit-flips are silently undetectable; padding oracles leak plaintext on decryption error paths. → Rule: no-unauthenticated-encryption
• openssl enc without -pbkdf2 -iter <N> (or similar explicit KDF flags). Defaults to a single-MD5-iteration KDF. → Rule: crypto-flag-verification
• Reusing GCM nonces with the same key. Catastrophic — recover the authentication key and forge arbitrary ciphertexts. Use a counter, not a random, when collision-likelihood matters.
• Encrypt-then-truncate. Truncating an AEAD ciphertext breaks the tag. If you need length-hiding, pad before encrypting, not after.

Section 2: KDF (Key Derivation Function)

Use when: You have an Input Keying Material (IKM) and need to turn it into one or more cryptographic keys. The right KDF depends entirely on the entropy class of the IKM.

Decision tree (READ FIRST)

What is the entropy class of your input?
│
├── HIGH ENTROGY (≥128 bits effective)
│   - Output of another KDF
│   - Hardware-derived secret (TPM, YubiKey HMAC, FIDO2 PRF)
│   - DH/ECDH shared secret
│   - Random key from CSPRNG
│   ↓
│   USE: HKDF-Extract + HKDF-Expand (RFC 5869)
│
└── LOW ENTROPY (passwords, passphrases, PINs, recovery codes)
    ↓
    USE: Argon2id (preferred) OR PBKDF2-HMAC-SHA-256 ≥600k iter (legacy/FIPS)

The most common mistake (review finding H1 in the motivating gap analysis): applying PBKDF2 with 100k iterations to a 256-bit hardware-derived secret. This slows the defender without slowing the attacker, because the attacker is not doing brute force on a 256-bit key — that's already infeasible. PBKDF2 only buys you anything when the input is brute-forceable. With a high-entropy input, use HKDF.

Suggested defaults

Vetted alternatives

Required pattern: domain separation when deriving multiple keys

When one IKM produces multiple output keys (e.g., enc_key AND mac_key), use distinct info strings via HKDF-Expand. Never reuse a single derived key for two purposes. This is the fix for review finding B2:

prk     = HKDF-Extract(salt, ikm)
enc_key = HKDF-Expand(prk, info="app-aead-v1",   length=32)
mac_key = HKDF-Expand(prk, info="app-mac-v1",    length=32)
sub_key = HKDF-Expand(prk, info="app-token-v1",  length=32)

The info string MUST include a version suffix (-v1) so you can rotate without changing the IKM.

Research path

1. OWASP Password Storage Cheat Sheet — kept current with iteration count guidance
2. RFC 9106 §4 — Argon2 parameter selection for your latency budget
3. "How (not) to use OAEP" / "How (not) to derive keys" — IACR ePrint searches surface failure-mode papers
4. NIST SP 800-132 for password-based; SP 800-108 for high-entropy

Anti-patterns (BLOCK on these)

• SHA-256(secret_a || secret_b) as a KDF. Concat-and-hash is not a KDF. → Rule: no-adhoc-kdf
• MD5(password || salt) anywhere. → Rule: no-adhoc-kdf
• PBKDF2 over a 256-bit hardware-derived secret (review H1). High-entropy IKM doesn't benefit from iteration count.
• Same key for enc_key and mac_key (review B2). → Rule: no-key-reuse-across-purposes
• Iteration count below OWASP guidance (PBKDF2-SHA256 < 600k as of 2023). The number drifts upward annually — keep yours current.

Section 3: MAC (Message Authentication Code)

Use when: You need to detect tampering of data you control end-to-end (sender and receiver share a key). If parties don't share a key, you need a signature, not a MAC — see Section 4.

Suggested default

HMAC-SHA-256 (libsodium crypto_auth_*, OpenSSL EVP_MAC family).

Rationale:

• Universally available; FIPS-approved
• Length-extension safe (HMAC construction wraps the underlying hash properly)
• Performance is fine for any reasonable message size

Vetted alternatives

Required pattern: distinct keys for distinct purposes

Authentication keys MUST NOT be the same as encryption keys. See KDF Section's domain separation pattern. If you find yourself writing HMAC(key, data) where key is also an encryption key, stop and derive a separate mac_key.

Anti-patterns (BLOCK on these)

• Custom MAC: SHA-256(key || data) is not a MAC. Use HMAC. (Length-extension makes this a real attack on Merkle-Damgård hashes; SHA-256 is technically vulnerable, SHA3 isn't, but use HMAC anyway for hygiene.)
• MAC-then-encrypt without an authenticated mode: gives an attacker a decryption oracle. Encrypt-then-MAC, or use AEAD.
• A "signature" that is SHA-256(data || shared_key) (review finding B2) — that's a custom keyed hash with the encryption key reused as the MAC key. Two violations: ad-hoc construction AND key reuse. Always two distinct primitives, two distinct keys.

Section 4: Signature

Use when: You need a third party to verify data integrity using only a public key. If both parties share a secret, use a MAC (Section 3) — signatures are slower, larger, and more dangerous when misused.

Suggested default

Ed25519 (libsodium crypto_sign_*).

Rationale:

• Deterministic (no nonce-reuse footgun like ECDSA)
• ~100x faster than RSA for verification
• Small keys (32 byte public, 64 byte signature)
• No side-channel pitfalls in reference implementation

Vetted alternatives

Anti-patterns (BLOCK on these)

• "A signature is a hash of the data plus a key" — that's a MAC, not a signature. Reviewer cannot verify with public material; anyone with the key can forge. Real signatures are asymmetric — secret key signs, public key verifies. (Review B2: the construction was SHA-256(manifest || derived_key) and labeled sign_dual — both wrong.)
• ECDSA with random nonce when you don't have a perfect CSPRNG every signing call → key recovery in ~2 signatures. Use RFC 6979 deterministic ECDSA or switch to Ed25519.
• Self-rolled "multi-sig" by concatenating signatures or hashing them. Use a real threshold scheme (FROST for Schnorr/Ed25519, MuSig2) or document the security argument.

Section 5: Hash Function

Use when: One-way fingerprint, content-addressing, deduplication, indexing.

Acceptable use of HMAC-SHA-1 (review H7 context)

HMAC-SHA-1 is acceptable as a PRF even in 2026. The known weaknesses of SHA-1 (collision resistance) do not apply when SHA-1 is used inside HMAC's construction (PRF security is what matters). Examples: YubiKey 5 OTP slot's challenge-response is hard-locked to HMAC-SHA-1 — using it is fine, but document the rationale.

That said: do not introduce HMAC-SHA-1 in greenfield code. Auditors flag it, and explaining why it's actually OK costs you reviewer time. Plan migration to a FIDO2 PRF (HMAC-SHA-256 underlying) when hardware permits.

Section 6: Random Number Generation

/dev/urandom and /dev/random are both fine for cryptographic use on modern Linux; the historical "random for keys, urandom for the rest" advice is obsolete. See man 7 random.

Section 7: openssl enc and other command-line crypto tools

openssl enc is a footgun-rich tool. It's also ubiquitous, so it shows up. Apply these rules:

Required when using openssl enc

• Always pass -pbkdf2 -iter <N> (N ≥ 600,000 for SHA-256). Without these flags, OpenSSL uses a single-MD5-iteration KDF (EVP_BytesToKey), which is essentially zero work to brute-force. → Rule: crypto-flag-verification
• Use -aes-256-gcm or another AEAD mode, not -aes-256-cbc. enc does support GCM as of OpenSSL 1.1.0+.
• Read the password from a file descriptor (-pass fd:N) or env var (-pass env:VAR), never via -k password (visible in ps).

Better: don't use openssl enc for new code

For a security product, use a small program that calls libsodium's crypto_secretstream_xchacha20poly1305_* directly, or use the age tool. openssl enc is a Swiss Army knife with many rusty blades; the failure modes (silent default to weak KDF, CBC default, no AEAD by default until you know to ask) are not what you want at the bottom of your security stack.

Other CLI tools

Section 8: When to roll your own — DON'T

If you're reading this skill, you almost certainly should not be designing a new primitive. Use existing libraries that wrap reviewed implementations. The bar for "new primitive" is:

• Multiple independent academic analyses spanning ≥3 years
• IACR ePrint papers from non-authors confirming security claims
• A reference implementation with formal verification (e.g., HACL*, BearSSL)
• A use case the existing primitives genuinely don't address

If you can't check all four boxes, use the suggested default.

Worked example: the gap analysis findings

This skill exists because a 2026-05-03 pre-production review caught real problems no STRIDE/OWASP pass would have surfaced. Walking through what the skill would flag:

Finding B1 — openssl enc -aes-256-cbc without MAC

• Section 1 anti-pattern: "CBC without a separate MAC" → BLOCK
• Section 7 anti-pattern: openssl enc without explicit AEAD mode → BLOCK
• Remediation: switch to -aes-256-gcm OR wrap CBC ciphertext in HMAC-SHA-256(mac_key, iv || ct) with a separate mac_key from HKDF

Finding B2 — sign_dual produces SHA-256(manifest || derived_key)

• Section 4 anti-pattern: "a hash of data plus a key is not a signature" → BLOCK
• Section 2 anti-pattern: "concat-and-hash is not a KDF" (the upstream key combination) → BLOCK
• Section 3 anti-pattern: same key for encryption and authentication → BLOCK
• Remediation: HKDF-Extract + HKDF-Expand to derive enc_key AND mac_key AND (if you genuinely need third-party verification) a real Ed25519 signing key. Three primitives, three keys, three purposes.

Finding H1 — PBKDF2 100k iter on a 256-bit hardware-derived secret

• Section 2 decision tree: high-entropy IKM → use HKDF, not PBKDF2
• Remediation: drop the PBKDF2 step; use HKDF over the combined secrets

Finding H6 — openssl enc -aes-256-cbc -pass fd:0 without -pbkdf2 -iter

• Section 7 required flags: BLOCK without -pbkdf2 -iter
• Remediation: add -pbkdf2 -iter 600000, then either migrate to -aes-256-gcm or layer HMAC. Better: replace with a libsodium-based small program.

Finding H7 — HMAC-SHA-1 on YubiKey 5 OTP slot

• Section 5 acceptable use: HMAC-SHA-1 as PRF is fine; document why
• Forward plan: migrate to FIDO2 PRF (HMAC-SHA-256) on next hardware refresh

Output format

When this skill is invoked as part of a review, produce findings in this format:

### Finding: <SHORT-NAME>

**Severity**: BLOCK | HIGH | MEDIUM | LOW
**Location**: <file:line> or <component>
**Section**: <skill section, e.g., "Section 1: AEAD anti-pattern">
**Rule**: <enforcement rule, e.g., `no-unauthenticated-encryption`>

**Issue**: <one-paragraph explanation of what's wrong>

**Remediation**:
<concrete fix, with code snippet if helpful>

**References**:
- <RFC, NIST publication, or IACR paper>

When a cryptographic-decisions.md (template — see templates/cryptographic-decisions.md) is being created, the skill drives the Decision and Rationale sections.

Related

• Rules that enforce this skill's anti-patterns (auto-deployed via aiwg-utils if installed):
  • no-unauthenticated-encryption
  • no-key-reuse-across-purposes
  • no-adhoc-kdf
  • crypto-flag-verification
• Template: cryptographic-decisions.md — record-of-decision per primitive
• Agent: applied-cryptographer — narrow-scope reviewer that loads this skill on activation
• Companion skill: chain-of-trust-design — the other half of "is your security design sound"

Standards referenced

• NIST SP 800-38D (GCM), 800-57 (Key Management), 800-108 (KDFs), 800-132 (Password-based)
• RFC 5869 (HKDF), 8439 (ChaCha20-Poly1305 IETF), 8452 (AES-GCM-SIV), 9106 (Argon2)
• OWASP Password Storage Cheat Sheet, Cryptographic Storage Cheat Sheet
• FIPS 140-3, FIPS 186-5 (signatures)