Keyring-rs
A cross-platform library to manage storage and retrieval of passwords (and other credential-like secrets) in the underlying platform secure store, with a fully-developed example that provides a command-line interface.
Published on crates.io
Usage
Currently supports Linux, iOS, macOS, and Windows. Please file issues if you have any problems or bugs!
To use this library in your project add the following to your Cargo.toml
file:
[]
= "1"
This will give you access to the keyring
crate in your code. Now you can use the Entry::new
function to create a new keyring entry. The new
function expects a non-empty service
name and a non-empty username
which together identify the entry.
Passwords can be added to an entry using its set_password
method. They can then be read back using the get_password
method, and deleted using the delete_password
method. (The persistence of the Entry
is determined via Rust rules, so deleting the password doesn't delete the entry, but it does delete the underlying platform credential which was used to store the password.)
extern crate keyring;
use Error;
Errors
Creating and operating on entries can yield a keyring::Error
which provides both a platform-independent code that classifies the error and, where available, underlying platform errors and/or more information about what went wrong.
Examples
The keychain-rs project contains a sample application (cli
) and a sample library (ios
).
The application is a command-line interface to the keyring. This can be a great way to explore how the library is used, and it allows experimentation with the use of different service names, usernames, and targets. When run in "singly verbose" mode (-v), it outputs the retrieved credentials on each get
run. When run in "doubly verbose" mode (-vv), it also outputs any errors returned. This can be a great way to see which errors result from which conditions on each platform.
The sample library is a full exercise of all the iOS functionality; it's meant to be loaded into an iOS test harness such as the one found in this project. While the library can be compiled and linked to on macOS as well, doing so doesn't provide any advantages over the standard macOS tests.
Client Testing
This crate comes with a "mock" credential store that can be used by clients who want to test without accessing the native platform store. The mock store is cross-platform and allows mocking errors as well as successes.
Extensibility
This crate comes with built-in support for the keychain on Mac, the credential manager on Windows, and both secret-service and the kernel keyring on Linux. But it's also designed to allow clients to "bring their own credential stores" by providing traits that clients can implement. See the developer docs for details.
Dev Notes
- We build using GitHub CI.
- Each tag is built on Ubuntu x64, Win 10 x64, and Mac intel x64. The
cli
example executable is posted for all platforms with the tag.
Headless Linux
If you are trying to use keyring on a headless linux box, be aware that there are known issues with getting dbus and secret-service and the gnome keyring to work properly in headless environments. For a quick workaround, look at how this project's CI workflow uses the linux-test.sh script; a similar solution is also documented in the Python Keyring docs (search for "Using Keyring on headless Linux systems"). For an excellent treatment of all the headless dbus issues, see this answer on ServerFault.
Note that you can build this crate without secret-service support; this makes the Linux keyring (which works normally on headless linux) the default credential store on Linux platforms.
License
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.
Contributors
Thanks to the following for helping make this library better, whether through contributing code, discussion, or bug reports!
- @Alexei-Barnes
- @bhkaminski
- @brotskydotcom
- @complexspaces
- @dario23
- @dten
- @gondolyr
- @hwchen
- @jasikpark
- @jkhsjdhjs
- @jonathanmorley
- @jyuch
- @landhb
- @lexxvir
- @MaikKlein
- @Phrohdoh
- @Rukenshia
- @samuela
- @stankec
- @steveatinfincia
- @Sytten
If you should be on this list, but don't find yourself, please contact @brotskydotcom.
Contribution
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.