encryption

What this skill does

# Encryption Skill

---
name: encryption
version: 1.0.0
domain: security/cryptography
risk_level: HIGH
languages: [python, typescript, rust, go]
frameworks: [sqlcipher, cryptography, libsodium]
requires_security_review: true
compliance: [GDPR, HIPAA, PCI-DSS, SOC2]
last_updated: 2025-01-15
---

> **MANDATORY READING PROTOCOL**: Before implementing ANY encryption, read `references/advanced-patterns.md` for key derivation and `references/security-examples.md` for implementation patterns.

## 1. Overview

### 1.1 Purpose and Scope

This skill provides secure-by-default patterns for implementing encryption in JARVIS AI Assistant, covering:

- **SQLCipher**: Encrypted SQLite database with AES-256-GCM
- **Argon2id**: Memory-hard key derivation function
- **Key Management**: Secure generation, storage, rotation, and destruction
- **Secure Memory**: Protection against memory disclosure attacks

### 1.2 Risk Assessment

**Risk Level**: HIGH

**Justification**:
- Cryptographic failures expose all protected data
- Key compromise leads to complete confidentiality loss
- Implementation errors are catastrophic and often undetectable
- Regulatory violations (GDPR, HIPAA, PCI-DSS) carry severe penalties

**Attack Surface**:
- Key derivation weaknesses
- Insecure random number generation
- Timing side-channels
- Memory disclosure (cold boot, crash dumps)
- Key reuse across contexts

## 2. Core Responsibilities

### 2.1 Primary Functions

1. **Encrypt data at rest** using AES-256-GCM with authenticated encryption
2. **Derive keys securely** using Argon2id with appropriate parameters
3. **Manage key lifecycle** including rotation, escrow, and destruction
4. **Protect key material** in memory and during operations
5. **Integrate with OS keychains** for master key storage

### 2.2 Core Principles

1. **TDD First** - Write tests before implementation; test encryption/decryption round-trips, authentication failures, and edge cases
2. **Performance Aware** - Cache derived keys, use streaming for large data, leverage hardware acceleration
3. **Security by Default** - Use authenticated encryption modes, memory-hard KDFs, secure random sources
4. **Defense in Depth** - Multiple layers of protection, fail securely, minimize key exposure

### 2.3 Security Principles

- **NEVER** implement custom cryptographic algorithms
- **NEVER** use ECB mode or unauthenticated encryption
- **ALWAYS** use cryptographically secure random number generators
- **ALWAYS** validate ciphertext authenticity before decryption
- **ALWAYS** use constant-time comparison for authentication tags

## 3. Implementation Workflow (TDD)

### Step 1: Write Failing Test First

```python
import pytest
from cryptography.exceptions import InvalidTag

class TestEncryptionTDD:
    """TDD tests for encryption implementation."""

    def test_encrypt_decrypt_roundtrip(self):
        """Test that encryption followed by decryption returns original data."""
        from jarvis.security.encryption import SecureEncryption

        key = secrets.token_bytes(32)
        encryptor = SecureEncryption(key)

        plaintext = b"sensitive data for JARVIS"
        ciphertext = encryptor.encrypt(plaintext)
        decrypted = encryptor.decrypt(ciphertext)

        assert decrypted == plaintext
        assert ciphertext != plaintext  # Must be encrypted

    def test_tampered_ciphertext_raises_error(self):
        """Test that tampered ciphertext is rejected."""
        from jarvis.security.encryption import SecureEncryption

        key = secrets.token_bytes(32)
        encryptor = SecureEncryption(key)

        ciphertext = encryptor.encrypt(b"secret")
        tampered = ciphertext[:-1] + bytes([ciphertext[-1] ^ 0xFF])

        with pytest.raises(InvalidTag):
            encryptor.decrypt(tampered)

    def test_key_derivation_consistency(self):
        """Same password + salt = same key; different salt = different key."""
        from jarvis.security.encryption import SecureKeyDerivation
        password = "strong_password_123"
        salt = secrets.token_bytes(16)
        key1, _ = SecureKeyDerivation.derive_key(password, salt)
        key2, _ = SecureKeyDerivation.derive_key(password, salt)
        assert key1 == key2 and len(key1) == 32

        key3, salt3 = SecureKeyDerivation.derive_key(password)
        assert key1 != key3  # Different salt = different key
```

