# ML-KEM-768 Security Design Philosophy

## Overview

This document explains the security design philosophy for ML-KEM-768 implementations in the MetaMUI Crypto Primitives library, particularly focusing on the use of domain separation and the three-tier encapsulation approach.

## Domain Separation: A Security Best Practice

Domain separation is a cryptographic technique that ensures different uses of the same cryptographic primitive produce distinct outputs, even with identical inputs. This prevents cross-protocol attacks and enhances security in production systems.

## Three-Tier Encapsulation Design

Our ML-KEM-768 implementations follow a three-tier approach:

### 1. Production Encapsulation (`encapsulate_production`)
**Purpose**: Military-grade security for production deployments

**Features**:
- Domain separation with timestamps
- Audit logging capabilities
- Additional entropy mixing
- Never uses deterministic randomness
- Includes operation identifiers

**Example (Python)**:
```python
# Domain separation with timestamp
timestamp = struct.pack('>Q', int(time.time() * 1000000))
domain = b"MLKEM768-ENCAPS-V1.0-" + timestamp

# Mix entropy with domain separator
m_final = sha3_256(domain + m)
```

**When to use**: Always use this in production systems.

### 2. Test Encapsulation (`encapsulate_test`)
**Purpose**: Reproducible testing with security best practices

**Features**:
- Domain separation with test prefix
- Deterministic for reproducibility
- Still follows security principles
- Prevents test vectors from being used in production

**Example (Python)**:
```python
# Standardized domain separation for testing
m = sha3_256(b"MLKEM768-TEST-V1.0" + test_seed)
```

**When to use**: Use for unit tests, integration tests, and development.

### 3. Raw Deterministic Encapsulation (`encapsulate_deterministic`)
**Purpose**: Cross-language compatibility testing only

**Features**:
- No domain separation
- Direct deterministic operation
- Matches reference implementations exactly
- Required for test vector validation

**When to use**: ONLY for cross-language compatibility test vectors.

## Security Rationale

### Why Domain Separation in Tests?

1. **Prevents Misuse**: Test vectors with domain separation cannot be accidentally used in production
2. **Security Culture**: Reinforces security-first thinking even in test code
3. **Attack Prevention**: Prevents potential attacks that might leverage known test vectors
4. **Clear Distinction**: Makes it obvious when looking at outputs whether they're from tests or production

### Production Security Features

The production encapsulation includes several additional security measures:

1. **Timestamp Integration**: Ensures uniqueness even if the same RNG output occurs
2. **Audit Trail**: Allows security monitoring without exposing secrets
3. **Entropy Enhancement**: Additional mixing prevents weak RNG issues
4. **Version Binding**: Domain includes version information for algorithm agility

## Implementation Guidelines

### For New Language Implementations

1. **Always implement all three tiers**
2. **Default to `encapsulate_test` for testing**
3. **Clearly document when `encapsulate_deterministic` is used**
4. **Include warnings on raw deterministic functions**

### For Cross-Language Testing

When testing compatibility across languages:

1. **Use `encapsulate_raw_compatibility` (or equivalent) for vector matching**
2. **Document why raw mode is being used**
3. **Include security warnings in test files**
4. **Never use raw mode examples in documentation without warnings**

## Example Test Structure

```python
class MLKemTests:
    def test_security_focused(self):
        """Test with domain separation - recommended approach"""
        ct, ss = mlkem.encapsulate_test(pk, test_seed)
        # This is the secure, recommended way
    
    def test_cross_language_compatibility(self):
        """ONLY for verifying cross-language compatibility"""
        # WARNING: This is only for compatibility testing
        # Never use this approach in production
        ct, ss = mlkem.encapsulate_raw_compatibility(pk, test_seed)
```

## Summary

The three-tier design balances security best practices with practical testing needs:

- **Production**: Maximum security with all features enabled
- **Test**: Security-conscious testing with reproducibility
- **Raw**: Minimal mode only for compatibility verification

This approach ensures that even our test infrastructure promotes security-first thinking, which is essential for military-grade cryptographic systems.