# Security

Security model, cryptographic choices, and best practices for SRX.

---

## Overview

SRX is designed with a **security-first** approach. Every design decision prioritizes correctness and security over convenience or performance.

### Core Principles

1. **No Custom Cryptography** - Only proven, battle-tested primitives
2. **Defense in Depth** - Multiple layers of protection
3. **Fail Secure** - Errors default to secure states
4. **Conservative Defaults** - Secure by default, configurable for advanced users

---

## Cryptographic Choices

### Encryption: XChaCha20-Poly1305

SRX uses **XChaCha20-Poly1305** for authenticated encryption.

#### Why XChaCha20?

| Property | XChaCha20 | AES-GCM |
|----------|-----------|---------|
| Timing-attack resistant | ✅ Yes | ⚠️ Hardware dependent |
| Hardware acceleration | Not needed | Required for safety |
| Nonce size | 192 bits | 96 bits |
| Key size | 256 bits | 128/256 bits |
| Software performance | ~1 GB/s | ~500 MB/s (no AES-NI) |

#### Advantages

- **Constant-time implementation** - Immune to timing attacks
- **Large nonce space** - 192-bit nonces allow random generation without collision risk
- **No hardware dependency** - Safe on all CPUs, including embedded
- **AEAD construction** - Encryption and authentication in one operation

#### Parameters

| Parameter | Value |
|-----------|-------|
| Cipher | XChaCha20 |
| Authentication | Poly1305 |
| Key size | 256 bits |
| Nonce size | 192 bits (24 bytes) |
| Auth tag size | 128 bits (16 bytes) |

---

### Key Derivation: Argon2id

SRX uses **Argon2id** for deriving encryption keys from passwords.

#### Why Argon2id?

Argon2id is the **winner of the Password Hashing Competition (2015)** and provides:

- **Memory hardness** - Resists GPU/ASIC attacks
- **Side-channel resistance** - Hybrid mode combines Argon2i and Argon2d
- **Configurable resources** - Adjustable memory, time, and parallelism

#### Default Parameters

| Parameter | Value | Rationale |
|-----------|-------|-----------|
| Memory | 64 MiB | Resists GPU attacks |
| Iterations | 3 | Balance of security and usability |
| Parallelism | 4 threads | Utilizes modern CPUs |
| Salt | 128 bits | Prevents rainbow tables |
| Output | 256 bits | Matches XChaCha20 key size |

#### Security Level

With default parameters, Argon2id provides approximately:

- **~$2^{20}$ memory-hard operations** per guess
- **~$2^{22}$ CPU operations** per guess
- Effective protection against brute-force attacks

---

### Integrity: BLAKE3

SRX uses **BLAKE3** for file integrity verification.

#### Why BLAKE3?

| Property | BLAKE3 | SHA-256 | SHA-512 |
|----------|--------|---------|---------|
| Speed | ~1 GB/s | ~300 MB/s | ~500 MB/s |
| Parallelism | ✅ Yes | ❌ No | ❌ No |
| Output | 256 bits | 256 bits | 512 bits |
| Security | 256-bit | 256-bit | 512-bit |

#### Advantages

- **Extremely fast** - Optimized for modern CPUs with SIMD
- **Parallelizable** - Takes advantage of multi-core processors
- **Proven security** - Based on BLAKE2, analyzed in SHA-3 competition

---

## Security Model

### Threat Model

SRX protects against:

| Threat | Protection |
|--------|------------|
| **Passive eavesdropping** | Encrypted data is unreadable without password |
| **Data tampering** | Poly1305 authentication detects any modification |
| **Chunk manipulation** | Per-chunk tags prevent reordering or replacement |
| **Password cracking** | Argon2id makes brute-force attacks expensive |
| **Chosen-ciphertext attacks** | AEAD construction is provably secure |
| **Replay attacks** | Each chunk has a unique nonce |
| **Length extension attacks** | BLAKE3 is immune |

### What SRX Does NOT Protect Against

| Threat | Reason |
|--------|--------|
| **Password compromise** | Strong passwords are user's responsibility |
| **Side-channel attacks on host** | Assumes trusted execution environment |
| **Metadata leakage** | Archive size approximates original file size |
| **Ransomware** | SRX does not prevent file deletion |
| **Keylogging** | Passwords can be intercepted during input |
| **Memory dumps** | Keys exist in memory during processing |

---

## Best Practices

### Password Guidelines

#### ✅ Strong Passwords

```bash
# Use a passphrase (4+ random words)
srx pack file.txt file.srx -p "correct-horse-battery-staple"

# Use a password manager
srx pack file.txt file.srx -p "$(pass show archives/file)"

# Read from a secure file
srx pack file.txt file.srx -p "$(cat ~/.secure_password)"
```

