Struct Lockbox 

pub struct Lockbox<State = Writable> { /* private fields */ }

Open encrypted lockbox container.

A Lockbox owns the encrypted storage backend plus the decrypted metadata needed to make changes. Mutations are staged in memory until commit() is called; reopening a lockbox after an interrupted commit returns the last published state.

Implementations

impl Lockbox

pub fn try_to_bytes(&self) -> Result<Vec<u8>, Error>

pub fn commit(&mut self) -> Result<(), Error>

Persist pending lockbox changes atomically to the backing storage.

Returns storage, encoding, or security-limit errors if pending changes cannot be written. On error, in-memory metadata is rolled back to the state before the commit attempt.

impl<State> Lockbox<State>

where State: Send,

pub fn extract_to_directory( &self, destination: &Path, policy: &ExtractPolicy, ) -> Result<(), Error>

Extract all permitted entries into a destination directory.

Returns Error::Io for host filesystem failures, Error::SecurityLimitExceeded when the extraction policy rejects the destination or size/count limits, and lockbox read errors for corrupt or missing stored entries.

impl<State> Lockbox<State>

pub fn open_file( &self, path: &LockboxPath, ) -> Result<LockboxFileReader<'_, State>, Error>

Open a seekable read handle over a file inside the lockbox.

pub fn add_file( &mut self, path: &LockboxPath, data: &[u8], replace: bool, ) -> Result<(), Error>

where State: WritableLockboxState,

Add or replace a file from an in-memory byte slice.

When replace is false, returns Error::AlreadyExists if path already names an existing file or symlink. When replace is true, returns Error::NotFound if there is no existing entry to replace. Returns Error::InvalidPath for directory-only or unsafe lockbox paths and propagates storage or encoding errors from the write.

pub fn add_file_with_permissions( &mut self, path: &LockboxPath, data: &[u8], permissions: u32, replace: bool, ) -> Result<(), Error>

where State: WritableLockboxState,

Add or replace a file with explicit Unix-style permissions.

permissions is a Unix mode value containing only the low permission bits, written in Rust as octal literals such as 0o600, 0o640, or 0o755. File type bits, sticky/setuid/setgid bits, and platform ACLs are not supported.

When replace is false, returns Error::AlreadyExists if path already names an existing file or symlink. When replace is true, returns Error::NotFound if there is no existing entry to replace. Returns Error::InvalidPath for directory-only or unsafe lockbox paths, Error::InvalidPath for unsupported permission bits, and propagates storage or encoding errors from the write.

pub fn add_file_from_reader( &mut self, path: &LockboxPath, reader: impl Read, replace: bool, ) -> Result<(), Error>

where State: WritableLockboxState,

Add or replace a file by streaming bytes from a reader.

When replace is false, returns Error::AlreadyExists if path already names an existing file or symlink. When replace is true, returns Error::NotFound if there is no existing entry to replace. Returns Error::InvalidPath for directory-only or unsafe lockbox paths and propagates reader, storage, or encoding errors from the write.

pub fn add_file_from_path( &mut self, source: &Path, destination: &LockboxPath, replace: bool, ) -> Result<(), Error>

where State: WritableLockboxState,

Add or replace a file by reading from a host filesystem path.

When replace is false, returns Error::AlreadyExists if destination already names an existing file or symlink. When replace is true, returns Error::NotFound if there is no existing entry to replace. Returns Error::InvalidPath for directory-only or unsafe destination paths and Error::Io if the host file cannot be read.

pub fn add_file_from_reader_with_permissions( &mut self, path: &LockboxPath, reader: impl Read, permissions: u32, replace: bool, ) -> Result<(), Error>

where State: WritableLockboxState,

Add or replace a streamed file with explicit Unix-style permissions.

permissions is a Unix mode value containing only the low permission bits, written in Rust as octal literals such as 0o600, 0o640, or 0o755. File type bits, sticky/setuid/setgid bits, and platform ACLs are not supported.

