Files
skills/public/cryptography-key-management.md

17 KiB

name, description
name description
cryptography-key-management Comprehensive cryptographic key lifecycle management, KMS integration, and compliance

Cryptographic Key Management

Scope: Key lifecycle (generation, distribution, storage, rotation, destruction), KMS platforms (AWS KMS, GCP KMS, Azure Key Vault, external secret manager), HSM integration, compliance (FIPS 140-2, PCI-DSS, HIPAA, GDPR) Lines: ~500 Last Updated: 2025-10-27

When to Use This Skill

Activate this skill when:

  • Implementing key generation, distribution, storage, rotation, or destruction
  • Integrating with Key Management Services (AWS KMS, GCP KMS, Azure Key Vault, Vault)
  • Designing key hierarchies (Root → KEK → DEK)
  • Implementing envelope encryption patterns
  • Meeting compliance requirements (PCI-DSS, HIPAA, FIPS 140-2, GDPR, SOC 2)
  • Managing HSM integration for high-security applications
  • Automating key rotation with zero-downtime
  • Auditing key usage and access control
  • Managing secrets (API keys, passwords, tokens)
  • Implementing multi-party computation or key escrow

Core Concepts

Key Management Lifecycle

Five Phases:

1. Generation → 2. Distribution → 3. Storage → 4. Rotation → 5. Destruction
     ↑                                                              │
     └──────────────────────────────────────────────────────────────┘
                        (Cycle repeats)

Critical Principle: The security of encrypted data depends entirely on the security of the encryption keys.

Key Hierarchies

Three-Tier Model (Recommended):

┌─────────────────────────────────────────────┐
│ Level 1: Root Key (Master Key)              │  ← Stored in HSM
│ - Rarely rotated (annually or never)        │  ← Rarely used
│ - Encrypts KEKs only                        │  ← FIPS 140-2 Level 3+
└───────────────────┬─────────────────────────┘
                    │ Encrypts
                    ▼
┌─────────────────────────────────────────────┐
│ Level 2: Key Encryption Key (KEK)           │  ← Stored in KMS
│ - Rotated periodically (quarterly/annually) │  ← Encrypts DEKs
│ - One KEK per application/tenant            │
└───────────────────┬─────────────────────────┘
                    │ Encrypts
                    ▼
┌─────────────────────────────────────────────┐
│ Level 3: Data Encryption Key (DEK)          │  ← Stored encrypted with data
│ - Rotated frequently (per file/record)      │  ← Encrypts actual data
│ - One DEK per file/record/tenant            │
└───────────────────┬─────────────────────────┘
                    │ Encrypts
                    ▼
            ┌──────────────────┐
            │  Encrypted Data  │
            └──────────────────┘

Benefits:

  • Efficient rotation: Rotate KEK by re-encrypting DEKs (not data)
  • Separation of concerns: Different keys for different purposes
  • Reduced blast radius: Compromise of one level doesn't expose others

Key Generation

Cryptographically Secure Random Number Generators (CSRNGs)

Platform Sources:

Platform CSRNG Entropy Source
Linux /dev/urandom Kernel CSPRNG (hardware RNG, interrupts, disk I/O)
macOS /dev/random Yarrow algorithm
Windows CryptGenRandom Windows CryptoAPI
AWS KMS GenerateDataKey FIPS 140-2 validated
GCP KMS GenerateRandomBytes Cloud HSM

Python Example:

import os
import secrets

# Generate 256-bit AES key
key = os.urandom(32)  # 32 bytes = 256 bits

# Or use secrets module (Python 3.6+)
key = secrets.token_bytes(32)
hex_key = secrets.token_hex(32)  # 64 hex characters

❌ Never use:

  • random.random() (Python) - Predictable
  • Math.random() (JavaScript) - Predictable
  • Timestamp-based seeds
  • Hardcoded keys

Key Derivation Functions (KDFs)

For deriving keys from passwords:

KDF Standard Security Use Case
Argon2id RFC 9106 Highest (memory-hard) Password hashing, key derivation (recommended)
scrypt RFC 7914 High (memory-hard) Key derivation from passwords
PBKDF2 RFC 8018 Moderate FIPS compliance, legacy systems
HKDF RFC 5869 High Key derivation from shared secrets (not passwords)

