Module keyring::credential

Defines the credential model for each supported platform.

This crate has a very simple model of a keyring: it has any number of entries, each of which is identified by a <username, service> pair, has no other metadata, and has a UTF-8 string as its “password”. Furthermore, there is only one keyring.

This crate runs on several different platforms, each of which has its own secure storage system with its own model for what constitutes a “generic” secure credential: where it is stored, how it is identified, what metadata it has, and what kind of “password” it allows. These platform credentials provide the persistence for keyring entries.

In order to bridge the gap between the keyring entry model and each platform’s credential model, this crate uses a “credential mapper”: a function which maps from keyring entries to platform credentials. The inputs to a credential mapper are the platform, optional target specification, service, and username of the keyring entry; its output is a platform-specific “recipe” for identifying and annotating the platform credential which the crate will use for this entry.

This module provides a credential model for each supported platform, and a credential mapper which the crate uses by default. The default credential mapper can be “advised” by providing a suggested “target” when creating an entry: on Linux and Mac this target is interpreted as the collection/keychain to put the credential in; on Windows this target is taken literally as the “target name” of the credential.

Clients who want to use a different algorithm for mapping service/username pairs to platform credentials can also provide the specific credential spec they want to use when creating the entry.

See the top-level library documentation for more information about the platform-specific credential mapping. Or read the code here :).

Structs

IosCredential

iOS credentials all go in the user keychain identified by service and account.

LinuxCredential

Linux supports multiple credential stores, each named by a string. Credentials in a store are identified by an arbitrary collection of attributes, and each can have “label” metadata for use in graphical editors.

MacCredential

MacOS supports multiple OS-provided credential stores, and used to support creating arbitrary new credential stores (but that has been deprecated). Credentials on Mac also can have “type” but we don’t reflect that here because the type is actually opaque once set and is only used in the Keychain UI.

WinCredential

Windows has only one credential store, and each credential is identified by a single string called the “target name”. But generic credentials also have three pieces of metadata with suggestive names.

Enums

MacKeychainDomain

There are four pre-defined Mac keychains. Now that file-based keychains are deprecated, those are the only domains that can be accessed.

Platform

The supported platforms.

PlatformCredential

While defined cross-platform, instantiated platform credentials always contain just the model for the current runtime Platform.

Functions

default_target

Create the default target credential for a keyring entry. The caller can provide an optional target parameter to influence the mapping.