# Cryptography in CQRIT

## Goals

1. **Quantum-resistant encryption** - Protection against quantum computer attacks
2. **No persistent key storage** - Keys never stored anywhere
3. **Client-side execution** - All operations in user's browser
4. **Deterministic key derivation** - Same inputs always produce same keys
5. **Social recovery** - Multi-party reconstruction without single point of failure

## Cryptographic Components

### 1. Key Derivation Function (KDF)

**Purpose:** Transform human-memorable secrets into cryptographic keys

**Algorithm:** PBKDF2 (Password-Based Key Derivation Function 2)

**Configuration:**
- Hash function: HMAC-SHA-256
- Iterations: Configurable (high count for security)
- Salt: User-specific unique salt
- Output: 256-bit derived key

**Input:**
- User memory inputs (answers to personal questions)
- User-specific salt
- Workspace identifier (for workspace-specific keys)
- Iteration count

**Process:**
```
Memory Inputs + Salt + Workspace ID → PBKDF2 (HMAC-SHA-256, high iterations) → Derived Key
```

**Properties:**
- **Deterministic:** Same inputs always produce same output
- **One-way:** Cannot reverse to get inputs from key
- **Slow:** High iteration count defends against brute force
- **Salted:** User-specific salt prevents rainbow tables
- **WASM-Optimized:** Rust/WebAssembly implementation ~100x faster than JavaScript

**Implementation Details:**
- Loop unrolling in WASM for performance
- Stack-allocated buffers
- Single-block optimization for most common case
- Dual implementation: JavaScript (compatibility) + Rust (performance)

**Security Note:**
Key strength depends on entropy of memory inputs. Weak inputs = weak keys.

### 2. Post-Quantum Encryption

**Algorithm:** ML-KEM-1024 (Module-Lattice-Based Key Encapsulation Mechanism)

**Standard:** NIST FIPS 203 (formerly CRYSTALS-Kyber)

**Security Level:** NIST Level 5 (highest)

**Why ML-KEM-1024:**
- NIST-standardized post-quantum algorithm (approved 2024)
- Lattice-based cryptography (MLWE hardness)
- Resistant to Shor's algorithm (quantum threat to RSA/ECC)
- Designed to replace/supplement classical key exchange
- Highest NIST security level available

**Purpose:**
- Protect against quantum computer attacks
- Future-proof encrypted data
- Defend against harvest-now-decrypt-later threats
- Primary encryption for content and sensitive data

**Implementation:**
- Key encapsulation mechanism (KEM)
- Session key establishment
- Post-quantum key exchange
- Combined with HKDF for key derivation

**Key Derivation Strategy:**
```
ML-KEM Shared Secret + Additional Derived Key + Workspace ID
           ↓ (HKDF-SHA-256)
     Derived Master Key
           ↓
    ┌──────┴──────┐
    ↓             ↓
Content Key   Workspace Key
```

### 3. Symmetric Encryption

**Purpose:** Encrypt user data with derived keys

**Algorithm:** AES-256-GCM (Advanced Encryption Standard - Galois/Counter Mode)

**Key Size:** 256-bit (quantum-safe key length)

**Properties:**
- **Authenticated encryption** (AEAD - integrity + confidentiality)
- **Authentication tag** prevents tampering
- **Nonce uniqueness** (random nonce per encryption)
- **Fast performance** (suitable for large files)
- **Chunk-based** encryption for large data

**Process:**
```
Plaintext + 256-bit Key + Random Nonce → AES-256-GCM → Ciphertext + Auth Tag
```

**Implementation:**
- Variable-sized encrypted chunks for large files
- Metadata encrypted alongside content
- Native browser Web Crypto API when available
- Rust for performance

