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>

Commits pending mutations and serializes the complete lockbox.

File-backed lockboxes should normally use Lockbox::commit instead.

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,

Creates a form definition, or creates a new revision of its alias.

New definitions receive a random stable type id and an empty description.

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

where State: WritableLockboxState,

Creates or revises a form definition with descriptive text.

Aliases are convenient names but may become ambiguous after imported definitions; use a type id when deterministic resolution is required.

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,

Creates or revises a definition using a caller-supplied stable type id.

This is intended for synchronization and migration code that must preserve identity across lockboxes.

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,

Creates or revises a fully identified and described form definition.

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

where State: WritableLockboxState,

Appends the next revision for an existing form type.

Existing records keep their captured labels and revision until a field is next updated.

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

Resolves the newest form definition by type id or unambiguous alias.

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

Lists the newest revision of every form type in stable order.

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

Lists every stored revision for type_id, oldest first.

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

where State: WritableLockboxState,

Imports an exact definition revision without renumbering it.

Re-importing identical content is idempotent; conflicting content for the same type id and revision is rejected.

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

where State: WritableLockboxState,

Creates an empty record from the newest matching form definition.

type_reference may be a type id or unambiguous alias. The record path must not already exist.

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

Returns a cloned form record, or None when path has no record.

Secret field values remain in secure-memory containers.

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

Lists all form records in lockbox path order.

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

where State: WritableLockboxState,

Deletes the form record at path without deleting its definition.

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,

Sets a non-secret field after validating it against the latest definition.

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

where State: WritableLockboxState,

Copies a secret into the named secret field.

The supplied SecretString remains owned by the caller; the lockbox stores an independent secure clone. If the latest definition currently declares the field as non-secret, this operation appends a secret-field definition revision and securely upgrades that field in every record of the same form type. A secret field cannot be downgraded by setting a normal value.

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

where State: WritableLockboxState,

Sets a normal or secret field and captures its current label and revision.

Prefer Lockbox::set_form_field_normal and Lockbox::set_form_field_secret when the sensitivity is known.

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

Returns a cloned field value, or None when the record or field is absent.

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>

Creates an uncommitted in-memory lockbox protected by password.

A random content key is generated and wrapped in a password key slot. Call Lockbox::commit before serializing the lockbox.

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

Creates an uncommitted in-memory lockbox for a contact public key.

A random content key is generated and wrapped to contact. The contact recipient receives read-only access unless an owner signing key is set.

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

Opens in-memory lockbox bytes for writing using a password key slot.

Returns Error::InvalidKey when no password slot can be unwrapped.

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

Opens in-memory lockbox bytes using the matching contact private key.

Contact recipients open read-only unless the caller subsequently supplies the owner signing key through the supported binding API.

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 list_mirror_projects(&self) -> Result<Vec<MirrorProject>, Error>

Lists every configured mirror project in stable name order.

Project definitions are encrypted as hidden variables inside the lockbox, so they travel with the archive rather than relying on a separate host-side manifest.

pub fn mirror_project(&self, name: &str) -> Result<Option<MirrorProject>, Error>

Returns the named mirror project, or None when it is not configured.

impl<State> Lockbox<State>

where State: WritableLockboxState,

pub fn create_mirror_project( &mut self, project: MirrorProject, adopt: bool, ) -> Result<(), Error>

Stores a new mirror project without copying host files.

The destination must not overlap another project. A non-empty destination is rejected unless adopt is true; adoption makes the existing subtree managed without changing its current entries.

pub fn update_mirror_project( &mut self, project: &MirrorProject, ) -> Result<(), Error>

Replaces a mirror project’s stored configuration.

This is intended for explicit rule, policy, or host rebind operations. It performs the same name, path, rule, and overlap validation as creation but does not modify managed files. The destination is immutable; changing ownership requires forgetting or deleting the old project and explicitly creating a new one.

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

Forgets a mirror project while preserving its managed files.

After this call the former destination is an ordinary lockbox subtree and can be changed through the normal file APIs.

pub fn with_mirror_project_mutation<T>( &mut self, name: &str, operation: impl FnOnce(&mut Lockbox<State>, &MirrorProject) -> Result<T, Error>, ) -> Result<T, Error>

Runs a mutation scoped to one mirror’s managed directory.

Inside the callback the ordinary file mutation APIs accept paths at or below the selected destination and reject every path outside it. Outside the callback those APIs reject changes to all managed destinations. This lets higher-level clients reuse the normal file API while keeping project ownership enforcement in the core.

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,

Creates every missing parent directory required by path.

The path itself is not created.

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 description(&self) -> Result<Option<String>, Error>

Return the encrypted human-readable description of this lockbox.

The description is stored as ordinary encrypted lockbox metadata at /.revault/description. It is unavailable until the lockbox has been opened. Ok(None) means no description has been assigned.

Example

if let Some(description) = lockbox.description()? {
    println!("Lockbox purpose: {description}");
}

pub fn set_description(&mut self, description: &str) -> Result<(), Error>

where State: WritableLockboxState,

Store or replace this lockbox’s encrypted human-readable description.

description is UTF-8 text with the same validation and one-mebibyte size limit as a normal variable value. Call Lockbox::commit to authenticate and publish the change. Use Lockbox::clear_description to remove it.

Example

let mut lockbox = Lockbox::create_in_memory(
    LockboxProtection::Password(&password),
    &signing_key,
)?;
lockbox.set_description("Deployment credentials for Project Atlas")?;
lockbox.commit()?;

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

where State: WritableLockboxState,

Remove this lockbox’s encrypted description, if one is present.

Call Lockbox::commit to authenticate and publish the change. Repeated calls are safe.

Example

lockbox.clear_description()?;
lockbox.commit()?;

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, Error::AlreadyExists if the name conflicts with an existing variable directory, 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. An existing normal variable is upgraded to secret sensitivity atomically. Secret variables cannot be downgraded through Lockbox::set_variable; delete and recreate them to make that sensitivity reduction explicit.

Returns Error::InvalidInput if the secret plaintext contains unsupported characters, Error::SecurityLimitExceeded if the secret plaintext exceeds the configured variable value size limit, Error::AlreadyExists if the name conflicts with an existing variable directory, or 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

Creates an uncommitted, in-memory lockbox from a raw content key.

This low-level constructor is intended for language bindings and format migrations. Prefer Lockbox::create_in_memory in application code so the key is wrapped in an access slot before the lockbox is shared.

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

Creates an uncommitted in-memory lockbox with runtime tuning options.

The raw content key is copied into secure memory. The returned lockbox has no key slot until one is explicitly added.

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

Creates an uncommitted in-memory lockbox with a caller-supplied id.

This is primarily useful to preserve identity during a migration.

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

Creates an uncommitted in-memory lockbox with a supplied id and options.

This is the most configurable raw-key constructor used by bindings and migrations. Call Lockbox::commit before serializing the result.

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

Opens in-memory lockbox bytes for writing with a raw content key.

Integrity and format validation are performed before the lockbox is returned. Prefer password or contact-key opening in application code.

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

Opens in-memory lockbox bytes with a raw key and runtime tuning options.

The returned lockbox is writable and owns both the archive bytes and a secure copy of the content key.

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,

Sets the owner signing key used to authenticate subsequent commits.

The next commit records the public verification key and hybrid signatures. Opening that lockbox for later writes requires the same owner keypair.

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.