Expand description
§Windows native credential store for the keyring crate
This module implements a credential store for the keyring crate that uses the Windows Credential Manager as its back end.
§Usage
To make this store the default for creation of keyring entries, execute this code:
keyring_core::set_default_store(windows_native_keyring_store::Store::new().unwrap())§Mapping service and user values to credentials
Each entry in keyring is mapped to a generic credential in the Windows Credential Manager.
The identifier for each credential in Windows is a target_name string. If an entry is created with
an explicit target modifier, that value is used as the target_name.
Otherwise, a target_name string is generated by concatenating a prefix string, the user,
a delimiter string, the service, and a suffix string. The prefix, delimiter, and suffix strings
are part of the store configuration. Their default values are: empty strings for the prefix and suffix,
and a ‘.’ for the delimiter.
Note that service and user strings, by default, can contain the delimiter string, so it is possible for entries with different service and user strings to map to the same description (and thus the same credential in the store). If you are worried about this, you can avoid it by configuring your store to forbid the delimiter string in the service string.
§Persistence Type
Each generic credential can have one of three persistence types, defined precisely in the Windows API here, and represented in this API by the CredPersist enumeration values Session, Local, and Enterprise.
By default, created credentials have Enterprise persistence,
but you can specify a desired persistence by using the persistence modifier at entry
creation time with a (case-insensitive) value of Session, Local, or Enterprise. Note
that this type will only be applied when the credential’s secret is written; it does not
control the persistence of an existing credential in the store whose value is read via the entry.
The persistence of an existing credential can be read and updated via its persistence attribute.
Note that updating this attribute on an existing credential does not update the remembered
persistence in the entry used to access that credential. Thus, setting the secret in a credential
always changes its persistence to match that specified when the entry was created.
§Attributes
In addition to the persistence attribute mentioned in the last section,
there are three string attributes that are held on each generic credential:
target_alias, username, and comment. The username attribute will be set
from the user specifier whenever an entry is written.
All four attributes on existing credentials can be read and set using the
get_attributes and
update_attributes methods.
§Warnings
Tests show that operating on the same entry from different threads
does not reliably sequence the operations in the same order they
are initiated. (For example, setting a password on one thread and
then immediately spawning another to get the password may return a
NoEntry error on the spawned thread.) So be careful not to
access the same entry on multiple threads simultaneously.
Tests show that changing a credential’s persistence type immediately before reading it may cause the read to fail, especially if the credential manager is busy on multiple threads.
Re-exports§
pub use cred::CredPersist;pub use store::Store;