Argon2id Example:

from argon2 import PasswordHasher
from argon2.low_level import hash_secret_raw, Type
import secrets

password = b"user-password"
salt = secrets.token_bytes(16)

# Derive 256-bit key
key = hash_secret_raw(
    secret=password,
    salt=salt,
    time_cost=3,          # Iterations
    memory_cost=65536,    # 64 MB
    parallelism=4,        # 4 threads
    hash_len=32,          # 256-bit key
    type=Type.ID          # Argon2id
)

Key Storage

Storage Tiers

Tier Security Cost Use Case
Tier 1: HSM Highest (FIPS 140-2 Level 3/4) Root keys, CA keys
Tier 2: Cloud KMS High (FIPS 140-2 Level 2/3) $$ Application keys, KEKs
Tier 3: Encrypted DB Moderate $ Encrypted DEKs
Tier 4: OS Keystore Moderate $ Local development
Tier 5: Plaintext ❌ Never N/A N/A

Hardware Security Module (HSM)

FIPS 140-2 Levels:

Level Requirements Use Case
Level 1 Software only Basic applications
Level 2 Tamper-evident seals, role-based auth Enterprise
Level 3 Tamper-resistant hardware, identity-based auth Financial, healthcare (recommended)
Level 4 Environmental protection (voltage, temp) Government, military

HSM Vendors:

  • Cloud: AWS CloudHSM, Google Cloud HSM, Azure Dedicated HSM
  • On-premise: Thales Luna, nCipher nShield, Utimaco SecurityServer

Cloud KMS Platforms

AWS KMS:

import boto3

kms = boto3.client('kms')

# Create key
response = kms.create_key(Description='App encryption key')
key_id = response['KeyMetadata']['KeyId']

# Enable automatic rotation
kms.enable_key_rotation(KeyId=key_id)

# Encrypt data
ciphertext = kms.encrypt(KeyId=key_id, Plaintext=b'Secret data')

# Decrypt
plaintext = kms.decrypt(CiphertextBlob=ciphertext['CiphertextBlob'])

external secret manager:

# Enable transit engine
vault secrets enable transit

# Create encryption key
vault write -f transit/keys/my-key

# Encrypt
vault write transit/encrypt/my-key plaintext=$(echo "Secret data" | base64)

# Decrypt
vault write transit/decrypt/my-key ciphertext="vault:v1:..."

Key Rotation

Why Rotate Keys?

Reasons:

  1. Limit blast radius of compromise
  2. Compliance requirements (PCI-DSS, HIPAA)
  3. Cryptographic hygiene (reduce ciphertext under single key)
  4. Mitigate key exposure (employee departure, system compromise)

Rotation Frequency:

  • Root/Master keys: Annually
  • KEKs: Quarterly
  • DEKs: Monthly or per-dataset
  • Session keys: Per-session (ephemeral)
  • API keys/passwords: 90 days
  • Emergency: Immediately upon suspected compromise

Rotation Strategies

Strategy 1: Envelope Encryption (Zero-Downtime)

Re-encrypt KEKs with new root key, DEKs with new KEK. Data stays encrypted with DEKs (no change).

Strategy 2: Versioned Keys (Multi-Version)

Keep old and new keys active. Write new data with new key, read old data with old key. Background job gradually re-encrypts.

AWS KMS Automatic Rotation:

# Enable automatic rotation (annual)
aws kms enable-key-rotation --key-id <key-id>

# Check rotation status
aws kms get-key-rotation-status --key-id <key-id>

Access Control

Principle of Least Privilege

Best Practices:

  • Separate keys by environment (dev, staging, prod)
  • Separate keys by application/tenant
  • Use IAM roles (not user credentials) for applications
  • Require MFA for key administrative operations
  • Use encryption context for additional security
  • Audit all key access (CloudTrail, Cloud Audit Logs)

AWS KMS IAM Policy Example:

{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Action": ["kms:Decrypt", "kms:GenerateDataKey"],
    "Resource": "arn:aws:kms:us-east-1:123456789012:key/*",
    "Condition": {
      "StringEquals": {
        "kms:EncryptionContext:Department": "Finance"
      }
    }
  }]
}

