SecureStore 0.100.0

This is a major update to both the securestore crate and the ssclient companion CLI app. Care has been taken not to break any existing code for the most common scenarios; please let us know if you run into any problems by opening a GitHub issue: https://github.com/neosmart/securestore-rs/

Documentation Updates

First, some notes about the documentation, which has seen the lion's share of improvements and will probably be the most noticeable change for new SecureStore users:

• The documentation has been completely overhauled. This includes the crate docs, the securestore repo readme, the ssclient repo readme, and the overall repo readme.
• The crate documentation has been expanded to assume zero previous knowledge of the SecureStore protocol, and is sufficient on its own without any of the repo READMEs to get one off the ground with the securestore crate.
• An overall project repo README has been added that provides a holistic overview of the SecureStore for rust project, with an annotated walkthrough indicating how a typical user would create a new SecureStore vault, add secrets to it, and access those secrets from a prototypical rust webapp.
• The documentation on using interchangeable keys (where a vault can be decrypted with either a password or an equivalent keyfile) has been greatly improved to try and make sure this is the default approach most users take, unless they have good reasons for doing otherwise.
• The crate docs have been expanded to include non-type documentation at a module level.
• Examples have been added to the crate documentation where they would be most beneficial to new users.

securestore API updates:

Changes and improvements to the securestore API, most relevant for existing securestore users:

• SecretsManager::new() has been changed to no longer take a store path, just the KeySource, so it can be used behind APIs in advance of knowing where the end user will want the SecureStore vault saved to.
• Accordingly, SecretsManager::save_as() has been added which lets users save a vault to any path of their choosing, not just the path it was loaded from.
• SecretsManager::export_keyfile() has been renamed to export_key() for simplicity and clarity. The old name remains available as an alias, so this is not a breaking change.
• SecretsManager::get() is no longer generic and is hard-coded to return a String, which should cover 99.99% of all secrets and lets you avoid needing to specify the return type. To retrieve binary secrets or secrets implementing BinaryDeserializable, use the new SecretsManager::get_as<T>() function (which is the old get() under a new name).
• BinaryDeserializable impls no longer return a type-erased Result<T, Box<dyn std::error::Error>> and instead have an associated Error type, they now return Result<T, Self::Error>.
• BinarySerializable has been implemented for Vec<u8> so you don't have to pass the vector as a slice to SecretsManager::set().
• SecretsManager::export_key() now uses a new plain-text format, emitting keyfiles in a PEM-like fashion with ASCII armor and a base64-encoded payload. The older binary keyfile format is still supported (and will stay supported).
• An earlier change making KeySource::File(path) generic over AsRef<Path> caused literal usage of KeySource::Csprng or KeySource::Password to break, as rust was not using the default type fallback (you would have had to use KeySource::<&Path>::Csprng or similar to get that code to compile)! This has been fixed by making KeySource no longer generic, and replacing KeySource::File(AsRef<Path>) with KeySource::Path(&Path). This is not a breaking a change because a new function KeySource::from_file(AsRef<Path>) has been added an aliased to KeySource::File() specifically to keep existing code compiling. KeySource::from_file() returns a GenericKeySource (which you should not use directly and cannot implement), which SecretsManager::load() and SecretsManager::new() have been updated to accept in lieu of a KeySource value directly.
• securestore::Error now implements std::error::Error::source(), previously the internal error could be obtained only via the securestore-specific Error::inner().
• All dependencies have been updated. Note: The minimum supported rust version has been incremented due to the update of the clap crate, which requires Edition 2021 support to compile.
• OpenSSL is no longer built/used as a static library by default for Windows users. Doing some research, it seems that rust devs on Windows are more likely to have OpenSSL installed (although perhaps not up to date!) than they are to have the dependencies required to build OpenSSL itself (these include the Visual Studio command line tools plus extremely niche OpenSSL-specific build-deps like perl.exe and more). The old behavior may be restored by opting into the openssl-vendored feature (optionally just for Windows targets) in your Cargo.toml (this is not a new feature, but was previously the default when compiling securestore under Windows).

ssclient CLI updates:

Changes and improvements to the ssclient companion CLI app:

• ssclient is now git-aware. For your safety, when a new key is generated or a copy of an existing key is exported, ssclient will check if it is being exported to a path under git control. If so, a .gitignore file will be created (if it doesn't exist) and a rule ignoring the newly-exported key will be added to the ignore file (if such a rule doesn't already exist). This behavior can be be disabled by supplying the --no-vcs argument when invoking ssclient to perform such an operation). Support for other VCS makes and models is coming (pull requests are welcome).
• ssclient will no longer fail to decrypt/retrieve binary secrets that were added to a SecureStore vault via the API (the ssclient CLI tool cannot be used to add binary secrets). These secrets will be displayed or exported as base64 strings (except if exporting with --format json (the default), in which case they will be exported as binary arrays).
• Keys are now generated/exported in a new plain-text format, emitting keyfiles in a PEM-like fashion with ASCII armor and a base64-encoded payload. The older binary keyfile format is still supported (and will stay supported).
• Certain combinations of options/switches to ssclient that were previously rejected are now accepted and make it easier to export keyfiles from passwords or to securely duplicate a keyfile (by both using a keyfile as a source and exporting a keyfile simultaneously).
• The command line synopsis and help output has been improved and expanded. Make sure to see ssclient --help (not just ssclient -h) for the expanded help documentation, and checkout the expanded help for each of the ssclient subcommands (via ssclient help get, ssclient help set, etc).

When upgrading your securestore dependency, make sure to also upgrade your ssclient installation (via cargo install ssclient) to make sure the two remain in sync. Using an older version of ssclient with stores or keyfiles generated from newer securestore crate versions may give you unexpected results!