Merge pull request #245 from brotskydotcom/v4

Get to v4.0.0-beta.1

Author: brotskydotcom

Cargo.toml

@@ -6,7 +6,7 @@ keywords = ["password", "credential", "keychain", "secret-service", "cross-platf
 license = "MIT OR Apache-2.0"
 name = "keyring"
 repository = "https://github.com/hwchen/keyring-rs.git"
-version = "4.0.0-alpha.1"
+version = "4.0.0-beta.1"
 rust-version = "1.85"
 edition = "2024"
 exclude = [".github/"]

README.md

@@ -17,7 +17,7 @@ keyring = "4"
 
 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.
 
-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.
+Passwords (strings) or secrets (binary data) can be added to an entry using its `set_password` or `set_secret` methods, respectively. (These methods create or update 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.
 
 ```rust
 use keyring::{Entry, Result};
@@ -46,11 +46,11 @@ The `ios` library is a full exercise of all the iOS functionality; it's meant to
 
 ## 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.
+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. See the [developer docs](https://docs.rs/keyring/) for details.
 
 ## Extensibility
 
-This crate allows clients to "bring their own credential store" by providing traits that clients can implement. See the [developer docs](https://docs.rs/keyring/) for details.
+This crate allows clients to bring their own credential store by providing traits that clients can implement. See the [developer docs](https://docs.rs/keyring/) for details.
 
 ## Platforms
 
@@ -60,13 +60,15 @@ This crate provides built-in implementations of the following platform-specific
 * _macOS_, _iOS_: Keychain Services.
 * _Windows_: The Windows Credential Manager.
 
+It can be built and used on other platforms, but will not provide a built-in credential store implementation; you will have to bring your own.
+
 ### 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:
 
-* 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 crate to statically link the dbus library with your app.
+* The default build of this crate expects that `libdbus` will be installed on users' machines. If you have users whose machines might not have `libdbus` installed, you can specify the `vendored` feature when building this crate to statically link the dbus library with your app.
 * Every call to the Secret Service is done via an inter-process call, which takes time (typically tens if not hundreds of milliseconds).
 * 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.
 
@@ -76,11 +78,11 @@ The *macOS and iOS credential stores* do not allow service names or usernames to
 
 ## Upgrading from v3
 
-There are no functional API changes between v4 and v3; all the changes are in the keystores and how they are specified.
-
-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.
+There are no functional API changes between v4 and v3. All the changes are in the keystore implementations and how features are used to select keystores:
 
-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.
+* 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. These keystores are being contributed directly to the existing [secret-service](https://crates.io/crates/secret-service) and [linux-keyutils](https://crates.io/crates/linux-keyutils) crates, respectively.
+* Version 4 of this crate 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.
+* The built-in macOS keystore now supports use of the Data Protection keychain, which is the same keychain used by iOS. You can specify a target of "Data Protection" (or simply "Protected") to write and read credentials in that keychain. 
 
 All v2/v3 data is fully forward-compatible with v4 data; there have been no changes at all in that respect.
 

src/ios.rs

@@ -136,7 +136,7 @@ impl IosCredential {
             ));
         }
         if let Some(target) = target {
-            if target.to_ascii_lowercase() != "default" {
+            if !target.eq_ignore_ascii_case("default") {
                 return Err(ErrorCode::Invalid(
                     "target".to_string(),
                     "only 'default' is allowed".to_string(),
@@ -188,3 +188,98 @@ fn decode_error(err: Error) -> ErrorCode {
         _ => ErrorCode::PlatformFailure(Box::new(err)),
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::{IosCredential, default_credential_builder};
+    use crate::credential::CredentialPersistence;
+    use crate::{Entry, Error, tests::generate_random_string};
+
+    #[test]
+    fn test_persistence() {
+        assert!(matches!(
+            default_credential_builder().persistence(),
+            CredentialPersistence::UntilDelete
+        ))
+    }
+
+    fn entry_new(service: &str, user: &str) -> Entry {
+        crate::tests::entry_from_constructor(IosCredential::new_with_target, service, user)
+    }
+
+    #[test]
+    fn test_invalid_parameter() {
+        let credential = IosCredential::new_with_target(None, "", "user");
+        assert!(
+            matches!(credential, Err(Error::Invalid(_, _))),
+            "Created credential with empty service"
+        );
+        let credential = IosCredential::new_with_target(None, "service", "");
+        assert!(
+            matches!(credential, Err(Error::Invalid(_, _))),
+            "Created entry with empty user"
+        );
+        let credential = IosCredential::new_with_target(Some(""), "service", "user");
+        assert!(
+            matches!(credential, Err(Error::Invalid(_, _))),
+            "Created entry with empty target"
+        );
+    }
+
+    #[test]
+    fn test_missing_entry() {
+        crate::tests::test_missing_entry(entry_new);
+    }
+
+    #[test]
+    fn test_empty_password() {
+        crate::tests::test_empty_password(entry_new);
+    }
+
+    #[test]
+    fn test_round_trip_ascii_password() {
+        crate::tests::test_round_trip_ascii_password(entry_new);
+    }
+
+    #[test]
+    fn test_round_trip_non_ascii_password() {
+        crate::tests::test_round_trip_non_ascii_password(entry_new);
+    }
+
+    #[test]
+    fn test_round_trip_random_secret() {
+        crate::tests::test_round_trip_random_secret(entry_new);
+    }
+
+    #[test]
+    fn test_update() {
+        crate::tests::test_update(entry_new);
+    }
+
+    #[test]
+    fn test_get_credential() {
+        let name = generate_random_string();
+        let entry = entry_new(&name, &name);
+        let credential: &IosCredential = entry
+            .get_credential()
+            .downcast_ref()
+            .expect("Not a mac credential");
+        assert!(
+            credential.get_credential().is_err(),
+            "Platform credential shouldn't exist yet!"
+        );
+        entry
+            .set_password("test get_credential")
+            .expect("Can't set password for get_credential");
+        assert!(credential.get_credential().is_ok());
+        entry
+            .delete_credential()
+            .expect("Couldn't delete after get_credential");
+        assert!(matches!(entry.get_password(), Err(Error::NoEntry)));
+    }
+
+    #[test]
+    fn test_get_update_attributes() {
+        crate::tests::test_noop_get_update_attributes(entry_new);
+    }
+}

src/lib.rs

@@ -189,8 +189,8 @@ pub mod secret_service;
 #[cfg_attr(docsrs, doc(cfg(target_os = "macos")))]
 pub mod macos;
 
-#[cfg(all(target_os = "ios", feature = "apple-native"))]
-#[cfg_attr(docsrs, doc(cfg(target_os = "ios")))]
+#[cfg(all(any(target_os = "macos", target_os = "ios"), feature = "apple-native"))]
+#[cfg_attr(docsrs, doc(cfg(any(target_os = "macos", target_os = "ios"))))]
 pub mod ios;
 
 //
@@ -505,8 +505,7 @@ mod tests {
         }
     }
 
-    /// A basic round-trip unit test given an entry and a password.
-    pub fn test_round_trip(case: &str, entry: &Entry, in_pass: &str) {
+    fn test_round_trip_no_delete(case: &str, entry: &Entry, in_pass: &str) {
         entry
             .set_password(in_pass)
             .unwrap_or_else(|err| panic!("Can't set password for {case}: {err:?}"));
@@ -516,7 +515,12 @@ mod tests {
         assert_eq!(
             in_pass, out_pass,
             "Passwords don't match for {case}: set='{in_pass}', get='{out_pass}'",
-        );
+        )
+    }
+
+    /// A basic round-trip unit test given an entry and a password.
+    pub fn test_round_trip(case: &str, entry: &Entry, in_pass: &str) {
+        test_round_trip_no_delete(case, entry, in_pass);
         entry
             .delete_credential()
             .unwrap_or_else(|err| panic!("Can't delete password for {case}: {err:?}"));
@@ -637,7 +641,7 @@ mod tests {
     {
         let name = generate_random_string();
         let entry = f(&name, &name);
-        test_round_trip("initial ascii password", &entry, "test ascii password");
+        test_round_trip_no_delete("initial ascii password", &entry, "test ascii password");
         test_round_trip(
             "updated non-ascii password",
             &entry,