Crate securestore

This crate contains the rust implementation of SecureStore, an open standard for cross-language/cross-platform secrets storage and retrieval. A SecureStore is represented on-disk as a plain-text, human-readable (JSON) file, intended to be stored and versioned alongside the code using it. Refer to the accompanying article for more information on the SecureStore protocol.

SecureStore vaults are created by or loaded from an existing vault and represented in memory as instances of SecretsManager, the primary type exposed by this crate. Typically, one SecretsManager instance should be created to service all retrieval and storage requests of secrets for an app.

For maximum flexibility and per the SecureStore protocol, the private keys used to encrypt or decrypt secrets in the vault can come from different sources (that may possibly even be used interchangeably); this key source is specified as a variant of the KeySource enum at the time of creating or loading a SecretsManager instance.

For best results, this crate should be used alongside the ssclient companion CLI app (available via cargo install ssclient). Typically, a new SecureStore vault is created with ssclient create ... and loaded with secrets at the command line with a series of ssclient set ... commands; this crate is then used by your application’s logic at runtime to load the store created by ssclient (via SecretsManager::load()) and retrieve the secrets (via SecretsManager::get()), although all the functionality needed to create and initialize a new store and its secrets directly yourself (without ssclient) is also available via the SecretsManager API.

A full and annotated example of using ssclient and this securestore crate in tandem may be found online, but an abbreviated version is shown below.

Example

First, create a new store and set some secret value at the command line with the companion ssclient crate:

$ cargo install ssclient
$ ssclient create secrets.json --export-key secrets.key
$ ssclient -k secrets.key set db_password pgsql123

Then in your code, load the store with the newly-created key file and retrieve the secret:

use securestore::{KeySource, SecretsManager};
use std::path::Path;

let key_path = Path::new("secrets.key");
let sman = SecretsManager::load("secrets.json", KeySource::Path(key_path))
    .expect("Failed to load secrets store!");
let db_password = sman.get("db_password")
    .expect("Couldn't get db_password from vault!");

assert_eq!(db_password, String::from("pgsql123"));

Structs

Error

The high-level wrapper type for user-facing errors in the SecureStore API.

SecretsManager

SecretsManager is the primary interface used for interacting with this crate, and is an in-memory representation of an encrypted SecureStore vault.

Enums

ErrorKind

A strongly-typed enumeration of errors one can expect to encounter in using the SecureStore API.

KeySource

A KeySource specifies the source of the encryption/decryption keys used by a SecretsManager instance when loading or interacting with a SecureStore vault.

Traits

BinaryDeserializable

A trait enabling directly retrieving a secret from the SecureStore vault as an instance of the implementing type.

BinarySerializable

A trait enabling directly saving a secret of the implementing type to the SecureStore vault.

GenericKeySource

This type is used internally for generic function overload purposes. See and use KeySource instead.