Crate uv_keyring 

Keyring

This is a cross-platform library that does storage and retrieval of passwords (or other secrets) in an underlying platform-specific secure credential store. A top-level introduction to the library’s usage, as well as a small code sample, may be found in the library’s entry on crates.io. Currently supported platforms are Linux, FreeBSD, OpenBSD, Windows, and macOS.

Design

This crate implements a very simple, platform-independent concrete object called an entry. Each entry is identified by a <service name, user name> pair of UTF-8 strings. Entries support setting, getting, and forgetting (aka deleting) passwords (UTF-8 strings) and binary secrets (byte arrays). Each created entry provides security and persistence of its secret by wrapping a credential held in a platform-specific, secure credential store.

The cross-platform API for creating an entry supports specifying an (optional) UTF-8 target attribute on entries, but the meaning of this attribute is credential-store (and thus platform) specific, and should not be thought of as part of the credential’s identification. See the documentation of each credential store to understand the effect of specifying the target attribute on entries in that store, as well as which values are allowed for target by that store.

The platform-specific credential identified for an entry provides the secure storage for that entry’s password or secret.

Crate-provided Credential Stores

This crate runs on several different platforms, and on each one it provides (by default) an implementation of a default credential store used on that platform by Entry::new. These implementations work by mapping the data used to identify an entry to data used to identify platform-specific storage objects. For example, on macOS, the service and user provided for an entry are mapped to the service and user attributes that identify a generic credential in the macOS keychain.

Typically, platform-specific credential stores (called keystores in this crate) have a richer model of a credential than the one used by this crate to identify entries. These keystores expose their specific model in the concrete credential objects they use to implement the Credential trait. In order to allow clients to access this richer model, the Credential trait has an as_any method that returns a reference to the underlying concrete object typed as Any, so that it can be downgraded to its concrete type.

Credential store features

Each of the platform-specific credential stores is associated a feature. This feature controls whether that store is included when the crate is built for its specific platform. For example, the macOS Keychain credential store implementation is only included if the "apple-native" feature is specified and the crate is built with a macOS target.

The available credential store features, listed here, are all included in the default feature set:

• apple-native: Provides access to the Keychain credential store on macOS.

• windows-native: Provides access to the Windows Credential Store on Windows.

• secret-service: Provides access to Secret Service.

If you suppress the default feature set when building this crate, and you don’t separately specify one of the included keystore features for your platform, then no keystore will be built in and calls to Entry::new will fail.

Interoperability with Third Parties

Each of the platform-specific credential stores provided by this crate uses an underlying store that may also be used by modules written in other languages. If you want to interoperate with these third party credential writers, then you will need to understand the details of how the target, service, and user of this crate’s generic model are used to identify credentials in the platform-specific store. These details are in the implementation of this crate’s keystores, and are documented in the headers of those modules.

(N.B. Since the included credential store implementations are platform-specific, you may need to use the Platform drop-down on docs.rs to view the storage module documentation for your desired platform.)

Caveats

This module expects passwords to be UTF-8 encoded strings, so if a third party has stored an arbitrary byte string then retrieving that as a password will return a BadEncoding error. The returned error will have the raw bytes attached, so you can access them, but you can also just fetch them directly using get_secret rather than get_password.

While this crate’s code is thread-safe, the underlying credential stores may not handle access from different threads reliably. In particular, accessing the same credential from multiple threads at the same time can fail, especially on Windows and Linux, because the accesses may not be serialized in the same order they are made. And for RPC-based credential stores such as the dbus-based Secret Service, accesses from multiple threads (and even the same thread very quickly) are not recommended, as they may cause the RPC mechanism to fail.

Structs

Entry

Enums

Error

Each variant of the Error enum provides a summary of the error. More details, if relevant, are contained in the associated value, which may be platform-specific.

Type Aliases

Credential

A thread-safe implementation of the Credential API.

Result