**Security:**
- Quantum-safe key length (Grover's algorithm reduces to 128-bit effective, still secure)
- Authentication tag detects any tampering
- Each encryption uses unique random nonce

### 4. PQXDH Protocol

**Full Name:** Post-Quantum Extended Diffie-Hellman

**Purpose:** Hybrid key exchange combining classical and post-quantum cryptography

**Components:**
1. **ML-KEM-1024:** Post-quantum key encapsulation
2. **X25519:** Classical elliptic curve key exchange (Curve25519)
3. **Combined Security:** Both must be broken to compromise

**Properties:**
- Hybrid post-quantum + classical security
- Forward secrecy (ephemeral keys)
- Asynchronous communication support
- Defense-in-depth approach

**Security Advantage:**
- If quantum computers break X25519, ML-KEM still protects
- If ML-KEM has flaws, X25519 provides fallback security
- Provides security against both current and future threats

**Use Case:**
When sharing encrypted data with other users, PQXDH establishes shared secrets without key transmission.

### 5. Group Encryption (Threshold Cryptography)

**Purpose:** Allow multiple parties to share encrypted data with configurable approval requirements

**Schemes:**

**All Required (N-of-N):**
- All group members must approve to decrypt
- Complete consensus required
- Highest security

**Some Required (M-of-N):**
- M out of N members must approve
- Example: 2 of 3, 3 of 5
- Threshold signatures

**One Required (1-of-N):**
- Any single member can decrypt
- Convenient for trusted groups
- Lower security threshold

**Implementation:**
- Threshold secret sharing (Shamir-based or modern alternatives)
- Each participant uses their own memory-derived key
- No single party has full key material
- Reconstruction happens client-side

**Example:**
```
Family Will Access:
- Total members: 3 (Alice, Bob, Carol)
- Required: 2 of 3
- Any two can reconstruct access
- No single point of failure
```

### 6. Additional Cryptographic Algorithms

#### **RSA-2048** (Asymmetric Encryption)
- **Key Size:** 2048-bit
- **Mode:** RSA-OAEP with SHA-256
- **Purpose:** 
  - Asymmetric encryption for user-to-user communication
  - Hybrid encryption (encrypt AES keys)
  - Secure key exchange between users
- **Use Case:** Combines symmetric and asymmetric encryption for optimal security
- **Note:** Classical algorithm (quantum-vulnerable), supplemented by ML-KEM for quantum safety

#### **Ed25519** (Digital Signatures)
- **Curve:** Curve25519 (Edwards curve, twisted)
- **Purpose:** Digital signatures for authentication
- **Properties:**
  - Fast signature generation and verification
  - Small signature size (64 bytes)
  - Deterministic signatures
  - 128-bit security level (quantum: ~64-bit)
- **Use Case:** Public key authentication, integrity verification

#### **X25519** (Key Exchange)
- **Curve:** Curve25519 (Montgomery curve)
- **Purpose:** Elliptic curve Diffie-Hellman key exchange
- **Security:** 128-bit classical security
- **Use Case:** Part of PQXDH hybrid protocol

#### **HKDF** (HMAC-based Key Derivation)
- **Hash Algorithms:** SHA-256 / SHA-512
- **Purpose:** Derive multiple keys from single master key
- **Use Cases:**
  - Workspace-specific key derivation
  - Content encryption key derivation
  - Combined with ML-KEM shared secrets
- **Process:** Extract-and-Expand paradigm

#### **Hashing & Message Authentication**

**SHA-256:**
- 256-bit secure hash
- General-purpose hashing
- Used in HKDF, HMAC, integrity checks

**SHA-512:**
- 512-bit secure hash
- High-security hashing
- Used in HMAC-SHA-512 for quantum-safe authentication

**HMAC (Hash-based Message Authentication Code):**
- Variants: HMAC-SHA-256, HMAC-SHA-512
- Purpose: Message authentication and integrity
- Use cases: Question set hashing, key verification, content authentication

## Advanced Security Features

### Memory-Only Key Storage

**Core Security Principle:** Keys exist exclusively in volatile memory and are never persisted.

**Implementation:**
- **Volatile Storage Only:** All cryptographic keys stored in RAM
- **Short TTL:** Automatic key timeout and expiration
- **Always Encrypted:** Keys encrypted in memory using quantum-safe algorithms
- **No Persistence:** Keys never written to disk, database, or permanent storage
- **Automatic Clearing:** Keys wiped from memory after use

**Process:**
```
User Login → Derive Key (PBKDF2) → Store in Encrypted Memory → Use for Session → Auto-Expire → Clear
```

**Security Benefits:**
- No key files to steal or compromise
- Memory dumps cannot reveal plaintext keys
- Reduces attack surface dramatically
- Automatic security through expiration

### Device-Specific Obfuscation

**Purpose:** Additional layer of key protection using device characteristics

**Implementation:**
- Each device generates unique random ID on first use
- Device ID serves as derived key for additional obfuscation layer
- Keys derived using: Memory Inputs + User Salt + Device ID + Workspace ID
- Multi-layer key derivation prevents cross-device key prediction

**Process:**
```
Memory Inputs + User Salt + Device Random ID + Workspace ID
           ↓ (PBKDF2 + HKDF)
     Device-Specific Key
           ↓
    Obfuscated in Memory
```

**Security Benefits:**
- Keys unique per device even with same memory inputs
- Stolen memory dump from Device A cannot be used on Device B
- Additional entropy layer beyond user inputs
- Device binding without hardware requirements

### Remote View Obfuscation

**Purpose:** Protect against screen scraping, remote access tools, and keyloggers

**Implementation:**

**1. Canvas-Based UI Rendering:**
- All sensitive UI elements rendered using HTML5 Canvas
- Prevents screen scraping and remote inspection tools
- Data not visible in DOM or accessibility tree
- Remote viewing software sees only canvas pixels

**2. Canvas-Based Input Protection:**
- Custom canvas-based input fields for sensitive data
- Prevents keyloggers from capturing user input
- Input events processed internally
- No DOM input elements for sensitive data

**3. Data-in-Transit Obfuscation:**
- All data moving within application is hashed and encrypted
- DOM manipulation uses encrypted values only
- Sensitive data never appears in plaintext in memory dumps
- Additional obfuscation prevents pattern analysis

**4. Anti-Analysis Protection:**
- Data structures obfuscated to resist reverse engineering
- Remote view/control software cannot extract information
- Memory layout randomization
- Timing attack mitigations

**Security Benefits:**
- Protection against remote access Trojans (RATs)
- Keylogger resistance
- Screen capture protection
- Enterprise remote view software bypassed

### Multi-Layer Encryption Architecture

**Defense-in-Depth Strategy:** Multiple independent encryption layers

**Layer 1: Content Encryption**
- AES-256-GCM with content-specific key
- Derived from: Master Key + Content ID
- Each item independently encrypted

**Layer 2: Workspace Encryption**
- Additional encryption using workspace-specific key
- Derived from: Master Key + Workspace ID
- Isolates content across workspaces

**Layer 3: Post-Quantum Layer**
- ML-KEM-1024 for shared/synchronized content
- Protects against quantum threats
- Applied to multi-user or cloud-synced data

**Process:**
```
Plaintext
   ↓ (AES-256-GCM, Content Key)
Content Ciphertext
   ↓ (AES-256-GCM, Workspace Key)  
Workspace Ciphertext
   ↓ (ML-KEM-1024, Optional for sharing)
Final Ciphertext
```

**Security Benefits:**
- Multiple algorithms must be broken simultaneously
- Different keys for each layer
- Compromise of one layer doesn't expose plaintext
- Quantum and classical protections combined

## Execution Environment

### Dual Implementation Architecture

**Strategy:** Both JavaScript and Rust/WebAssembly implementations for all cryptographic operations

**JavaScript Implementation:**
- Uses @noble libraries (post-quantum, curves)
- Web Crypto API for AES, SHA, HMAC
- Maximum compatibility (works in all modern browsers)
- No build step required
- Inspectable source code

**Rust/WebAssembly Implementation:**
- Uses Rust crates: ml-kem, aes-gcm, x25519-dalek, ed25519-dalek, rsa
- Compiled to WebAssembly for near-native performance
- Memory-safe (Rust ownership model prevents buffer overflows)
- ~100x faster for PBKDF2 operations
- Hardware acceleration where available

**Libraries:**

*JavaScript:*
- `@noble/post-quantum` - ML-KEM implementation
- `@noble/curves` - X25519, Ed25519, secp256k1
- Web Crypto API - AES-256-GCM, SHA-256, HMAC

*Rust:*
- `ml-kem` - Post-quantum KEM (NIST FIPS 203)
- `aes-gcm` - AES-256-GCM encryption
- `x25519-dalek` - ECDH key exchange
- `ed25519-dalek` - Digital signatures
- `rsa` - RSA-2048 encryption
- `pbkdf2`, `hkdf`, `hmac`, `sha2` - Key derivation

**Cross-Compatibility:**
Both implementations produce identical cryptographic results. System automatically selects optimal implementation.

### Primary: Rust + WebAssembly

**Advantages:**
- **Performance:** Near-native execution speed (~100x faster than JS for KDF)
- **Memory safety:** Rust prevents buffer overflows, use-after-free
- **Sandboxing:** WASM provides isolation from browser
- **Security:** Type safety and ownership model
- **Optimizations:** Loop unrolling, stack-allocated buffers, single-block optimization

**Implementation:**
- Cryptographic primitives in Rust
- Compiled to WebAssembly (.wasm files)
- Executed in browser WASM VM
- Automatic fallback if WASM unavailable

### Fallback: JavaScript

**Advantages:**
- **Compatibility:** Works in all modern browsers (2020+)
- **No compilation:** Direct execution
- **Debuggable:** Source code visible
- **Flexible:** Easier to update and modify

**Trade-offs:**
- Slower than WASM (but still acceptable for most operations)
- Less memory-safe than Rust (but uses vetted libraries)

**When Used:**
- Old browsers without WebAssembly support
- Explicit user preference
- WASM loading failure

### Browser Requirements

**Minimum:**
- Web Crypto API support (for AES, SHA, HMAC)
- WebAssembly support (preferred, not required)
- IndexedDB (for local storage)

**Recommended:**
- Modern browser (Chrome, Firefox, Safari, Edge 2020+)
- JavaScript enabled
- Cookies/localStorage enabled for session management

## Cryptographic Lifecycle

### Key Generation

```
1. User inputs memory secrets
2. KDF processes inputs (100-500ms)
3. Private key generated in memory
4. Key used for session
5. Key cleared from memory
6. NEVER stored
```

### Encryption

```
1. User data (plaintext)
2. Private key (from memory)
3. Generate unique nonce
4. Apply AES-256-GCM
5. Post-quantum layer (if sharing)
6. Output: ciphertext + auth tag
7. Store encrypted data
8. Clear plaintext from memory
```

### Decryption

```
1. Retrieve encrypted data
2. Regenerate key from memory inputs
3. Verify auth tag
4. Decrypt with AES-256-GCM
5. Return plaintext
6. Clear key from memory
```

## Security Properties

### What CQRIT Cryptographically Guarantees

✅ **Post-Quantum Resistance**
- ML-KEM-1024 (NIST Level 5) protects against quantum attacks
- AES-256 quantum-safe key length
- Future-proof against Q-day (quantum threat day)

✅ **Zero Server-Side Key Exposure**
- Keys never transmitted to server
- Keys never stored on server
- Server breach cannot expose keys
- Zero-knowledge architecture

✅ **Memory-Only Key Storage**
- Keys exist only in volatile RAM
- Short TTL with automatic expiration
- Always encrypted in memory using quantum-safe algorithms
- No persistent key storage anywhere

✅ **Device-Specific Security**
- Device-specific obfuscation layer
- Keys derived using unique device ID
- Cross-device key prediction prevented
- Multi-layer key derivation

✅ **Remote View Protection**
- Canvas-based UI prevents screen scraping
- Keylogger resistance (canvas-based inputs)
- DOM protection (no plaintext in DOM)
- Data-in-transit obfuscation

✅ **Deterministic Key Regeneration**
- Same inputs = same keys
- Multi-device support without key sync
- No key files to transfer

✅ **Authenticated Encryption**
- AES-256-GCM provides integrity and confidentiality
- Tampering detection via authentication tag
- Man-in-the-middle attack protection

✅ **Forward Secrecy** (for shared data)
- Session keys ephemeral in PQXDH
- Past communication secure even if current keys compromised
- Keys not reused across sessions

✅ **Multi-Layer Defense**
- Multiple independent encryption layers
- Different algorithms and keys per layer
- One layer compromise doesn't expose plaintext

### What CQRIT Does NOT Guarantee

❌ **Mathematical Proof of "Unbreakability"**
- Relies on computational hardness assumptions (MLWE for ML-KEM, AES security)
- No cryptographic system provides absolute proof
- Trust in NIST-reviewed algorithms

❌ **Protection Against Weak Inputs**
- Security depends on entropy of memory inputs
- "password123" is cryptographically weak regardless of KDF
- User responsibility to choose strong inputs

❌ **Protection Against Fully Compromised Device**
- If device has root-level malware, keys can be stolen during active use
- Standard device security required (antivirus, OS updates, trusted software)
- Browser/OS integrity assumed

❌ **Protection Against Physical Coercion**
- User can be tortured to reveal memory inputs
- Coercion resistance (high-threshold recovery) mitigates but doesn't eliminate
- Cannot protect users from physical harm

❌ **Protection Against Browser/OS Backdoors**
- Trusts browser and operating system integrity
- Cannot protect if browser itself is malicious
- No protection against nation-state browser backdoors

❌ **Side-Channel Attack Resistance**
- Web platform not designed for constant-time operations
- Timing attacks possible in theory
- Power analysis, EM radiation side-channels out of scope

❌ **Protection Against Supply Chain Attacks**
- If npm packages or dependencies compromised, system vulnerable
- Mitigation: SubResourceIntegrity (SRI), open-source review
- Cannot guarantee entire dependency tree is trustworthy

## Threat Model

### Threats CQRIT Protects Against

1. **Quantum Adversaries**
   - ML-KEM-1024 resists Shor's algorithm
   - AES-256 resists Grover's algorithm (128-bit effective security)
   - Harvest-now-decrypt-later defense

2. **Server/Database Breach**
   - No keys on server (memory-only, client-side)
   - Encrypted data useless without user's memory inputs
   - Even full database dump reveals only ciphertext

3. **Network Interception (MITM)**
   - Keys never transmitted over network
   - Plaintext never transmitted
   - AES-GCM authentication prevents tampering
   - HTTPS provides transport security

4. **Device Loss/Theft (Offline Attack)**
   - Keys not stored on device
   - Encrypted data requires memory inputs
   - User regenerates key on new device

5. **Rainbow Table Attacks**
   - User-specific salt prevents precomputed tables
   - Each user has unique KDF parameters
   - Device-specific obfuscation adds additional entropy

6. **Screen Scraping / Remote Access Tools**
   - Canvas-based UI prevents DOM inspection
   - Remote viewing software sees only pixels
   - Sensitive data never in accessibility tree

7. **Keyloggers**
   - Canvas-based input fields prevent keyboard capture
   - Input events processed internally
   - No DOM input elements for sensitive data

8. **Memory Dump Analysis (Limited)**
   - Keys encrypted in memory with quantum-safe algorithms
   - Multi-layer key derivation prevents plaintext recovery
   - Short TTL limits exposure window

### Threats Requiring Additional Mitigations

1. **Weak Memory Inputs**
   - **Mitigation:** User education, entropy checking
   - **User responsibility:** Choose high-entropy answers
   - System cannot force strong inputs

2. **Device Malware (Active Session)**
   - **Partial mitigation:** Keys cleared after use, obfuscation
   - **User responsibility:** Use trusted, malware-free devices
   - **Limitation:** Cannot protect if device fully compromised during active use

3. **Phishing Attacks**
   - **Mitigation:** URL verification, HTTPS
   - **User responsibility:** Verify authentic site
   - **Limitation:** Cannot prevent user from using fake site

4. **Physical Coercion ($5 Wrench Attack)**
   - **Mitigation:** High-threshold social recovery (10-of-10)
   - **User configuration:** Must be set up proactively
   - **Limitation:** User can still be harmed (system makes coercion pointless, not impossible)

5. **Supply Chain Attacks**
   - **Mitigation:** Open-source code, SRI, dependency pinning
   - **Community:** Public review and auditing
   - **Limitation:** Cannot guarantee entire supply chain integrity

3. **Physical Coercion**
   - Anti-kidnapping features
   - Duress protocols

4. **Side-Channel Attacks**
   - Constant-time implementations where applicable
   - Timing attack mitigations

## Cryptographic Assumptions

CQRIT's security relies on:

1. **MLWE Problem Hardness** (CRYSTALS-Kyber)
   - Assumption: Module Learning With Errors is hard for quantum computers

2. **KDF Security**
   - Assumption: KDF properly implemented with sufficient iterations

3. **AES-256 Security**
   - Assumption: AES-256 remains secure against classical attacks

4. **Implementation Correctness**
   - Assumption: No critical bugs in cryptographic code

5. **Browser Security Model**
   - Assumption: Browser provides secure execution environment

## Algorithm Transparency

### Public Standards

- **CRYSTALS-Kyber:** NIST PQC Selected Algorithm
- **PQXDH:** Open protocol specification
- **AES-256-GCM:** NIST standard
- **Shamir's Secret Sharing:** Published 1979

### Audibility

- Rust cryptographic libraries publicly available
- WebAssembly can be inspected
- JavaScript fallback source inspectable
- No security through obscurity

## Performance

**Key Derivation:**
- ~100-500ms (depends on iteration count)
- One-time per session

**Encryption:**
- Small data (<1KB): ~1-10ms
- Large files (>1MB): ~100-1000ms

**Decryption:**
- Similar to encryption

**Post-Quantum Operations:**
- Slower than RSA but acceptable (~10-100ms)

## Future Roadmap

- Additional NIST PQC algorithms
- Formal verification of critical components
- Hardware security module (HSM) integration
- Quantum random number generator (QRNG)

---

**For Security Researchers:**
If you discover vulnerabilities: security@cqrit.io

**Next:** Read [Key Management](key-management.md)