# revault_lockbox_api
reVault lets people keep files and structured secrets in portable, encrypted
archives called **lockboxes**. A lockbox is a `.lbox` file that can be stored,
moved, backed up, or shared. Its contents are encrypted, and every change is
signed by its owner.
`revault_lockbox_api` is the Rust storage engine behind those lockboxes. Use it
when you are building an application, service, or language wrapper that needs
to create or read `.lbox` files directly. If you simply want to use reVault at
the terminal, start with
[revault_cli](https://crates.io/crates/revault_cli) instead.
Before the API details, these terms establish the model:
- A **lockbox** is the encrypted archive and its associated access rules.
- A **content key** is the random secret that encrypts a lockbox's contents.
- A **key slot** is a protected copy of the content key. A password or a
recipient's public key can unlock a slot without directly encrypting every
archive record.
- An **owner signing key** proves that a change was authorised by the lockbox
owner.
- A **vault** is a higher-level, local private store for profiles, contacts,
and lockbox keys. Vault management is provided by `revault_vault_api` and the
CLI, not by this crate.
This crate deliberately does not manage a local vault, active sessions,
command-line prompts, or agent caching. Those user-facing concerns live in
higher-level crates such as `revault_vault_api` and `revault_cli`.
For the complete ecosystem overview, see the
[reVault project README](https://github.com/onepub-dev/reVault#readme).
## Purpose
Use `revault_lockbox_api` when an application needs direct access to the lockbox file
format:
- create password, content-key, or contact-protected lockboxes
- store files, directories, symlinks, variables, and form records
- read and list lockbox contents without the CLI
- update lockbox contents with explicit owner signing
- inspect public lockbox metadata
- recover intact records from damaged lockbox files
- build native, server-side, or WASM wrappers around the core API
## Storage Capabilities
A lockbox is an encrypted archive with structured metadata. It can hold:
- **Files**: in-memory bytes, reader streams, and files imported from the host
filesystem.
- **Directory-like paths**: lockbox paths are canonical internal paths such as
`/docs/readme.txt`; directories are represented by the paths of stored
entries.
- **Permissions**: file mode bits can be stored with file records and restored
by extraction policies on platforms that support them.
- **Symlinks**: lockbox symlinks store an internal source path and internal
target path.
- **Variables**: named metadata values that are not exposed as files and do not
appear in normal file listings.
- **Secret variables**: variable values stored in secure memory while opened and
accessed through callback APIs.
- **Forms**: versioned form definitions plus form records with normal and
secret fields. This supports structured data such as login records without
flattening everything into files.
- **Key slots**: password and contact key slots can open the same random
lockbox content key.
- **Key-directory backups**: higher-level vault code can keep encrypted backup
copies of key-directory data for recovery flows.
## Encryption And Authentication
Lockbox storage uses a random content key to encrypt file data and private
metadata. Passwords and contacts do not encrypt archive contents directly; they
open or wrap the content key.
- **Content encryption**: pages are encrypted and authenticated with
ChaCha20-Poly1305.
- **Password slots**: pass phrases are stretched with Argon2id and used to wrap
the content key with ChaCha20-Poly1305.
- **Contact slots**: contact sharing uses a hybrid pre-quantum and
post-quantum key wrap: X25519 plus ML-KEM-768 derive the wrapping key, then
ChaCha20-Poly1305 encrypts the content key.
- **Commit authentication**: owner commits are signed with both Ed25519 and
ML-DSA-65. Verification requires both signatures to be present and valid.
- **Explicit write authority**: `Lockbox::open` returns a read-only handle;
mutating an existing lockbox requires `Lockbox::open_for_write` and an
owner signing key.
The hybrid design keeps a mature pre-quantum primitive in the path while adding
post-quantum protection. For key wrapping, an attacker should need to break both
the X25519 and ML-KEM-768 sides to recover the wrapping key. For commit
authentication, requiring both Ed25519 and ML-DSA-65 avoids treating a commit as
authentic unless it verifies under both the established classical signature and
the post-quantum signature.
## Compression And Layout
Lockbox compresses before storing encrypted payloads when compression is useful.
High-entropy data is detected and left uncompressed to avoid wasting space or
CPU. Repeated or text-like data is stored with zstd compression.
The archive layout is optimized for both small and large records:
- small files and metadata can be packed into shared pages;
- larger file payloads can be split across compression frames;
- decoded page and compression-frame caches accelerate repeated reads;
- workload profiles tune import, read-mostly, and extraction-heavy workloads;
- recovery scanning can rebuild intact files, symlinks, variables, and forms
from damaged lockboxes when enough records survive.
## Integration Surface
The optional `vault-integration` feature exposes a narrow API used by
`revault_vault_api` for content-key caching and key-directory backup recovery.
Normal callers should use the standard `Lockbox` open/create APIs.
## Archive Format
The on-disk `.lbox` format is described in
[archive format reference](https://github.com/onepub-dev/reVault/blob/master/rust/revault_lockbox_api/ARCHIVE_FORMAT.md). That document covers the fixed header,
pages, page objects, commit roots, commit authentication, TOC, variables, forms,
key directories, and recovery rules.
Implementation notes such as page-cache boundaries, compaction flow, key
removal maintenance, and recovery scan behavior are in
[implementation guide](https://github.com/onepub-dev/reVault/blob/master/rust/revault_lockbox_api/IMPLEMENTATION_GUIDE.md).
## Create And Read A Lockbox
```rust
use revault_lockbox_api::{
Lockbox, LockboxOpen, LockboxPath, LockboxProtection, OwnerSigningKeyPair,
SecretString,
};
fn main() -> revault_lockbox_api::Result<()> {
let path = std::path::Path::new("example.lbox");
let pass_phrase = SecretString::try_from_bytes(b"correct horse battery staple".to_vec())?;
let signing_key = OwnerSigningKeyPair::generate()?;
let mut lockbox = Lockbox::create_file(
path,
LockboxProtection::Password(&pass_phrase),
&signing_key,
)?;
lockbox.add_file(
&LockboxPath::new("/notes/hello.txt")?,
b"hello from reVault",
false,
)?;
lockbox.commit()?;
let opened = Lockbox::open(path, LockboxOpen::Password(&pass_phrase))?;
let bytes = opened.get_file(&LockboxPath::new("/notes/hello.txt")?)?;
assert_eq!(bytes, b"hello from reVault");
Ok(())
}
```
## Reopen For Mutation
Opening a lockbox with `Lockbox::open` is intentionally read-only. To
modify an existing lockbox, reopen it for write and provide the owner signing
key that should sign the next commit.
```rust
use revault_lockbox_api::{
Lockbox, LockboxOpen, LockboxPath, LockboxProtection, OwnerSigningKeyPair,
SecretString,
};
fn main() -> revault_lockbox_api::Result<()> {
let path = std::path::Path::new("mutable.lbox");
let pass_phrase = SecretString::try_from_bytes(b"correct horse battery staple".to_vec())?;
let signing_key = OwnerSigningKeyPair::generate()?;
Lockbox::create_file(
path,
LockboxProtection::Password(&pass_phrase),
&signing_key,
)?;
let mut lockbox = Lockbox::open_for_write(
path,
LockboxOpen::Password(&pass_phrase),
&signing_key,
)?;
lockbox.add_file(&LockboxPath::new("/updated.txt")?, b"updated", false)?;
lockbox.commit()?;
Ok(())
}
```
In a real application, keep the owner signing key somewhere durable and
protected. The local vault does this for CLI-managed lockboxes.
## Worked Examples
The `examples/` directory contains runnable examples for the main archive
features:
- `files_and_directories.rs`: add in-memory and host files, then list and read
them.
- `symlinks_and_permissions.rs`: preserve executable permissions and store a
lockbox symlink.
- `variables.rs`: store normal and secret variables.
- `forms.rs`: define a form, create a record, and store normal and secret
fields.
- `recovery.rs`: damage a lockbox, scan it, and salvage intact records.
Run one with:
```sh
cargo run -p revault_lockbox_api --example files_and_directories
```
## Benchmarks
Core archive performance benchmarks live in `benches/`. See
`BENCHMARKS.md` for Criterion usage, the reproducible PGP comparison harness,
sample results, and profiler notes.
See the [reVault repository README](https://github.com/onepub-dev/reVault#readme)
for the complete project overview.