Deep dive into Burning Ash Protocol's encryption architecture — AES-256-GCM, envelope encryption, and key management.

Encryption

Burning Ash Protocol uses military-grade encryption to ensure your documents remain secure. This page explains the encryption architecture in detail.

Overview

BAP employs a layered encryption approach:

AES-256-GCM for symmetric encryption of all data
Envelope encryption for key management
Shamir's Secret Sharing for distributing decryption capability

Encryption Architecture

Key Hierarchy

┌─────────────────────────────────────────────────────────────┐
│                   Master Key (env/config)                    │
│                         (256-bit)                            │
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│            Key Encryption Key (KEK) - per host              │
│         Derived via HKDF(master_key, host_id)              │
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│           Data Encryption Key (DEK) - per will              │
│                     (256-bit AES)                          │
│         Encrypted by KEK, stored in database               │
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│                   Document Encryption                       │
│    Each document encrypted with DEK + unique nonce          │
└─────────────────────────────────────────────────────────────┘

AES-256-GCM

BAP uses AES-256-GCM (Galois/Counter Mode) for all symmetric encryption:

256-bit key — Strongest AES variant
Authenticated encryption — Detects tampering
Unique nonces — Each encryption uses a random 12-byte nonce
No ciphertext expansion — Only 12 bytes overhead (the nonce)

Why GCM?

Mode	Authentication	Performance	Notes
GCM	✅ Built-in	Fast	Recommended for authenticated encryption
CBC	❌ Separate MAC	Fast	Requires separate authentication
CTR	❌ Separate MAC	Fast	Requires separate authentication
ECB	❌ None	Fast	Never use for multiple blocks

GCM provides both encryption and integrity verification in one operation, making it ideal for BAP's use case.

Envelope Encryption

Envelope encryption is a technique where:

A Data Encryption Key (DEK) encrypts documents directly
The DEK is encrypted (wrapped) by the Key Encryption Key (KEK)
Only the encrypted DEK is stored in the database

Benefits

Key rotation — Rotating the master key only requires re-encrypting DEKs, not all documents
Key isolation — Each will has its own DEK
Performance — DEK is small; documents are encrypted directly

Implementation

// Generate DEK
dek := make([]byte, 32)
rand.Read(dek)

// Encrypt DEK with KEK
dekEncrypted, nonce := crypto.Encrypt(dek, kek)

// Store dekEncrypted in database

Document Encryption

File Format

Each encrypted file has a specific format:

┌─────────────────────────────────────────────────────────────┐
│                    Magic Number (2 bytes)                   │
│                         0xBA 0x50                          │
├─────────────────────────────────────────────────────────────┤
│                    Format Version (1 byte)                  │
│                          0x01                              │
├─────────────────────────────────────────────────────────────┤
│                   Algorithm (1 byte)                       │
│                     0x01 = AES-256-GCM                     │
├─────────────────────────────────────────────────────────────┤
│              Original File Size (4 bytes)                  │
│                    Big-endian uint32                       │
├─────────────────────────────────────────────────────────────┤
│                    Nonce (12 bytes)                        │
│                     Random per file                         │
├─────────────────────────────────────────────────────────────┤
│                    Ciphertext + Tag                        │
│               (variable length, 16-byte tag)                 │
└─────────────────────────────────────────────────────────────┘

Streaming Encryption

For large files, BAP uses chunked encryption:

Files are encrypted in 1MB chunks
Each chunk has its own nonce
Each chunk is independently verifiable
Memory usage stays constant regardless of file size

This is implemented using the minio/sio library, which uses the DARE format.

Storage Provider Considerations

Provider	Upload As	Notes
Google Drive	application/octet-stream	Prevents thumbnail generation
Dropbox	application/octet-stream	Prevents content hashing
S3	application/octet-stream	Best practice
FTP/SFTP	Binary	Raw transfer

Key Derivation

HKDF

BAP uses HKDF (HMAC-based Key Derivation Function) for deriving keys:

// Derive host-specific KEK
kek := hkdf.SHA256(
    []byte(masterKey),
    []byte(hostID),
    "bap-kek",
)

Benefits

No master key exposure — Even with host data, master key can't be derived
Isolation — Compromise of one host's data doesn't affect others
Deterministic — Same inputs always produce same outputs

After encryption:

The DEK is split into N shares (one per survivor)
Each share is encrypted with the corresponding survivor's key
Only the encrypted shares are stored

See Shamir's Secret Sharing for details.

Key Management

Master Key

The master key is set via environment variable:

MASTER_KEY=0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef

Requirements:

64 hex characters (32 bytes)
Generated securely: openssl rand -hex 32

Key Rotation

To rotate the master key without re-encrypting documents:

# For each will:
1. Decrypt DEK with old master key
2. Re-encrypt DEK with new master key
3. Update database

Documents don't change — only the encrypted DEK wrappers in the database.

Key Storage

Master key — Environment variable or secret manager (never in code)
DEK — Encrypted with KEK, stored in database
SSS shares — Encrypted per-survivor, stored in database

Security Properties

What We Protect Against

Threat	Protection
Storage provider breach	Documents are encrypted before upload
Database breach	DEKs are encrypted; documents can't be read
Single survivor malice	Threshold requires multiple survivors
Server memory dump	Shares held only during active transfer
Document tampering	GCM authentication detects changes

What We Can't Protect Against

Threat	Mitigation
Master key loss	No recovery; data is lost
SSS share loss	Survivors need threshold shares; backup codes help
Physical access to running server	Minimize attack surface
Phishing	User education; verify URLs

Cryptographic Libraries

BAP uses:

Go crypto libraries — Built-in AES-GCM, HKDF
hashicorp/vault/shamir — Shamir's Secret Sharing
minio/sio — Streaming encryption for large files

Verification

Documents include SHA-256 hashes for tamper detection:

sha256(original_document) → stored in database
sha256(decrypted_document) → compared at access time

If hashes don't match, survivors are warned but access is still provided.

Compliance

BAP's encryption supports compliance with:

GDPR — Data is encrypted; deletion = crypto-shredding
SOC 2 — Encryption at rest
HIPAA — Appropriate safeguard level

Next Steps

Shamir's Secret Sharing — Threshold-based key distribution
How It Works — Complete system flow
Security Reporting — Report vulnerabilities

Encryption

On this page