keyring-rs

keyring-rs copied to clipboard

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:

[dependencies]
keyring = "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 std::error::Error;

fn main() -> Result<(), Box<dyn Error>> {
    let service = "my_application";
    let username = "my_name";
    let entry = keyring::Entry::new(&service, &username);

    let password = "topS3cr3tP4$$w0rd";
    entry.set_password(&password)?;

    let password = entry.get_password()?;
    println!("My password is '{}'", password);

    entry.delete_password()?;
    println!("My password has been deleted");

    Ok(())
}

Errors

The get_password, set_password and delete_password functions return a Result which, if the operation was unsuccessful, can yield a keyring::Error with a platform-independent code that describes the error.

Examples

The keychain-rs project contains a sample application (cli) and a sample library (ios).

The application is a command-line interface to the keychain. 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 using standard Rust tests.

Known Issues

Because credentials identified with empty service, user, or target names are handled inconsistently at the platform layer, the library had inconsistent (and arguably buggy - see #86) behavior in this case. As of version 1.2, this inconsistency was eliminated by having the library always fail on access when using credentials created with empty strings via new or new_with_target. The prior platform-specific behavior can still be accessed, however, by using new_with_credential to produce the same credential that would have been produced before the change.

A better way to handle empty strings (and other problematic argument values) would be to allow Entry creation to fail gracefully on arguments that are known not to work on a given platform. That would be a breaking API change, however, so it will have to wait until the next major version.

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.

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!

• @bhkaminski
• @brotskydotcom
• @dario23
• @dten
• @gondolyr
• @jasikpark
• @jonathanmorley
• @jyuch
• @lexxvir
• @MaikKlein
• @Phrohdoh
• @Rukenshia
• @samuela
• @stankec
• @steveatinfincia

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.