Struct Vault 

pub struct Vault { /* private fields */ }

Implementations

impl Vault

pub fn open_or_create(path: Option<&Path>) -> Result<Self>

Open an existing database or create a new one if it doesn’t exist.

This function initializes a database instance from a given file system path. If a path is provided, it attempts to use that specific path. If no path is provided (None is passed), it will determine a default database path using the default_db_path function.

Parameters

• path - An optional reference to a path (Option<&Path>). If Some, the database will be opened or created at the specified path. If None, a default path is used.

Returns

• Result<Self> - On success, returns an instance of Self with an open database. If any operation fails (e.g., obtaining the default path or opening the database), an error is returned.

Errors

This function returns an error if:

• Obtaining the default database path via default_db_path fails.
• Opening the database at the specified or default path fails.

pub fn open_default() -> Result<Self>

Opens the default instance of a resource.

This function attempts to open the default instance of a resource. If the default instance does not exist, it will create a new one. The specific behavior of this function depends on the implementation of Self::open_or_create.

Returns

• Result<Self> - If successful, returns an instance of the resource wrapped in Ok. If an error occurs during the opening or creation process, it returns an Err containing the corresponding error.

Errors

This function will return an error if the resource cannot be opened or created for any reason, such as insufficient permissions or missing configuration.

pub fn db_path(&self) -> &Path

pub fn get_backup_config(&self) -> Result<BackupConfig>

Retrieves the backup configuration for the system.

This function attempts to load the backup configuration from a JSON file stored in the directory containing the database. If the configuration file does not exist, a default BackupConfig instance is returned.

Behavior

• The configuration file is named backup_config.json, and its location is inferred based on the parent directory of the db_path provided.
• If the parent directory cannot be determined, the current directory (".") is used as the fallback location to look for the configuration file.
• The function reads the contents of the file and deserializes it into a BackupConfig object using serde_json.
• If the file does not exist, the function returns the default BackupConfig object.

Errors

This function may return an error in the following scenarios:

• If the configuration file exists, but reading its contents fails, an std::io::Error is returned.
• If deserialization of the file content into a BackupConfig object fails, a serde_json::Error is returned.

Returns

A Result wrapping the backup configuration:

• Ok(BackupConfig) if the configuration is successfully loaded or the default configuration is returned.
• Err if an error occurs while reading or deserializing the configuration file.

pub fn set_backup_config(&self, config: &BackupConfig) -> Result<()>

Sets the backup configuration for the database by saving it to a file named backup_config.json in the parent directory of the database path.

The method performs the following steps:

1. Resolves the backup_config.json file path in the parent directory of self.db_path.
2. Ensures the parent directory for the file exists, creating it if necessary.
3. Serializes the BackupConfig object to a pretty-printed JSON string.
4. Writes the serialized JSON string to the file.

Arguments

• config - A reference to a BackupConfig object containing the backup configuration settings that will be saved to the file.

Returns

• Ok(()) if the backup configuration is successfully saved.
• Err if any file system or serialization operation fails.

Errors

This function can return an error in the following cases:

• Failure to create the parent directory for the config file.
• Failure to serialize the BackupConfig object into a JSON string.
• Failure to write the serialized JSON string to the file.

pub fn get_db_path(&self) -> &Path

Get the database path for this vault

pub fn is_initialized(&self) -> bool

pub fn initialize(&mut self, master: &str) -> Result<()>

Initializes the storage system with a master key.

This function is used to initialize the storage backend only if it has not been initialized already. It generates a vault key that is securely wrapped using the derived master key, and then stores the necessary metadata in the database.

Parameters

• master: A reference to a string slice representing the master key. This key is used as the input to derive a secure key for wrapping the vault key.

Returns

• Ok(()): If the storage is successfully initialized or was already initialized.
• Err: If any step in the initialization process fails (e.g., key derivation, key wrapping, or database write).

Implementation Details

• First, the function checks whether the storage system has already been initialized using the is_initialized() method. If true, it immediately returns Ok(()).
• The function then generates secure key derivation parameters (KdfParams) using KdfParams::default_secure().
• Using the provided master key and the key derivation parameters, a derived key is computed (derive_key function).
• A new random vault key is generated (KeyMaterial::random()), which serves as the key to encrypt secure data.
• The vault key is securely wrapped using the derived master key, resulting in the wrapped key and a verifier (wrap_vault_key function).
• The derived key, wrapped vault key, and verifier are then persisted into the database by calling db.write_meta.

Errors

• Fails with an error if:
  • The master key derivation fails.
  • The vault key wrapping fails.
  • Writing the required metadata to the database fails.
• Errors are returned as a Result::Err, allowing the caller to handle the failure.

pub fn unlock(&mut self, master: &str) -> Result<()>

Unlocks the vault using the provided master key.

This function attempts to unlock a vault instance by using the given master key. It reads the metadata from the vault, validates the provided master key against the verifier, and upon successful verification, derives and stores the corresponding vault key.

Arguments

• master - A string slice representing the master key used to unlock the vault.

Returns

