Expand description
Core encrypted lockbox storage engine.
revault_lockbox_api owns the portable .lbox file format and the in-memory API
for storing files, symlinks, variable values, and key slots. Dot-prefixed
variable components may be used by applications for hidden metadata; they
remain ordinary encrypted variables at the API layer. It does not
know about a user’s Vault or Session Agent; those are implemented in
revault_vault_api.
Start with Lockbox::create_in_memory for an in-memory archive or
Lockbox::create_file for a file-backed archive. Add password or contact
key slots before sharing the resulting .lbox file. Secret variables and
secret form fields are exposed only through callback-scoped secure values.
§Example
use revault_lockbox_api::{
Lockbox, LockboxPath, LockboxProtection, OwnerSigningKeyPair, SecretString,
};
let password = SecretString::try_from_slice(b"correct horse")?;
let signing_key = OwnerSigningKeyPair::generate()?;
let mut lockbox = Lockbox::create_in_memory(
LockboxProtection::Password(&password),
&signing_key,
)?;
lockbox.add_file(&LockboxPath::new("/notes.txt")?, b"encrypted", false)?;
lockbox.commit()?;
let encrypted_archive = lockbox.try_to_bytes()?;
assert!(!encrypted_archive.is_empty());See the reVault repository README for installation, security guidance, and end-to-end examples.
Re-exports§
pub use lockbox::ContentChunk;pub use lockbox::ContentStreamOptions;pub use lockbox::ContentStreamOrder;pub use lockbox::ImportStats;pub use lockbox::Lockbox;pub use lockbox::LockboxFileInspection;pub use lockbox::LockboxFileMut;pub use lockbox::LockboxFileReader;pub use lockbox::LockboxInspector;pub use lockbox::LockboxOpen;pub use lockbox::LockboxOwnerInspection;pub use lockbox::LockboxProtection;pub use lockbox::MirrorMissingFilePolicy;pub use lockbox::MirrorProject;pub use lockbox::OpenFileOptions;pub use lockbox::ReadOnly;pub use lockbox::RecoveryScanner;pub use lockbox::VariableValueRef;pub use lockbox::Writable;
Modules§
- external_
source - Read-only archives supplied by an immutable external byte source.
Structs§
- Cache
Stats - Snapshot of decoded-page cache usage.
- Contact
KeyPair - Hybrid X25519 + ML-KEM-768 contact keypair.
- Contact
Public Key - Public hybrid X25519 + ML-KEM-768 contact key.
- Contact
Wrapped Key - Content key wrapped to a hybrid X25519 + ML-KEM-768 contact.
- Content
Chunk - Metadata for one streamed content range.
- Content
Stream Options - Options for streaming lockbox file content without extracting to disk.
- Extract
Policy - Safety and behavior limits for extracting lockbox contents.
- Form
Definition - Versioned schema describing the fields accepted by a form record.
- Form
Field Definition - Schema for one named field in a form definition.
- Form
Field Value - One value stored in a form record with captured display metadata.
- Form
Record - Stored form instance tied to a definition revision.
- Form
Type Id - Stable UUID-shaped identifier shared by all revisions of a form definition.
- Import
Stats - Coarse import pipeline timing counters.
- List
Options - Options for listing lockbox entries.
- Lockbox
- Open lockbox container with persisted encryption, signing, and compression choices.
- Lockbox
Create Options - Independent creation choices. Runtime cache/worker settings are not persisted. The default size padding is a privacy measure, not an 8 MiB archive minimum.
- Lockbox
Entry - Metadata returned by lockbox listing and stat APIs.
- Lockbox
File Inspection - Public metadata read from a lockbox file without decrypting its contents.
- Lockbox
File Mut - Seekable read/write handle over a file inside a writable lockbox.
- Lockbox
File Reader - Seekable read handle over a file inside a lockbox.
- Lockbox
Format Options - Persisted choices, restored automatically when an archive is reopened.
- Lockbox
Glob - Validated glob pattern for matching paths inside a lockbox.
- Lockbox
Id - Stable UUID-style identifier embedded in each lockbox.
- Lockbox
Inspector - Read-only diagnostics for an opened lockbox.
- Lockbox
KeySlot - Public metadata for one key slot.
- Lockbox
Options - Options used when creating or opening a lockbox.
- Lockbox
Owner Inspection - Owner-signing metadata verified from an opened lockbox.
- Lockbox
Path - Canonical path for an directory, file or symlink entry inside a lockbox.
- Mirror
Project - Persistent configuration for one host-to-lockbox mirror project.
- Open
File Options - Options used when opening a writable file handle inside a lockbox.
- Owner
Signing KeyPair - Hybrid owner signing keypair used to authenticate writable commits.
- Owner
Signing Public Key - Public verification key for owner-signed lockbox commits.
- Page
Inspection - Public diagnostic view of one physical lockbox page.
- Page
Object Inspection - Public diagnostic view of one object inside a page.
- Password
Work Budget - Work admission shared by primary, mirror and explicit recovery attempts.
- Read
Only - Marker for lockbox handles that can read but cannot be committed.
- Recovery
Report - Summary produced by lockbox recovery and salvage scans.
- Recovery
Report Options - Rendering options for
RecoveryReport. - Recovery
Scanner - Scans damaged lockbox storage and reports or salvages recoverable content.
- Secret
String - UTF-8 secret stored in guarded, zeroizing memory.
- Secret
Vec - Variable-length byte sequence stored in guarded, zeroizing memory.
- Transaction
Recovery Progress - Progress reported while explicit transaction recovery is running.
- Transaction
Recovery Status - Authenticated recovery work advertised by the selected lockbox header.
- Variable
Name - Validated, case-sensitive variable name stored inside a lockbox.
- Variable
Name Pattern - Validated case-sensitive variable-name filter.
- Writable
- Marker for lockbox handles that can be mutated and committed.
- Zstd
Level - Zstd compression level, from 1 (fastest) to 22 (strongest).
Enums§
- Artifact
Kind - Native persisted artifact whose format version was rejected.
- Cache
Limit - Decoded-page cache size policy.
- Compression
- Compression applied to newly written files and eligible metadata. Secure variable and form pages retain their uncompressed encoding.
- Content
Stream Order - Ordering used by
Lockbox::stream_content. - Encryption
- Encryption choice and, when enabled, the material protecting the content key.
- Encryption
Mode - Persisted encryption mode.
- Error
- Error type returned by lockbox operations.
- Form
Field Kind - Validation and sensitivity category for a form field.
- Form
Value - Sensitivity-aware payload stored by a form field.
- Lockbox
Entry Kind - Kind of logical node returned by lockbox listing and stat APIs.
- Lockbox
KeySlot Algorithm - Algorithm used by a key slot to wrap the lockbox content key.
- Lockbox
KeySlot Protection - User-facing protection type represented by a key slot.
- Lockbox
Open - Key material used to open an existing lockbox file.
- Lockbox
Protection - Key material used when creating a new lockbox file.
- Mirror
Missing File Policy - Controls what an update does with files that exist only in a mirror’s managed lockbox directory.
- Signing
- Signing choice and, when enabled, the private key used for commits.
- Signing
Mode - Persisted commit-signing requirement.
- Size
Padding - Creation-time size-hiding policy, persisted in the authenticated header.
- Transaction
Recovery Control - Decision returned by a controlled recovery progress callback.
- Transaction
Recovery Outcome - Result of an explicit controlled recovery attempt.
- Transaction
Recovery Phase - Durable recovery phase for an interrupted transaction.
- Variable
Sensitivity - Sensitivity marker for variables stored in a lockbox.
- Variable
Value Ref - Borrowed variable value yielded by
Lockbox::visit_variables. - Worker
Policy - Worker policy for CPU-heavy lockbox work.
- Workload
Profile - High-level access pattern hint for cache and write behavior.
Constants§
- DEFAULT_
PASSWORD_ SLOT_ BUDGET - Default maximum password-slot derivations in one open operation. This is an operation limit, not a limit on valid persisted key directories.
- LOCKBOX_
FORMAT_ VERSION - Current native lockbox format written by the crash-recoverable protocol.
- MAX_
KEY_ SLOT_ NAME_ BYTES - Maximum UTF-8 byte length for a user-facing key slot name.
- MAX_
TRANSACTION_ REDACTION_ BYTES - Maximum total physical bytes redacted by one transaction.
- MAX_
TRANSACTION_ REDACTION_ MANIFEST_ BYTES - Maximum encrypted manifest payload bytes for one transaction.
- MAX_
TRANSACTION_ REDACTION_ OBJECT_ IDS - Maximum object references retained by the in-memory redaction scheduler.
- MAX_
TRANSACTION_ REDACTION_ RANGES - Maximum physical ranges scheduled by one crash-recoverable redaction transaction.
Functions§
- probe_
lockbox_ format_ version - Read a native format discriminator without opening its contents.
Type Aliases§
- Result
- Convenient result alias for lockbox operations.