Compliance Standards

PCI-DSS Requirements

Requirement 3.6: Protect cryptographic keys

  • 3.6.1: Access to keys limited (need-to-know)
  • 3.6.2: Keys stored securely
  • 3.6.3: Keys distributed securely
  • 3.6.4: Keys changed at least annually (or upon suspected compromise)
  • 3.6.5: Retirement/destruction of old keys
  • 3.6.6: Split knowledge/dual control for manual key operations

HIPAA Requirements

Security Rule § 164.312(a)(2)(iv): Encryption and decryption (addressable)

  • Use NIST-approved algorithms
  • Encrypt ePHI at rest and in transit
  • Secure key management procedures
  • Access controls for encryption keys
  • Audit logging

GDPR Requirements

Article 32: Security of processing

  • Encryption of personal data (recommended, not required)
  • Pseudonymization and encryption as appropriate technical measures
  • Regular testing and evaluation of security measures

FIPS 140-2 Requirements

Approved Algorithms:

  • Encryption: AES, Triple-DES
  • Hashing: SHA-256, SHA-384, SHA-512
  • Key Exchange: Diffie-Hellman, ECDH
  • Signatures: RSA, ECDSA

❌ Not Approved:

  • ChaCha20-Poly1305 (secure but not FIPS-approved)
  • MD5, SHA-1 (deprecated)

Best Practices

Key Management Checklist

✅ Generation:

  • Use CSRNG (not predictable random)
  • Sufficient key length (AES-256, RSA-2048+)
  • Generate in secure environment (HSM, KMS)

✅ Distribution:

  • Use key wrapping (envelope encryption)
  • Never transmit keys in plaintext
  • Use separate channels for key distribution (out-of-band)

✅ Storage:

  • Never store keys with data
  • Use HSM or KMS for master keys
  • Encrypt keys at rest (key hierarchy)
  • Separate keys by environment

✅ Rotation:

  • Automate rotation schedules
  • Use envelope encryption for zero-downtime
  • Test rotation procedures regularly
  • Maintain key version history

✅ Destruction:

  • Cryptographic erasure (destroy KEK)
  • Secure overwrite (DOD 5220.22-M)
  • Grace period before deletion (30-90 days)
  • Audit log destruction events

✅ Access Control:

  • Principle of least privilege
  • Role-based access control (RBAC)
  • Require MFA for administrative operations
  • Audit all key access

✅ Monitoring:

  • Enable audit logging (CloudTrail, Cloud Audit Logs)
  • Monitor for unusual key access patterns
  • Alert on failed decryption attempts
  • Track key age and rotation status

Anti-Patterns

❌ Never do:

  • Hardcode keys in source code
  • Store keys in version control (Git)
  • Store keys in plaintext configuration files
  • Use the same key for all environments
  • Store keys with encrypted data
  • Reuse nonces/IVs
  • Use weak algorithms (DES, 3DES, RC4)
  • Skip key rotation
  • Allow public access to keys
  • Test before committing code changes

Level 3: Resources

Reference Materials

