use crate::crypto::{NONCE_LEN, SALT_LEN, TAG_LEN};
use crate::error::{MnemoError, Result};
pub const MAGIC: &[u8; 4] = b"MNEM";
pub const VERSION: u16 = 8;
pub const VERSION_V9: u16 = 9;
pub const DEFAULT_NEW_VERSION: u16 = VERSION_V9;
pub const MAX_VERSION: u16 = VERSION_V9;
pub const MIGRATABLE_FROM: u16 = 4;
pub const PAGE_SIZE: usize = 8192;
pub const PAYLOAD: usize = PAGE_SIZE - NONCE_LEN - TAG_LEN; pub const WRAPPED_DEK_LEN: usize = 48;
pub const FLAG_ENCRYPTED: u32 = 1;
pub const HEADER_CRC_OFF: usize = 238;
pub const HEADER_SEAL_NONCE_OFF: usize = 242;
pub const HEADER_SEAL_TAG_OFF: usize = HEADER_SEAL_NONCE_OFF + NONCE_LEN;
pub const SEAL_AAD_PREFIX: &[u8] = b"mnemo-header-seal-v7";
pub const HEADER_CACHE_START_OFF: usize = HEADER_SEAL_TAG_OFF + TAG_LEN;
pub const HEADER_CACHE_PAGES_OFF: usize = HEADER_CACHE_START_OFF + 8;
pub const HEADER_CACHE_LEN_OFF: usize = HEADER_CACHE_PAGES_OFF + 8;
const _: () = assert!(HEADER_CACHE_LEN_OFF + 8 <= PAGE_SIZE);
pub const V9_FIELDS_OFF: usize = HEADER_CACHE_LEN_OFF + 8; pub const V9_RESERVED_OFF: usize = V9_FIELDS_OFF + 4 * 8 + 5 * 32; pub const V9_CRC_OFF: usize = 508;
pub const V9_HEADER_LEN: usize = 512;
pub const SEAL_AAD_PREFIX_V9: &[u8] = b"mnemo-header-seal-v9";
const _: () = assert!(V9_FIELDS_OFF == 294);
const _: () = assert!(V9_RESERVED_OFF <= V9_CRC_OFF);
const _: () = assert!(V9_CRC_OFF + 4 == V9_HEADER_LEN);
pub(crate) fn is_zero_u64(v: &u64) -> bool {
*v == 0
}
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
pub struct RunPtr {
pub start: u64,
pub pages: u64,
pub len: u64,
pub gen: u64,
}
impl RunPtr {
pub fn is_empty(&self) -> bool {
self.pages == 0
}
fn write(&self, b: &mut [u8], o: usize) {
b[o..o + 8].copy_from_slice(&self.start.to_le_bytes());
b[o + 8..o + 16].copy_from_slice(&self.pages.to_le_bytes());
b[o + 16..o + 24].copy_from_slice(&self.len.to_le_bytes());
b[o + 24..o + 32].copy_from_slice(&self.gen.to_le_bytes());
}
fn read(b: &[u8], o: usize) -> RunPtr {
RunPtr {
start: rd_u64(b, o),
pages: rd_u64(b, o + 8),
len: rd_u64(b, o + 16),
gen: rd_u64(b, o + 24),
}
}
}
#[derive(Clone, Debug)]
pub struct Header {
pub version: u16,
pub page_size: u32,
pub flags: u32,
pub dimensions: u32,
pub created_at: i64,
pub write_counter: u64,
pub next_page: u64,
pub catalog_start: u64,
pub catalog_pages: u64,
pub catalog_len: u64,
pub vector_count: u64,
pub m_cost: u32,
pub t_cost: u32,
pub p_cost: u32,
pub salt: [u8; SALT_LEN],
pub dek_nonce: [u8; NONCE_LEN],
pub wrapped_dek: [u8; WRAPPED_DEK_LEN],
pub index_start: u64,
pub index_pages: u64,
pub index_len: u64,
pub wal_start: u64,
pub wal_pages: u64,
pub wal_seq: u64,
pub manifest_start: u64,
pub manifest_pages: u64,
pub manifest_len: u64,
pub seal_nonce: Option<[u8; NONCE_LEN]>,
pub seal_tag: Option<[u8; TAG_LEN]>,
pub cache_start: u64,
pub cache_pages: u64,
pub cache_len: u64,
pub catalog_gen: u64,
pub index_gen: u64,
pub manifest_gen: u64,
pub cache_gen: u64,
pub free: RunPtr,
pub keys: RunPtr,
pub bm25: RunPtr,
pub index_delta: RunPtr,
pub catalog_delta: RunPtr,
}
fn header_seal_aad(h: &Header) -> Vec<u8> {
let mut aad = Vec::with_capacity(SEAL_AAD_PREFIX.len() + 2 + 18 * 8);
aad.extend_from_slice(SEAL_AAD_PREFIX);
aad.extend_from_slice(&h.version.to_le_bytes());
aad.extend_from_slice(&h.write_counter.to_le_bytes());
aad.extend_from_slice(&h.next_page.to_le_bytes());
aad.extend_from_slice(&h.catalog_start.to_le_bytes());
aad.extend_from_slice(&h.catalog_pages.to_le_bytes());
aad.extend_from_slice(&h.catalog_len.to_le_bytes());
aad.extend_from_slice(&h.vector_count.to_le_bytes());
aad.extend_from_slice(&h.index_start.to_le_bytes());
aad.extend_from_slice(&h.index_pages.to_le_bytes());
aad.extend_from_slice(&h.index_len.to_le_bytes());
aad.extend_from_slice(&h.wal_start.to_le_bytes());
aad.extend_from_slice(&h.wal_pages.to_le_bytes());
aad.extend_from_slice(&h.wal_seq.to_le_bytes());
aad.extend_from_slice(&h.manifest_start.to_le_bytes());
aad.extend_from_slice(&h.manifest_pages.to_le_bytes());
aad.extend_from_slice(&h.manifest_len.to_le_bytes());
if h.version >= 8 {
aad.extend_from_slice(&h.cache_start.to_le_bytes());
aad.extend_from_slice(&h.cache_pages.to_le_bytes());
aad.extend_from_slice(&h.cache_len.to_le_bytes());
}
aad
}
fn rd_u16(b: &[u8], o: usize) -> u16 {
u16::from_le_bytes(b[o..o + 2].try_into().unwrap())
}
fn rd_u32(b: &[u8], o: usize) -> u32 {
u32::from_le_bytes(b[o..o + 4].try_into().unwrap())
}
fn rd_u64(b: &[u8], o: usize) -> u64 {
u64::from_le_bytes(b[o..o + 8].try_into().unwrap())
}
fn rd_i64(b: &[u8], o: usize) -> i64 {
i64::from_le_bytes(b[o..o + 8].try_into().unwrap())
}
impl Header {
pub fn to_page(&self) -> [u8; PAGE_SIZE] {
let mut b = [0u8; PAGE_SIZE];
b[0..4].copy_from_slice(MAGIC);
b[4..6].copy_from_slice(&self.version.to_le_bytes());
b[6..10].copy_from_slice(&self.page_size.to_le_bytes());
b[10..14].copy_from_slice(&self.flags.to_le_bytes());
b[14..18].copy_from_slice(&self.dimensions.to_le_bytes());
b[18..26].copy_from_slice(&self.created_at.to_le_bytes());
b[26..34].copy_from_slice(&self.write_counter.to_le_bytes());
b[34..42].copy_from_slice(&self.next_page.to_le_bytes());
b[42..50].copy_from_slice(&self.catalog_start.to_le_bytes());
b[50..58].copy_from_slice(&self.catalog_pages.to_le_bytes());
b[58..66].copy_from_slice(&self.catalog_len.to_le_bytes());
b[66..74].copy_from_slice(&self.vector_count.to_le_bytes());
b[74..78].copy_from_slice(&self.m_cost.to_le_bytes());
b[78..82].copy_from_slice(&self.t_cost.to_le_bytes());
b[82..86].copy_from_slice(&self.p_cost.to_le_bytes());
b[86..86 + SALT_LEN].copy_from_slice(&self.salt);
b[102..102 + NONCE_LEN].copy_from_slice(&self.dek_nonce);
b[114..114 + WRAPPED_DEK_LEN].copy_from_slice(&self.wrapped_dek);
b[162..170].copy_from_slice(&self.index_start.to_le_bytes());
b[170..178].copy_from_slice(&self.index_pages.to_le_bytes());
b[178..186].copy_from_slice(&self.index_len.to_le_bytes());
b[186..194].copy_from_slice(&self.wal_start.to_le_bytes());
b[194..202].copy_from_slice(&self.wal_pages.to_le_bytes());
b[202..210].copy_from_slice(&self.wal_seq.to_le_bytes());
b[214..222].copy_from_slice(&self.manifest_start.to_le_bytes());
b[222..230].copy_from_slice(&self.manifest_pages.to_le_bytes());
b[230..238].copy_from_slice(&self.manifest_len.to_le_bytes());
if self.version >= VERSION_V9 {
self.write_v9_tail(&mut b);
return b;
}
let crc = crate::wal::checksum(&b[0..HEADER_CRC_OFF]);
b[HEADER_CRC_OFF..HEADER_CRC_OFF + 4].copy_from_slice(&crc.to_le_bytes());
if self.version >= 8 {
b[HEADER_CACHE_START_OFF..HEADER_CACHE_START_OFF + 8]
.copy_from_slice(&self.cache_start.to_le_bytes());
b[HEADER_CACHE_PAGES_OFF..HEADER_CACHE_PAGES_OFF + 8]
.copy_from_slice(&self.cache_pages.to_le_bytes());
b[HEADER_CACHE_LEN_OFF..HEADER_CACHE_LEN_OFF + 8]
.copy_from_slice(&self.cache_len.to_le_bytes());
}
b
}
pub fn from_page(b: &[u8]) -> Result<Header> {
if b.len() < PAGE_SIZE {
return Err(MnemoError::BadMagic);
}
if &b[0..4] != MAGIC {
return Err(MnemoError::BadMagic);
}
let version = rd_u16(b, 4);
if !(MIGRATABLE_FROM..=MAX_VERSION).contains(&version) {
return Err(MnemoError::UnsupportedVersion(version));
}
let (crc_off, stored_crc) = if version >= VERSION_V9 {
(V9_CRC_OFF, rd_u32(b, V9_CRC_OFF))
} else {
(HEADER_CRC_OFF, rd_u32(b, HEADER_CRC_OFF))
};
if crate::wal::checksum(&b[0..crc_off]) != stored_crc {
return Err(MnemoError::HeaderChecksum);
}
let mut salt = [0u8; SALT_LEN];
salt.copy_from_slice(&b[86..86 + SALT_LEN]);
let mut dek_nonce = [0u8; NONCE_LEN];
dek_nonce.copy_from_slice(&b[102..102 + NONCE_LEN]);
let mut wrapped_dek = [0u8; WRAPPED_DEK_LEN];
wrapped_dek.copy_from_slice(&b[114..114 + WRAPPED_DEK_LEN]);
let v9 = version >= VERSION_V9;
let o = V9_FIELDS_OFF;
let h = Header {
version,
page_size: rd_u32(b, 6),
flags: rd_u32(b, 10),
dimensions: rd_u32(b, 14),
created_at: rd_i64(b, 18),
write_counter: rd_u64(b, 26),
next_page: rd_u64(b, 34),
catalog_start: rd_u64(b, 42),
catalog_pages: rd_u64(b, 50),
catalog_len: rd_u64(b, 58),
vector_count: rd_u64(b, 66),
m_cost: rd_u32(b, 74),
t_cost: rd_u32(b, 78),
p_cost: rd_u32(b, 82),
salt,
dek_nonce,
wrapped_dek,
index_start: rd_u64(b, 162),
index_pages: rd_u64(b, 170),
index_len: rd_u64(b, 178),
wal_start: rd_u64(b, 186),
wal_pages: rd_u64(b, 194),
wal_seq: rd_u64(b, 202),
manifest_start: rd_u64(b, 214),
manifest_pages: rd_u64(b, 222),
manifest_len: rd_u64(b, 230),
seal_nonce: if version >= 7 {
let mut n = [0u8; NONCE_LEN];
n.copy_from_slice(&b[HEADER_SEAL_NONCE_OFF..HEADER_SEAL_NONCE_OFF + NONCE_LEN]);
Some(n)
} else {
None
},
seal_tag: if version >= 7 {
let mut t = [0u8; TAG_LEN];
t.copy_from_slice(&b[HEADER_SEAL_TAG_OFF..HEADER_SEAL_TAG_OFF + TAG_LEN]);
Some(t)
} else {
None
},
cache_start: if version >= 8 {
rd_u64(b, HEADER_CACHE_START_OFF)
} else {
0
},
cache_pages: if version >= 8 {
rd_u64(b, HEADER_CACHE_PAGES_OFF)
} else {
0
},
cache_len: if version >= 8 {
rd_u64(b, HEADER_CACHE_LEN_OFF)
} else {
0
},
catalog_gen: if v9 { rd_u64(b, o) } else { 0 },
index_gen: if v9 { rd_u64(b, o + 8) } else { 0 },
manifest_gen: if v9 { rd_u64(b, o + 16) } else { 0 },
cache_gen: if v9 { rd_u64(b, o + 24) } else { 0 },
free: if v9 {
RunPtr::read(b, o + 32)
} else {
RunPtr::default()
},
keys: if v9 {
RunPtr::read(b, o + 64)
} else {
RunPtr::default()
},
bm25: if v9 {
RunPtr::read(b, o + 96)
} else {
RunPtr::default()
},
index_delta: if v9 {
RunPtr::read(b, o + 128)
} else {
RunPtr::default()
},
catalog_delta: if v9 {
RunPtr::read(b, o + 160)
} else {
RunPtr::default()
},
};
if v9 {
let canon = h.to_page();
let same = (0..V9_CRC_OFF)
.filter(|i| !(HEADER_SEAL_NONCE_OFF..HEADER_SEAL_TAG_OFF + TAG_LEN).contains(i))
.all(|i| canon[i] == b[i]);
if !same {
return Err(MnemoError::Invalid(
"v9 header is not in canonical form (reserved bytes set?)".into(),
));
}
}
Ok(h)
}
fn write_v9_tail(&self, b: &mut [u8; PAGE_SIZE]) {
b[HEADER_CACHE_START_OFF..HEADER_CACHE_START_OFF + 8]
.copy_from_slice(&self.cache_start.to_le_bytes());
b[HEADER_CACHE_PAGES_OFF..HEADER_CACHE_PAGES_OFF + 8]
.copy_from_slice(&self.cache_pages.to_le_bytes());
b[HEADER_CACHE_LEN_OFF..HEADER_CACHE_LEN_OFF + 8]
.copy_from_slice(&self.cache_len.to_le_bytes());
let o = V9_FIELDS_OFF;
b[o..o + 8].copy_from_slice(&self.catalog_gen.to_le_bytes());
b[o + 8..o + 16].copy_from_slice(&self.index_gen.to_le_bytes());
b[o + 16..o + 24].copy_from_slice(&self.manifest_gen.to_le_bytes());
b[o + 24..o + 32].copy_from_slice(&self.cache_gen.to_le_bytes());
self.free.write(b, o + 32);
self.keys.write(b, o + 64);
self.bm25.write(b, o + 96);
self.index_delta.write(b, o + 128);
self.catalog_delta.write(b, o + 160);
b[V9_RESERVED_OFF..V9_CRC_OFF].fill(0);
b[V9_HEADER_LEN..].fill(0);
let crc = crate::wal::checksum(&b[0..V9_CRC_OFF]);
b[V9_CRC_OFF..V9_CRC_OFF + 4].copy_from_slice(&crc.to_le_bytes());
}
fn seal_aad_v9(&self) -> Vec<u8> {
let canon = self.to_page();
let mut aad = Vec::with_capacity(SEAL_AAD_PREFIX_V9.len() + V9_CRC_OFF);
aad.extend_from_slice(SEAL_AAD_PREFIX_V9);
aad.extend_from_slice(&canon[0..V9_CRC_OFF]);
aad
}
pub fn validate_seal(&self, dek: &[u8; crate::crypto::KEY_LEN]) -> Result<()> {
if self.version < 7 {
return Ok(());
}
let nonce = self.seal_nonce.ok_or(MnemoError::HeaderTampered)?;
let tag = self.seal_tag.ok_or(MnemoError::HeaderTampered)?;
let aad = if self.version >= VERSION_V9 {
self.seal_aad_v9()
} else {
header_seal_aad(self)
};
crate::crypto::aead_decrypt(dek, &nonce, &tag, &aad)
.map(|_| ())
.map_err(|_| MnemoError::HeaderTampered)
}
pub fn apply_seal(
&mut self,
page: &mut [u8; PAGE_SIZE],
dek: &[u8; crate::crypto::KEY_LEN],
) -> Result<()> {
if self.version < 7 {
return Ok(());
}
let nonce = crate::crypto::random_nonce();
let aad = if self.version >= VERSION_V9 {
self.seal_aad_v9()
} else {
header_seal_aad(self)
};
let tag_buf = crate::crypto::aead_encrypt(dek, &nonce, &[], &aad)?;
if tag_buf.len() != TAG_LEN {
return Err(MnemoError::Crypto(
"header seal: unexpected tag length".into(),
));
}
let mut tag = [0u8; TAG_LEN];
tag.copy_from_slice(&tag_buf);
page[HEADER_SEAL_NONCE_OFF..HEADER_SEAL_NONCE_OFF + NONCE_LEN].copy_from_slice(&nonce);
page[HEADER_SEAL_TAG_OFF..HEADER_SEAL_TAG_OFF + TAG_LEN].copy_from_slice(&tag);
if self.version >= VERSION_V9 {
let crc = crate::wal::checksum(&page[0..V9_CRC_OFF]);
page[V9_CRC_OFF..V9_CRC_OFF + 4].copy_from_slice(&crc.to_le_bytes());
}
self.seal_nonce = Some(nonce);
self.seal_tag = Some(tag);
Ok(())
}
}
const _: () = assert!(HEADER_CRC_OFF + 4 <= PAGE_SIZE);
const _: () = assert!(TAG_LEN == 16);
#[cfg(test)]
mod tests {
use super::*;
use crate::crypto::{KEY_LEN, SALT_LEN};
fn v9_header() -> Header {
Header {
version: VERSION_V9,
page_size: PAGE_SIZE as u32,
flags: FLAG_ENCRYPTED,
dimensions: 384,
created_at: 1_700_000_000,
write_counter: 7,
next_page: 42,
catalog_start: 20,
catalog_pages: 1,
catalog_len: 300,
vector_count: 5,
m_cost: 8,
t_cost: 1,
p_cost: 1,
salt: [3u8; SALT_LEN],
dek_nonce: [4u8; NONCE_LEN],
wrapped_dek: [5u8; WRAPPED_DEK_LEN],
index_start: 0,
index_pages: 0,
index_len: 0,
wal_start: 1,
wal_pages: 8,
wal_seq: 9,
manifest_start: 21,
manifest_pages: 1,
manifest_len: 90,
seal_nonce: None,
seal_tag: None,
cache_start: 0,
cache_pages: 0,
cache_len: 0,
catalog_gen: 9,
index_gen: 0,
manifest_gen: 9,
cache_gen: 0,
free: RunPtr {
start: 30,
pages: 1,
len: 40,
gen: 9,
},
keys: RunPtr {
start: 31,
pages: 1,
len: 60,
gen: 3,
},
bm25: RunPtr::default(),
index_delta: RunPtr::default(),
catalog_delta: RunPtr::default(),
}
}
fn sealed(h: &mut Header, dek: &[u8; KEY_LEN]) -> [u8; PAGE_SIZE] {
let mut page = h.to_page();
h.apply_seal(&mut page, dek).unwrap();
page
}
fn recrc(page: &mut [u8; PAGE_SIZE]) {
let crc = crate::wal::checksum(&page[0..V9_CRC_OFF]);
page[V9_CRC_OFF..V9_CRC_OFF + 4].copy_from_slice(&crc.to_le_bytes());
}
#[test]
fn v9_header_round_trips_and_fits_in_512_bytes() {
let dek = [9u8; KEY_LEN];
let mut h = v9_header();
let page = sealed(&mut h, &dek);
assert!(page[V9_HEADER_LEN..].iter().all(|&b| b == 0));
let back = Header::from_page(&page).unwrap();
back.validate_seal(&dek).unwrap();
assert_eq!(back.free, h.free);
assert_eq!(back.keys, h.keys);
assert_eq!(back.catalog_gen, 9);
assert_eq!(back.manifest_gen, 9);
assert_eq!(back.dimensions, 384);
}
#[test]
fn v9_seal_covers_fields_the_v8_seal_left_out() {
let dek = [9u8; KEY_LEN];
let mut h = v9_header();
let page = sealed(&mut h, &dek);
for off in [
14usize,
10,
74,
86,
V9_FIELDS_OFF + 32 + 24,
V9_FIELDS_OFF + 64,
] {
let mut t = page;
t[off] ^= 1;
recrc(&mut t);
let parsed = Header::from_page(&t).unwrap();
assert!(
matches!(parsed.validate_seal(&dek), Err(MnemoError::HeaderTampered)),
"byte {off} not covered by the v9 seal"
);
}
}
#[test]
fn v9_torn_or_noncanonical_header_is_rejected() {
let dek = [9u8; KEY_LEN];
let mut h = v9_header();
let page = sealed(&mut h, &dek);
let mut t = page;
t[HEADER_SEAL_TAG_OFF] ^= 1;
assert!(matches!(
Header::from_page(&t),
Err(MnemoError::HeaderChecksum)
));
let mut t = page;
t[V9_RESERVED_OFF] = 1;
recrc(&mut t);
assert!(matches!(Header::from_page(&t), Err(MnemoError::Invalid(_))));
let mut t = page;
t[HEADER_CRC_OFF] = 1;
recrc(&mut t);
assert!(matches!(Header::from_page(&t), Err(MnemoError::Invalid(_))));
}
#[test]
fn versions_past_v9_are_refused() {
let dek = [9u8; KEY_LEN];
let mut h = v9_header();
let mut page = sealed(&mut h, &dek);
page[4..6].copy_from_slice(&10u16.to_le_bytes());
assert!(matches!(
Header::from_page(&page),
Err(MnemoError::UnsupportedVersion(10))
));
}
}