When replace is false, returns Error::AlreadyExists if path already names an existing file or symlink. When replace is true, returns Error::NotFound if there is no existing entry to replace. Returns Error::InvalidPath for directory-only or unsafe lockbox paths, Error::InvalidPath for unsupported permission bits, and propagates reader, storage, or encoding errors from the write.

pub fn get_file(&self, path: &LockboxPath) -> Result<Vec<u8>, Error>

Return the complete contents of a file.

Returns Error::InvalidPath for directory-only paths, Error::NotFound if path is absent or not a file, Error::CorruptRecord if stored file metadata is inconsistent, and Error::Io if an internal write into the output buffer fails.

pub fn extract_file_to_writer( &self, path: &LockboxPath, writer: impl Write, ) -> Result<(), Error>

Extract a file’s contents to a writer.

Returns Error::InvalidPath for directory-only paths, Error::NotFound if path is absent or not a file, Error::CorruptRecord if stored file metadata is inconsistent, and Error::Io if the writer fails.

pub fn extract_file_to( &self, source: &LockboxPath, destination: &Path, replace: bool, ) -> Result<(), Error>

Extract a file’s contents to a host filesystem path.

When replace is false, returns Error::AlreadyExists if the destination path already exists. When replace is true, returns Error::NotFound if the destination path does not already exist. Returns Error::Io if the destination file cannot be created. Returns the same errors as extract_file_to_writer for lockbox read failures.

pub fn permissions(&self, path: &LockboxPath) -> Option<u32>

Return stored Unix-style permissions for a file or symlink.

The returned value uses the low Unix permission bits only, for example 0o600, 0o640, or 0o755.

pub fn read_file_range( &self, path: &LockboxPath, offset: u64, len: u64, ) -> Result<Vec<u8>, Error>

Read a bounded byte range from a file.

Returns Error::InvalidPath for directory-only paths, Error::NotFound if path is absent or not a file, and Error::CorruptRecord if stored file metadata is inconsistent. A range outside the file returns an empty vector rather than an error.

pub fn stream_content<F>( &self, options: ContentStreamOptions, visitor: F, ) -> Result<(), Error>

where F: FnMut(ContentChunk, &mut dyn Read) -> Result<(), Error>,

Stream file content ranges without extracting files to the host filesystem.

impl Lockbox

pub fn open_file_for_write( &mut self, path: &LockboxPath, options: OpenFileOptions, ) -> Result<LockboxFileMut<'_>, Error>

Open a seekable read/write handle over a file inside the lockbox.

impl<State> Lockbox<State>

pub fn define_form( &mut self, alias: &str, name: &str, fields: Vec<FormFieldDefinition>, ) -> Result<FormDefinition, Error>

where State: WritableLockboxState,

pub fn define_form_with_description( &mut self, alias: &str, name: &str, description: &str, fields: Vec<FormFieldDefinition>, ) -> Result<FormDefinition, Error>

where State: WritableLockboxState,

pub fn define_form_with_type_id( &mut self, type_id: FormTypeId, alias: &str, name: &str, fields: Vec<FormFieldDefinition>, ) -> Result<FormDefinition, Error>

where State: WritableLockboxState,

pub fn define_form_with_type_id_and_description( &mut self, type_id: FormTypeId, alias: &str, name: &str, description: &str, fields: Vec<FormFieldDefinition>, ) -> Result<FormDefinition, Error>

where State: WritableLockboxState,

pub fn revise_form_definition( &mut self, type_id: &FormTypeId, name: &str, description: &str, fields: Vec<FormFieldDefinition>, ) -> Result<FormDefinition, Error>

where State: WritableLockboxState,

pub fn resolve_form_definition( &self, reference: &str, ) -> Result<FormDefinition, Error>

pub fn list_form_definitions(&self) -> Result<Vec<FormDefinition>, Error>

pub fn list_form_definition_revisions( &self, type_id: &FormTypeId, ) -> Result<Vec<FormDefinition>, Error>

