You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardexpand all lines: README.md
+17-26
Original file line number
Diff line number
Diff line change
@@ -9,15 +9,15 @@ A cross-platform library to manage storage and retrieval of passwords (and other
9
9
10
10
## Usage
11
11
12
-
To use this crate in your project, you must include it in your `Cargo.toml` and specify a feature for each supported credential store you want to use. For example, if you want to use the platform credential stores on Mac and Win, and use the Secret Service (synchronously) on Linux and \*nix platforms, you would add a snippet such as this to your `[dependencies]` section:
12
+
To use this crate in your project, include it in your `Cargo.toml` and don't disable the default features:
13
13
14
14
```toml
15
-
keyring = { version = "3", features = ["apple-native", "windows-native", "sync-secret-service"] }
15
+
keyring = "4"
16
16
```
17
17
18
18
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 takes a service name and a user's name which together identify the entry.
19
19
20
-
Passwords (strings) or secrets (binary data) can be added to an entry using its `set_password` or `set_secret` methods, respectively. (These methods create an entry in the underlying 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 then be removed using the `delete_credential` method.
20
+
Passwords (strings) or secrets (binary data) can be added to an entry using its `set_password` or `set_secret` methods, respectively. (These methods create an entry in the underlying platform's persistent 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 then be removed using the `delete_credential` method.
21
21
22
22
```rust
23
23
usekeyring::{Entry, Result};
@@ -40,9 +40,9 @@ Creating and operating on entries can yield a `keyring::Error` which provides bo
40
40
41
41
The keychain-rs project contains a sample application (`keyring-cli`) and a sample library (`ios`).
42
42
43
-
The `keyring-cli` application is a command-line interface to the full functionality of the keyring. Invoke it without arguments to see usage information. It handles binary data input and output using base64 encoding. It can be installed using `cargo install` and used to experiment with library functionality. It can also be used when debugging keyring-based applications to probe the contents of the credential store; just be sure to build it using the same features/credential stores that are used by your application.
43
+
The `keyring-cli` application is a command-line interface to the full functionality of the keyring. Invoke it without arguments to see usage information. It handles binary data input and output using base64 encoding. It can be installed using `cargo install` and used to experiment with library functionality. It can also be used when debugging keyring-based applications to probe the contents of the credential store.
44
44
45
-
The `ios` 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](https://github.com/brotskydotcom/rust-on-ios). While the library can be compiled and linked to on macOS as well, doing so doesn't provide any advantages over using the crate directly.
45
+
The `ios` 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](https://github.com/brotskydotcom/rust-on-ios).
46
46
47
47
## Client Testing
48
48
@@ -56,44 +56,35 @@ This crate allows clients to "bring their own credential store" by providing tra
56
56
57
57
This crate provides built-in implementations of the following platform-specific credential stores:
58
58
59
-
*_Linux_: The DBus-based Secret Service, the kernel keyutils, and a combo of the two.
60
-
*_FreeBSD_, _OpenBSD_: The DBus-based Secret Service.
61
-
*_macOS_, _iOS_: The local keychain.
59
+
*_Linux_, _FreeBSD_, _OpenBSD_: The DBus-based Secret Service.
60
+
*_macOS_, _iOS_: Keychain Services.
62
61
*_Windows_: The Windows Credential Manager.
63
62
64
-
To enable the stores you want, you use features: there is one feature for each possibly-included credential store. If you specify a feature (e.g., `dbus-secret-service`) _and_ your target platform (e.g., `freebsd`) supports that credential store, it will be included as the default credential store in that build. That way you can have a build command that specifies a single credential store for each of your target platforms, and use that same build command for all targets.
65
-
66
-
If you don't enable any credential stores that are supported on a given platform, the _mock_ keystore will be the default on that platform. See the [developer docs](https://docs.rs/keyring/) for details of which features control the inclusion of which credential stores.
67
-
68
63
### Platform-specific issues
69
64
70
65
Since neither the maintainers nor GitHub do testing on BSD variants, we rely on contributors to support these platforms. Thanks for your help!
71
66
72
67
If you use the *Secret Service* as your credential store, be aware of the following:
73
68
74
-
*Access to credential stores via this crate is always *synchronous*; that is, it blocks the thread on which it was invoked. This is true *even if* your feature set specifies using the Zbus-based `secret-service` crate, which offers an async interface, because this crate always uses the blocking interface. If your application is using an async runtime already, and you build with the `async-secret-service` feature in this crate, you should (1) specify the same async runtime you are using as a feature for this crate, and (2) be sure to have a separate thread that is used for all `keyring` calls that access the credential store. Failure to use a separate thread is known to cause deadlocks.
75
-
*Because credential store access from this crate is always synchronous, there is really no reason not to use the `sync-secret-service` feature (rather than `async-secret-service`) with this crate, *even if* your code is already using one of the async runtimes. Yes, this feature requires that `libdbus` be installed on your user’s machines, but it is by default in all desktop OS installs that include a Secret Service implementation (such as the Gnome Keyring or the KWallet). If you want to be extra careful, you can use the additional `vendored` feature to this crate to statically link the dbus library with your app so it’s not required on user machines. Just keep in mind that, in the event of an update to `libdbus`, using the `vendored` feature will require a rebuild of your app to get the `libdbus` update to your users.
76
-
*Every call to the Secret Service is done via an inter-process call, which takes time (typically tens if not hundreds of milliseconds). If, for some reason, your code is pounding on the Secret Service like a database, you will want to implement a write-through transactional backing cache to protect your users from slowdowns. The `mock` credential store can be adapted for this purpose.
69
+
*This implementation requires that `libdbus` be installed on user machines. If you have users whose machines might not have `libdbus` installed, you can specify the `vendored` when building this crateto statically link the dbus library with your app.
70
+
*Every call to the Secret Service is done via an inter-process call, which takes time (typically tens if not hundreds of milliseconds).
71
+
*By default, this implementation does not encrypt secrets when sending them to or fetching them from the Dbus. If you want them encrypted, you can specify the `encrypted` feature when building this crate.
77
72
78
73
If you use the *Windows-native credential store*, be careful about multi-threaded access, because the Windows credential store does not guarantee your calls will be serialized in the order they are made. Always access any single credential from just one thread at a time, and if you are doing operations on multiple credentials that require a particular serialization order, perform all those operations from the same thread.
79
74
80
-
The *macOS and iOS credential stores* do not allow service or user names to be empty, because empty fields are treated as wildcards on lookup. Use some default, non-empty value instead.
81
-
82
-
## Upgrading from v2
83
-
84
-
The major functional change between v2 and v3 is the addition of synchronous support for the Secret Service via the [dbus-secret-service crate](https://crates.io/crates/dbus-secret-service). This means that keyring users of the Secret Service no longer need to link with an async runtime. (There are other advantages as well; see [above](#platform-specific-issues) for details.)
75
+
The *macOS and iOS credential stores* do not allow service names or usernames to be empty, because empty fields are treated as wildcards on lookup. Use some default, non-empty value instead.
85
76
86
-
The main API change between v2 and v3 is the addition of support for non-string (i.e., binary) "password" data. To accommodate this, two changes have been made:
77
+
## Upgrading from v3
87
78
88
-
1.There are two new methods on `Entry` objects: `set_secret`and `get_secret`. These are the analogs of `set_password` and `get_password`, but instead of taking or returning strings they take or return binary data (byte arrays/vectors).
79
+
There are no functional API changes between v4 and v3; all the changes are in the keystores and how they are specified.
89
80
90
-
2. The v2 method `delete_password` has been renamed `delete_credential`, both to clarify what's actually being deleted and to emphasize that it doesn't matter whether it's holding a "password" or a "secret".
81
+
Version 4 of this crate removes a number of the built-in credential stores that were available in version 3, namely the async secret service and linux keyutils.
91
82
92
-
Another API change between v2 and v3 is that the notion of a default feature set has gone away: you must now specify explicitly which crate-supported keystores you want included (other than the `mock` keystore, which is always present). So all keyring client developers will need to update their `Cargo.toml` file to use the new features correctly.
83
+
Version 4 of this crate also dispenses with the need to explicitly specify which credential store you want to use on each platform. Instead, the default feature set provides a single credential store on each platform. If you would rather bring your own store, and not build this crate's built-in ones, you can simply suppress the default feature set.
93
84
94
-
All v2 data is fully forward-compatible with v3 data; there have been no changes at all in that respect.
85
+
All v2/v3 data is fully forward-compatible with v4 data; there have been no changes at all in that respect.
95
86
96
-
The MSRV has been moved to 1.75, and all direct dependencies are at their latest stable versions.
87
+
The Rust edition of this crate has moved to 2024, and the MSRV has moved to 1.85.
0 commit comments