Struct Vault 

pub struct Vault { /* private fields */ }

A vault that stores its master key in the OS keychain and delegates encryption/decryption to encryptman.

Each Vault instance is bound to a service name (and optionally a target username) that identifies the keychain entry. The same service name is also used as the HKDF context in encryptman, so different service names produce different encryption keys from the same underlying keychain entry.

Examples

use encryptman_keyring::Vault;

let vault = Vault::new("my-app").unwrap();
let ct = vault.encrypt("secret").unwrap();
let pt = vault.decrypt(&ct).unwrap();
assert_eq!(pt, "secret");
Vault::delete("my-app").unwrap();

Implementations

impl Vault

pub fn new(service: &str) -> Result<Self, Error>

Create or open a vault with the given service name.

On first call, a new random master key is generated and stored in the OS keychain. On subsequent calls, the existing key is loaded.

The service is used as the keyring service name and as the encryptman HKDF context ("encryptman:{service}").

Errors

Returns Error::Keychain if the OS keychain is unavailable.

pub fn new_with_target(service: &str, target: &str) -> Result<Self, Error>

Create or open a vault with a custom target (username) in the keyring.

This is useful when multiple independent vaults are needed within the same service namespace.

Errors

Returns Error::Keychain if the OS keychain is unavailable.

pub fn migrate_from_file(service: &str, key_path: &Path) -> Result<Self, Error>

Migrate a file-based key into the OS keychain.

Reads a 32-byte key from key_path, stores it in the keychain under the given service name, and deletes the file on success.

Returns the vault ready for use.

Errors

• Error::FileRead if the file cannot be read.
• Error::InvalidFileKeyLength if the file is not exactly 32 bytes.
• Error::Keychain if the OS keychain is unavailable.

pub fn migrate_from_file_with_target( service: &str, target: &str, key_path: &Path, ) -> Result<Self, Error>

Migrate a file-based key with a custom target (username).

See Vault::migrate_from_file for details.

pub fn encrypt(&self, plaintext: &str) -> Result<String, Error>

Encrypt a plaintext string using the vault’s master key.

Delegates to encryptman::encrypt. Each call produces a unique ciphertext (random nonce).

Errors

Returns Error::Crypto if encryption fails.

pub fn decrypt(&self, ciphertext: &str) -> Result<String, Error>

Decrypt a ciphertext string using the vault’s master key.

Delegates to encryptman::decrypt.

Errors

Returns Error::Crypto if decryption fails (wrong key, corrupted data, or invalid base64).

pub fn encrypt_with_context( &self, context: &str, plaintext: &str, ) -> Result<String, Error>

Encrypt with a custom HKDF context.

The context is appended to "encryptman:" to derive a domain-specific AES key from the master key.

Errors

Returns Error::Crypto if encryption fails.

pub fn decrypt_with_context( &self, context: &str, ciphertext: &str, ) -> Result<String, Error>

Decrypt with a custom HKDF context.

The context must match the one used during encryption.

Errors

Returns Error::Crypto if decryption fails.

pub fn master_key(&self) -> &MasterKey

Return a reference to the underlying master key.

This is useful when you need direct access to the key for advanced use cases (e.g., custom encryption contexts or binary data).

pub fn encrypt_bytes(&self, plaintext: &[u8]) -> Result<Vec<u8>, Error>

Encrypt arbitrary bytes using the vault’s master key.

Delegates to encryptman::encrypt_bytes_with_context using the vault’s service name as context.

Errors

Returns Error::Crypto if encryption fails.

pub fn decrypt_bytes(&self, packed: &[u8]) -> Result<Vec<u8>, Error>

Decrypt arbitrary bytes using the vault’s master key.

Delegates to encryptman::decrypt_bytes_with_context using the vault’s service name as context.

Errors

Returns Error::Crypto if decryption fails.

pub fn encrypt_bytes_with_context( &self, context: &str, plaintext: &[u8], ) -> Result<Vec<u8>, Error>

Encrypt arbitrary bytes with a custom HKDF context.

Errors

Returns Error::Crypto if encryption fails.

pub fn decrypt_bytes_with_context( &self, context: &str, packed: &[u8], ) -> Result<Vec<u8>, Error>

Decrypt arbitrary bytes with a custom HKDF context.

Errors

Returns Error::Crypto if decryption fails.

pub fn delete(service: &str) -> Result<(), Error>

Delete the master key from the OS keychain.

This is an associated function because deletion only requires the service name — no vault instance (or master key) is needed.

Warning: This is destructive. All encrypted data will become unrecoverable unless you have a backup of the key.

Errors

Returns Error::Keychain if the keychain entry cannot be deleted.

pub fn delete_with_target(service: &str, target: &str) -> Result<(), Error>

Delete the master key with a custom target from the OS keychain.

This is an associated function — no vault instance needed.

See Vault::delete for details.

Trait Implementations

impl Debug for Vault

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

Formats the value using the given formatter.