Files
qbz/crates/qbz-secrets/src/cipher.rs
T
vicrodh 1743c9e5ec feat(secrets): add qbz-secrets crate for device-bound secret wrapping
Foundation for the offline-cache hardening story. The offline cache
needs to persist per-track AES content keys to disk, but storing them
plaintext would make copying the SQLite DB enough to decrypt the
cached audio on another machine.

qbz-secrets provides a uniform wrap/unwrap API backed by:

1. **OS keyring** (preferred): libsecret/gnome-keyring on Linux,
   Keychain on macOS, DPAPI on Windows. A 256-bit master AES key
   lives inside the OS secure store; all wraps go through it. This
   is the gold-standard device binding used by commercial music
   apps (Spotify, Apple Music, Tidal) for the same class of data.

2. **HKDF fallback**: when the OS keyring is not reachable (headless
   setups — Raspberry Pi, Docker, the future qbzd daemon on a
   server), the master key is derived on demand via HKDF-SHA256
   over service_name + machine_id + a persistent per-install UUID.
   Weaker than keyring (reversible by anyone with filesystem access
   to both sources) but still device-bound against cross-machine
   copy attacks, and lets daemon/headless variants work at all.

Every wrap uses AES-256-GCM with a fresh random 12-byte nonce. The
on-disk envelope carries a version byte + backend marker + nonce +
ciphertext+tag, so (a) we detect tampering via GCM, (b) we refuse to
silently unwrap a blob produced by a backend we can't reach, and (c)
we have a forward-compat path for future key rotation.

4 unit tests cover: small-secret round-trip, 16-byte content-key
round-trip (the exact CMAF use case), GCM tamper detection, and
nonce-randomness (two wraps of the same input differ).

This crate intentionally has zero QBZ dependencies — it's a generic
primitive. Next commits wire it into the offline cache schema + the
DB migration.

cc
2026-04-17 00:53:01 -06:00

43 lines
1.3 KiB
Rust

//! AES-256-GCM authenticated encryption primitive shared by both backends.
use aes_gcm::aead::{Aead, KeyInit};
use aes_gcm::{Aes256Gcm, Key, Nonce};
use rand::RngCore;
use crate::envelope::{WrappedSecret, NONCE_LEN};
use crate::error::SecretError;
pub(crate) fn wrap_with_key(
key: &[u8; 32],
backend_marker: u8,
plaintext: &[u8],
) -> Result<Vec<u8>, SecretError> {
let cipher = Aes256Gcm::new(Key::<Aes256Gcm>::from_slice(key));
let mut nonce_bytes = [0u8; NONCE_LEN];
rand::rng().fill_bytes(&mut nonce_bytes);
let nonce = Nonce::from_slice(&nonce_bytes);
let ciphertext = cipher
.encrypt(nonce, plaintext)
.map_err(|e| SecretError::Cipher(e.to_string()))?;
Ok(WrappedSecret::build(backend_marker, &nonce_bytes, &ciphertext))
}
pub(crate) fn unwrap_with_key(
key: &[u8; 32],
expected_marker: u8,
wrapped: &[u8],
) -> Result<Vec<u8>, SecretError> {
let parsed = WrappedSecret::parse(wrapped)?;
if parsed.backend_marker != expected_marker {
return Err(SecretError::BackendMismatch);
}
let cipher = Aes256Gcm::new(Key::<Aes256Gcm>::from_slice(key));
let nonce = Nonce::from_slice(parsed.nonce);
cipher
.decrypt(nonce, parsed.ciphertext)
.map_err(|e| SecretError::Cipher(e.to_string()))
}