pub fn import_form_definition( &mut self, definition: FormDefinition, ) -> Result<FormDefinition, Error>

where State: WritableLockboxState,

pub fn create_form_record( &mut self, path: &LockboxPath, type_reference: &str, name: &str, ) -> Result<FormRecord, Error>

where State: WritableLockboxState,

pub fn get_form_record( &self, path: &LockboxPath, ) -> Result<Option<FormRecord>, Error>

pub fn list_form_records(&self) -> Result<Vec<FormRecord>, Error>

pub fn delete_form_record(&mut self, path: &LockboxPath) -> Result<(), Error>

where State: WritableLockboxState,

pub fn move_form_records( &mut self, moves: &[(LockboxPath, LockboxPath)], ) -> Result<(), Error>

where State: WritableLockboxState,

Move one or more form records while preserving all field values.

The complete move is validated before records are changed. Existing unrelated records are never overwritten.

pub fn set_form_field_normal( &mut self, path: &LockboxPath, field_id: &str, value: &str, ) -> Result<(), Error>

where State: WritableLockboxState,

pub fn set_form_field_secret( &mut self, path: &LockboxPath, field_id: &str, value: &SecureString, ) -> Result<(), Error>

where State: WritableLockboxState,

pub fn set_form_field( &mut self, path: &LockboxPath, field_id: &str, value: FormValue, ) -> Result<(), Error>

where State: WritableLockboxState,

pub fn get_form_field( &self, path: &LockboxPath, field_id: &str, ) -> Result<Option<FormFieldValue>, Error>

impl Lockbox

