Struct tor_hsservice::internal_prelude::KeyMgr

pub(crate) struct KeyMgr {
    default_store: Box<dyn Keystore>,
    secondary_stores: Vec<Box<dyn Keystore>>,
    key_info_extractors: Vec<&'static dyn KeyPathInfoExtractor>,
}

A key manager that acts as a frontend to a default Keystore and any number of secondary Keystores.

Note: KeyMgr is a low-level utility and does not implement caching (the key stores are accessed for every read/write).

The KeyMgr accessors - currently just get() - search the configured key stores in order: first the default key store, and then the secondary stores, in order.

Concurrent key store access

The key stores will allow concurrent modification by different processes. In order to implement this safely without locking, the key store operations (get, insert, remove) will need to be atomic.

Note: KeyMgr::generate and KeyMgr::get_or_generate should not be used concurrently with any other KeyMgr operation that mutates the same key (i.e. a key with the same ArtiPath), because their outcome depends on whether the selected key store contains the specified key (and thus suffers from a TOCTOU race).

Fields

default_store: Box<dyn Keystore>

secondary_stores: Vec<Box<dyn Keystore>>

key_info_extractors: Vec<&'static dyn KeyPathInfoExtractor>

Implementations

impl KeyMgr

pub fn get<K>(&self, key_spec: &dyn KeySpecifier) -> Result<Option<K>, Error>

where K: ToEncodableKey,

Read a key from one of the key stores, and try to deserialize it as K::Key.

The key returned is retrieved from the first key store that contains an entry for the given specifier.

Returns Ok(None) if none of the key stores have the requested key.

pub fn get_entry<K>( &self, entry: &KeystoreEntry<'_> ) -> Result<Option<K>, Error>

where K: ToEncodableKey,

Retrieve the specified keystore entry, and try to deserialize it as K::Key.

The key returned is retrieved from the key store specified in the KeystoreEntry.

Returns Ok(None) if the key store does not contain the requested entry.

Returns an error if the specified key_type does not match K::Key::key_type().

pub fn get_or_generate<K>( &self, key_spec: &dyn KeySpecifier, selector: KeystoreSelector<'_>, rng: &mut dyn KeygenRng ) -> Result<K, Error>

where K: ToEncodableKey, <K as ToEncodableKey>::Key: Keygen,

Read the key identified by key_spec.

The key returned is retrieved from the first key store that contains an entry for the given specifier.

If the requested key does not exist in any of the key stores, this generates a new key of type K from the key created using using K::Key’s Keygen implementation, and inserts it into the specified keystore, returning the newly inserted value.

This is a convenience wrapper around get() and generate().

pub fn generate<K>( &self, key_spec: &dyn KeySpecifier, selector: KeystoreSelector<'_>, rng: &mut dyn KeygenRng, overwrite: bool ) -> Result<K, Error>

where K: ToEncodableKey, <K as ToEncodableKey>::Key: Keygen,

Generate a new key of type K, and insert it into the key store specified by selector.

If the key already exists in the specified key store, the overwrite flag is used to decide whether to overwrite it with a newly generated key.

On success, this function returns the newly generated key.

Returns Error::KeyAlreadyExists if the key already exists in the specified key store and overwrite is false.

IMPORTANT: using this function concurrently with any other KeyMgr operation that mutates the key store state is not recommended, as it can yield surprising results! The outcome of KeyMgr::generate depends on whether the selected key store contains the specified key, and thus suffers from a TOCTOU race.

pub fn insert<K>( &self, key: K, key_spec: &dyn KeySpecifier, selector: KeystoreSelector<'_> ) -> Result<Option<K>, Error>

where K: ToEncodableKey,

Insert key into the Keystore specified by selector.

If this key is not already in the keystore, None is returned.

If this key already exists in the keystore, its value is updated and the old value is returned.

Returns an error if the selected keystore is not the default keystore or one of the configured secondary stores.

pub fn remove<K>( &self, key_spec: &dyn KeySpecifier, selector: KeystoreSelector<'_> ) -> Result<Option<K>, Error>

where K: ToEncodableKey,

Remove the key identified by key_spec from the Keystore specified by selector.

Returns an error if the selected keystore is not the default keystore or one of the configured secondary stores.

Returns the value of the removed key, or Ok(None) if the key does not exist in the requested keystore.

Returns Err if an error occurred while trying to remove the key.

pub fn remove_entry( &self, entry: &KeystoreEntry<'_> ) -> Result<Option<()>, Error>

Remove the specified keystore entry.

Like KeyMgr::remove, except this function does not return the value of the removed key.

A return value of Ok(None) indicates the key was not found in the specified key store, whereas Ok(Some(()) means the key was successfully removed.

pub fn list_matching( &self, pat: &KeyPathPattern ) -> Result<Vec<KeystoreEntry<'_>>, Error>

Return the keystore entry descriptors of the keys matching the specified KeyPathPattern.

NOTE: This searches for matching keys in all keystores.

pub fn describe(&self, path: &KeyPath) -> Result<KeyPathInfo, KeyPathError>

Describe the specified key.

Returns KeyPathError::Unrecognized if none of the registered KeyPathInfoExtractors is able to parse the specified KeyPath.

This function uses the KeyPathInfoExtractors registered using register_key_info_extractor, or by DefaultKeySpecifier.