Crate uv_keyring Copy item path

§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 abstract behavior of entries and credential stores are captured by two types (with associated traits):

• a credential builder, represented by the CredentialBuilder type (and CredentialBuilderApi trait). Credential builders are given the identifying information (and target, if any) provided for an entry and map it to the identifying information for a platform-specific credential.
• a credential, represented by the Credential type (and CredentialApi trait). The platform-specific credential identified by the builder for an entry is what provides the secure storage for that entry’s password/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 (see default_credential_builder). 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 and Entry::new_with_target will fail unless the client brings their own keystore (see next section).

§Client-provided Credential Stores

In addition to the keystores implemented by this crate, clients are free to provide their own keystores and use those. There are two mechanisms provided for this:

• Clients can give their desired credential builder to the crate for use by the Entry::new and Entry::new_with_target calls. This is done by making a call to set_default_credential_builder. The major advantage of this approach is that client code remains independent of the credential builder being used.

• Clients can construct their concrete credentials directly and then turn them into entries by using the Entry::new_with_credential call. The major advantage of this approach is that credentials can be identified however clients want, rather than being restricted to the simple model used by this crate.

§Mock Credential Store

In addition to the platform-specific credential stores, this crate always provides a mock credential store that clients can use to test their code in a platform independent way. The mock credential store allows for pre-setting errors as well as password values to be returned from Entry method calls. If you want to use the mock credential store as your default in tests, make this call:

uv_keyring::set_default_credential_builder(uv_keyring::mock::default_credential_builder())

§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.