Merge pull request #199 from brotskydotcom/doc-fixes

Update the README for known platform issues.  This will be version 3.0.5

Author: brotskydotcom

Cargo.toml

@@ -6,7 +6,7 @@ keywords = ["password", "credential", "keychain", "keyring", "cross-platform"]
 license = "MIT OR Apache-2.0"
 name = "keyring"
 repository = "https://github.com/hwchen/keyring-rs.git"
-version = "3.0.4"
+version = "3.0.5"
 rust-version = "1.75"
 edition = "2021"
 exclude = [".github/"]

README.md

@@ -65,11 +65,23 @@ To enable the stores you want, you use features: there is one feature for each p
 
 If you don't enable any credential stores that are supported on a specific target, the _mock_ keystore will be the default on that target. If you enable multiple credential stores for a specific target, you will get a compile error. See the [developer docs](https://docs.rs/keyring/) for details of which features control the inclusion of which credential stores (and which platforms each credential store targets).
 
-Please note: Since neither the maintainers nor GitHub do testing on BSD variants, we rely on contributors to support these platforms. Thanks for your help!
+### Platform-specific issues
+
+Since neither the maintainers nor GitHub do testing on BSD variants, we rely on contributors to support these platforms. Thanks for your help!
+
+If you use the *Secret Service* as your credential store, be aware of the following:
+
+* 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.
+* 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.
+* 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.
+
+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.
+
+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.
 
 ## Upgrading from v2
 
-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.
+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.)
 
 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:
 

build-xplat-binaries.sh

@@ -27,13 +27,13 @@ credential stores.  The implementations of these platform-specific stores are ca
 in two types (with associated traits):
 
 - a _credential builder_, represented by the [CredentialBuilder] type
-(and [CredentialBuilderApi](credential::CredentialBuilderApi) trait).  Credential
-builders are given the identifying information provided for an entry and map
-it to the identifying information for a platform-specific credential.
+  (and [CredentialBuilderApi](credential::CredentialBuilderApi) trait).  Credential
+  builders are given the identifying information provided for an entry and map
+  it to the identifying information for a platform-specific credential.
 - a _credential_, represented by the [Credential] type
-(and [CredentialApi](credential::CredentialApi) trait).  The platform-specific credential
-identified by a builder for an entry is what provides the secure storage
-for that entry's password/secret.
+  (and [CredentialApi](credential::CredentialApi) trait).  The platform-specific credential
+  identified by a builder for an entry is what provides the secure storage
+  for that entry's password/secret.
 
 ## Crate-provided Credential Stores
 
@@ -72,32 +72,32 @@ credential stores you intend to use.
 
 Here are the available credential store features:
 
-* `apple-native`: Provides access to the Keychain credential store on macOS and iOS.
-
-* `windows-native`: Provides access to the Windows Credential Store on Windows.
-
-* `linux-native`: Provides access to the `keyutils` storage on Linux.
-
-* `sync-secret-service`: Provides access to the DBus-based
-[Secret Service](https://specifications.freedesktop.org/secret-service/latest/)
-storage on Linux, FreeBSD, and OpenBSD.  This is a _synchronous_ keystore that provides
-support for encrypting secrets when they are transferred across the bus. If you wish
-to use this encryption support, additionally specify one (and only one) of the
-`crypto-rust` or `crypto-openssl` features (to choose the implementation libraries
-used for the encryption). By default, this keystore requires that the DBus library be
-installed on the user's machine (and the openSSL library if you specify it for
-encryption), but you can avoid this requirement by specifying the `vendored` feature
-(which will cause the build to include those libraries statically).
-
-* `async-secret-service`: Provides access to the DBus-based
-[Secret Service](https://specifications.freedesktop.org/secret-service/latest/)
-storage on Linux, FreeBSD, and OpenBSD.  This is an _asynchronous_ keystore that
-always encrypts secrets when they are transferred across the bus. You _must_ specify
-both an async runtime feature (either `tokio` or `async-io`) and a cryptographic
-implementation (either `crypto-rust` or `crypto-openssl`) when using this
-keystore. If you want to use openSSL encryption but those libraries are not
-installed on the user's machine, specify the `vendored` feature
-to statically link them with the built crate.
+- `apple-native`: Provides access to the Keychain credential store on macOS and iOS.
+
+- `windows-native`: Provides access to the Windows Credential Store on Windows.
+
+- `linux-native`: Provides access to the `keyutils` storage on Linux.
+
+- `sync-secret-service`: Provides access to the DBus-based
+  [Secret Service](https://specifications.freedesktop.org/secret-service/latest/)
+  storage on Linux, FreeBSD, and OpenBSD.  This is a _synchronous_ keystore that provides
+  support for encrypting secrets when they are transferred across the bus. If you wish
+  to use this encryption support, additionally specify one (and only one) of the
+  `crypto-rust` or `crypto-openssl` features (to choose the implementation libraries
+  used for the encryption). By default, this keystore requires that the DBus library be
+  installed on the user's machine (and the openSSL library if you specify it for
+  encryption), but you can avoid this requirement by specifying the `vendored` feature
+  (which will cause the build to include those libraries statically).
+
+- `async-secret-service`: Provides access to the DBus-based
+  [Secret Service](https://specifications.freedesktop.org/secret-service/latest/)
+  storage on Linux, FreeBSD, and OpenBSD.  This is an _asynchronous_ keystore that
+  always encrypts secrets when they are transferred across the bus. You _must_ specify
+  both an async runtime feature (either `tokio` or `async-io`) and a cryptographic
+  implementation (either `crypto-rust` or `crypto-openssl`) when using this
+  keystore. If you want to use openSSL encryption but those libraries are not
+  installed on the user's machine, specify the `vendored` feature
+  to statically link them with the built crate.
 
 ## Client-provided Credential Stores
 
@@ -106,16 +106,16 @@ are free to provide their own secure stores and use those.  There are
 two mechanisms provided for this:
 
 - Clients can give their desired credential builder to the crate
-for use by the [Entry::new] and [Entry::new_with_target] calls.
-This is done by making a call to [set_default_credential_builder].
-The major advantage of this approach is that client code remains
-independent of the credential builder being used.
+  for use by the [Entry::new] and [Entry::new_with_target] calls.
+  This is done by making a call to [set_default_credential_builder].
+  The major advantage of this approach is that client code remains
+  independent of the credential builder being used.
 
 - Clients can construct their concrete credentials directly and
-then turn them into entries by using the [Entry::new_with_credential]
-call. The major advantage of this approach is that credentials
-can be identified however clients want, rather than being restricted
-to the simple model used by this crate.
+  then turn them into entries by using the [Entry::new_with_credential]
+  call. The major advantage of this approach is that credentials
+  can be identified however clients want, rather than being restricted
+  to the simple model used by this crate.
 
 ## Mock Credential Store
 

src/lib.rs

@@ -67,7 +67,7 @@ fn test_simultaneous_create_then_move() {
 }
 
 #[test]
-#[cfg(any(not(target_os = "windows"), feature = "windows-test-threading"))]
+#[cfg(not(target_os = "windows"))]
 fn test_create_set_then_move() {
     let name = generate_random_string();
     let entry = Entry::new(&name, &name).expect("Can't create entry");