Struct Secret 

pub struct Secret(/* private fields */);

A 256-bit symmetric encryption key for content encryption

Each Secret is used to encrypt a single item (node or data blob) using ChaCha20-Poly1305 AEAD. The encrypted format is: nonce (12 bytes) || encrypted(hash(32 bytes) || plaintext) || tag (16 bytes). The BLAKE3 hash of the plaintext is prepended before encryption to enable content verification without full decryption (useful for filesystem sync operations).

Examples

// Generate a new random secret
let secret = Secret::generate();

// Encrypt data
let plaintext = b"sensitive data";
let ciphertext = secret.encrypt(plaintext)?;

// Decrypt data
let recovered = secret.decrypt(&ciphertext)?;
assert_eq!(plaintext, &recovered[..]);

Implementations

impl Secret

pub fn generate() -> Self

Generate a new random secret using a cryptographically secure RNG

pub fn from_slice(data: &[u8]) -> Result<Self, SecretError>

Create a secret from a byte slice

Errors

Returns an error if the slice length is not exactly SECRET_SIZE bytes.

pub fn bytes(&self) -> &[u8]

Get a reference to the secret key bytes

pub fn encrypt(&self, data: &[u8]) -> Result<Vec<u8>, SecretError>

Encrypt data using ChaCha20-Poly1305 AEAD

The output format is: nonce (12 bytes) || encrypted(hash(32) || plaintext) || auth_tag (16 bytes). A BLAKE3 hash of the plaintext is computed and prepended to the data before encryption. A random nonce is generated for each encryption operation.

Errors

Returns an error if encryption fails (should be rare, only on system RNG failure).

pub fn decrypt(&self, data: &[u8]) -> Result<Vec<u8>, SecretError>

Decrypt data using ChaCha20-Poly1305 AEAD

Expects input in the format: nonce (12 bytes) || encrypted(hash(32) || plaintext) || auth_tag (16 bytes). Returns only the plaintext (hash is stripped but verified for integrity).

Errors

Returns an error if:

• Data is too short to contain a nonce
• Authentication tag verification fails (data was tampered with or wrong key)
• Decrypted data is too short to contain the hash header
• Hash verification fails (data corruption)

pub fn extract_plaintext_hash( &self, data: &[u8], ) -> Result<[u8; 32], SecretError>

Extract the BLAKE3 hash of the plaintext without decrypting the full content

This is useful for filesystem sync operations where you only need to compare content hashes without loading the entire file into memory.

Errors

Returns an error if:

• Data is too short to contain a nonce
• Authentication tag verification fails (data was tampered with or wrong key)
• Decrypted data is too short to contain the hash header

pub fn encrypt_reader<R>(&self, reader: R) -> Result<impl Read, SecretError>

where R: Read,

Create an encrypted reader from a plaintext reader

This buffers all data in memory, encrypts it, and returns a reader over the encrypted data. Future optimization: implement true streaming encryption.

pub fn decrypt_reader<R>(&self, reader: R) -> Result<impl Read, SecretError>

where R: Read,

Create a decrypted reader from an encrypted reader

This buffers all encrypted data in memory, decrypts it, and returns a reader over the plaintext. Future optimization: implement true streaming decryption.

Trait Implementations

impl Clone for Secret

fn clone(&self) -> Secret

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Secret

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Secret

fn default() -> Self

Returns the “default value” for a type.

impl Deref for Secret

type Target = [u8; 32]

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl<'de> Deserialize<'de> for Secret

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl From<[u8; 32]> for Secret

fn from(bytes: [u8; 32]) -> Self

Converts to this type from the input type.

impl PartialEq for Secret

fn eq(&self, other: &Secret) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Serialize for Secret

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for Secret