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
impl SecretsManager
Sourcepub fn new<K: GenericKeySource>(key_source: K) -> Result<SecretsManager, Error>
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.
Sourcepub fn load<P: AsRef<Path>, K: GenericKeySource>(
path: P,
key_source: K,
) -> Result<SecretsManager, Error>
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"));
Sourcepub fn save(&self) -> Result<(), Error>
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.
Sourcepub fn export_key<P: AsRef<Path>>(&self, path: P) -> Result<(), Error>
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());
Sourcepub fn get(&self, name: &str) -> Result<String, Error>
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
.
Sourcepub fn get_as<T: BinaryDeserializable>(&self, name: &str) -> Result<T, Error>
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.
Sourcepub fn set<T: BinarySerializable>(&mut self, name: &str, value: T)
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.
Sourcepub fn remove(&mut self, name: &str) -> Result<(), Error>
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.