Crate keyring

Keyring

This is a cross-platform library that does storage and retrieval of passwords (or other secrets) in an underlying platform-specific secure 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, macOS, and iOS.

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, optionally augmented by a target string (which can be used to distinguish two entries that have the same service name and user name). Entries support setting, getting, and forgetting (aka deleting) passwords (UTF-8 strings) and binary secrets (byte arrays).

Entries provide persistence for their passwords by wrapping credentials held in platform-specific credential stores. The implementations of these platform-specific stores are captured in two types (with associated traits):

• a credential builder, represented by the CredentialBuilder type (and CredentialBuilderApi trait). Credential builders are given the identifying information 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 a 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 it provides one or more implementations of credential stores on each platform. 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 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 with one or more features. These features control whether that store is included when the crate is built. For example, the macOS Keychain credential store is only included if the "apple-native" feature is specified (and the crate is built with a macOS target).

If no specified credential store features apply to a given platform, this crate will use the (platform-independent) mock credential store (see below) on that platform. Specifying multiple credential store features for a given platform is not supported, and will cause compile-time errors. There are no default features in this crate: you must specify explicitly which platform-specific credential stores you intend to use.

Here are the available credential store features:

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

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

• linux-native: Provides access to the keyutils storage on Linux.

• sync-secret-service: Provides access to the DBus-based Secret Service storage on Linux, FreeBSD, and OpenBSD. This is a synchronous keystore that provides support for encrypting secrets when they are transferred across the bus. If you wish to use this encryption support, additionally specify one (and only one) of the crypto-rust or crypto-openssl features (to choose the implementation libraries used for the encryption). By default, this keystore requires that the DBus library be installed on the user’s machine (and the openSSL library if you specify it for encryption), but you can avoid this requirement by specifying the vendored feature (which will cause the build to include those libraries statically).

• async-secret-service: Provides access to the DBus-based Secret Service storage on Linux, FreeBSD, and OpenBSD. This is an asynchronous keystore that always encrypts secrets when they are transferred across the bus. You must specify both an async runtime feature (either tokio or async-io) and a cryptographic implementation (either crypto-rust or crypto-openssl) when using this keystore. If you want to use openSSL encryption but those libraries are not installed on the user’s machine, specify the vendored feature to statically link them with the built crate.

Client-provided Credential Stores

In addition to the platform stores implemented by this crate, clients are free to provide their own secure stores 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.

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 secure-storage modules, 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.

Re-exports

• pub use credential::Credential;
• pub use credential::CredentialBuilder;
• pub use error::Error;
• pub use error::Result;
• pub use secret_service as default;

Modules

• credential
  Platform-independent secure storage model
• error
  Platform-independent error model.
• mock
  Mock credential store
• secret_service
  secret-service credential store

Structs

• Entry

Functions

• set_default_credential_builder
  Set the credential builder used by default to create entries.