keyring-rs

If you are building an application that requires full control over specific credential stores, do not link directly against the keyring crate using the cli feature, as this will include unnecessary dependencies.

Instead, follow this pattern:

1. Take a dependency on the keyring-core crate.
2. Add the specific credential store crates you want to use as dependencies.
3. Use the sample code found in the cli module of the keyring crate as a reference for instantiating and accessing your desired stores.

To provide your application with the ability to set, get, and delete plain-text and binary secrets in native secure stores (Mac, Windows, and *nix), link to the keyring crate using the default v1 feature. This provides a simple wrapper around the native OS credential stores using the original 'v1' API.

/* Add to your Cargo.toml to use the default v1 API */
[dependencies]
keyring = "4.1.6"

For scripting keyring commands in Python, use the rust-native-keyring project on PyPI instead of the Rust CLI. This is more efficient for automation as it avoids the overhead of reloading stores for every single command.

Install via pip:

pip install rust-native-keyring

Use in Python:

import rust_native_keyring

The keyring-cli is a command-line interface used to issue individual keyring calls and examine results. It is useful for manual verification of credential store behavior.

To see available commands and usage information, run:

keyring-cli --help

Use use_named_store(name: &str) to set the default credential store using its string identifier. If the name is "sample", it defaults to a persistent sample store. For all other names, it uses default configurations. This function returns an Error::Invalid if the name is not recognized.

Available store names include:

• android
• keychain
• keyutils
• protected
• sample
• secret-service
• dbus-secret-service
• sqlite
• windows

use_named_store("keychain");

The Entry struct provides methods to manipulate data within the credential store:

Use use_native_store(prefer_secret_service: bool) to automatically select the most appropriate OS-provided credential store for the current platform.

Platform Behavior:

• Android: Uses android store.
• macOS: Uses keychain store.
• Windows: Uses windows store.
• Linux: Uses secret-service if prefer_secret_service is true; otherwise, uses keyutils.
• FreeBSD/OpenBSD: Uses secret-service store.
• Other: Falls back to the sample store.

If no native store is available, it defaults to the sample store.

use_native_store(true).unwrap();

The following functions allow you to manage the lifecycle and inspect the state of the global default store:

• release_store(): Unsets the current default store.
• store_info() -> String: Returns a debug description of the currently active default store. Returns "None" if no store is set.
• use_sample_store(config: &HashMap<&str, &str>): Sets the default store to the keyring-core::Sample store, which is available on all platforms.

The Entry type provides a high-level interface for managing text or binary secrets in the platform's native credential store. To use this API, you must enable the v1 feature in your Cargo.toml.

Supported platforms and stores:

• macOS: Keychain Services
• Windows: Windows Credential Manager
• *nix: Secret Service

Common operations include creating a new entry, setting/getting passwords (strings), setting/getting secrets (bytes), and deleting credentials.

use keyring::v1::Entry;

// Create a new entry
let entry = Entry::new("my_service", "my_username")?;

// Manage a text password
entry.set_password("my_password")?;
let password = entry.get_password()?;

// Manage a binary secret
entry.set_secret(b"binary_data")?;
let secret = entry.get_secret()?;

// Delete the credential
entry.delete_credential()?;