pub fn create_in_memory( protection: LockboxProtection<'_>, signing_key: &OwnerSigningKeyPair, ) -> Result<Lockbox, Error>

Create a new in-memory lockbox using the supplied key material.

This is the bytes-oriented counterpart to Lockbox::create_file. Call commit after mutations, then try_to_bytes to serialize the lockbox.

pub fn create_file( path: &Path, protection: LockboxProtection<'_>, signing_key: &OwnerSigningKeyPair, ) -> Result<Lockbox, Error>

Create a new lockbox file using the supplied key material.

Returns Error::Io if the host file cannot be created or written, Error::SecurityLimitExceeded if key material cannot be generated or wrapped, and storage/encoding errors from the initial commit.

pub fn open_bytes( bytes: Vec<u8>, open: LockboxOpen<'_>, ) -> Result<Lockbox<ReadOnly>, Error>

Open an in-memory lockbox using the supplied open key material.

pub fn open_bytes_for_write( bytes: Vec<u8>, open: LockboxOpen<'_>, signing_key: &OwnerSigningKeyPair, ) -> Result<Lockbox, Error>

Open an in-memory lockbox for mutation and attach signing_key for commits.

pub fn open( path: &Path, open: LockboxOpen<'_>, ) -> Result<Lockbox<ReadOnly>, Error>

Open an existing lockbox file using the supplied open key material.

Password and contact opens use only key slots embedded in the lockbox file. This method does not read the local vault, cached content keys, or vault-stored key-directory backups. Use revault_vault_api::Vault when that behavior is required.

Returns Error::Io if the host file cannot be read, Error::InvalidKey when the supplied open material cannot authenticate the content key, or corrupt/truncated errors if the lockbox structure cannot be parsed.

pub fn open_for_write( path: &Path, open: LockboxOpen<'_>, signing_key: &OwnerSigningKeyPair, ) -> Result<Lockbox, Error>

Open a lockbox file for mutation and attach signing_key for commits.

pub fn open_for_write_with_signing_key( path: &Path, open: LockboxOpen<'_>, load_signing_key: impl FnOnce(&Lockbox<ReadOnly>) -> Result<OwnerSigningKeyPair, Error>, ) -> Result<Lockbox, Error>

Open a lockbox file for mutation after loading its owner signing key.

This is for lockboxes that store their own owner signing key, such as the local vault. The callback receives a read-only borrow of the opened lockbox and must return the key that will sign future commits.

pub fn create_with_password(password: &SecureString) -> Result<Lockbox, Error>

pub fn create_with_contact(contact: &ContactPublicKey) -> Result<Lockbox, Error>

pub fn open_with_password( bytes: Vec<u8>, password: &SecureString, ) -> Result<Lockbox, Error>

pub fn open_with_contact( bytes: Vec<u8>, contact: &ContactKeyPair, ) -> Result<Lockbox, Error>

pub fn add_password(&mut self, password: &SecureString) -> Result<u64, Error>

Add another password that can open this lockbox and return its key id.

A password does not encrypt file content directly. The lockbox content key is random; each password wraps that same content key in an embedded key-directory entry. Lockbox::open with LockboxOpen::Password tries each embedded password entry until one unwraps the content key.

Returns Error::Io if random salt generation fails, Error::InvalidInput if internal password-derivation parameters are invalid, Error::InvalidKey if authenticated key wrapping fails, or Error::SecurityLimitExceeded if secure memory access fails.

pub fn add_contact(&mut self, contact: &ContactPublicKey) -> Result<u64, Error>

Add a contact public key to the lockbox and return its key id.

Once a contact’s public key has been added to a lockbox, the matching contact’s private keypair can be used to open the lockbox. Add contacts with their public key, not their private keypair.

To add a contact to the box, you must be able to open the box with your own key.

Returns Error::SecurityLimitExceeded if secure key access or key wrapping fails.

pub fn add_contact_named( &mut self, name: impl Into<String>, contact: &ContactPublicKey, ) -> Result<u64, Error>

Add a contact public key selected by a local name and return its key id.

The name is validated for caller-side label storage, but is not stored in the lockbox. Persisting names would leak who can open a shared lockbox.

pub fn delete_key(&mut self, id: u64) -> Result<(), Error>

Delete a key from the lockbox and compact obsolete key directory pages.

Returns Error::NotFound if id does not exist, Error::SecurityLimitExceeded when attempting to remove the last key, or storage/encoding errors if compaction fails.

pub fn list_key_slots(&self) -> Vec<LockboxKeySlot>

List the keys that can open this lockbox.

pub fn replace_password( &mut self, old_password: &SecureString, new_password: &SecureString, ) -> Result<u64, Error>

Replace one existing password with a new password and return the new key id.

The old password is used only to find a matching embedded password entry. Other passwords and contact keys are left unchanged. Returns Error::InvalidKey if no embedded password entry matches old_password; returns storage or encoding errors if compaction fails after the replacement.

pub fn replace_content_key_with_contacts( &mut self, retained_contacts: &[(String, ContactPublicKey)], ) -> Result<Vec<(String, u64)>, Error>

Replace the lockbox content key and grant access to the supplied contacts.

This is the low-level primitive for true revocation. It rewrites the archive with a fresh content key and creates a new key directory containing only retained_contacts. Password slots and contacts not supplied by the caller are intentionally not preserved.

impl<State> Lockbox<State>

pub fn list( &self, options: ListOptions, ) -> Result<impl Iterator<Item = Result<LockboxEntry, Error>>, Error>

Return an iterator over entries matching listing options.

Returns Error::InvalidPath if the list root or glob pattern is unsafe. Iteration returns only table-of-contents metadata. It does not read symlink page objects; call get_symlink_target for symlink targets.

pub fn stat(&self, path: &LockboxPath) -> Option<LockboxEntry>

Return metadata for one file, symlink, or directory.

pub fn exists(&self, path: &LockboxPath) -> bool

Return true when path names an existing file, symlink, or directory entry.

pub fn is_dir(&self, path: &LockboxPath) -> bool

Return true when path names an existing directory entry.

impl<State> Lockbox<State>

pub fn create_dir( &mut self, path: &LockboxPath, create_parents: bool, ) -> Result<(), Error>

where State: WritableLockboxState,

Create a directory entry.

When create_parents is true, missing parent directories are created first. The root directory / is implicit and cannot be created.

pub fn create_parent_dirs_for( &mut self, path: &LockboxPath, ) -> Result<(), Error>

where State: WritableLockboxState,

pub fn remove_dir(&mut self, path: &LockboxPath) -> Result<(), Error>

where State: WritableLockboxState,

Remove an empty directory entry.

pub fn remove_dir_recursive(&mut self, path: &LockboxPath) -> Result<(), Error>

where State: WritableLockboxState,

Remove a directory entry and all descendants.

pub fn set_permissions( &mut self, path: &LockboxPath, permissions: u32, ) -> Result<(), Error>

where State: WritableLockboxState,

Change stored Unix-style permission bits on a file, symlink, or directory.

pub fn delete(&mut self, path: &LockboxPath) -> Result<(), Error>

where State: WritableLockboxState,

Delete a file or symlink from the lockbox.

Returns Error::InvalidPath for directory-only paths, Error::NotFound if path does not name an existing entry, and storage errors if pending data must be flushed before deletion.

pub fn rename( &mut self, from: &LockboxPath, to: &LockboxPath, ) -> Result<(), Error>

where State: WritableLockboxState,

Rename one file/symlink or a directory prefix.

Returns Error::InvalidPath for unsafe file paths, self-nested directory moves, or generated destination paths that are not valid lockbox file paths. Returns Error::NotFound when the source file or directory prefix does not exist. Existing destination entries are replaced by the rename.

impl<State> Lockbox<State>

pub fn add_symlink( &mut self, path: &LockboxPath, target: &LockboxPath, replace: bool, ) -> Result<(), Error>

where State: WritableLockboxState,

Add or replace a symbolic link.

When replace is false, returns Error::AlreadyExists if path already names an existing file or symlink. When replace is true, returns Error::NotFound if there is no existing entry to replace. Returns Error::InvalidPath for directory-only or unsafe lockbox paths and propagates storage errors from the write.

pub fn get_symlink_target( &self, path: &LockboxPath, ) -> Result<LockboxPath, Error>

Return the target path for a symbolic link.

Returns Error::InvalidPath for directory-only paths, Error::NotFound if path is absent or not a symlink, and Error::CorruptRecord if the stored symlink metadata is inconsistent.

pub fn is_symlink(&self, path: &LockboxPath) -> bool

Return true when the logical path is a symbolic link.

impl<State> Lockbox<State>

pub fn set_variable( &mut self, name: &VariableName, value: &str, ) -> Result<(), Error>

where State: WritableLockboxState,

Store or replace a non-secret variable.

Returns Error::InvalidInput if the value contains unsupported characters, Error::SecurityLimitExceeded if the value exceeds the configured variable value size limit, Error::InvalidOperation when attempting to overwrite an existing secret variable as non-secret, and Error::CorruptRecord if stored variable metadata cannot be loaded.

pub fn set_secret_variable( &mut self, name: &VariableName, value: &SecureString, ) -> Result<(), Error>

where State: WritableLockboxState,

Store or replace a secret variable.

Secret values remain in secure storage. Changing an existing variable between normal and secret sensitivity requires deleting it first.

Returns Error::InvalidInput if the secret plaintext contains unsupported characters, Error::SecurityLimitExceeded if the secret plaintext exceeds the configured variable value size limit, Error::InvalidOperation when attempting to overwrite an existing non-secret variable as secret, and Error::CorruptRecord if stored variable metadata cannot be loaded.

pub fn get_variable(&self, name: &VariableName) -> Result<Option<String>, Error>

Return a non-secret variable by name.

Returns Ok(None) when the variable is absent. Returns Error::InvalidOperation if the variable exists but is secret, and Error::CorruptRecord if stored variable metadata cannot be loaded.

pub fn with_secret_variable<R>( &self, name: &VariableName, f: impl FnOnce(&SecureString) -> R, ) -> Result<Option<R>, Error>

Access a secret variable within a callback.

The callback receives the SecretString handle. Use SecretString::with_str inside the callback when plaintext access is required.

Returns Ok(None) when the variable is absent. Returns Error::InvalidOperation if the variable exists but is non-secret, and Error::CorruptRecord if stored variable metadata cannot be loaded.

pub fn variable_sensitivity( &self, name: &VariableName, ) -> Result<Option<VariableSensitivity>, Error>

Return the sensitivity of a variable, if it exists.

Returns Error::CorruptRecord if stored variable metadata cannot be loaded.

pub fn delete_variable(&mut self, name: &VariableName) -> Result<(), Error>

where State: WritableLockboxState,

Delete a variable if it exists.

Returns Error::CorruptRecord if stored variable metadata cannot be loaded.

pub fn move_variables( &mut self, moves: &[(VariableName, VariableName)], ) -> Result<(), Error>

where State: WritableLockboxState,

Move one or more variables without exposing or copying their plaintext.

The operation is validated in full before any variable is changed. Sources must exist, destinations must be unique, and a destination may not replace a variable that is not itself being moved.

pub fn list_variables( &self, ) -> Result<Vec<(VariableName, VariableSensitivity)>, Error>

List variable names with their sensitivity.

Returns Error::CorruptRecord if stored variable metadata cannot be loaded.

pub fn visit_variables( &self, f: impl FnMut(&VariableName, VariableValueRef<'_>) -> Result<(), Error>, ) -> Result<(), Error>

Visit every variable.

Normal values are provided as borrowed strings. Secret values are provided as SecretString references so callers must explicitly use the secret type’s scoped accessors.

Returns Error::CorruptRecord if stored variable metadata cannot be loaded, or any error returned by the visitor callback.

impl Lockbox

pub fn create(key: impl AsRef<[u8]>) -> Lockbox

pub fn create_with_options( key: impl AsRef<[u8]>, options: LockboxOptions, ) -> Lockbox

pub fn create_with_lockbox_id( key: impl AsRef<[u8]>, lockbox_id: LockboxId, ) -> Lockbox

pub fn create_with_lockbox_id_and_options( key: impl AsRef<[u8]>, lockbox_id: LockboxId, options: LockboxOptions, ) -> Lockbox

pub fn open_bytes_with_key( bytes: Vec<u8>, key: impl AsRef<[u8]>, ) -> Result<Lockbox, Error>

pub fn open_bytes_with_key_options( bytes: Vec<u8>, key: impl AsRef<[u8]>, options: LockboxOptions, ) -> Result<Lockbox, Error>

impl Lockbox

pub fn inspect_file( path: impl AsRef<Path>, ) -> Result<LockboxFileInspection, Error>

Inspect public lockbox metadata without decrypting stored contents.

This reads the lockbox header and key directory only. It does not open file contents and does not require a password, contact private key, or cached content key.

impl<State> Lockbox<State>

pub fn lockbox_id(&self) -> LockboxId

Return the stable id embedded in this lockbox.

pub fn owner_inspection(&self) -> Result<LockboxOwnerInspection, Error>

Return verified owner-signing metadata for this opened lockbox.

pub fn set_owner_signing_key(&mut self, keypair: OwnerSigningKeyPair)

where State: WritableLockboxState,

pub fn set_workload_profile(&mut self, profile: WorkloadProfile)

Set cache behavior tuned for the caller’s expected access pattern.

pub fn workload_profile(&self) -> WorkloadProfile

Return the currently selected workload profile.

pub fn set_worker_policy(&mut self, policy: WorkerPolicy)

Set the worker policy used for native page/frame preparation.

pub fn worker_policy(&self) -> WorkerPolicy

Return the currently selected worker policy.

pub fn reset_import_stats(&self)

Reset import diagnostic counters.

pub fn import_stats(&self) -> ImportStats

Return cumulative import diagnostic counters for this handle.

pub fn inspector(&self) -> LockboxInspector<'_, State>

Return a read-only diagnostics view for this lockbox.

Trait Implementations

impl<State> Debug for Lockbox<State>

where State: Debug,

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

Formats the value using the given formatter.