armdb 0.15.0

sharded bitcask key-value storage optimized for NVMe
Documentation
//! Per-session AES-256-GCM key domains for the transaction log.
//!
//! Every encrypted open draws a fresh epoch. Its HKDF-derived key uses the
//! record's `tx_id`, zero-padded to 12 bytes, as the nonce. Recovery resolves
//! each record's stored epoch. Copy-forward seals under the current epoch:
//! across sessions the ciphertext changes, while repeated copy-forward in one
//! session reproduces identical bytes for the same immutable transaction.

use std::collections::BTreeMap;
use std::sync::Arc;

use ring::aead::{self, AES_256_GCM, Aad, LessSafeKey, Nonce, UnboundKey};
use ring::hkdf::{HKDF_SHA256, Prk, Salt};
use ring::rand::{SecureRandom, SystemRandom};

use crate::crypto::EncryptionContext;
use crate::error::{DbError, DbResult};
use crate::sync::Mutex;

struct EpochKey {
    key: LessSafeKey,
    #[cfg(any(test, feature = "test-faults"))]
    key_fp: [u8; 16],
}

pub(crate) struct LogKeys {
    prk: Prk,
    context: [u8; 256],
    epoch: [u8; 16],
    /// The session key needs no lock, so concurrent commits seal in parallel.
    current: EpochKey,
    /// Keys of earlier epochs met while reading, derived once each.
    others: Mutex<BTreeMap<[u8; 16], Arc<EpochKey>>>,
}

impl LogKeys {
    pub(crate) fn open_log(
        master: &[u8; 32],
        salt: &[u8; 16],
        context: Option<&EncryptionContext>,
    ) -> DbResult<Self> {
        let mut encoded = [0; 256];
        if let Some(context) = context {
            let bytes = context.as_bytes();
            encoded[0] = bytes.len() as u8;
            encoded[1..1 + bytes.len()].copy_from_slice(bytes);
        }
        let mut epoch = [0; 16];
        SystemRandom::new()
            .fill(&mut epoch)
            .map_err(|_| DbError::EncryptionError("failed to generate txlog epoch".into()))?;
        let prk = Salt::new(HKDF_SHA256, salt).extract(master);
        let current = derive(&prk, &encoded, &epoch)?;
        Ok(Self {
            prk,
            context: encoded,
            epoch,
            current,
            others: Mutex::new(BTreeMap::new()),
        })
    }

    pub(crate) fn epoch(&self) -> [u8; 16] {
        self.epoch
    }

    /// Seal under this session's epoch, authenticating the header and epoch.
    pub(crate) fn seal(&self, tx_id: u64, aad: &[u8], plaintext: &[u8]) -> DbResult<Vec<u8>> {
        let cipher = &self.current;
        #[cfg(any(test, feature = "test-faults"))]
        crate::crypto::seal_log::record(cipher.key_fp, *nonce_for(tx_id).as_ref(), plaintext);
        let mut buf = plaintext.to_vec();
        let tag = cipher
            .key
            .seal_in_place_separate_tag(nonce_for(tx_id), Aad::from(aad), &mut buf)
            .map_err(|_| DbError::EncryptionError("txlog record encryption failed".into()))?;
        buf.extend_from_slice(tag.as_ref());
        Ok(buf)
    }

    pub(crate) fn open(
        &self,
        epoch: &[u8; 16],
        tx_id: u64,
        aad: &[u8],
        sealed: &[u8],
    ) -> DbResult<Vec<u8>> {
        let other;
        let cipher = if *epoch == self.epoch {
            &self.current
        } else {
            // Resolve under the lock, decrypt after releasing it.
            other = {
                let mut others = crate::sync::lock(&self.others);
                match others.get(epoch) {
                    Some(key) => key.clone(),
                    None => {
                        let key = Arc::new(derive(&self.prk, &self.context, epoch)?);
                        others.insert(*epoch, key.clone());
                        key
                    }
                }
            };
            other.as_ref()
        };
        let mut buf = sealed.to_vec();
        let plaintext = cipher
            .key
            .open_in_place(nonce_for(tx_id), Aad::from(aad), &mut buf)
            .map_err(|_| {
                DbError::EncryptionError(format!(
                    "txlog record {tx_id}: decryption/authentication failed"
                ))
            })?;
        let len = plaintext.len();
        buf.truncate(len);
        Ok(buf)
    }
}

fn derive(prk: &Prk, context: &[u8; 256], epoch: &[u8; 16]) -> DbResult<EpochKey> {
    let info: [&[u8]; 3] = [
        b"armdb-txlog-v2",
        &context[..1 + usize::from(context[0])],
        epoch,
    ];
    let okm = prk
        .expand(&info, HKDF_SHA256)
        .map_err(|_| DbError::EncryptionError("txlog hkdf expand failed".into()))?;
    let mut key = [0; 32];
    okm.fill(&mut key)
        .map_err(|_| DbError::EncryptionError("txlog hkdf fill failed".into()))?;
    #[cfg(any(test, feature = "test-faults"))]
    let key_fp = ring::digest::digest(&ring::digest::SHA256, &key).as_ref()[..16]
        .try_into()
        .expect("SHA256 prefix");
    let unbound = UnboundKey::new(&AES_256_GCM, &key)
        .map_err(|_| DbError::EncryptionError("invalid txlog key".into()))?;
    Ok(EpochKey {
        key: LessSafeKey::new(unbound),
        #[cfg(any(test, feature = "test-faults"))]
        key_fp,
    })
}

fn nonce_for(tx_id: u64) -> Nonce {
    let mut bytes = [0; aead::NONCE_LEN];
    bytes[..8].copy_from_slice(&tx_id.to_le_bytes());
    Nonce::assume_unique_for_key(bytes)
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn txlog_epoch_cipher_rejects_wrong_key_salt_context_tx_id_and_aad() {
        let c = LogKeys::open_log(&[0x11; 32], &[0x22; 16], None).unwrap();
        let sealed = c.seal(7, b"header", b"payload").unwrap();
        assert_eq!(
            c.open(&c.epoch(), 7, b"header", &sealed).unwrap(),
            b"payload"
        );
        assert!(c.open(&c.epoch(), 8, b"header", &sealed).is_err());
        assert!(c.open(&c.epoch(), 7, b"other", &sealed).is_err());
        let ctx = EncryptionContext::new(b"tenant").unwrap();
        for (key, salt, context) in [
            ([0x33; 32], [0x22; 16], None),
            ([0x11; 32], [0x44; 16], None),
            ([0x11; 32], [0x22; 16], Some(&ctx)),
        ] {
            let other = LogKeys::open_log(&key, &salt, context).unwrap();
            assert!(other.open(&c.epoch(), 7, b"header", &sealed).is_err());
        }
        assert_eq!(c.seal(7, b"header", b"payload").unwrap(), sealed);
    }

    #[test]
    fn txlog_epoch_cipher_opens_records_of_an_earlier_epoch() {
        let old = LogKeys::open_log(&[0x11; 32], &[0x22; 16], None).unwrap();
        let sealed = old.seal(3, b"header", b"payload").unwrap();
        let new = LogKeys::open_log(&[0x11; 32], &[0x22; 16], None).unwrap();
        assert_ne!(old.epoch(), new.epoch());
        // First lookup derives the foreign key, the second reuses the cached one.
        for _ in 0..2 {
            assert_eq!(
                new.open(&old.epoch(), 3, b"header", &sealed).unwrap(),
                b"payload"
            );
        }
        assert_eq!(crate::sync::lock(&new.others).len(), 1);
        assert!(new.open(&new.epoch(), 3, b"header", &sealed).is_err());
    }
}