Merge pull request #115 from brotskydotcom/final-tweaks-for-release

brotskydotcom · web-flow · commit 276599942845 · 2023-02-18T18:57:28.000-08:00
Lots of doc updates and a few API cleanups. Also: FreeBSD support. This support is experimental because we don't do CI on FreeBSD so have to rely on field reports. Fixes #36. Contributed by @ryanvella.
diff --git a/.github/workflows/build.yaml b/.github/workflows/build.yaml
@@ -1,4 +1,4 @@
-name: Rust build (stable)
+name: build
 
 on: [workflow_dispatch, push, pull_request]
 
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,9 +1,14 @@
 ## Version 2.0
-- Introduce traits for pluggable credential-store implementations.
+- (API change) Allow creation of entries to fail.
+- (API change) Introduce an ambiguous error on credential lookup.
+- (API change) Make the `Error` enum non-exhaustive.
+- (API change) Introduce traits for pluggable credential-store implementations.  (This removes the old `platform` module.)
 - Add a `mock` credential store for easy cross-platform client testing.
-- Use service-level search in secret-service.
+- Upgrade to secret-service v3.
+- Always use service-level search in secret-service.
 - Allow creation of new collections in secret-service.
-- Add the kernel keyring as a linux credential store.
+- Add the kernel keyutils as a linux credential store.
+- Add build support for FreeBSD (thanks @ryanavella).
 
 ## Version 1.2.1
 - password length was not validated correctly on Windows (#85)
diff --git a/Cargo.toml b/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 = "2.0.0-rc.3"
+version = "2.0.0"
 edition = "2021"
 exclude = [".github/"]
 readme = "README.md"
@@ -34,6 +34,9 @@ security-framework = "2.6"
 secret-service = { version = "3", optional = true }
 linux-keyutils = { version = "0.2", features = ["std"] }
 
+[target.'cfg(target_os = "freebsd")'.dependencies]
+secret-service = { version = "3", optional = true }
+
 [target.'cfg(target_os = "windows")'.dependencies]
 byteorder = "1.2"
 winapi = { version =  "0.3", features = ["wincred", "winerror", "errhandlingapi", "minwindef"] }
diff --git a/README.md b/README.md
@@ -1,17 +1,15 @@
 ## Keyring-rs
-[![CI](https://github.com/hwchen/keyring-rs/actions/workflows/build.yaml/badge.svg)](https://github.com/hwchen/keyring-rs/actions?query=workflow%3Abuild)
-[![Crates.io](https://img.shields.io/crates/v/keyring.svg?style=flat-square)](https://crates.io/crates/keyring)
-[![API Documentation on docs.rs](https://docs.rs/keyring/badge.svg)](https://docs.rs/keyring)
+[![build](https://github.com/hwchen/keyring-rs/actions/workflows/build.yaml/badge.svg)](https://github.com/hwchen/keyring-rs/actions)
+[![dependencies](https://deps.rs/repo/github/hwchen/keyring-rs/status.svg)](https://github.com/hwchen/keyring-rs)
+[![crates.io](https://img.shields.io/crates/v/keyring.svg?style=flat-square)](https://crates.io/crates/keyring)
+[![docs.rs](https://docs.rs/keyring/badge.svg)](https://docs.rs/keyring)
 
 A cross-platform library to manage storage and retrieval of passwords
 (and other secrets) in the underlying platform secure store, 
 with a fully-developed example that provides a command-line interface.
 
 ## Usage
 
-**Currently supports Linux, iOS, macOS, and Windows.**
-Please file issues if you have have questions or problems.
-
 To use this library in your project add the following to your `Cargo.toml` file:
 
 ```toml
@@ -26,11 +24,7 @@ and a user name 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 removed 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 is used to store the password.)
+and removed using the `delete_password` method.
 
 ```rust
 use keyring::{Entry, Result};
@@ -57,16 +51,12 @@ underlying platform errors or more information about what went wrong.
 The keychain-rs project contains a sample application (`cli`) 
 and a sample library (`ios`).
 
-The application is a command-line interface to the keyring.  
+The `cli` application is a command-line interface to the keyring. 
 It can be used to explore how the library is used.
 It can also be used in debugging keyring-based applications
 to probe the contents of the credential store.
-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.
 
-The sample library is a full exercise of all the iOS functionality; 
+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).
@@ -75,23 +65,55 @@ doing so doesn't provide any advantages over the standard macOS tests.
 
 ## Client Testing
 
-This crate comes with a "mock" credential store
+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 keyutils on Linux.
-But it's also designed to allow clients 
-to "bring their own credential stores" 
+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/latest/keyring/) 
 for details.
 
+## Platforms
+
+This crate provides secure storage support for
+Linux (secret-service and kernel keyutils),
+iOS (keychain), macOS (keychain),
+and Windows (credential manager).
+
+It also builds on FreeBSD (secret-service),
+and probably works there,
+but since neither the maintainers nor GitHub do
+building and testing on FreeBSD, we can't be sure.
+
+Please file issues if you have questions or problems.
+
+## Upgrading from v1
+
+The v2 release,
+although it adds a lot of functionality relative to v1,
+is fully compatible with respect to persisted entry data:
+it will both read and set passwords on entries that were
+originally written by v1, and entries written
+by v2 will be readable and updatable by v1.
+
+From a client API point of view, the biggest difference
+between v2 and v1 is that entry creation using `Entry::new`
+and `Entry::new_with_target` can now fail, so v1 client
+code will need to add an `unwrap` or other error handling
+in order to work with v2.
+
+There are also new `Error` variants in v2, and the enum
+has been declared non-exhaustive (to allow for variants
+to be added without breaking client code).
+This means that v1 client code that relies on exhaustive
+matching will need to be updated.
+
 ## License
 
 Licensed under either of
@@ -123,6 +145,7 @@ whether through contributing code, discussion, or bug reports!
 - @MaikKlein
 - @Phrohdoh
 - @Rukenshia
+- @ryanavella
 - @samuela
 - @stankec
 - @steveatinfincia
diff --git a/examples/cli.rs b/examples/cli.rs
@@ -83,6 +83,9 @@ fn execute_set_password(description: &str, entry: &Entry, password: &str) {
         Ok(()) => {
             println!("(Password for '{description}' set successfully)")
         }
+        Err(Error::Ambiguous(creds)) => {
+            eprintln!("More than one credential found for {description}: {creds:?}")
+        }
         Err(err) => {
             eprintln!("Couldn't set password for '{description}': {err}",);
         }
@@ -110,7 +113,10 @@ fn execute_delete_password(description: &str, entry: &Entry) {
     match entry.delete_password() {
         Ok(()) => println!("(Password for '{description}' deleted)"),
         Err(Error::NoEntry) => {
-            eprintln!("(No password for '{description}' found)");
+            eprintln!("(No password found for '{description}')");
+        }
+        Err(Error::Ambiguous(creds)) => {
+            eprintln!("More than one credential found for {description}: {creds:?}")
         }
         Err(err) => {
             eprintln!("Couldn't delete password for '{description}': {err}",);
diff --git a/src/error.rs b/src/error.rs
@@ -1,6 +1,6 @@
 /*!
 
-Defines a platform-independent error model.
+Platform-independent error model.
 
 There is an escape hatch here for surfacing platform-specific
 error information returned by the platform-specific storage provider,
diff --git a/src/ios.rs b/src/ios.rs
@@ -1,6 +1,6 @@
 /*!
 
-# iOS Keychain Credential Store
+# iOS Keychain credential store
 
 iOS credential stores are called Keychains.  On iOS there is only one of these.
 Generic credentials on iOS can be identified by a large number of _key/value_ attributes;
diff --git a/src/keyutils.rs b/src/keyutils.rs
@@ -1,6 +1,6 @@
 /*!
 
-# Linux kernel credential store (via keyutils)
+# Linux kernel (keyutils) credential store
 
 Modern linux kernels have a built-in secure store, [keyutils](https://www.man7.org/linux/man-pages/man7/keyutils.7.html).
 This module (written primarily by [@landhb](https://github.com/landhb)) uses that secure store
diff --git a/src/lib.rs b/src/lib.rs
@@ -122,6 +122,11 @@ use crate::secret_service as default;
 #[cfg(all(target_os = "linux", feature = "linux-default-keyutils"))]
 use keyutils as default;
 
+#[cfg(target_os = "freebsd")]
+pub mod secret_service;
+#[cfg(target_os = "freebsd")]
+use crate::secret_service as default;
+
 #[cfg(target_os = "windows")]
 pub mod windows;
 #[cfg(target_os = "windows")]
diff --git a/src/macos.rs b/src/macos.rs
@@ -1,6 +1,6 @@
 /*!
 
-# macOS Keychain Credential Store
+# macOS Keychain credential store
 
 macOS credential stores are called keychains.
 The OS automatically creates three of them (or four if removable media is being used).
diff --git a/src/mock.rs b/src/mock.rs
@@ -1,6 +1,6 @@
 /*!
 
-# Mock Credential Store
+# Mock credential store
 
 To facilitate testing of clients, this crate provides a Mock credential store
 that is platform-independent, provides no persistence, and allows the client
diff --git a/src/secret_service.rs b/src/secret_service.rs
@@ -1,6 +1,6 @@
 /*!
 
-# secret-service Credential Store
+# secret-service credential store
 
 Items in the secret-service are identified by an arbitrary collection
 of attributes, and each has "label" for use in graphical editors.  This
diff --git a/src/windows.rs b/src/windows.rs
@@ -1,6 +1,6 @@
 /*!
 
-# Windows Crendential Manager Credential Store
+# Windows Crendential Manager credential store
 
 This module uses Windows Generic credentials to store entries.
 These are identified by a single string (called their _target name_).

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-name: Rust build (stable)`
	`1`	`+name: build`
`2`	`2`
`3`	`3`	`on: [workflow_dispatch, push, pull_request]`
`4`	`4`