Vauchi DocsCrypto Key Hierarchy
Visual documentation of Vauchi's cryptographic key hierarchy and derivation paths.
Master Hierarchy
┌────────────────────────────────────┐
│ Identity Creation │
│ │
│ │
│ ┌────────────────────────────────┐ │
│ │ │ │
│ │ │ │
│ │ Master Seed ├─┼───────────────────HKDF────────────┬──────────┐
│ │ (256-bit, CSPRNG) │ │ info='Vauchi_Exchange_Seed_v2' │
│ │ │ │ │ │
│ └────────────────┬───────────────┘ │ └──────────┼─────────────────────────HKDF─────────────────────────────────────┐
│ │ │ │ info='Vauchi_Shred_Key_v2' │
└──────────────────┼─────────────────┘ │ │
raw seed │ │
(Ed25519 requirement) │ │
│ │ │
┌──────────────────┼─────────────────┐ ┌────────────┼────────────┐ ┌───────────────────┼───────────────────────────────────────────────────────────────────────────────────┐
│ Signing│Keys │ │ Exchange Keys │ │ │ Shredding Hierarchy │
│ │ │ │ │ │ │ │ │
│ ▼ │ │ ▼ │ │ ▼ │
│ ┌────────────────────────────────┐ │ │ ┌─────────────────────┐ │ │ ┌───────────────────────────────────┐ │
│ │ │ │ │ │ │ │ │ │ │ │
│ │ │ │ │ │ │ │ │ │ │ │
│ │ Identity Signing Key │ │ │ │ Exchange Secret Key │ │ │ │ SMK ├──────────────────────HKDF───────────────────────┐ │
│ │ (Ed25519 secret) │ │ │ │ (X25519) │ │ │ │ (Shredding Master Key) │ info='Vauchi_FileKey_Key_v2' │ │
│ │ │ │ │ │ │ │ │ │ │ │ │
│ └────────────────┬───────────────┘ │ │ └──────────┬──────────┘ │ │ └─────────────────┬─────────────────┘ │ │
│ │ │ │ │ │ │ │ │ │
│ │ │ │ │ │ │ HKDF │ │
│ │ │ │ │ │ │ info='Vauchi_Storage_Key_v2' │ │
│ │ │ │ │ │ │ │ │ │
│ ▼ │ │ ▼ │ │ ▼ ▼ │
│ ┌────────────────────────────────┐ │ │ ┌─────────────────────┐ │ │ ┌───────────────────────────────────┐ ┌───────────────────────────┐ │
│ │ │ │ │ │ │ │ │ │ │ │ │ │
│ │ │ │ │ │ │ │ │ │ │ │ │ │
│ │ Identity Public Key │ │ │ │ Exchange Public Key │ │ ┌┄┄┤ SEK │ │ FKEK │ │
│ │ (Ed25519 public) │ │ │ │ (X25519) │ │ ┆│ │ (Storage Encryption Key) │ │ (File Key Encryption Key) │ │
│ │ │ │ │ │ │ │ ┆│ │ │ │ │ │
│ └────────────────────────────────┘ │ │ └─────────────────────┘ │ ┆│ └─────────────────┬─────────────────┘ └───────────────────────────┘ │
│ │ │ │ ┆│ ┆ │
└────────────────────────────────────┘ └─────────────────────────┘ ┆└───────────────────┆───────────────────────────────────────────────────────────────────────────────────┘
┆ encrypts
┆ ┆
┌┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┌┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┘ ┆
┌──────────────encrypts─────────────────────────────────────────────────────────encrypts───────────────────────────────────────────────────────────────┆───────────────────┐
│ ┆ Per-Contact Keys ┆ │
│ ┆ ┆ ┆ │
│ ▼ ▼ ▼ │
│ ┌────────────────────────────────┐ ┌─────────────────────┐ ┌───────────────────────────────────┐ │
│ │ │ │ │ │ │ │
│ │ │ │ │ │ │ │
│ │ CEK (Contact 1) │ │ CEK (Contact 2) │ │ CEK (Contact N) │ │
│ │ random 256-bit │ │ random 256-bit │ │ random 256-bit │ │
│ │ │ │ │ │ │ │
│ └────────────────────────────────┘ └─────────────────────┘ └───────────────────────────────────┘ │
│ │
└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
Key Derivation Details
HKDF Convention
All HKDF derivations use standard RFC 5869 (documented as "DP-5"):
HKDF-SHA256:
- salt: None (zeros per RFC 5869 §2.2)
- ikm: master_seed (32 bytes, high-entropy input)
- info: domain string (e.g., "Vauchi_Exchange_Seed_v2")
- output: 32 bytes
This follows standard HKDF convention: high-entropy seed as IKM, no salt needed.
Key Sizes
| Key | Size | Algorithm |
|---|---|---|
| Master Seed | 256 bits | CSPRNG |
| Identity Signing | 32+64 bytes | Ed25519 (seed+keypair) |
| Exchange | 32 bytes | X25519 |
| SMK | 256 bits | HKDF-SHA256 |
| SEK | 256 bits | HKDF-SHA256 |
| FKEK | 256 bits | HKDF-SHA256 |
| CEK | 256 bits | CSPRNG |
Double Ratchet Key Hierarchy
┌────────────────────────────────┐
│ Initial Key Agreement (X3DH) │
│ │
│ │
│ ┌────────────────────────────┐ │
│ │ │ │
│ │ │ │
│ │ X3DH Shared Secret │ │
│ │ (32 bytes) │ │
│ │ │ │
│ └──────────────┬─────────────┘ │
│ │ │
└────────────────┼───────────────┘
HKDF
init
│
┌────────────────┼───────────────────────────────────────────────────────────────────────────────┐
│ │ Root Chain │
│ │ │
│ ▼ │
│ ┌────────────────────────────┐ │
│ │ │ │
│ │ Root Key 0 │ │
│ │ │ │
│ └──────────────┬─────────────┘ │
│ │ │
│ │ │
│ │ │
│ │ │
│ │ │
│ │ │
│ │ │
│ │ │
│ ▼ │
│ ┌────────────────────────────┐ │
│ │ │ │
│ │ DH(our_secret × their_pub) ├─────────────────┐ │
│ │ │ │ │
│ └──────────────┬─────────────┘ │ │
│ │ HKDF │
│ │ │ │
│ HKDF │ │
│ │ │ │
│ │ │ │
│ │ │ │
│ │ │ │
│ │ │ │
│ ▼ ▼ │
│ ┌────────────────────────────┐ ┌─────────────────────┐ │
│ │ │ │ │ │
│ │ Root Key 1 ├───┬──┤ Send Chain Key 0 │ │
│ │ │ │ │ │ │
│ └────────────────────────────┘ │ └──────────┬──────────┘ │
│ │ │ │
│ │ HKDF │
│ HKDF────────────────┴──────CHAIN_KEY_INFO─────────────────────────┐ │
│ MESSAGE_KEY_INFO │ │ │
│ ▼ ▼ ▼ │
│ ┌────────────────────────────┐ ┌─────────────────────┐ ┌────────────────────────────┐ │
│ │ │ │ │ │ │ │
│ │ Message Key 0 │ ┌──┤ Send Chain Key 1 │ ┌──┤ DH(our_secret × their_pub) │ │
│ │ │ │ │ │ │ │ │ │
│ └────────────────────────────┘ │ └─────────────────────┘ │ └──────────────┬─────────────┘ │
│ │ │ │ │
│ │ │ │ │
│ │ │ HKDF │
│ │ │ │ │
│ ┌─────────────────┘ ┌─────────────┘ │ │
│ HKDF HKDF │ │
│ │ │ │ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌────────────────────────────┐ ┌─────────────────────┐ ┌────────────────────────────┐ │
│ │ │ │ │ │ │ │
│ │ Message Key 1 │ │ Root Key 2 ├──┬──┤ Recv Chain Key 0 │ │
│ │ │ │ │ │ │ │ │
│ └────────────────────────────┘ └─────────────────────┘ │ └────────────────────────────┘ │
│ │ │
│ │ │
│ HKDF────────────────────────────HKDF────────────┴─────────────────┐ │
│ MESSAGE_KEY_INFO CHAIN_KEY_INFO │ │
│ ▼ ▼ ▼ │
│ ┌────────────────────────────┐ ┌─────────────────────┐ ┌────────────────────────────┐ │
│ │ │ │ │ │ │ │
│ │ Message Key 0 │ │ Recv Chain Key 1 │ │ Root Key N │ │
│ │ │ │ │ │ │ │
│ └────────────────────────────┘ └──────────┬──────────┘ └────────────────────────────┘ │
│ │ │
└────────────────────────────────────────────────┼───────────────────────────────────────────────┘
│
┌────────────────────────────────────────────────┼───────────────────────────────────────────────┐
│ Receive│Chain │
│ ┌────────────────────────────┐ │ │
│ │ │ │ │
│ │ Message Key 1 │◄─────HKDF───────┘ │
│ │ │ │
│ └────────────────────────────┘ │
│ │
└────────────────────────────────────────────────────────────────────────────────────────────────┘
Device Key Derivation
┌───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ Master Identity │
│ │
│ │
│ ┌────────────────────────────┐ │
│ │ │ │
│ │ Master Seed │ │
│ │ │ │
│ └────────────────────────────┘ │
│ │ │
│ │ │
│ ├────────────────────────────┬─────────────────────────────────────────────────┐ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌────────────────────────────┐ ┌────────────────┐ ┌───────────────────────────────────────────┐ │
│ │ │ │ │ │ │ │
│ │ │ │ │ │ │ │
│ │ Device Index 0 ├──┐ │ Device Index 1 ├──┐ │ Device Index 2├─────┐ │ │
│ │ (Primary) │ │ │ │ │ │ │ │ │
│ │ │ │ │ │ │ │ │ │ │
│ └──────────────┬─────────────┘ │ └────────────────┘ │ └───────────────────────────────────┴───────┴─┼─────HKDF(seed,─device_index=2)────────────────┬──────────────────────┐
│ │ │ │ │ │ │
└────────────────┼────────────────┼──────────────────────┼──────────────────────────────────────────────────────────────┘ │ │
HKDF(seed, device_index=0) │ │ │ │
│ │ │ │ │
│ └───────────┐ └─────HKDF(seed,─device_index=1)───────┬──────────────────────┐ │ │
┌────────────────┼────────────────────────────┼─────────┐ ┌───────────────────────┼──────────────────────┼─────────┐ ┌─────────┼──────────────────────┼─────────┐
│ │ Device 0 Keys │ │ │ Device 1 Keys │ │ │ │ Device 2 Keys │ │
│ │ │ │ │ │ │ │ │ │ │ │
│ ▼ ▼ │ │ ▼ ▼ │ │ ▼ ▼ │
│ ┌────────────────────────────┐ ┌────────────────┐ │ │ ┌───────────────────────────────────┬───────┬────────┐ │ │ ┌───────────────┐ ┌────────────────┐ │
│ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │
│ │ Signing Key 0 │ │ Exchange Key 0 │ │ │ │ Signing Key 1 │ Exchange Key 1 │ │ │ │ Signing Key 2 │ │ Exchange Key 2 │ │
│ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │
│ └────────────────────────────┘ └────────────────┘ │ │ └───────────────────────────────────┴───────┴────────┘ │ │ └───────────────┘ └────────────────┘ │
│ │ │ │ │ │
└───────────────────────────────────────────────────────┘ └────────────────────────────────────────────────────────┘ └──────────────────────────────────────────┘
Crypto-Shredding Paths
┌───────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ Destruction Targets │
│ │
│ │
│ ┌───────────────────────────────┐ ┌───────────────────────────┐ ┌───────────────────────────┐ │
│ │ │ │ │ │ │ │
│ │ Destroy Seed │ │ Destroy SMK │ │ Destroy CEK │ │
│ │ │ │ │ │ │ │
│ └───────────────┬───────────────┘ └─────────────┬─────────────┘ └─────────────┬─────────────┘ │
│ │ │ │ │
└─────────────────┼───────────────────────────────────┼─────────────────────────────────┼───────────────┘
Complete identity destruction Storage shredding Per-contact shredding
│ │ │
│ │ │
┌─────────────────┼───────────────────────────────────┼─────────────────────────────────┼───────────────┐
│ │ Effect │ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌───────────────────────────────┐ ┌───────────────────────────┐ ┌───────────────────────────┐ │
│ │ │ │ │ │ │ │
│ │ All data unreadable │ │ All local data unreadable │ │ Single contact unreadable │ │
│ │ │ │ │ │ │ │
│ └───────────────────────────────┘ └───────────────────────────┘ └───────────────────────────┘ │
│ │
└───────────────────────────────────────────────────────────────────────────────────────────────────────┘
Key Storage Locations
┌───────────────────────┬────────────────────────────────────────┐ ┌────────────────────────┐
│ Platform Keychain │ Memory Only │ │ SQLite Database │
│ │ │ │ │
│ │ │ │ │
│ ┌───────────────────┐ │ ┌───────────────────────┐ │ │ ┌────────────────────┐ │
│ │ │ │ │ │ │ │ │ │ │
│ │ │ │ │ │ │ │ │ │ │
│ │ SMK ├derive─on─boot─►│ SEK (derived at boot) │ │ ├─────encrypt/decrypt───┼►│ Data encrypted │ │
│ │ (encrypted) │ │ │ │ │ │ │ with SEK │ │
│ │ │ │ │ │ │ │ │ │ │
│ └───────────────────┘ │ └───────────┬───────────┘ │ │ └────────────────────┘ │
│ │ │ │ │ │
├───────────────────────┘ │ │ │ │
│ │ │ │ │
│ │ │ │ │
│ │ │ │ │
│ ┌───────────────────┐ │ │ │ ┌────────────────────┐ │
│ │ │ │ │ │ │ │ │
│ │ │ │ │ │ │ │ │
│ │ Message keys ├────────┐ ├─────────────┼─encrypt/decrypt─────────────┼►│ CEK encrypted │ │
│ │ (single use) │ │ │ │ │ │ with SEK │ │
│ │ │ │ │ │ │ │ │ │
│ └─delete─after─use──┘ │ │ │ │ └────────────────────┘ │
│ ▲ │ │ │ │ │
│ │ │ │ │ │ │
│ ├──────────────────┘ │ │ │ │
│ derive │ │ │ │
│ │ │ │ │ │
│ ┌─────────┴─────────┐ │ │ │ ┌────────────────────┐ │
│ │ │ │ │ │ │ │ │
│ │ │ │ │ │ │ │ │
│ │ Active chain keys │ └─────────────┼─encrypt/decrypt─────────────┼►│ Ratchet state │ │
│ │ │ │ │ │ encrypted with SEK │ │
│ │ │ │ │ │ │ │
│ └───────────────────┘ │ │ └────────────────────┘ │
│ │ │ │
└────────────────────────────────────────────────────────────────┘ └────────────────────────┘
Backup Key Derivation
┌────────────────────────────────────────────┐ ┌───────────────────────────────────────────────────────────────────────────────┐
│ User Input │ │ Backup Contents │
│ │ │ │
│ │ │ │
│ ┌────────────────────┐ ┌─────────────┐ │ │ ┌──────────────┐ ┌─────────────┐ ┌──────────────┐ ┌─────────────┐ │
│ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │
│ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │
│ │ Password │ │ Random Salt │ │ │ │ Display Name │ │ Master Seed │ │ Device Index │ │ Device Name │ │
│ │ │ │ (16 bytes) │ │ │ │ │ │ │ │ │ │ │ │
│ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │
│ └──────────┬─────────┘ └──────┬──────┘ │ │ └───────┬──────┘ └──────┬──────┘ └───────┬──────┘ └──────┬──────┘ │
│ │ │ │ │ │ │ │ │ │
└────────────┼──────────────────────┼────────┘ └─────────┼───────────────────┼────────────────────┼───────────────────┼────────┘
│ │ │ │ │ │
│ │ │ │ │ │
│ │ │ │ │ │
┌────────────┼───────────┐ │ │ │ │ │
│ Key Derivation │ │ │ │ │ │
│ │ │ │ │ │ │ │
│ ▼ │ │ │ │ │ │
│ ┌────────────────────┐ │ │ │ │ │ │
│ │ │ │ │ │ │ │ │
│ │ │ │ │ │ │ │ │
│ │ Argon2id │◄┼──────────┘ │ │ │ │
│ │ m=64MB, t=3, p=4 │ │ │ │ │ │
│ │ │ │ │ │ │ │
│ └──────────┬─────────┘ │ │ │ │ │
│ │ │ │ │ │ │
└────────────┼───────────┘ │ │ │ │
│ │ │ │ │
│ │ │ │ │
│ │ │ │ │
┌────────────┼───────────┐ │ │ │ │
│ Output │ │ │ │ │
│ │ │ │ │ │ │
│ ▼ │ │ │ │ │
│ ┌────────────────────┐ │ │ │ │ │
│ │ │ │ │ │ │ │
│ │ │ │ │ │ │ │
│ │ Backup Key │ │ ┌───────┘ ┌──────┘ ┌───────┘ ┌──────┘
│ │ (256 bits) │ │ │ │ │ │
│ │ │ │ │ │ │ │
│ └──────────┬─────────┘ │ │ │ │ │
│ │ │ │ │ │ │
│ XChaCha20-Poly1305 │ │ │ │ │
│ │ │ │ │ │ │
│ │ │ │ │ │ │
│ ▼ │ │ │ │ │
│ ┌────────────────────┐ │ │ │ │ │
│ │ │ │ │ │ │ │
│ │ Encrypted Backup │◄┼───────────────────────┴────────────────────┴───────────────────┴────────────────────┘
│ │ │ │
│ └────────────────────┘ │
│ │
└────────────────────────┘
Security Properties by Key
| Key | Fwd Secrecy | Break-in Rec. | Zeroized |
|---|---|---|---|
| Master Seed | N/A | No | Yes |
| Identity Signing | No | No | Yes |
| Exchange Key | No | No | Yes |
| SMK | No | No | Yes |
| SEK | No | No | Yes (mem) |
| CEK | Per-contact | N/A | Yes |
| Root Key | Via DH ratchet | Yes | Yes |
| Chain Key | Via sym ratchet | N/A | Yes |
| Message Key | Single-use | N/A | Yes |
Related Documentation
- Crypto Reference — Algorithm details
- Architecture Overview — System design
- Message Delivery Flow — Ratchet in action