• Ok(()) - If the vault is successfully unlocked and the vault key is derived.
• Err - If the vault metadata is uninitialized, the derived master key is invalid, or there is an issue during the unlocking process.

Errors

This function can return the following errors wrapped in a Result:

• eyre!("Vault not initialized") - If the vault metadata is not present.
• eyre!("Invalid master key") - If the provided master key is invalid or fails verification.
• Other errors arising from key derivation or vault key unwrapping.

Implementation Details

1. Reads metadata from the vault, including a key derivation function (KDF) configuration (kdf), a wrapped vault key (wrapped), and a verifier.
2. Derives a key from the provided master key using the KDF.
3. Verifies the derived key against the verifier. If the verification fails, returns an error.
4. Attempts to unwrap the vault key using the derived key. Upon success, stores the derived vault key (vk) within the instance’s key field.

pub const fn is_unlocked(&self) -> bool

pub fn list_items(&self) -> Result<Vec<Item>>

Retrieves a list of items from the database, decrypting their stored values.

Returns

• Ok(Vec<Item>): A vector of decrypted items if the operation is successful.
• Err(anyhow::Error): An error if the database is locked, decryption fails, or another issue occurs.

Implementation Details

1. The function attempts to retrieve the encryption key (vk) from the self.key field. If the key is unavailable, an error is returned with the message "Locked".
2. The database records are fetched using self.db.list_items().
3. For each record:
   • The ciphertext is decrypted using aead_decrypt with the provided nonce, ciphertext, and additional authentication data (AAD).
   • The decrypted plaintext is converted to a UTF-8 string to derive the item’s value.
   • An Item is constructed with the decrypted and existing meta-information, such as id, name, kind, and timestamps.
4. The constructed items are aggregated into a Vec<Item> and returned.

Errors

• Returns an error if:
  • The encryption key is not available (e.g., when the data store is locked).
  • The database query fails.
  • The decryption operation fails (e.g., due to invalid data).
  • The plaintext fails UTF-8 validation.
  • An invalid ItemKind is provided.

Dependencies

• aead_decrypt: A function used to decrypt the encrypted data.
• String::from_utf8: Used to convert decrypted data into a String.
• ItemKind::from_str: Parses the kind field into its corresponding ItemKind enum variant.

Notes

• Ensure self.key is properly initialized before calling this method.
• The database schema must provide the required fields for each item: id, name, kind, ciphertext, nonce, and timestamps.

pub fn get_item_by_name(&self, name: &str) -> Result<Option<Item>>

Retrieves an item by its name from the list of items.

This method searches for an item in the collection of items maintained by the instance. It returns the first item that matches the provided name, if it exists.

Parameters

• name: The name of the item to search for, provided as a string slice (&str).

Returns

• Ok(Some(Item)): If an item with the given name is found.
• Ok(None): If no item with the given name exists in the collection.
• Err(Error): If an error occurs while retrieving the list of items.

Errors

This function will return an error if the call to self.list_items() fails.

pub fn create_item(&mut self, item: &NewItem) -> Result<()>

Creates a new item and inserts it into the database.

This function encrypts the value of the provided item using an AEAD encryption scheme and then stores the encrypted data, along with additional metadata, in the database. The encryption process uses the key stored within the struct and associates the encrypted value with the provided item’s name and kind.

Parameters

• item: A reference to a NewItem, containing the data required to create the item.

Returns

• Ok(()) on successful encryption and insertion of the item.
• Err(anyhow::Error) if any step of the process fails, including:
  • The key is not available (when the struct is in a “Locked” state).
  • Failure during the encryption process.
  • Errors encountered during the database insertion.

Errors

This function returns an error in the following scenarios:

• If the struct’s key field is None, indicating it is locked.
• If encryption fails for any reason.
• If the database insertion fails.

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

Deletes an item from the database with the specified ID.

Parameters

• id (i64): The unique identifier of the item to be deleted.

Returns

• Result<()>: Returns Ok(()) if the item is successfully deleted, or an error if the deletion fails.

Errors

This function will return an error if:

• The item with the specified ID does not exist.
• There is a failure in the underlying database operation.

pub fn change_master_key( &mut self, current_master: &str, new_master: &str, ) -> Result<()>

Changes the master key for the vault.

This function updates the master key used to protect the vault by verifying the current master key and re-encrypting the vault key using the new master key. It also updates the key derivation function (KDF) parameters for the new master key and persists the updated metadata in the database.

Arguments

• current_master - The currently active master key used to protect the vault. This must be provided to verify the existing setup and decrypt the vault key.
• new_master - The new master key to which the vault will be re-encrypted. It must conform to the same security requirements as the old master key.

Returns

• Result<()> - Returns Ok(()) on successful master key change, or an error if the operation fails. Possible error cases include:
  • The vault is not initialized.
  • The provided current_master key is invalid.
  • Issues with deriving keys, unwrapping the vault key, or re-wrapping with the new key.
  • Errors while persisting the updated metadata.

Behavior

