securestore

Struct SecretsManager

Source
pub struct SecretsManager { /* private fields */ }
Expand description

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

An existing plain-text SecureStore vault can be loaded with SecretsManager::load() or a new vault can be created with new() and then saved to disk with save() or save_as().

Individual secrets can be set, retrieved, and removed with SecretsManager::set(), get(), and remove() respectively. The names/keys of all secrets stored in this vault can be enumerated via SecretsManager::keys().

Implementations§

Source§

impl SecretsManager

Source

pub fn new<K: GenericKeySource>(key_source: K) -> Result<SecretsManager, Error>

Creates a new instance of SecretsManager, encrypting its secrets with the specified KeySource.

Note that the usage of KeySource::Path is taken to mean that there is an existing compatible private key already available at the specified path. To generate a new key file, use KeySource::Csprng then export the generated key to the desired path with export_key().

Most users will likely prefer to create a new SecureStore vault and manage its secrets by using the companion CLI utility ssclient, then load() the SecureStore at runtime to retrieve its secrets.

Source

pub fn load<P: AsRef<Path>, K: GenericKeySource>( path: P, key_source: K, ) -> Result<SecretsManager, Error>

Load the contents of an on-disk SecureStore vault located at path into a new SecretsManager instance, decrypting its contents with the KeySource specified by the key_source parameter.

Note that changes to the vault are not written to disk unless and until save() or save_as() is called.

§Panics:

In debug mode, if an attempt is made to load an existing vault but key_source is set to KeySource::Csprng (which should only be used when initializing a new secrets vault). In release mode, this does not panic but the vault will invariably fail to decrypt.

§Example:

First, in the shell:

ssclient create secrets.json --export-key secrets.key
ssclient set password mYpassWORD123

Then, in rust:

use securestore::SecretsManager;

let secrets = SecretsManager::load("secrets.json", "secrets.key").unwrap();
let password = secrets.get("password").unwrap();
assert_eq!(password, String::from("mYpassWORD123"));
Source

pub fn save(&self) -> Result<(), Error>

Saves changes to the underlying vault specified by the path supplied during construction of this SecretsManager instance.

Note that changes to a SecretsManager instance and its underlying vault are transient and will be lost unlesss they are flushed to disk via save() or save_as().

§Panics:

If a call to save() is made on a SecretsManager initialized with SecretsManager::new() rather than opened with load(); use save_as() instead.

Source

pub fn save_as<P: AsRef<Path>>(&self, path: P) -> Result<(), Error>

Export the current vault plus any changes that have been made to it to the path specified by the path argument.

Note that changes to a SecretsManager instance and its underlying vault are transient and will be lost unlesss they are flushed to disk via save() or save_as().

Source

pub fn export_key<P: AsRef<Path>>(&self, path: P) -> Result<(), Error>

Exports the private key(s) resident in memory to a path on-disk. Note that in addition to being used for exporting existing keys previously loaded into the secrets store and keys newly generated by the secrets store, it can also be used to export keys derived from passwords to their equivalent keyfiles to facilitate subsequent passwordless access.

As of securestore 0.100, the keyfile is written in a PEM-like format, with ASCII armor and a base64-encoded payload. Previous versions exported a binary version of the keyfile. Both are fully supported.

§Example:
use securestore::{SecretsManager, KeySource};

let vault_pass = KeySource::Password("myVaultPass123");
let mut sman = SecretsManager::new(vault_pass).unwrap();
sman.set("password", "password123");
sman.save_as("secrets.json").unwrap();
sman.export_key("passwordless.key").unwrap();

// We can now use either the vault password "myVaultPass123" or the
// equivalent keyfile "passwordless.key" to load the store and access
// the secrets.

let vault_key = KeySource::from_file("passwordless.key");
let sman = SecretsManager::load("secrets.json", vault_key).unwrap();
assert_eq!("password123", sman.get("password").unwrap());
Source

pub fn get(&self, name: &str) -> Result<String, Error>

Decrypt and retrieve the single secret identified by name from the loaded store as a String. If the secret cannot be found, an Error with Error::kind() set to ErrorKind::SecretNotFound is returned.

See get_as() to retrieve either binary secrets or secrets of arbitrary types implementing BinaryDeserializable.

Source

pub fn get_as<T: BinaryDeserializable>(&self, name: &str) -> Result<T, Error>

Decrypt and retrieve the single secret identified by name from the loaded store, deserializing it to the requested type. If the secret cannot be found, an Error with Error::kind() set to ErrorKind::SecretNotFound is returned.

Out-of-the-box, this crate supports retrieving String and Vec<u8> secrets. BinaryDeserializable may be implemented to support directly retrieving arbitrary types, but it is preferred to internally deserialize from one of the primitive supported types previously mentioned after calling get() to ensure maximum compatibility with other SecureStore clients.

Source

pub fn set<T: BinarySerializable>(&mut self, name: &str, value: T)

Add a new secret or replace the existing secret identified by name with the value value to the store.

Out-of-the-box, this crate supports String, &str, Vec<u8>, and &[u8] secrets. BinarySerializable may be implemented to support directly setting arbitrary types, but it is preferred to internally serialize to one of the primitive supported types previously mentioned before calling set() to ensure maximum compatibility with other SecureStore clients.

Source

pub fn remove(&mut self, name: &str) -> Result<(), Error>

Remove the secret identified by name from the store. If there is no secret by that name, an Error with Error::kind() set to ErrorKind::SecretNotFound is returned.

Source

pub fn keys<'a>(&'a self) -> impl Iterator<Item = &'a str>

Retrieve a list of the names of secrets stored in the vault.

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = Infallible

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.