### Step 2: Implement Minimum to Pass

Implement only what's needed to pass the tests. Start with basic encryption/decryption, then add key derivation.

### Step 3: Refactor Following Patterns

After tests pass, add: memory protection, error handling, AAD support, key caching.

### Step 4: Run Full Verification

```bash
# Run encryption tests with coverage
pytest tests/security/test_encryption.py -v --cov=jarvis.security.encryption --cov-fail-under=90

# Run security-specific tests
pytest tests/security/ -k "encryption or crypto" -v

# Check for timing vulnerabilities
pytest tests/security/test_timing.py -v

# Verify no secrets in output
pytest --log-cli-level=DEBUG 2>&1 | grep -i "key\|secret\|password" && echo "WARNING: Secrets in logs!"
```

## 4. Technology Stack

### 4.1 Recommended Libraries

| Language | Library | Version | Notes |
|----------|---------|---------|-------|
| Python | `cryptography` | >=42.0.0 | Uses OpenSSL 3.x backend |
| Python | `argon2-cffi` | >=23.1.0 | Reference Argon2 implementation |
| TypeScript | `@noble/ciphers` | >=0.5.0 | Audited pure-JS implementation |
| Rust | `ring` | >=0.17.0 | BoringSSL-backed |
| Go | `crypto/cipher` | stdlib | Use with `golang.org/x/crypto` |

### 4.2 SQLCipher Configuration

**Minimum Version**: SQLCipher 4.5.6+ (includes SQLite 3.44.2)

```python
# SQLCipher secure configuration
SQLCIPHER_PRAGMAS = {
    'key': None,  # Set via secure key injection
    'cipher': 'aes-256-gcm',
    'kdf_iter': 256000,  # PBKDF2 iterations
    'cipher_page_size': 4096,
    'cipher_kdf_algorithm': 'PBKDF2_HMAC_SHA512',
    'cipher_hmac_algorithm': 'HMAC_SHA512',
    'cipher_plaintext_header_size': 0,
}
```

## 5. Performance Patterns

### 5.1 Key Caching

**Bad:** Deriving key on every operation (~500ms per Argon2id call)

**Good - Cache with TTL:**
```python
class CachedKeyManager:
    def __init__(self, cache_ttl: int = 300):
        self._cache: dict[str, tuple[bytes, float]] = {}
        self._ttl = cache_ttl

    def get_key(self, password: str, salt: bytes) -> bytes:
        cache_key = f"{hash(password)}:{salt.hex()}"
        if cache_key in self._cache:
            key, ts = self._cache[cache_key]
            if time.time() - ts < self._ttl:
                return key
        key, _ = SecureKeyDerivation.derive_key(password, salt)
        self._cache[cache_key] = (key, time.time())
        return key
```

### 5.2 Streaming Encryption for Large Data

**Bad:** `data = f.read()` loads entire file into memory

**Good - Stream with chunking (64KB chunks):**
```python
nonce = secrets.token_bytes(12)
encryptor = Cipher(algorithms.AES(key), modes.GCM(nonce)).encryptor()
with open(input_path, 'rb') as fin, open(output_path, 'wb') as fout:
    fout.write(nonce)
    while chunk := fin.read(64 * 1024):
        fout.write(encryptor.update(chunk))
    fout.write(encryptor.finalize() + encryptor.tag)
```

### 5.3 Hardware Acceleration

**Bad:** PyCryptodome without OpenSSL backend (10-100x slower)

**Good:** Use `cryptography` library - auto-detects AES-NI via OpenSSL 3.x backend

### 5.4 Batch Operations

**Bad - Individual loop with append:**
```python
results = []
for record in records:
    results.append(encryptor.encrypt(record))
```

**Good - List comprehension with single encryptor:**
```python
encryptor = SecureEncryption(key)
results = [encryptor.encrypt(record) for record in records]

# For large batches, use ProcessPoolExecutor for parallelization
```

### 5.5 Memory-Safe Key Handling

**Bad - Keys remain in memory:**
```python
self.key = SecureKeyDerivation.derive_key(password)  # Never cleared
```

**Good - Zero key