mirror of
https://github.com/hanzoai/skills.git
synced 2026-11-19 00:47:36 +00:00
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]>
631 lines
28 KiB
HTML
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'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'\x00' * 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'my_secret_key_123'
|
|
|
|
# ✅ CORRECT: Key from environment/vault
|
|
import os
|
|
SECRET_KEY = os.environ['SECRET_KEY'].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"Secret message")
|
|
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) -> 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"user_password")
|
|
# 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="base64_encoded_key"</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('secretsmanager')
|
|
response = client.get_secret_value(SecretId='my-app/secret-key')
|
|
return response['SecretString'].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 = {
|
|
'v1': load_key('key_v1'),
|
|
'v2': load_key('key_v2'), # New key
|
|
}
|
|
self.current_version = 'v2'
|
|
|
|
def encrypt(self, data):
|
|
key = self.keys[self.current_version]
|
|
ciphertext = encrypt_with_key(key, data)
|
|
return {
|
|
'version': self.current_version,
|
|
'ciphertext': ciphertext
|
|
}
|
|
|
|
def decrypt(self, encrypted_data):
|
|
version = encrypted_data['version']
|
|
key = self.keys[version] # Use old key if needed
|
|
return decrypt_with_key(key, encrypted_data['ciphertext'])</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) -> tuple:
|
|
salt = os.urandom(16)
|
|
key = hashlib.pbkdf2_hmac('sha256', password.encode(), salt, 100000)
|
|
return salt, key
|
|
|
|
def verify_password(password: str, salt: bytes, expected_key: bytes) -> bool:
|
|
key = hashlib.pbkdf2_hmac('sha256', 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):
|
|
"""KEK = Key Encryption Key (from KMS)"""
|
|
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 {
|
|
'encrypted_dek': encrypted_dek,
|
|
'kek_nonce': kek_nonce,
|
|
'data_nonce': data_nonce,
|
|
'ciphertext': ciphertext
|
|
}
|
|
|
|
def decrypt(self, encrypted_data):
|
|
# Decrypt DEK with KEK
|
|
dek = self.kek.decrypt(
|
|
encrypted_data['kek_nonce'],
|
|
encrypted_data['encrypted_dek'],
|
|
None
|
|
)
|
|
|
|
# Decrypt data with DEK
|
|
aesgcm_dek = AESGCM(dek)
|
|
plaintext = aesgcm_dek.decrypt(
|
|
encrypted_data['data_nonce'],
|
|
encrypted_data['ciphertext'],
|
|
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 {
|
|
'nonce': nonce,
|
|
'ciphertext': ciphertext,
|
|
'metadata': metadata # Sent in clear
|
|
}
|
|
|
|
def decrypt_with_metadata(key, encrypted):
|
|
aesgcm = AESGCM(key)
|
|
associated_data = json.dumps(encrypted['metadata']).encode()
|
|
|
|
# Decryption fails if metadata was tampered
|
|
plaintext = aesgcm.decrypt(
|
|
encrypted['nonce'],
|
|
encrypted['ciphertext'],
|
|
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() < lockout_until:
|
|
remaining = (lockout_until - datetime.now()).seconds
|
|
raise Exception(f"Locked out for {remaining}s")
|
|
|
|
# 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 >= 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 (<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 "encryption"
|
|
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 "secret" 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):
|
|
"""Test basic encryption/decryption"""
|
|
key = AESGCM.generate_key(bit_length=256)
|
|
aesgcm = AESGCM(key)
|
|
plaintext = b"Test message"
|
|
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):
|
|
"""Test that tampering is detected"""
|
|
key = AESGCM.generate_key(bit_length=256)
|
|
aesgcm = AESGCM(key)
|
|
plaintext = b"Test message"
|
|
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):
|
|
"""Test that same plaintext with different nonces produces different ciphertext"""
|
|
key = AESGCM.generate_key(bit_length=256)
|
|
aesgcm = AESGCM(key)
|
|
plaintext = b"Test message"
|
|
|
|
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> |