keyring-core is a cross-platform library to manage storage and retrieval of passwords (and other secrets) in secure
credential stores. It provides the API used by the keyring CLI. If you are a
developer looking to integrate secret-management facilities into your app, this is the crate you should use as a
dependency, along with one or more keyring-compatible credential-stores.
To use this crate in your project, include it in your Cargo.toml:
keyring-core = "0.1"In your client code, set your default credential store using the set_default_store function. Then you can
use the Entry::new function to create a new keyring entry. The new function takes a service name and a user's name
which together identify the entry.
Passwords (strings) or secrets (binary data) can be added to an entry using its set_password or set_secret methods,
respectively. (These methods create or update an entry in your chosen credential store.) The password or secret can then
be read back using the get_password or get_secret methods. The underlying credential (with its password/secret data)
can be removed using the delete_credential method.
use keyring_core::{set_default_store, mock, Entry, Result};
fn main() -> Result<()> {
set_default_store(mock::default_store());
let entry = Entry::new("my-service", "my-name")?;
entry.set_password("topS3cr3tP4$$w0rd")?;
let password = entry.get_password()?;
println!("My password is '{}'", password);
entry.delete_credential()?;
Ok(())
}Creating and operating on entries can yield an Error enum that
classifies the error and, where relevant, includes underlying credential store errors or more information about what
went wrong.
This crate comes with two cross-platform credential stores that can be used by clients who want to test their credential-store independent logic. Neither of these stores are either secure or robust, so they should not be used in production.
The first of these is a mock store with no persistence which allows mocking errors as well as successes. The other is a sample store with file-based persistence. See the developer docs for details.
There are a few changes in the API since its last inclusion in the keyring crate v3:
- The older API expected credential stores to be singletons, so that each store module's
default_credential_storefunction could be called multiple times and relied on to return the same store. In the current API, credential stores can be objects with their own lifecycle, so they are given toset_default_credential_storevia anArcrather than aBox. - The new API is a lot more crisp about whether an entry has been created directly or has been created by wrapping a
credential, and what the difference between those two scenarios are. As a result, the Ambiguous error returns a list
of entries rather than a list of credentials, and it makes clear which of those entries (if any) is the one that holds
the credential that would have been created by the API on a
set_passwordcall.
Licensed under either of
- Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
- MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)
at your option.
The full list of library contributors may be found in the Contributors file.
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.