Learn with the lab. Ship with production cryptography.
CryptoToolkit makes crypto mechanics visible, but its browser demos should not protect real secrets. This checklist shows what has to change when a lesson becomes a real product design.
Do not port the demo
Use maintained production primitives instead of copying educational code. The handoff starts by naming the real library, key owner, rotation trigger, envelope format, and rollback plan.
| Need | Use instead | Why |
|---|---|---|
| Browser encryption | Web Crypto API | Native key objects and vetted AES-GCM implementation. |
| Backend AEAD | libsodium or Google Tink | Misuse-resistant wrappers, tested primitives, and keyset support. |
| Password hashing | Backend Argon2id library | Calibrated memory and iteration parameters under server policy. |
| Key storage | KMS, HSM, or Vault Transit | Keys are separated from app data and app logs. |
Minimum questions before production
- What exact asset is protected: message, file, database field, token, backup, or session?
- What attacker is in scope: stolen storage, malicious admin, network attacker, offline guesser, or tenant escape?
- Where are keys generated, stored, rotated, revoked, backed up, and destroyed?
- How are nonces allocated and prevented from repeating?
- Which metadata is authenticated as AAD?
- How will old ciphertexts decrypt after a key or algorithm migration?
Safe AEAD envelope shape
A production envelope should bind security metadata into the authentication tag:
suite_id || key_id || nonce || ciphertext || tagPass fields such as suite_id, key_id, tenant, resource type, and resource ID as AAD when they are security-relevant. The AAD does not need to be secret, but it must not be silently mutable.
Misuse tests to require
- Repeated nonce or invocation counter is rejected before encryption.
- Swapping metadata such as key ID, suite ID, tenant, or resource ID breaks authentication.
- Old suite ciphertext can be decrypted but not newly encrypted.
- Weak password or undersized Argon2id parameters are rejected.
- Decrypt failure does not reveal whether the passphrase, tag, or metadata was wrong.
- Logs and metrics never include plaintext, key material, passphrases, raw envelopes, or customer secrets.
Use CryptoToolkit for the lesson boundary
Start with the AES-GCM, GCM nonce reuse, HMAC, and constant-time modules to understand what can fail. Then move production work to Web Crypto, libsodium, Tink, or a mature language-native library with key management around it.
For the repository version of this checklist, read docs/production-handoff.md on GitHub.