pub struct DatabaseCipher { /* private fields */ }Expand description
Cryptographic engine managing page-level encryption and verification.
Deliberately does not implement Clone so raw key material is never
silently duplicated in memory; sensitive key and salt bytes are scrubbed via
zeroize on Drop.
Implementations§
Source§impl DatabaseCipher
impl DatabaseCipher
Sourcepub fn new(key: [u8; 32], salt: [u8; 16]) -> Self
pub fn new(key: [u8; 32], salt: [u8; 16]) -> Self
Initialize cipher with raw 256-bit key and 16-byte salt
Sourcepub fn from_passphrase(passphrase: &str, salt: [u8; 16]) -> Self
pub fn from_passphrase(passphrase: &str, salt: [u8; 16]) -> Self
Initialize cipher by deriving 256-bit key from passphrase and salt via PBKDF2
Sourcepub fn from_passphrase_with_iterations(
passphrase: &str,
salt: [u8; 16],
iterations: u32,
) -> Self
pub fn from_passphrase_with_iterations( passphrase: &str, salt: [u8; 16], iterations: u32, ) -> Self
Initialize cipher with custom PBKDF2 iteration count
Sourcepub fn set_epoch(&mut self, epoch: u32)
pub fn set_epoch(&mut self, epoch: u32)
Set database epoch (e.g. incremented after major checkpoints / rollbacks)
Sourcepub fn derive_nonce_with_seq(
&self,
page_id: PageId,
sequence: u32,
epoch: u32,
) -> [u8; 12]
pub fn derive_nonce_with_seq( &self, page_id: PageId, sequence: u32, epoch: u32, ) -> [u8; 12]
Derive unique 12-byte AEAD nonce with monotonic write sequence and epoch Formally satisfies RFC 8439 Nonce Uniqueness Requirement: Nonce = Epoch (4B) || PageId (4B) || Sequence (4B)
Sourcepub fn derive_nonce(&self, page_id: PageId) -> [u8; 12]
pub fn derive_nonce(&self, page_id: PageId) -> [u8; 12]
Default 12-byte nonce for backward compatibility (sequence 0, epoch 1)
Sourcepub fn generate_kcv(&self) -> Result<[u8; 16]>
pub fn generate_kcv(&self) -> Result<[u8; 16]>
Generate 16-byte Key Check Value (KCV) tag for header validation.
Returns Err if the ChaCha20-Poly1305 cipher fails, so callers always
know when KCV generation is impossible rather than silently receiving a
zeroed tag that would bypass authentication checks.
Sourcepub fn verify_kcv(&self, stored_kcv: &[u8; 16]) -> bool
pub fn verify_kcv(&self, stored_kcv: &[u8; 16]) -> bool
Constant-time verification of stored KCV against candidate key.
Uses the audited subtle crate (ConstantTimeEq) to prevent timing side-channel leakage.
Returns false (not-equal) on internal error rather than panicking.
Sourcepub fn encrypt_page(&self, page_id: PageId, plaintext: &[u8]) -> Result<Vec<u8>>
pub fn encrypt_page(&self, page_id: PageId, plaintext: &[u8]) -> Result<Vec<u8>>
Encrypt a 4,096-byte in-memory page into a 4,096-byte disk page using XChaCha20-Poly1305 with a cryptographically secure 24-byte (192-bit) random nonce from the OS CSPRNG.
Every write produces a completely distinct ciphertext even if page contents are identical, guaranteeing absolute immunity against nonce reuse attacks per RFC 8439.
Sourcepub fn encrypt_page_with_nonce(
&self,
page_id: PageId,
nonce_bytes: &[u8; 24],
plaintext: &[u8],
) -> Result<Vec<u8>>
pub fn encrypt_page_with_nonce( &self, page_id: PageId, nonce_bytes: &[u8; 24], plaintext: &[u8], ) -> Result<Vec<u8>>
Encrypt a 4,096-byte in-memory page with an explicitly provided 24-byte nonce (useful for deterministic tests)
Sourcepub fn encrypt_page_with_seq(
&self,
page_id: PageId,
sequence: u32,
epoch: u32,
plaintext: &[u8],
) -> Result<Vec<u8>>
pub fn encrypt_page_with_seq( &self, page_id: PageId, sequence: u32, epoch: u32, plaintext: &[u8], ) -> Result<Vec<u8>>
Legacy compatibility wrapper: forwards to encrypt_page_with_nonce using a 24-byte padded nonce
Sourcepub fn decrypt_page(&self, page_id: PageId, disk_page: &[u8]) -> Result<Vec<u8>>
pub fn decrypt_page(&self, page_id: PageId, disk_page: &[u8]) -> Result<Vec<u8>>
Decrypt a 4,096-byte disk page back into an in-memory page using XChaCha20-Poly1305.
Reads the 24-byte random XNonce from bytes [4056..4080] and the 16-byte Poly1305 tag
from bytes [4080..4096]. Authenticates Associated Data against page_id.