Struct UnlockedKeyring 

pub struct UnlockedKeyring { /* private fields */ }

File backed keyring.

Implementations

impl UnlockedKeyring

pub async fn load( path: impl AsRef<Path>, secret: Option<Secret>, ) -> Result<Self, Error>

Load from a keyring file.

Arguments

• path - The path to the file backend.
• secret - The service key, usually retrieved from the Secrets portal. Pass None for unencrypted keyrings.

pub async unsafe fn load_unchecked( path: impl AsRef<Path>, secret: Secret, ) -> Result<Self, Error>

Load from a keyring file without validating the secret.

Arguments

• path - The path to the file backend.
• secret - The service key, usually retrieved from the Secrets portal.

Safety

This method skips validation and doesn’t verify that the secret can decrypt all items in the keyring. Use only for recovery scenarios where you need to access a partially corrupted keyring. The keyring may contain items that cannot be decrypted with the provided secret, and writing new items may use a different secret than existing items.

pub async fn temporary(secret: Secret) -> Result<Self, Error>

Creates a temporary backend, that is never stored on disk.

pub async fn temporary_unencrypted() -> Result<Self, Error>

Creates a temporary unencrypted backend, that is never stored on disk.

pub async fn load_from_v0( source: impl AsRef<Path>, target_path: impl Into<PathBuf>, secret: Option<Secret>, ) -> Result<Self, Error>

Load a v0 (legacy gnome-keyring) file and migrate it to v1 format.

The migrated keyring will be written to target_path when write() is called.

Arguments

• source - Path to the legacy v0 keyring file.
• target_path - Where the v1 keyring should be stored.
• secret - The encryption secret, or None for unencrypted keyrings.

pub async fn open(name: &str, secret: Option<Secret>) -> Result<Self, Error>

Open a keyring with given name from the default directory.

This function will automatically migrate the keyring to the latest format.

Arguments

• name - The name of the keyring.
• secret - The service key, usually retrieved from the Secrets portal.

pub async fn open_at( data_dir: impl AsRef<Path>, name: &str, secret: Option<Secret>, ) -> Result<Self, Error>

Open or create a keyring at a specific data directory.

This is useful for tests and cases where you want explicit control over where keyrings are stored, avoiding the default XDG_DATA_HOME location.

This function will automatically migrate the keyring to the latest format.

Arguments

• data_dir - Base data directory (keyrings stored in data_dir/keyrings/v1/)
• name - The name of the keyring.
• secret - The service key, usually retrieved from the Secrets portal.

Example

let temp_dir = tempfile::tempdir()?;
let keyring = UnlockedKeyring::open_at(
    temp_dir.path(),
    "test-keyring",
    Some(Secret::from("password")),
)
.await?;
keyring
    .create_item("item", &[("attr", "value")], Secret::text("secret"), false)
    .await?;
keyring.write().await?; // Writes to temp_dir/keyrings/v1/test-keyring.keyring
//

pub fn lock(self) -> LockedKeyring

Lock the keyring.

pub async fn lock_item(&self, item: UnlockedItem) -> Result<LockedItem, Error>

Lock an item using the keyring’s key.

pub async fn unlock_item(&self, item: LockedItem) -> Result<UnlockedItem, Error>

Unlock an item using the keyring’s key.

pub async fn key(&self) -> Result<Option<Arc<Key>>, Error>

Get the encryption key for this keyring.

Returns None for unencrypted keyrings.

pub fn path(&self) -> Option<&Path>

Return the associated file if any.

pub async fn modified_time(&self) -> Duration

Get the modification timestamp

pub async fn n_items(&self) -> usize

Retrieve the number of items

This function will not trigger a key derivation and can therefore be faster than items().len().

pub async fn all_items( &self, ) -> Result<Vec<Result<UnlockedItem, InvalidItemError>>, Error>

Retrieve all items including those that cannot be decrypted.

Returns a Vec where each element is either an UnlockedItem or an InvalidItemError for items that failed to decrypt.

Use this method when you need to know about or handle decryption failures. For most use cases, items() is more convenient as it only returns successfully decrypted items.

pub async fn items(&self) -> Result<Vec<UnlockedItem>, Error>

Retrieve the list of available UnlockedItems.

Items that cannot be decrypted are silently skipped. Use all_items() if you need access to decryption errors.

pub async fn search_items( &self, attributes: &impl AsAttributes, ) -> Result<Vec<UnlockedItem>, Error>

Search items matching the attributes.

pub async fn lookup_item( &self, attributes: &impl AsAttributes, ) -> Result<Option<UnlockedItem>, Error>

Find the first item matching the attributes.

pub async fn lookup_item_index( &self, attributes: &impl AsAttributes, ) -> Result<Option<usize>, Error>

Find the index in the list of items of the first item matching the attributes.

pub async fn delete(&self, attributes: &impl AsAttributes) -> Result<(), Error>

Delete an item.

pub async fn create_item( &self, label: &str, attributes: &impl AsAttributes, secret: impl Into<Secret>, replace: bool, ) -> Result<UnlockedItem, Error>

Create a new item

Arguments

• label - A user visible label of the item.
• attributes - A map of key/value attributes, used to find the item later.
• secret - The secret to store.
• replace - Whether to replace the value if the attributes matches an existing secret.

pub async fn replace_item_index( &self, index: usize, item: &UnlockedItem, ) -> Result<(), Error>

Replaces item at the given index.

The index refers to the index of the Vec returned by items(). If the index does not exist, the functions returns an error.

pub async fn delete_item_index(&self, index: usize) -> Result<(), Error>

Deletes item at the given index.

The index refers to the index of the Vec returned by items(). If the index does not exist, the functions returns an error.

pub async fn create_items( &self, items: Vec<ItemDefinition>, ) -> Result<(), Error>

Create multiple items in a single operation to avoid re-writing the file multiple times.

This is more efficient than calling create_item() multiple times.

pub async fn write(&self) -> Result<(), Error>

Write the changes to the keyring file.

pub async fn change_secret(&self, secret: Secret) -> Result<(), Error>

Change keyring secret

Arguments

• secret - The new secret to store.

pub async fn validate_secret(&self, secret: &Secret) -> Result<bool, Error>

Validate that a secret can decrypt the items in this keyring.

For empty keyrings, this always returns true since there are no items to validate against.

Arguments

• secret - The secret to validate.

pub async fn validate_unencrypted(&self) -> Result<bool, Error>

pub async fn delete_broken_items(&self) -> Result<usize, Error>

Delete any item that cannot be decrypted with the key associated to the keyring.

This can only happen if an item was created using Self::load_unchecked or prior to 0.4 where we didn’t validate the secret when using Self::load or modified externally.

Trait Implementations

impl Debug for UnlockedKeyring

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

Formats the value using the given formatter.

impl From<UnlockedKeyring> for Keyring

fn from(keyring: UnlockedKeyring) -> Self

Converts to this type from the input type.