Comprehensive Documentation:

  • resources/REFERENCE.md - 2,000+ line technical reference covering:
    • Complete key lifecycle (generation, distribution, storage, rotation, destruction)
    • KMS platforms (AWS KMS, GCP KMS, Azure Key Vault, external secret manager)
    • HSM integration (FIPS 140-2 levels, PKCS#11, vendor comparison)
    • Compliance standards (PCI-DSS, HIPAA, GDPR, SOC 2, FIPS 140-2)
    • Secrets management patterns
    • Access control and audit logging
    • Multi-party computation and key escrow
    • Detailed implementation examples

Production Scripts

Three executable scripts (all with --help and --json support):

  1. scripts/audit_keys.py (848 lines)

    • Comprehensive key audit across multiple KMS platforms
    • Checks key age, rotation status, compliance violations
    • Detects unused keys, overly permissive policies
    • Security score calculation
    • Multi-platform support (AWS KMS, GCP KMS, Azure Key Vault, external secret manager)
  2. scripts/rotate_master_keys.py (821 lines)

    • Automated master key rotation with zero-downtime
    • Re-encrypts DEKs without touching data (envelope encryption)
    • Rollback capability with backup
    • Progress tracking and resume
    • Multi-platform support (AWS KMS, GCP KMS, local, Vault)
  3. scripts/generate_key_hierarchy.py (698 lines)

    • Generate complete key hierarchies (Root → KEK → DEK)
    • Configurable tiers (2 or 3 levels)
    • Multiple algorithms (AES-256, RSA-2048, ECC-P256)
    • Key wrapping and export
    • ASCII tree visualization

Production Examples

Five production-ready examples:

  1. examples/aws_kms_integration.py

    • Create and manage AWS KMS keys
    • Envelope encryption with GenerateDataKey
    • Automatic key rotation
    • Key policies and access control
    • Encryption context usage
  2. examples/hashicorp_vault_setup.py

    • Transit secrets engine configuration
    • Key creation, rotation, and versioning
    • Encryption as a service
    • Re-wrapping (re-encrypt with new version)
    • Auto-rotation configuration
  3. examples/key_rotation_automation.py

    • Automated rotation scheduling
    • Zero-downtime rotation workflow
    • CloudWatch metrics integration
    • Rollback procedures
    • Monitoring and alerting
  4. examples/secrets_management.py

    • Secure API key and password storage
    • Secret versioning and rotation
    • KMS-backed encryption
    • Secure password generation
    • Audit logging
  5. examples/compliance_config.py

    • Compliance policy templates (PCI-DSS, HIPAA, GDPR, SOC 2, FIPS 140-2)
    • Automated compliance validation
    • Key lifecycle enforcement
    • Audit trail generation
    • Violation reporting

Usage

Run scripts:

# Audit all keys in AWS KMS
./scripts/audit_keys.py --platform aws-kms --region us-east-1 --json

# Rotate master key
./scripts/rotate_master_keys.py --platform aws-kms --key-id alias/master-key

# Generate 3-tier key hierarchy
./scripts/generate_key_hierarchy.py --tiers 3 --dek-count 100 --visualize

Integrate examples:

# Use AWS KMS integration
from examples.aws_kms_integration import AWSKMSKeyManager

manager = AWSKMSKeyManager(region='us-east-1')
envelope = manager.encrypt_with_envelope(plaintext, 'alias/my-key')
decrypted = manager.decrypt_with_envelope(envelope)

Quick Reference

Common Commands

AWS KMS:

# Create key
aws kms create-key --description "App key"

# Enable rotation
aws kms enable-key-rotation --key-id <key-id>

# Encrypt
aws kms encrypt --key-id alias/my-key --plaintext fileb://secret.txt

# Decrypt
aws kms decrypt --ciphertext-blob fileb://encrypted.bin

external secret manager:

# Enable transit
vault secrets enable transit

# Create key
vault write -f transit/keys/my-key

# Encrypt
vault write transit/encrypt/my-key plaintext=$(base64 <<< "secret")

# Rotate
vault write -f transit/keys/my-key/rotate

Google Cloud KMS:

# Create key ring
gcloud kms keyrings create my-keyring --location global

# Create key
gcloud kms keys create my-key --location global --keyring my-keyring --purpose encryption

# Encrypt
gcloud kms encrypt --location global --keyring my-keyring --key my-key --plaintext-file secret.txt --ciphertext-file encrypted.bin

  • cryptography-encryption-at-rest - Protecting stored data
  • security-tls-configuration - Certificates and TLS key management
  • cryptography-crypto-best-practices - Cryptographic implementation guidelines
  • security-secrets-management - Application secrets and credentials

Resources

Standards and Specifications

  • NIST SP 800-57: Recommendation for Key Management
  • NIST SP 800-175B: Guideline for Using Cryptographic Standards
  • FIPS 140-2: Security Requirements for Cryptographic Modules
  • RFC 5869: HKDF (HMAC-based Key Derivation Function)
  • RFC 9106: Argon2 Memory-Hard Function

Compliance Resources

  • PCI-DSS Requirement 3: Protect stored cardholder data
  • HIPAA Security Rule: Encryption and Decryption
  • GDPR Article 32: Security of processing
  • SOC 2 Trust Services Criteria: Confidentiality

Tools and Libraries