Encryption model
.rkvey v5 format: preamble, per-compartment AEAD, append-only commits, and secret isolation.
The .rkvey v5 (Rust Key Vault) format implements a layered encryption model, inspired by HKDF and AEAD best practices. The mental model is simple: master password → master key → subkeys → encrypted compartments.
Each entry is split into compartments (metadata, protected secrets, manifest, and attachment files), each with its own key derived via HKDF. Decrypting one compartment does not reveal the others.
QubKey v5 encryption model
Master password
User input (UTF-8) — never stored in plaintext
Argon2id
Salt
16 bytes (preamble)
Memory
64 MB
Iterations
3
Parallelism
4
Output
256 bits
Master Key
256 bits · vault root key
HKDF-SHA256
info="hdr"
Header Key
header_key
HKDF-SHA256
info="idx"
Index Key
index_key
HKDF-SHA256
info="compartment"
Compartment Key
compartment_key
Per entry (v5)
HKDF(master_key, salt=file∥entry_id, info=kind∥sub_id) → Compartment Key
Encrypted compartments
Key derivation
Derivation transforms your master password into usable cryptographic keys. Argon2id is intentionally costly in time and memory (~500 ms, 64 MB) to slow down attempts to guess the password on a stolen copy of the file. In v5, each entry compartment then receives its own key via HKDF.
User input → Master password (UTF-8)
Argon2id → master_key (256 bits) with random salt
HKDF-SHA256 → index_key for B-Tree
HKDF-SHA256 → compartment_key per entry and compartment kind (metadata, secrets, attachment…)
| Parameter | Value | Description | Default |
|---|---|---|---|
Variant | Argon2id | OWASP-recommended hybrid variant — resistant to GPU and side-channel attacks | — |
Memory | 64 MB | Memory required per derivation — increases hardware cost of parallel attacks | 65536 KB |
Iterations | 3 | Passes over memory — security/performance balance (~500 ms) | — |
Parallelism | 4 | Parallel threads | — |
Output | 32 bytes | Derived key length | — |
Salt | 16 bytes | Random salt stored in preamble | — |
AEAD encryption
AES-256-GCM (default)
- AES-NI hardware support on modern processors
- Nonce: 12 bytes, authentication tag: 16 bytes
- Theoretical limit: ~64 GB encrypted data per key
When to choose it: machines with hardware AES acceleration, standard daily use.
Default cipher on most platforms for optimal performance.
XChaCha20-Poly1305 (optional)
- Extended nonce: 24 bytes (negligible collision probability)
- No hardware dependency — consistent performance on all CPUs
- Recommended for long-lived keys
When to choose it: archived vaults, machines without AES-NI, ChaCha20 preference.
Enabled in vault advanced settings.
File structure
Structure legend (v5):
preamble— magic bytes, format version, Argon2id saltheader.enc— encrypted vault metadata (name, creation date, settings)index/— encrypted B-Tree for O(log n) search without decrypting secretscompartments/— AEAD blocks by kind: metadata, protected secrets, manifest, attachment filesappend/— commit region: new compartments + index snapshot + validated footer
Integrity and commits
Resilience
Append-only commits guarantee integrity on interruption:
- New compartments are appended at the end of the file
- An encrypted index snapshot is written
- Data is synced to disk (fsync)
- A validated footer finalizes the commit (consistency point)
Real scenario: you edit an entry and power is cut during the write. On restart, QubKey finds the latest valid footer — no data lost, no silent corruption. Periodic compaction rewrites a clean file when too much obsolete space accumulates.
Per-compartment isolation
Via HKDF-SHA256, each compartment receives a unique compartment_key, derived from the master key with the entry identifier and compartment kind. Practical consequences:
- Viewing an entry decrypts metadata only; secrets stay masked until an explicit reveal
- Attachments are loaded one at a time (download / preview), not when the vault opens
- The B-Tree index uses its own
index_key, separate from data - Changing a secret does not necessarily rewrite unchanged attachment files
This isolation is built natively into the .rkvey v5 format.
Cryptographic primitives
| Primitive | Usage | Library |
|---|---|---|
| Argon2id | Password → key derivation | argon2 (RustCrypto) |
| HKDF-SHA256 | Key → subkeys derivation | hkdf (RustCrypto) |
| AES-256-GCM | AEAD encryption | aes-gcm (RustCrypto) |
| XChaCha20-Poly1305 | AEAD encryption (alt) | chacha20poly1305 (RustCrypto) |
| HMAC-SHA256 | File integrity | hmac (RustCrypto) |
| CSPRNG | Random generation | getrandom (OS) |