Cryptography Learning Toolkit 🔐

Production-grade educational cryptography system implementing modern cryptographic primitives, key derivation functions, asymmetric digital signatures, and interactive vulnerability laboratories demonstrating historic cryptanalytic failures.

---

Overview & Problem Statement

Cryptography is the mathematical bedrock of information security, yet insecure implementations remain rampant: developers misuse block cipher modes (ECB), reuse nonces in authenticated stream ciphers (GCM), or rely on weak hashing for passwords. Abstract theory often fails to communicate why these practices are fatal.

Cryptography Learning Toolkit provides a dual-mode platform:

1. Defensive Reference Suite: Clean, type-annotated implementations of industry-standard primitives (AES-GCM, ChaCha20-Poly1305, Ed25519, RSA-OAEP, HKDF, Argon2id).
2. Offensive Vulnerability Laboratories: Safe, interactive demonstrations of historical cryptanalytic failures—showing how subtle mistakes lead to total plaintext and key recovery.

---

Architecture & Module Structure

flowchart TD
    subgraph Modern Cryptographic Primitives
        Sym[Symmetric: AES-256-GCM / ChaCha20-Poly1305]
        Asym[Asymmetric: Ed25519 Signatures / RSA-4096 OAEP]
        KDF[Key Derivation: HKDF / PBKDF2 / Argon2id]
        Hash[Hashing & MAC: SHA-2 / SHA-3 / HMAC / BLAKE2b]
    end

    subgraph Interactive Cryptanalytic Labs
        ECB[Lab 1: ECB Pattern Leakage]
        Nonce[Lab 2: GCM Nonce Reuse - Two-Time Pad]
        Padding[Lab 3: CBC Padding Oracle Simulation]
        BitFlip[Lab 4: CBC Bit-Flipping Malleability Attack]
    end

    subgraph Interfaces
        Sym --> CLI[Typer CLI / Rich Terminal]
        Asym --> CLI
        KDF --> CLI
        Hash --> CLI
        ECB --> CLI
        Nonce --> CLI
        Padding --> CLI
        BitFlip --> CLI
        CLI --> REST[FastAPI Interactive Lab Control Plane]
    end

Loading

---

Verified Features

Modern Cryptographic Primitives

• Authenticated Symmetric Ciphers: AES-256-GCM and ChaCha20-Poly1305 with authenticated associated data (AAD).
• Asymmetric Encryption & Signatures: Ed25519 high-speed digital signatures and RSA-4096 with OAEP padding and PSS signatures.
• Key Derivation Functions (KDF): HKDF (RFC 5869) for key expansion and memory-hard Argon2id (RFC 9106) for password hashing.
• Hashing & MACs: SHA-256, SHA-512, BLAKE2b, and HMAC integrity verification.

Interactive Failure Labs

• Lab 1: ECB Visual Pattern Leakage: Encrypts structured bitmap data with AES-ECB, demonstrating deterministic ciphertext block leakage.
• Lab 2: Nonce Reuse in Authenticated Ciphers: Demonstrates how reusing a nonce with AES-GCM or ChaCha20 leads to keystream extraction (two-time pad vulnerability).
• Lab 3: CBC Padding Oracle: Simulates padding oracle decryption without knowing the underlying key.
• Lab 4: Bit-Flipping Malleability: Manipulates unauthenticated CBC ciphertext bytes to tamper with decrypted plaintexts (e.g. elevating admin=false to admin=true).

---

Technology Stack

• Runtime: Python 3.12+
• Core Cryptography: cryptography (PyCA) & argon2-cffi
• CLI: Typer & Rich
• API: FastAPI & Uvicorn
• Testing: Pytest, Ruff, Mypy, Bandit

---

Requirements & Installation

# Clone the repository
git clone https://github.com/Krish9800/crypto-learning-toolkit.git
cd crypto-learning-toolkit

# Create and activate virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install -e .

---

Verified Usage Examples

1. Command-Line Interface (CLI)

# Compute cryptographic hash with avalanche metrics
crypto-toolkit hash "Hello, World!" --algo sha256

# Test Strict Avalanche Criterion (SAC)
crypto-toolkit avalanche "Security123"

# Derive key using Argon2id
crypto-toolkit kdf --type argon2id --password "SuperSecretPassphrase"

# Run Lab 1: ECB Mode Visual Pattern Leakage
crypto-toolkit lab ecb-leak

# Run Lab 2: GCM Nonce Reuse Keystream Recovery
crypto-toolkit lab nonce-reuse

# Run Lab 3: CBC Bit-Flipping Malleability Attack
crypto-toolkit lab bit-flipping

2. REST API Service

# Launch the API daemon
uvicorn crypto_toolkit.api.app:app --host 127.0.0.1 --port 8000

Endpoints available at http://127.0.0.1:8000/docs:

• POST /symmetric/encrypt — Encrypt data using AES-GCM or ChaCha20-Poly1305
• POST /symmetric/decrypt — Decrypt and authenticate ciphertext
• POST /symmetric/compare-modes — Compare ECB vs CBC vs GCM output structures
• POST /hash — Hash text with multi-algorithm outputs
• POST /kdf — Derive cryptographic keys from passwords
• POST /labs/{lab_name} — Execute interactive cryptanalysis laboratories

---

Testing & Quality Gates

# Run unit and cryptanalytic tests
pytest --cov=crypto_toolkit --cov-report=term-missing

# Linting and style verification
ruff check .
ruff format --check .

# Static type analysis
mypy src/crypto_toolkit

---

Security Model & Safe Scope

• Underlying Primitives: Relies strictly on audited, standard implementations from cryptography.io (OpenSSL backend) and argon2-cffi. Never attempts custom implementations of raw AES rounds or RSA math for production use.
• Safe Laboratory Boundaries: Vulnerability laboratories run in synthetic memory spaces and demonstrate known cryptanalytic principles on synthetic data only.
• Constant-Time Verification: Uses hmac.compare_digest and constant-time primitives to resist timing side-channel attacks.

---

Limitations & Known Issues

• Timing Lab Environment: High timing variance in shared virtualized environments (such as WSL2) can introduce jitter into micro-benchmark timing attacks.
• Hardware Acceleration: Hardware-accelerated AES-NI depends on host CPU support.

---

License & Attribution

This project is licensed under the MIT License — see the LICENSE file for details.

Note

Designed for security engineers, developers learning cryptography, and defensive security educators.