# Blake3 KDF Guide

## Overview

Blake3 KDF is a modern key derivation function that offers significant performance advantages over traditional KDFs like HKDF. It's designed for deriving cryptographic keys from high-entropy sources (NOT for password hashing).

## Key Features

- **Performance**: ~3x faster than HKDF-SHA256
- **Security**: 128-bit collision resistance, suitable for all KDF applications
- **Domain Separation**: Built-in via context strings
- **Simplicity**: Single function call vs HKDF's extract/expand pattern
- **Variable Output**: Can generate keys of any length

## When to Use Blake3 KDF

### ✅ Use Blake3 KDF for:
- Deriving encryption keys from shared secrets
- Key expansion from master keys
- Subkey generation in cryptographic protocols
- High-performance applications
- Modern systems without legacy constraints

### ❌ Don't Use Blake3 KDF for:
- Password hashing (use Argon2 or PBKDF2)
- Low-entropy inputs
- Systems requiring strict RFC 5869 compliance

## API Examples

### Python

```python
from metamui_crypto.blake3 import blake3_derive_key

# Basic key derivation
master_secret = get_master_secret()  # 32 bytes of entropy
encryption_key = blake3_derive_key(
    "myapp.encryption.v1",  # Context string
    master_secret,          # Key material
    32                      # Output length in bytes
)

# Deriving multiple keys with different contexts
auth_key = blake3_derive_key("myapp.auth.v1", master_secret, 32)
storage_key = blake3_derive_key("myapp.storage.v1", master_secret, 32)

# User-specific keys
user_key = blake3_derive_key(
    f"myapp.user.{user_id}.v1",
    master_secret,
    32
)

# Hierarchical key derivation
level1_key = blake3_derive_key("myapp.level1", master_secret, 32)
level2_key = blake3_derive_key("myapp.level2", level1_key, 32)
```

### Rust

```rust
use metamui_blake3::{Blake3, derive_key};

// Basic key derivation
let master_secret = get_master_secret(); // 32 bytes
let encryption_key = derive_key(
    "myapp.encryption.v1",
    &master_secret,
    32
);

// Multiple keys from same master
let auth_key = derive_key("myapp.auth.v1", &master_secret, 32);
let storage_key = derive_key("myapp.storage.v1", &master_secret, 32);
```

### TypeScript

```typescript
import { blake3DeriveKey } from '@metamui/blake3';

// Basic key derivation
const masterSecret = getMasterSecret(); // Uint8Array
const encryptionKey = blake3DeriveKey(
    "myapp.encryption.v1",
    masterSecret,
    32
);

// Deriving keys for different purposes
const authKey = blake3DeriveKey("myapp.auth.v1", masterSecret, 32);
const storageKey = blake3DeriveKey("myapp.storage.v1", masterSecret, 32);
```

## Context String Best Practices

Context strings provide domain separation, preventing keys from being related across different uses.

### Good Context Strings:
- `"myapp.encryption.v1"` - Versioned and specific
- `"myapp.user.12345.session"` - User and purpose specific
- `"myapp.api.signing.2025"` - Time-bound contexts
- `"com.example.app.tls.client"` - Reverse domain notation

### Bad Context Strings:
- `"key"` - Too generic
- `"1"` - Not descriptive
- `""` - Empty (will throw error)
- `"test"` - Weak, may be rejected

### Context String Requirements:
- Minimum 8 characters (enforced by implementation)
- Should be unique per use case
- Include version information when applicable
- Use consistent naming scheme

## Migration from HKDF

### Before (HKDF):
```python
# HKDF requires extract and expand phases
salt = b"optional salt"
prk = hkdf_extract(salt, master_secret)
encryption_key = hkdf_expand(prk, b"encryption", 32)
```

### After (Blake3 KDF):
```python
# Blake3 KDF is simpler and faster
encryption_key = blake3_derive_key(
    "myapp.encryption.v1",
    master_secret,
    32
)
```

## Performance Comparison

| Operation | HKDF-SHA256 | Blake3 KDF | Speedup |
|-----------|-------------|------------|---------|
| 32-byte key | ~1.5μs | ~0.5μs | 3x |
| 64-byte key | ~2.0μs | ~0.6μs | 3.3x |
| 128-byte key | ~3.0μs | ~0.8μs | 3.7x |

## Security Considerations

1. **Input Entropy**: Blake3 KDF is designed for high-entropy inputs. Never use it directly with passwords.

2. **Context Collision**: Ensure context strings are unique across your application to prevent key reuse.

3. **Key Material**: Always use cryptographically secure random sources for master secrets.

4. **Output Length**: Blake3 can generate very long outputs efficiently, but consider your actual security requirements.

## Common Patterns

### 1. Encryption + Authentication Keys
```python
# Derive separate keys for encryption and authentication
shared_secret = perform_key_exchange()
enc_key = blake3_derive_key("app.encrypt.v1", shared_secret, 32)
mac_key = blake3_derive_key("app.mac.v1", shared_secret, 32)
```

### 2. Temporal Keys
```python
# Time-bound keys
epoch = int(time.time() // 3600)  # Hourly rotation
session_key = blake3_derive_key(
    f"app.session.{epoch}",
    master_secret,
    32
)
```

### 3. Multi-tenant Applications
```python
# Tenant-specific keys
tenant_key = blake3_derive_key(
    f"app.tenant.{tenant_id}",
    master_secret,
    32
)

# Further derive user keys within tenant
user_key = blake3_derive_key(
    f"app.user.{user_id}",
    tenant_key,
    32
)
```

## Integration with MetaMUI

Blake3 KDF is now the default for non-password key derivation in:
- Hybrid encryption (ChaCha20-Poly1305, AES-GCM)
- ARIA-256 key derivation
- Future cryptographic protocols

The implementation automatically falls back to HKDF when Blake3 is not available, ensuring compatibility.

## Summary

Blake3 KDF provides a modern, fast, and secure way to derive cryptographic keys. Its performance advantages make it ideal for high-throughput applications, while its simple API reduces the chance of implementation errors. Use it for all non-password key derivation needs where legacy compatibility isn't required.