Skip to main content

Crate revault_lockbox_api

Crate revault_lockbox_api 

Source
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§

CacheStats
Snapshot of decoded-page cache usage.
ContactKeyPair
Hybrid X25519 + ML-KEM-768 contact keypair.
ContactPublicKey
Public hybrid X25519 + ML-KEM-768 contact key.
ContactWrappedKey
Content key wrapped to a hybrid X25519 + ML-KEM-768 contact.
ContentChunk
Metadata for one streamed content range.
ContentStreamOptions
Options for streaming lockbox file content without extracting to disk.
ExtractPolicy
Safety and behavior limits for extracting lockbox contents.
FormDefinition
Versioned schema describing the fields accepted by a form record.
FormFieldDefinition
Schema for one named field in a form definition.
FormFieldValue
One value stored in a form record with captured display metadata.
FormRecord
Stored form instance tied to a definition revision.
FormTypeId
Stable UUID-shaped identifier shared by all revisions of a form definition.
ImportStats
Coarse import pipeline timing counters.
ListOptions
Options for listing lockbox entries.
Lockbox
Open lockbox container with persisted encryption, signing, and compression choices.
LockboxCreateOptions
Independent creation choices. Runtime cache/worker settings are not persisted. The default size padding is a privacy measure, not an 8 MiB archive minimum.
LockboxEntry
Metadata returned by lockbox listing and stat APIs.
LockboxFileInspection
Public metadata read from a lockbox file without decrypting its contents.
LockboxFileMut
Seekable read/write handle over a file inside a writable lockbox.
LockboxFileReader
Seekable read handle over a file inside a lockbox.
LockboxFormatOptions
Persisted choices, restored automatically when an archive is reopened.
LockboxGlob
Validated glob pattern for matching paths inside a lockbox.
LockboxId
Stable UUID-style identifier embedded in each lockbox.
LockboxInspector
Read-only diagnostics for an opened lockbox.
LockboxKeySlot
Public metadata for one key slot.
LockboxOptions
Options used when creating or opening a lockbox.
LockboxOwnerInspection
Owner-signing metadata verified from an opened lockbox.
LockboxPath
Canonical path for an directory, file or symlink entry inside a lockbox.
MirrorProject
Persistent configuration for one host-to-lockbox mirror project.
OpenFileOptions
Options used when opening a writable file handle inside a lockbox.
OwnerSigningKeyPair
Hybrid owner signing keypair used to authenticate writable commits.
OwnerSigningPublicKey
Public verification key for owner-signed lockbox commits.
PageInspection
Public diagnostic view of one physical lockbox page.
PageObjectInspection
Public diagnostic view of one object inside a page.
PasswordWorkBudget
Work admission shared by primary, mirror and explicit recovery attempts.
ReadOnly
Marker for lockbox handles that can read but cannot be committed.
RecoveryReport
Summary produced by lockbox recovery and salvage scans.
RecoveryReportOptions
Rendering options for RecoveryReport.
RecoveryScanner
Scans damaged lockbox storage and reports or salvages recoverable content.
SecretString
UTF-8 secret stored in guarded, zeroizing memory.
SecretVec
Variable-length byte sequence stored in guarded, zeroizing memory.
TransactionRecoveryProgress
Progress reported while explicit transaction recovery is running.
TransactionRecoveryStatus
Authenticated recovery work advertised by the selected lockbox header.
VariableName
Validated, case-sensitive variable name stored inside a lockbox.
VariableNamePattern
Validated case-sensitive variable-name filter.
Writable
Marker for lockbox handles that can be mutated and committed.
ZstdLevel
Zstd compression level, from 1 (fastest) to 22 (strongest).

Enums§

ArtifactKind
Native persisted artifact whose format version was rejected.
CacheLimit
Decoded-page cache size policy.
Compression
Compression applied to newly written files and eligible metadata. Secure variable and form pages retain their uncompressed encoding.
ContentStreamOrder
Ordering used by Lockbox::stream_content.
Encryption
Encryption choice and, when enabled, the material protecting the content key.
EncryptionMode
Persisted encryption mode.
Error
Error type returned by lockbox operations.
FormFieldKind
Validation and sensitivity category for a form field.
FormValue
Sensitivity-aware payload stored by a form field.
LockboxEntryKind
Kind of logical node returned by lockbox listing and stat APIs.
LockboxKeySlotAlgorithm
Algorithm used by a key slot to wrap the lockbox content key.
LockboxKeySlotProtection
User-facing protection type represented by a key slot.
LockboxOpen
Key material used to open an existing lockbox file.
LockboxProtection
Key material used when creating a new lockbox file.
MirrorMissingFilePolicy
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.
SigningMode
Persisted commit-signing requirement.
SizePadding
Creation-time size-hiding policy, persisted in the authenticated header.
TransactionRecoveryControl
Decision returned by a controlled recovery progress callback.
TransactionRecoveryOutcome
Result of an explicit controlled recovery attempt.
TransactionRecoveryPhase
Durable recovery phase for an interrupted transaction.
VariableSensitivity
Sensitivity marker for variables stored in a lockbox.
VariableValueRef
Borrowed variable value yielded by Lockbox::visit_variables.
WorkerPolicy
Worker policy for CPU-heavy lockbox work.
WorkloadProfile
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.