crypto-misuse

Cryptographic Misuse

Rules (for AI agents)

ALWAYS

• Use a maintained, widely reviewed cryptographic API — the platform's own (Node crypto, Java JCE, .NET System.Security.Cryptography, Go crypto/*) or a reputable third-party one (PyCA cryptography, golang.org/x/crypto, Bouncy Castle). Prefer high-level, misuse-resistant APIs over assembling low-level primitives yourself. In Python, from Crypto… resolves to either the abandoned pycrypto or its maintained fork pycryptodome depending on what is installed — the import line is identical, so depend on pycryptodome explicitly.
• Use a cryptographically secure RNG for anything security-relevant: Python secrets.token_bytes / secrets.token_urlsafe, JS crypto.getRandomValues / crypto.randomBytes, Go crypto/rand.Read, Java SecureRandom.
• Hash passwords with a password-specific KDF and a unique random salt per password. Prefer Argon2id; scrypt where appropriate; bcrypt for legacy compatibility; PBKDF2-HMAC-SHA-256 where FIPS-140 compliance is required. Take minimum parameters from the current OWASP Password Storage Cheat Sheet, then benchmark on production hardware and choose the highest cost that still meets the application's authentication latency and availability budget. The cost is meant to be raised over time as hardware gets cheaper — it is not a constant to copy once.
• Account for bcrypt's 72-byte input limit: it silently truncates, so a long passphrase and its 72-byte prefix hash identically. If bcrypt must take unbounded input, pre-hash with SHA-256 and pass the digest base64-encoded, never as raw bytes — a raw digest can contain a NUL byte, which truncates the input again.
• Encrypt with a vetted AEAD: AES-GCM or ChaCha20-Poly1305, or AES-GCM-SIV where nonce-misuse resistance is specifically useful and the platform ships a reviewed implementation. Absent a stated key-size requirement, AES-256-GCM or ChaCha20-Poly1305 is a safe default — AES-128-GCM is not a finding.
• Follow the selected AEAD's nonce requirements. For AES-GCM and ChaCha20-Poly1305 the requirement is uniqueness under a given key, not randomness. A random 96-bit nonce is one strategy and carries a birthday bound; a counter-based nonce is often the stronger choice for high-volume encryption under one key. Do not assume nonce-misuse resistance unless the construction explicitly provides it.
• Compare MACs, authentication tokens, and other secret authenticators with the platform's constant-time helper: Python hmac.compare_digest, Node crypto.timingSafeEqual, Go crypto/subtle.ConstantTimeCompare, Java MessageDigest.isEqual, .NET CryptographicOperations.FixedTimeEquals. Node's helper throws when the buffers differ in length, so compare fixed-length digests rather than raw user input. For digital signatures, call the library's verification API instead of comparing signature bytes yourself. A constant-time comparison does not make the surrounding code constant-time.
• Select asymmetric algorithms and key sizes from current authoritative guidance rather than remembered constants. Prefer a modern platform-supported scheme (Ed25519, X25519, ECDSA P-256 or P-384); where RSA is required, enforce the current NIST SP 800-57 Part 1 minimum modulus. Key-size floors only move upward, so a remembered figure is one that has already expired.
• Obtain production keys from the platform's key-management boundary — see secret-detection for what counts as an embedded credential. What this skill owns is what comes after: version every key (carry a key id in the ciphertext envelope) so rotation does not strand data encrypted under the previous key, and derive per-purpose subkeys with a KDF instead of reusing one key across contexts.
• Consult protocol-security for anything on the wire — TLS versions and cipher suites, mTLS, certificate validation, gRPC channel credentials. It owns the transport; this skill owns the primitive.