1. Reads the current metadata (KDF parameters, wrapped key, and verifier) from the database.
2. Validates the current_master key using the stored KDF parameters and verifier.
3. Unwraps the vault key using the current_master key.
4. Generates new secure KDF parameters for the new_master key.
5. Derives a key from the new_master and wraps the vault key with it, generating a new verifier.
6. Writes the new KDF parameters, wrapped key, and verifier to the metadata in the database.
7. Updates the in-memory vault key if it is already unlocked.

Errors

• Returns an error if the vault has not been initialized (e.g., no metadata exists yet).
• Returns an error if the current_master key fails verification or cannot unwrap the vault key.
• Returns an error for any issues in key operations (e.g., deriving, wrapping, or unwrapping).
• Returns an error if writing the updated metadata to the database fails.

Notes

The updated master key takes effect immediately upon successful execution of this function. Ensure that the new_master key is securely stored and managed to prevent loss of access to the vault.

pub fn update_item(&mut self, id: u64, new_value: &str) -> Result<()>

Updates an item in the database with a new value, preserving the item’s associated metadata.

Parameters

• id: The unique identifier of the item to be updated.
• new_value: A reference to the new string value that will replace the current value of the item.

Returns

• Ok(()): If the operation is successful.
• Err: Returns an error in the following scenarios:
  • If the encryption key (self.key) is not available (locked).
  • If the specified item with the given id is not found in the list.
  • If there’s any failure during the encryption or database update.

Behavior

1. Verifies that the encryption key (self.key) is available. If not, an error is returned.
2. Retrieves the list of items stored and searches for the item matching the provided id.
3. If the item is found, constructs authenticated data (AD) using the item’s metadata (name and kind).
4. Encrypts the new_value using the encryption key (vk), the new value, and the constructed AD.
5. Updates the item in the database with the newly encrypted value and its corresponding nonce.

Errors

• If the encryption key is missing, an eyre!("Locked") error is returned.
• If the item is not found, an eyre!("Item not found") error is returned.
• Any failures during encryption or database operations propagate as errors.

pub fn open_by_id(vault_id: &str) -> Result<Self>

Opens an existing vault by its ID.

This function attempts to load the VaultRegistry and retrieves the vault information associated with the given vault_id. If the specified vault ID does not exist in the registry, it returns an error. If found, it proceeds to open or create the vault at the associated path.

Arguments

• vault_id - A string slice that represents the unique identifier of the vault to open.

Returns

• Ok(Self) - Returns an instance of the vault if the operation succeeds.
• Err(anyhow::Error) - Returns an error if the vault cannot be found, if the registry fails to load, or if the vault cannot be opened or created.

Errors

This function will return an error in the following cases:

• The VaultRegistry fails to load.
• The vault with the given vault_id is not found

pub fn create_new_vault( name: String, path: Option<PathBuf>, category: VaultCategory, description: Option<String>, master_password: &str, ) -> Result<(String, Self)>

Creates a new vault with the specified parameters.

Parameters

• name: The name of the vault to be created.
• path: An optional PathBuf specifying the directory path of the vault. If None, a default path is used.
• category: An instance of VaultCategory indicating the category for the vault (e.g., Personal, Business).
• description: An optional description providing additional details about the vault.
• master_password: A reference to a string containing the master password used for securing the vault.

Returns

• Ok((String, Self)): Returns a tuple containing:
  • String: The unique ID of the newly created vault.
  • Self: The newly initialized vault instance.
• Err(_): Returns an error if the vault creation or initialization process fails.

Errors

This function may return an error in the following cases:

• If the VaultRegistry fails to load.
• If the vault cannot be created in the registry (e.g., due to duplicate names or invalid paths).
• If the vault cannot be opened or initialized (e.g., due to issues with the provided path or master password).

Panics

Notes

• The vault ID generated is unique and can be used to reference the vault in the future.
• Initializing the vault with the master password is required to securely store and access its contents.

pub fn get_vault_id(&self) -> Result<Option<String>>

Retrieves the vault ID associated with the current instance’s database path (db_path).

This function searches through the VaultRegistry to locate a vault entry whose path matches the db_path of the current instance. If a match is found, the corresponding vault ID is returned. If no match is found, None is returned.

Returns

• Ok(Some(String)) if a matching vault ID is found in the registry.
• Ok(None) if no matching vault ID is found.
• Err if there is an issue loading the VaultRegistry.

Errors

This function may return an error if the VaultRegistry cannot be loaded properly.

pub fn open_active() -> Result<Self>

Opens the currently active vault.

This function retrieves the active vault from the VaultRegistry and attempts to open it. If no active vault is found in the registry, an error is returned. If a vault exists, it is either opened or created at the path associated with the active vault.

Returns

• Ok(Self) - If the active vault is successfully opened or created.
• Err(anyhow::Error) - If no active vault is found or an error occurs during the opening or creation process.

Errors

This function will return an error in the following cases:

• The VaultRegistry cannot be loaded.
• No active vault exists in the registry.
• An error occurs while trying to open or create the vault.

Trait Implementations

impl Clone for Vault

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Vault

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

Formats the value using the given formatter.