Key Management
Generating, storing, rotating, revoking, and distributing cryptographic keys
Skills taught: crypto.key-management
The Hardest Part of Cryptography
Key management is usually the weakest link in any cryptographic system. Cryptographic algorithms are strong; key management is where real-world breaches happen. A key stored in the same database as the encrypted data, hardcoded in source code, or checked into Git is an immediate critical vulnerability.
- Never hardcode keys in source code or config files
- Never store keys in the same location as the encrypted data
- Never commit keys to Git (even accidentally — rotate immediately if this happens)
- Keys should expire and be rotated regularly
- All key usage should be logged and auditable
- Envelope Encryption
- A two-layer scheme: data is encrypted with a DEK (Data Encryption Key); the DEK is encrypted with a KEK (Key Encryption Key) stored in a KMS. The plaintext KEK never leaves the KMS.
- HSM (Hardware Security Module)
- A tamper-resistant hardware device that generates and stores cryptographic keys. Keys never leave the HSM in plaintext. FIPS 140-2/3 Level 3+ rated HSMs are used by CAs and financial institutions.
- Key Rotation
- Generating a new key and re-encrypting data (or just old keys). Limits the exposure window if a key is compromised. Best practice: rotate annually or on suspected compromise.
Envelope Encryption with AWS KMS
import boto3
from cryptography.hazmat.primitives.ciphers.aead import AESGCM
import os
kms = boto3.client("kms", region_name="us-east-1")
KMS_KEY_ARN = "arn:aws:kms:us-east-1:123456789:key/your-key-id"
def encrypt_data(plaintext: bytes) -> dict:
# 1. Ask KMS for a data key (plaintext + encrypted copy)
response = kms.generate_data_key(KeyId=KMS_KEY_ARN, KeySpec="AES_256")
dek_plaintext = response["Plaintext"] # use to encrypt; discard after
dek_encrypted = response["CiphertextBlob"] # store with ciphertext
# 2. Encrypt data with the DEK
nonce = os.urandom(12)
aesgcm = AESGCM(dek_plaintext)
ciphertext = aesgcm.encrypt(nonce, plaintext, None)
# 3. Discard plaintext DEK (zero it from memory)
del dek_plaintext
# Store: encrypted_dek + nonce + ciphertext
return {"encrypted_dek": dek_encrypted, "nonce": nonce, "ciphertext": ciphertext}
def decrypt_data(envelope: dict) -> bytes:
# 1. Decrypt the DEK using KMS (KMS checks IAM permissions, logs the call)
response = kms.decrypt(CiphertextBlob=envelope["encrypted_dek"])
dek_plaintext = response["Plaintext"]
# 2. Decrypt data with the DEK
aesgcm = AESGCM(dek_plaintext)
return aesgcm.decrypt(envelope["nonce"], envelope["ciphertext"], None)
HashiCorp Vault for Secrets Management
# Start Vault dev server (testing only)
vault server -dev
# Store a secret
vault kv put secret/myapp db_password="s3cret"
# Read a secret
vault kv get secret/myapp
vault kv get -field=db_password secret/myapp
# Transit engine: encrypt/decrypt without storing keys
vault secrets enable transit
vault write -f transit/keys/myapp-key
# Encrypt
vault write transit/encrypt/myapp-key plaintext=$(base64 <<< "my secret data")
# Returns: vault:v1:...
# Decrypt
vault write transit/decrypt/myapp-key ciphertext="vault:v1:..."
# Returns base64-encoded plaintext
import os
from cryptography.hazmat.primitives.ciphers.aead import AESGCM
import base64
# --- Minimal approach: environment variable (acceptable for small projects) ---
# In production, inject from Vault/AWS Secrets Manager, never bake into image
key_hex = os.environ.get("ENCRYPTION_KEY") # 64 hex chars = 32 bytes
if not key_hex:
raise ValueError("ENCRYPTION_KEY not set")
key = bytes.fromhex(key_hex)
aesgcm = AESGCM(key)
# This is acceptable if:
# 1. The env var is injected at runtime (not in Dockerfile/docker-compose)
# 2. The key was generated with os.urandom(32)
# 3. You rotate it periodically
# 4. Access to the deployment system is restricted
# --- Generate a fresh key (do this once, store in KMS/Vault) ---
new_key = os.urandom(32)
print("Store this in KMS/Vault:", new_key.hex())
Environment Variables vs KMS for Key Storage
- Environment Variables: Key injected at runtime via env var
- AWS KMS / HashiCorp Vault: Dedicated key management service
Warning: If a secret key is accidentally committed to Git, treat it as permanently compromised. Rotate it immediately — Git history is public and tools like TruffleHog scan GitHub automatically for exposed credentials.
Tip: Use git-secrets or pre-commit hooks to prevent committing keys to Git. Run git secrets --scan before every push. Add patterns like AESGCM|private_key|AES_KEY to the blocklist.
Frequently Asked Questions
What is envelope encryption?
A two-layer scheme: data is encrypted with a DEK (Data Encryption Key). The DEK is then encrypted with a KEK (Key Encryption Key) stored in a KMS. You store the encrypted DEK alongside the ciphertext. The plaintext KEK never leaves the KMS.
How often should I rotate encryption keys?
NIST recommends annual rotation for symmetric keys used for encryption. Rotate immediately on any suspected compromise. Modern KMS services support automatic rotation without requiring data re-encryption.
What is the difference between a KMS and a secret manager?
A KMS (Key Management Service) focuses on cryptographic keys — generating, storing, and using them without exposing plaintext keys. A secret manager (Vault, AWS Secrets Manager) stores arbitrary secrets (API keys, passwords, certificates) and provides access control and audit logging.