pub struct KeyStore { /* private fields */ }Expand description
A KeyStore is a structure which contains a single “master key”, wrapped with one or more other keys. This is useful in cases where we want to encrypt data with a single key, while allowing users to add or remove keys at will, without having to a) re-encrypt the data when the keys change, or b) store multiple copies of the plaintext encrypted with the various different keys.
For example, users may want to be able to access a resource with either a password or a hardware authentication key, and the data they want to encrypt is relatively large (so re-encryption is expensive).
A KeyStore essentially contains a set of one or more wrapped keys, which it automatically loads from / persists to disk.
Implementations§
source§impl KeyStore
impl KeyStore
sourcepub fn new() -> Result<Self>
pub fn new() -> Result<Self>
Construct a new KeyStore. A new master key is generated from scratch.
Note that, before this KeyStore can be meaningfully persisted, you need
to wrap the master key with at least one key, via add_key.
sourcepub fn load_slice(data: &[u8]) -> Result<Self>
pub fn load_slice(data: &[u8]) -> Result<Self>
Load a previously-serialized (with to_vec) KeyStore from a byte slice.
sourcepub fn load_read<R: Read>(rd: R) -> Result<Self>
pub fn load_read<R: Read>(rd: R) -> Result<Self>
Load a previously-serialized (with to_vec) KeyStore from a reader.
sourcepub fn get_id(&self) -> String
pub fn get_id(&self) -> String
Return a string which “uniquely” identifies this KeyStore.
(This is quote “unique” because KeyStores with identical master keys
may return the same string here.) This string is mainly useful for
debugging / logging purposes.
sourcepub fn is_persistable(&self) -> bool
pub fn is_persistable(&self) -> bool
Return whether or not this KeyStore is meaningfully “persistable”. In other words, this returns whether or not this KeyStore has at least one wrapping key.
Because the master key is not persisted in plain text, if a KeyStore has no wrapping keys (yet), it is not useful to persist it, as it can never be opened again.
sourcepub fn open<K: AbstractKey>(&mut self, key: &K) -> Result<()>
pub fn open<K: AbstractKey>(&mut self, key: &K) -> Result<()>
Open this KeyStore (attempt to unwrap the master key) using the given wrapping key. If this fails, the structure will still be in a valid state, so you could e.g. try again with a different wrapping key.
sourcepub fn to_vec(&self) -> Result<Vec<u8>>
pub fn to_vec(&self) -> Result<Vec<u8>>
Serialize this KeyStore, so it can be persisted and then reloaded later.
sourcepub fn get_master_key(&self) -> Result<&Key>
pub fn get_master_key(&self) -> Result<&Key>
Return the unwrapped master key from this KeyStore. If this KeyStore has no master key (it was neither newly generated nor unwrapped), this will return an error instead.
sourcepub fn add_key<K: AbstractKey>(&mut self, key: &K) -> Result<bool>
pub fn add_key<K: AbstractKey>(&mut self, key: &K) -> Result<bool>
Add the given wrapping key to this KeyStore. When the KeyStore is opened in the future, this key can be used. Returns true if the key was successfully added, or false if it was already present in the KeyStore.
If this KeyStore has no master key (it was neither newly generated nor unwrapped), this will return an error instead.
sourcepub fn remove_key<K: AbstractKey>(&mut self, key: &K) -> Result<bool>
pub fn remove_key<K: AbstractKey>(&mut self, key: &K) -> Result<bool>
Remove the given key from this KeyStore, so it can no longer be used to open the KeyStore. Returns true if the key was removed, or false if the given key wasn’t found in this KeyStore. It is an error to remove the last wrapping key from a KeyStore (doing so would leave it unopenable in the future).
Note that it is possible to do this even if the KeyStore has no unwrapped master key (e.g., even if it has not been opened).
sourcepub fn iter_wrapped_keys(&self) -> impl Iterator<Item = &WrappedKey>
pub fn iter_wrapped_keys(&self) -> impl Iterator<Item = &WrappedKey>
Return an immutable iterator over this KeyStore’s wrapped keys. This may be useful to figure out which key to try to open with, for example, by checking the keys’ signatures.
This works even if the KeyStore has no unwrapped master key (e.g., even if it has not been opened).