Files
skills/public/cryptography-crypto-best-practices.html
zeekayandHanzo Dev 9e10c1c10e Each llms index points at the other two
hanzoskills.com/llms.txt now opens with the install line, the API
reference index and the company index, so an agent that lands on any
one of the three can find the rest.

robots.txt claimed 537 documents while llms.txt counts 920. The number
is gone from robots.txt; llms.txt derives it.

public/ is regenerated from scripts/site.py, which it had fallen
behind: the copy-prompt menu and agent bar were in the generator and
not in the committed pages. tests/site.mjs passes against the result.

Co-authored-by: Hanzo Dev <[email protected]>
2026-09-11 00:27:59 -07:00

631 lines
28 KiB
HTML

<!doctype html>
<html lang="en"><head>
<meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
<title>cryptography-crypto-best-practices</title>
<meta name="color-scheme" content="dark">
<style>
/* Committed to one visual world: a dark instrument panel. No light variant —
the dot field and the hairline rules only read on black, and a naive
inversion would wash both out. Every colour is painted explicitly so the page
never borrows a host background. */
@font-face{font-family:'Zen';src:url('/fonts/Zen-Variable.woff2') format('woff2');font-weight:100 900;font-style:normal;font-display:swap}
@font-face{font-family:'Zen';src:url('/fonts/Zen-Italic-Variable.woff2') format('woff2');font-weight:100 900;font-style:italic;font-display:swap}
@font-face{font-family:'Zen Mono';src:url('/fonts/ZenMono-Variable.woff2') format('woff2');font-weight:100 900;font-style:normal;font-display:swap}
@font-face{font-family:'Zen Mono';src:url('/fonts/ZenMono-Italic-Variable.woff2') format('woff2');font-weight:100 900;font-style:italic;font-display:swap}
@font-face{font-family:'Zen Pixel Square';src:url('/fonts/ZenPixel-Square.woff2') format('woff2');font-style:normal;font-display:swap}
:root{
--ink:#f4f4f2; --soft:#9c9c98; --faint:#6a6a66; --ground:#000; --panel:#0a0a0a;
--line:#232323; --line-hi:#3a3a3a; --accent:#f4f4f2;
--font-zen-sans:'Zen',-apple-system,BlinkMacSystemFont,"Segoe UI",Helvetica,Arial,sans-serif;
--font-zen-mono:'Zen Mono',ui-monospace,"SF Mono",SFMono-Regular,Menlo,Consolas,monospace;
--font-zen-pixel-square:'Zen Pixel Square',monospace;
--mono:var(--font-zen-mono);
--sans:var(--font-zen-sans);
/* Controls are pills and surfaces are soft, as on hanzo.ai. */
--r:999px; --r-soft:14px;
}
*{box-sizing:border-box}
html{-webkit-text-size-adjust:100%}
body{margin:0;background:var(--ground);color:var(--ink);font-family:var(--sans);
font-size:16px;line-height:1.65;-webkit-font-smoothing:antialiased}
.wrap{max-width:60rem;margin:0 auto;padding:0 1.75rem}
/* The dot field. A halftone made of one repeating radial-gradient, faded out
along the diagonal by a mask so it reads as a wave rather than wallpaper. */
/* No overflow clip here: the dot field is inset to the box already, and a clip
would cut off the copy-prompt menu. */
.hero{position:relative;border-bottom:1px solid var(--line)}
.hero::before{content:"";position:absolute;inset:0;
background-image:radial-gradient(var(--line-hi) 1px, transparent 1px);
background-size:7px 7px;
-webkit-mask-image:linear-gradient(115deg,#000 0%,rgba(0,0,0,.55) 38%,transparent 72%);
mask-image:linear-gradient(115deg,#000 0%,rgba(0,0,0,.55) 38%,transparent 72%);
pointer-events:none}
.hero .wrap{position:relative;padding-top:5.5rem;padding-bottom:4rem}
nav{border-bottom:1px solid var(--line)}
nav .in{max-width:60rem;margin:0 auto;padding:1.1rem 1.75rem;display:flex;
justify-content:space-between;align-items:center;gap:1rem}
.brand{font-family:var(--mono);font-size:.85rem;letter-spacing:.14em;
text-transform:uppercase;color:var(--ink);text-decoration:none;
display:inline-flex;align-items:center;gap:.6rem}
.brand i{font-style:normal;color:var(--faint)}
.mark{width:1.15em;height:1.15em;display:block;flex:0 0 auto}
nav a.up{font-family:var(--mono);font-size:.72rem;letter-spacing:.14em;
text-transform:uppercase;color:var(--soft);text-decoration:none}
nav a.up:hover{color:var(--ink)}
h1{font-family:var(--mono);font-size:clamp(2rem,5.4vw,3.4rem);line-height:1.12;
letter-spacing:-.02em;margin:0 0 1.1rem;font-weight:500;text-wrap:balance}
h1 em{font-style:normal;color:var(--faint)}
.lede{color:var(--soft);font-size:1.05rem;max-width:52ch;margin:0 0 2.25rem}
.btns{display:flex;flex-wrap:wrap;gap:.7rem;margin:0 0 .5rem;align-items:center}
.btn{display:inline-flex;align-items:center;gap:.5rem;font-family:var(--mono);
font-size:.72rem;letter-spacing:.14em;text-transform:uppercase;
padding:.8rem 1.4rem;border:1px solid var(--line-hi);border-radius:var(--r);
color:var(--ink);text-decoration:none;background:transparent;cursor:pointer;
line-height:1.2;font-weight:400}
.btn:hover{background:#141414;text-decoration:none;border-color:var(--soft)}
.btn.solid{background:var(--ink);color:#000;border-color:var(--ink)}
.btn.solid:hover{background:#d8d8d4}
.btn .chev{width:.7em;height:.7em;flex:0 0 auto;transition:transform .15s ease}
.btn[aria-expanded="true"] .chev{transform:rotate(180deg)}
/* Copy-prompt selector. Each row copies the prompt for its own target. */
.copy{position:relative;display:inline-flex}
.menu{position:absolute;top:calc(100% + .5rem);left:0;z-index:20;min-width:21rem;
background:var(--panel);border:1px solid var(--line-hi);border-radius:var(--r-soft);
padding:.4rem;display:flex;flex-direction:column;
box-shadow:0 12px 32px rgba(0,0,0,.75)}
.menu[hidden]{display:none}
.mi{display:flex;align-items:center;gap:.7rem;width:100%;text-align:left;
padding:.62rem .8rem;border:0;border-radius:calc(var(--r-soft) - .35rem);
background:transparent;color:var(--ink);font-family:var(--mono);font-size:.76rem;
letter-spacing:.04em;text-decoration:none;cursor:pointer;line-height:1.3;
white-space:nowrap}
.mi:hover,.mi:focus-visible{background:#181818;outline:none}
.mi .mark{width:1.05rem;height:1.05rem;color:var(--soft)}
.mi:hover .mark{color:var(--ink)}
.mi u{margin-left:auto;color:var(--faint);text-decoration:none;font-size:.68rem;
letter-spacing:.1em;text-transform:uppercase}
/* Works-with bar: one scrolling row, name and mark per agent. */
.strip{border-bottom:1px solid var(--line);background:var(--panel)}
.strip .in{max-width:60rem;margin:0 auto;padding:.9rem 1.75rem;display:flex;
align-items:center;gap:1.25rem;font-family:var(--mono);font-size:.72rem;
letter-spacing:.1em;text-transform:uppercase;color:var(--faint)}
.strip b{color:var(--soft);font-weight:400;flex:0 0 auto;
border-right:1px solid var(--line);padding-right:1.25rem;align-self:stretch;
display:flex;align-items:center}
.bar{display:flex;align-items:center;gap:.5rem;flex:1 1 auto;min-width:0;
overflow-x:auto;scrollbar-width:none;scroll-snap-type:x proximity;
-webkit-overflow-scrolling:touch;
-webkit-mask-image:linear-gradient(90deg,#000 calc(100% - 3rem),transparent);
mask-image:linear-gradient(90deg,#000 calc(100% - 3rem),transparent)}
.bar::-webkit-scrollbar{display:none}
.agent{display:inline-flex;align-items:center;gap:.45rem;flex:0 0 auto;
padding:.4rem .85rem;border:1px solid var(--line);border-radius:var(--r);
color:var(--soft);white-space:nowrap;scroll-snap-align:start;
text-decoration:none;background:var(--ground)}
.agent:hover{color:var(--ink);border-color:var(--line-hi);text-decoration:none}
.agent .mark{width:.95rem;height:.95rem}
h2{font-family:var(--mono);font-size:1.1rem;letter-spacing:-.01em;margin:2.75rem 0 .75rem;font-weight:500}
h3{font-size:1rem;margin:2rem 0 .5rem;font-weight:600}
h4,h5,h6{font-size:.94rem;margin:1.5rem 0 .5rem;font-weight:600}
p{margin:0 0 1rem;max-width:70ch}
ul,ol{margin:0 0 1rem;padding-left:1.35rem;max-width:70ch}
li{margin:.22rem 0}
a{color:var(--ink);text-decoration:underline;text-underline-offset:3px;
text-decoration-color:var(--line-hi)}
a:hover{text-decoration-color:var(--ink)}
a:focus-visible{outline:1px solid var(--ink);outline-offset:3px}
code{font-family:var(--mono);font-size:.85em;background:var(--panel);
border:1px solid var(--line);border-radius:5px;padding:.1em .36em}
pre{background:var(--panel);border:1px solid var(--line);padding:1rem 1.1rem;
border-radius:var(--r-soft);overflow-x:auto;margin:0 0 1.25rem}
pre code{background:none;border:0;padding:0;font-size:.82rem;line-height:1.7}
blockquote{margin:0 0 1rem;padding-left:1rem;border-left:1px solid var(--line-hi);color:var(--soft)}
hr{border:0;border-top:1px solid var(--line);margin:2.5rem 0}
table{border-collapse:collapse;width:100%;margin:0 0 1.25rem;font-size:.92rem;
display:block;overflow-x:auto}
th,td{border:1px solid var(--line);padding:.5rem .7rem;text-align:left}
.curl{display:block;background:var(--panel);border:1px solid var(--line);
border-radius:var(--r-soft);padding:.95rem 1.1rem;font-family:var(--mono);
font-size:.8rem;color:var(--soft);overflow-x:auto;margin:0 0 2.5rem;
white-space:pre;line-height:1.9}
.curl b{color:var(--ink);font-weight:400}
.curl i{font-style:normal;color:var(--faint)}
/* index */
#q{width:100%;padding:.85rem 1.2rem;font-family:var(--mono);font-size:.85rem;color:var(--ink);
background:var(--panel);border:1px solid var(--line);border-radius:var(--r);margin:0 0 .6rem}
#q::placeholder{color:var(--faint);text-transform:uppercase;letter-spacing:.1em;font-size:.72rem}
#q:focus{outline:none;border-color:var(--soft)}
#count{color:var(--faint);font-family:var(--mono);font-size:.72rem;letter-spacing:.1em;
text-transform:uppercase;margin:0 0 2rem}
.cat{margin:2.5rem 0 .5rem;font-family:var(--mono);font-size:.7rem;letter-spacing:.16em;
text-transform:uppercase;color:var(--faint);border-bottom:1px solid var(--line);
padding-bottom:.45rem}
.row{display:block;padding:.6rem .9rem;margin:0 -.9rem;border-bottom:1px solid var(--line);
border-radius:var(--r-soft);text-decoration:none}
.row:hover{background:#0a0a0a}
.nm{font-family:var(--mono);font-size:.84rem;color:var(--ink);display:block}
.ds{color:var(--soft);font-size:.9rem;display:block;margin-top:.12rem}
footer{margin-top:4rem;padding:2rem 0 4rem;border-top:1px solid var(--line);
color:var(--faint);font-size:.85rem}
footer a{color:var(--soft)}
.fmap{display:grid;gap:1.75rem;grid-template-columns:repeat(auto-fit,minmax(11rem,1fr));
margin:0 0 2rem;font-size:.85rem}
.fmap b{display:block;font-family:var(--mono);font-size:.68rem;letter-spacing:.16em;
text-transform:uppercase;color:var(--faint);font-weight:400;margin:0 0 .6rem;
border-bottom:1px solid var(--line);padding-bottom:.4rem}
.fmap a{display:inline-block;color:var(--ink);text-decoration:none;margin:.3rem .35rem 0 0}
.fmap a:hover{text-decoration:underline}
.fmap div{color:var(--faint);line-height:1.5}
.fend{border-top:1px solid var(--line);padding-top:1.25rem;font-size:.82rem}
@media (max-width:640px){
.hero .wrap{padding-top:3.25rem;padding-bottom:2.75rem}
.btns{gap:.5rem}
.btn{padding:.75rem 1.15rem;font-size:.68rem}
.copy,.copy .btn{width:100%;justify-content:center}
.menu{left:0;right:0;min-width:0}
.strip .in{flex-direction:column;align-items:flex-start;gap:.6rem;padding:.9rem 1.75rem}
.strip b{border-right:0;padding-right:0}
.bar{width:100%}
}
</style>
<link rel="alternate" type="text/markdown" href="/cryptography-crypto-best-practices.md">
<link rel="icon" href="/favicon.svg">
<link rel="canonical" href="https://hanzoskills.com/cryptography-crypto-best-practices">
</head>
<!-- Reading this with a machine? Every page here is also plain markdown.
This one: https://hanzoskills.com/cryptography-crypto-best-practices.md
Index: https://hanzoskills.com/llms.txt
Corpus: https://hanzoskills.com/all.md
Append .md to any path for the markdown twin. -->
<body>
<nav><div class="in">
<a class="brand" href="/"><svg class="mark" viewBox="0 0 67 67" fill="currentColor" aria-hidden="true"><path d="M22.21 67V44.6369H0V67H22.21Z"/><path d="M66.7038 22.3184H22.2534L0.0878906 44.6367H44.4634L66.7038 22.3184Z"/><path d="M22.21 0H0V22.3184H22.21V0Z"/><path d="M66.7198 0H44.5098V22.3184H66.7198V0Z"/><path d="M66.7198 67V44.6369H44.5098V67H66.7198Z"/></svg> HANZO<i>SKILLS</i></a>
<a class="up" href="/">All skills</a>
</div></nav>
<div class="wrap">
<h1>cryptography-crypto-best-practices</h1><p class="lede">Cryptography best practices, common mistakes, security patterns, and anti-patterns to avoid</p><h1>Cryptography Best Practices</h1>
<p><strong>Scope</strong>: Security patterns, common mistakes, anti-patterns, implementation guidelines <strong>Lines</strong>: ~340 <strong>Last Updated</strong>: 2025-10-27 <strong>Format Version</strong>: 1.0 (Atomic)</p>
<hr>
<h2>When to Use This Skill</h2>
<p>Activate this skill when:</p>
<ul><li>Implementing cryptographic systems</li><li>Reviewing security code</li><li>Choosing crypto algorithms</li><li>Handling keys and secrets</li><li>Building authentication systems</li><li>Conducting security audits</li><li>Preventing crypto vulnerabilities</li><li>Following compliance requirements</li></ul>
<h2>Golden Rules</h2>
<pre><code>1. Don&#x27;t roll your own crypto
2. Use high-level APIs and established libraries
3. Keep crypto libraries updated
4. Use authenticated encryption
5. Generate truly random keys
6. Never reuse nonces with same key
7. Use constant-time comparisons
8. Protect keys at rest and in transit</code></pre>
<hr>
<h2>Common Mistakes</h2>
<h3>Mistake 1: ECB Mode</h3>
<p><strong>Problem</strong>: Identical plaintext blocks → identical ciphertext</p>
<pre><code class="lang-python"># ❌ WRONG: ECB mode leaks patterns
from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes
cipher = Cipher(algorithms.AES(key), modes.ECB())
# Images encrypted with ECB show original patterns!</code></pre>
<p><strong>Solution</strong>: Use GCM or CTR mode</p>
<pre><code class="lang-python"># ✅ CORRECT: GCM mode (authenticated encryption)
from cryptography.hazmat.primitives.ciphers.aead import AESGCM
aesgcm = AESGCM(key)
ciphertext = aesgcm.encrypt(nonce, plaintext, None)</code></pre>
<h3>Mistake 2: Weak Random Number Generation</h3>
<pre><code class="lang-python"># ❌ WRONG: Predictable randomness
import random
key = random.randbytes(32) # NOT cryptographically secure
token = str(random.randint(1000, 9999)) # Predictable
# ✅ CORRECT: Cryptographically secure
import secrets
key = secrets.token_bytes(32)
token = secrets.token_urlsafe(32)</code></pre>
<h3>Mistake 3: Nonce Reuse</h3>
<pre><code class="lang-python"># ❌ WRONG: Reusing nonce with same key
nonce = b&#x27;\x00&#x27; * 12 # Fixed nonce!
for message in messages:
ciphertext = aesgcm.encrypt(nonce, message, None) # VULNERABLE!
# ✅ CORRECT: Random nonce for each message
import os
for message in messages:
nonce = os.urandom(12) # New nonce each time
ciphertext = aesgcm.encrypt(nonce, message, None)</code></pre>
<h3>Mistake 4: Unauthenticated Encryption</h3>
<pre><code class="lang-python"># ❌ WRONG: Encryption without authentication
cipher = Cipher(algorithms.AES(key), modes.CBC(iv))
ciphertext = cipher.encryptor().update(plaintext)
# Attacker can modify ciphertext!
# ✅ CORRECT: Authenticated encryption
from cryptography.hazmat.primitives.ciphers.aead import AESGCM
aesgcm = AESGCM(key)
ciphertext = aesgcm.encrypt(nonce, plaintext, None)
# Any tampering detected</code></pre>
<h3>Mistake 5: Timing Attacks</h3>
<pre><code class="lang-python"># ❌ WRONG: Variable-time comparison
def verify_token(submitted, expected):
return submitted == expected # Leaks timing info
# ✅ CORRECT: Constant-time comparison
import hmac
def verify_token(submitted, expected):
return hmac.compare_digest(submitted, expected)</code></pre>
<h3>Mistake 6: Hardcoded Keys</h3>
<pre><code class="lang-python"># ❌ WRONG: Key in source code
SECRET_KEY = b&#x27;my_secret_key_123&#x27;
# ✅ CORRECT: Key from environment/vault
import os
SECRET_KEY = os.environ[&#x27;SECRET_KEY&#x27;].encode()</code></pre>
<h3>Mistake 7: Weak Password Hashing</h3>
<pre><code class="lang-python"># ❌ WRONG: Fast hash (MD5, SHA-1, SHA-256)
import hashlib
password_hash = hashlib.sha256(password).hexdigest() # Too fast!
# ✅ CORRECT: Slow, salted hash
import bcrypt
password_hash = bcrypt.hashpw(password, bcrypt.gensalt(rounds=12))
# ✅ EVEN BETTER: Argon2
from argon2 import PasswordHasher
ph = PasswordHasher()
password_hash = ph.hash(password)</code></pre>
<hr>
<h2>Best Practices</h2>
<h3>Practice 1: Use High-Level APIs</h3>
<pre><code class="lang-python"># ✅ BEST: Fernet (symmetric encryption made easy)
from cryptography.fernet import Fernet
key = Fernet.generate_key()
f = Fernet(key)
ciphertext = f.encrypt(b&quot;Secret message&quot;)
plaintext = f.decrypt(ciphertext)
# Fernet handles:
# - Key derivation
# - IV generation
# - Authentication (HMAC)
# - Timestamp verification</code></pre>
<h3>Practice 2: Key Derivation</h3>
<pre><code class="lang-python"># ✅ CORRECT: Derive encryption keys from passwords
from cryptography.hazmat.primitives.kdf.pbkdf2 import PBKDF2HMAC
from cryptography.hazmat.primitives import hashes
import os
def derive_key(password: bytes, salt: bytes = None) -&gt; bytes:
if salt is None:
salt = os.urandom(16)
kdf = PBKDF2HMAC(
algorithm=hashes.SHA256(),
length=32,
salt=salt,
iterations=480000, # OWASP recommendation 2023
)
key = kdf.derive(password)
return key, salt
# Derive key from password
key, salt = derive_key(b&quot;user_password&quot;)
# Store salt with ciphertext</code></pre>
<h3>Practice 3: Secure Key Storage</h3>
<p><strong>Environment variables</strong>:</p>
<pre><code class="lang-bash"># ✅ Good for development
export SECRET_KEY=&quot;base64_encoded_key&quot;</code></pre>
<p><strong>Secrets management</strong>:</p>
<pre><code class="lang-python"># ✅ BETTER: Use secrets manager
import boto3
def get_key():
client = boto3.client(&#x27;secretsmanager&#x27;)
response = client.get_secret_value(SecretId=&#x27;my-app/secret-key&#x27;)
return response[&#x27;SecretString&#x27;].encode()</code></pre>
<p><strong>Hardware security modules</strong>:</p>
<pre><code class="lang-python"># ✅ BEST: Use HSM for production
# Keys never leave HSM
# Examples: AWS KMS, Google Cloud KMS, Azure Key Vault</code></pre>
<h3>Practice 4: Key Rotation</h3>
<pre><code class="lang-python"># ✅ Support multiple active keys
class KeyManager:
def __init__(self):
self.keys = {
&#x27;v1&#x27;: load_key(&#x27;key_v1&#x27;),
&#x27;v2&#x27;: load_key(&#x27;key_v2&#x27;), # New key
}
self.current_version = &#x27;v2&#x27;
def encrypt(self, data):
key = self.keys[self.current_version]
ciphertext = encrypt_with_key(key, data)
return {
&#x27;version&#x27;: self.current_version,
&#x27;ciphertext&#x27;: ciphertext
}
def decrypt(self, encrypted_data):
version = encrypted_data[&#x27;version&#x27;]
key = self.keys[version] # Use old key if needed
return decrypt_with_key(key, encrypted_data[&#x27;ciphertext&#x27;])</code></pre>
<h3>Practice 5: Salt Everything</h3>
<pre><code class="lang-python"># ✅ CORRECT: Unique salt per password
import os
import hashlib
def hash_password(password: str) -&gt; tuple:
salt = os.urandom(16)
key = hashlib.pbkdf2_hmac(&#x27;sha256&#x27;, password.encode(), salt, 100000)
return salt, key
def verify_password(password: str, salt: bytes, expected_key: bytes) -&gt; bool:
key = hashlib.pbkdf2_hmac(&#x27;sha256&#x27;, password.encode(), salt, 100000)
return hmac.compare_digest(key, expected_key)</code></pre>
<hr>
<h2>Secure Patterns</h2>
<h3>Pattern 1: Envelope Encryption</h3>
<p><strong>Encrypt data with DEK, encrypt DEK with KEK</strong>:</p>
<pre><code class="lang-python">from cryptography.hazmat.primitives.ciphers.aead import AESGCM
import os
class EnvelopeEncryption:
def __init__(self, kek):
&quot;&quot;&quot;KEK = Key Encryption Key (from KMS)&quot;&quot;&quot;
self.kek = AESGCM(kek)
def encrypt(self, plaintext):
# Generate Data Encryption Key
dek = AESGCM.generate_key(bit_length=256)
# Encrypt data with DEK
aesgcm_dek = AESGCM(dek)
data_nonce = os.urandom(12)
ciphertext = aesgcm_dek.encrypt(data_nonce, plaintext, None)
# Encrypt DEK with KEK
kek_nonce = os.urandom(12)
encrypted_dek = self.kek.encrypt(kek_nonce, dek, None)
return {
&#x27;encrypted_dek&#x27;: encrypted_dek,
&#x27;kek_nonce&#x27;: kek_nonce,
&#x27;data_nonce&#x27;: data_nonce,
&#x27;ciphertext&#x27;: ciphertext
}
def decrypt(self, encrypted_data):
# Decrypt DEK with KEK
dek = self.kek.decrypt(
encrypted_data[&#x27;kek_nonce&#x27;],
encrypted_data[&#x27;encrypted_dek&#x27;],
None
)
# Decrypt data with DEK
aesgcm_dek = AESGCM(dek)
plaintext = aesgcm_dek.decrypt(
encrypted_data[&#x27;data_nonce&#x27;],
encrypted_data[&#x27;ciphertext&#x27;],
None
)
return plaintext</code></pre>
<h3>Pattern 2: Authenticated Encryption with Associated Data (AEAD)</h3>
<pre><code class="lang-python"># Include metadata that must be authentic but not encrypted
from cryptography.hazmat.primitives.ciphers.aead import AESGCM
import json
def encrypt_with_metadata(key, plaintext, metadata):
aesgcm = AESGCM(key)
nonce = os.urandom(12)
# Metadata is authenticated but not encrypted
associated_data = json.dumps(metadata).encode()
ciphertext = aesgcm.encrypt(nonce, plaintext, associated_data)
return {
&#x27;nonce&#x27;: nonce,
&#x27;ciphertext&#x27;: ciphertext,
&#x27;metadata&#x27;: metadata # Sent in clear
}
def decrypt_with_metadata(key, encrypted):
aesgcm = AESGCM(key)
associated_data = json.dumps(encrypted[&#x27;metadata&#x27;]).encode()
# Decryption fails if metadata was tampered
plaintext = aesgcm.decrypt(
encrypted[&#x27;nonce&#x27;],
encrypted[&#x27;ciphertext&#x27;],
associated_data
)
return plaintext</code></pre>
<h3>Pattern 3: Rate Limiting Authentication</h3>
<pre><code class="lang-python"># Prevent brute force attacks
from datetime import datetime, timedelta
import time
class RateLimitedAuth:
def __init__(self):
self.attempts = {} # user_id → (count, lockout_until)
def check_password(self, user_id, password, expected_hash):
# Check if locked out
if user_id in self.attempts:
count, lockout_until = self.attempts[user_id]
if datetime.now() &lt; lockout_until:
remaining = (lockout_until - datetime.now()).seconds
raise Exception(f&quot;Locked out for {remaining}s&quot;)
# Verify password
if bcrypt.checkpw(password, expected_hash):
# Success - clear attempts
self.attempts.pop(user_id, None)
return True
# Failed - increment attempts
count, _ = self.attempts.get(user_id, (0, datetime.now()))
count += 1
if count &gt;= 5:
# Lock out after 5 failed attempts
lockout_until = datetime.now() + timedelta(minutes=15)
self.attempts[user_id] = (count, lockout_until)
else:
self.attempts[user_id] = (count, datetime.now())
# Add delay to slow brute force
time.sleep(min(count, 5)) # Max 5s delay
return False</code></pre>
<hr>
<h2>Security Checklist</h2>
<h3>Algorithm Selection</h3>
<pre><code>✅ Symmetric encryption: AES-256-GCM or ChaCha20-Poly1305
✅ Asymmetric encryption: RSA-OAEP (4096-bit) or ECIES
✅ Digital signatures: Ed25519, ECDSA (P-256), or RSA-PSS
✅ Key exchange: X25519 (ECDH) or DHE
✅ Hashing: SHA-256, SHA-3, or BLAKE2
✅ Password hashing: Argon2id, bcrypt, or scrypt
✅ MAC: HMAC-SHA256 or Poly1305
❌ Avoid: MD5, SHA-1, RC4, DES, 3DES
❌ Avoid: ECB mode, small RSA keys (&lt;2048), weak passwords</code></pre>
<h3>Implementation Checklist</h3>
<pre><code>□ Using cryptographically secure random (secrets/urandom)
□ Generating unique nonce/IV for each encryption
□ Using authenticated encryption (GCM, ChaCha20-Poly1305)
□ Constant-time comparisons for secrets
□ No hardcoded keys or secrets
□ Keys stored securely (HSM, secrets manager)
□ Key rotation supported
□ Passwords hashed with slow algorithm + salt
□ TLS 1.2+ for network communication
□ Certificate validation enabled
□ Inputs validated before crypto operations
□ Crypto library kept updated
□ Security audit performed</code></pre>
<hr>
<h2>Anti-Patterns</h2>
<h3>Anti-Pattern 1: Crypto as Obfuscation</h3>
<pre><code class="lang-python"># ❌ WRONG: XOR &quot;encryption&quot;
def xor_encrypt(data, key):
return bytes([d ^ key for d in data]) # Trivially broken
# ✅ CORRECT: Real encryption
from cryptography.fernet import Fernet
f = Fernet(key)
ciphertext = f.encrypt(data)</code></pre>
<h3>Anti-Pattern 2: Security Through Obscurity</h3>
<pre><code class="lang-python"># ❌ WRONG: Custom &quot;secret&quot; algorithm
def my_secure_hash(data):
# Secret algorithm only I know!
return some_complex_transformation(data)
# ✅ CORRECT: Standard algorithms
import hashlib
hash_digest = hashlib.sha256(data).hexdigest()</code></pre>
<h3>Anti-Pattern 3: Encrypt-Then-MAC Order</h3>
<pre><code class="lang-python"># ❌ RISKY: MAC-then-encrypt
mac = hmac.new(mac_key, plaintext).digest()
ciphertext = encrypt(plaintext + mac)
# ✅ CORRECT: Encrypt-then-MAC (or use AEAD)
ciphertext = encrypt(plaintext)
mac = hmac.new(mac_key, ciphertext).digest()
# ✅ BEST: Use AEAD (GCM) - handles authentication
ciphertext = aesgcm.encrypt(nonce, plaintext, None)</code></pre>
<hr>
<h2>Testing Cryptographic Code</h2>
<pre><code class="lang-python">import unittest
from cryptography.hazmat.primitives.ciphers.aead import AESGCM
import os
class TestEncryption(unittest.TestCase):
def test_encrypt_decrypt(self):
&quot;&quot;&quot;Test basic encryption/decryption&quot;&quot;&quot;
key = AESGCM.generate_key(bit_length=256)
aesgcm = AESGCM(key)
plaintext = b&quot;Test message&quot;
nonce = os.urandom(12)
ciphertext = aesgcm.encrypt(nonce, plaintext, None)
recovered = aesgcm.decrypt(nonce, ciphertext, None)
self.assertEqual(plaintext, recovered)
def test_tampering_detected(self):
&quot;&quot;&quot;Test that tampering is detected&quot;&quot;&quot;
key = AESGCM.generate_key(bit_length=256)
aesgcm = AESGCM(key)
plaintext = b&quot;Test message&quot;
nonce = os.urandom(12)
ciphertext = aesgcm.encrypt(nonce, plaintext, None)
# Tamper with ciphertext
tampered = bytearray(ciphertext)
tampered[0] ^= 1
tampered = bytes(tampered)
# Should raise exception
with self.assertRaises(Exception):
aesgcm.decrypt(nonce, tampered, None)
def test_different_nonces(self):
&quot;&quot;&quot;Test that same plaintext with different nonces produces different ciphertext&quot;&quot;&quot;
key = AESGCM.generate_key(bit_length=256)
aesgcm = AESGCM(key)
plaintext = b&quot;Test message&quot;
nonce1 = os.urandom(12)
nonce2 = os.urandom(12)
ciphertext1 = aesgcm.encrypt(nonce1, plaintext, None)
ciphertext2 = aesgcm.encrypt(nonce2, plaintext, None)
self.assertNotEqual(ciphertext1, ciphertext2)</code></pre>
<hr>
<h2>Related Skills</h2>
<ul><li><code>cryptography-cryptography-basics</code> - Fundamental concepts</li><li><code>cryptography-pki-fundamentals</code> - PKI and certificates</li><li><code>cryptography-tls-configuration</code> - TLS setup</li><li><code>security-vulnerability-assessment</code> - Security auditing</li></ul>
<hr>
<p><strong>Last Updated</strong>: 2025-10-27</p>
<footer>
<div class="fmap">
<div><b>Build</b>
<a href="https://hanzo.app">hanzo.app</a> app builder
<a href="https://hanzo.codes">hanzo.codes</a> code with an agent
<a href="https://hanzoskills.com">hanzoskills.com</a> what an agent reads</div>
<div><b>Run</b>
<a href="https://console.hanzo.ai">console.hanzo.ai</a> cloud console
<a href="https://api.hanzo.ai">api.hanzo.ai</a> the API</div>
<div><b>Account</b>
<a href="https://hanzo.id">hanzo.id</a> sign in
<a href="https://pay.hanzo.ai">pay.hanzo.ai</a> top up
<a href="https://billing.hanzo.ai">billing.hanzo.ai</a> invoices and usage</div>
<div><b>Company</b>
<a href="https://hanzo.ai">hanzo.ai</a> canonical
<a href="https://hanzo.ventures">hanzo.ventures</a> ventures</div>
</div>
<div class="fend"><a href="/cryptography-crypto-best-practices.md">This page as plain text</a> · <a href="/llms.txt">Index for agents</a></div>
</footer>
</div></body></html>