#### ❌ Weak Passwords

```bash
# Too short
srx pack file.txt file.srx -p "pass"  # ❌

# Common words
srx pack file.txt file.srx -p "password"  # ❌

# Personal information
srx pack file.txt file.srx -p "john1990"  # ❌

# On command line (visible in history)
srx pack file.txt file.srx -p "my_secret_password"  # ⚠️ Visible in ps, history
```

### Password Strength Guidelines

| Password Type | Entropy | Time to Crack* |
|---------------|---------|----------------|
| 6 characters | ~30 bits | Minutes |
| 8 characters | ~40 bits | Hours |
| 12 characters | ~60 bits | Years |
| 4 random words | ~80 bits | Centuries |
| 6 random words | ~120 bits | Heat death of universe |

*Assuming Argon2id with default parameters

### Secure Password Storage

```bash
# Use a password manager
pass generate archives/myfile 32
srx pack file.txt file.srx -p "$(pass show archives/myfile)"

# Or use environment variables (for scripts)
export SRX_PASSWORD="$(pass show archives/myfile)"
srx pack file.txt file.srx
```

---

## Security Configuration

### Memory-Constrained Environments

For systems with limited RAM, reduce Argon2 memory:

```bash
# Reduce memory to 32 MiB
export SRX_MEMORY_LIMIT=32
srx pack file.txt file.srx -p "password"
```

### High-Security Mode

For maximum security, increase Argon2 parameters:

```rust
use srx::Packer;

let packer = Packer::new("password".to_string())
    .memory_limit(256)    // 256 MiB
    .parallelism(8);      // 8 threads

packer.pack("sensitive.txt", "sensitive.srx")?;
```

### Performance vs Security Trade-offs

| Configuration | Memory | Time | Security Level | Use Case |
|---------------|--------|------|----------------|----------|
| Low | 32 MiB | 1 iteration | Standard | Embedded devices |
| Default | 64 MiB | 3 iterations | High | General use |
| High | 256 MiB | 4 iterations | Very High | Sensitive data |
| Maximum | 1 GiB | 8 iterations | Extreme | Top secret |

---

## Security Audit Checklist

Before using SRX for sensitive data, verify:

- [ ] Using strong, unique password
- [ ] Password stored securely (password manager)
- [ ] Archive stored in secure location
- [ ] Original file securely deleted (if needed)
- [ ] Backup copies maintained
- [ ] SRX version is up to date

---

## Vulnerability Reporting

If you discover a security vulnerability in SRX:

1. **Do NOT** open a public issue
2. Email security concerns to: security@example.com
3. Include:
   - Description of the vulnerability
   - Steps to reproduce
   - Potential impact
   - Suggested fix (if any)

We will respond within 48 hours and provide a timeline for a fix.

---

## Security FAQ

### Is SRX quantum-resistant?

SRX uses classical cryptography (XChaCha20, Argon2, BLAKE3). These are not quantum-resistant. However:

- **Current quantum computers** cannot break these algorithms
- **Post-quantum migration** is planned for a future version
- **Harvest now, decrypt later** attacks are mitigated by Argon2id's memory hardness

### Can I use SRX for passwords/keys?

SRX is designed for **file encryption**, not password/credential management. Use dedicated tools like:

- **pass** - Unix password manager
- **KeePassXC** - Cross-platform password manager
- **Bitwarden** - Cloud-based password manager

### What if I forget my password?

**There is no backdoor.** If you forget your password:

- The data is **permanently inaccessible**
- No recovery mechanism exists
- This is by design for security

### Is SRX suitable for classified/government data?

SRX uses **NIST-approved primitives** (ChaCha20, Poly1305) but:

- Not FIPS 140-2 certified
- Not evaluated by any government agency
- Use at your own discretion for sensitive data

### How does SRX compare to age/gpg?

| Feature | SRX | age | GPG |
|---------|-----|-----|-----|
| Authenticated encryption | ✅ Always | ✅ Always | ⚠️ Optional |
| Password hashing | Argon2id | scrypt | Iterated SHA |
| Random access | ✅ Yes | ❌ No | ❌ No |
| Streaming | ✅ Yes | ✅ Yes | ⚠️ Limited |
| Key escrow | ❌ No | ❌ No | ⚠️ Optional |

---

## Security Updates

Stay informed about security updates:

- **GitHub Security Advisories**: Enable notifications
- **Release Notes**: Check [RELEASE_NOTES.md](../RELEASE_NOTES.md)
- **Version**: Always use the latest stable version

---

## See Also

- [File Format](File-Format) - Technical format specification
- [FAQ](FAQ) - Frequently asked questions
- [Getting Started](Getting-Started) - Installation and usage