Struct tor_keymgr::mgr::KeyMgr

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

Available on crate feature keymgr only.

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>

The default key store.

secondary_stores: Vec<Box<dyn Keystore>>

The secondary key stores.

key_info_extractors: Vec<&'static dyn KeyPathInfoExtractor>

The key info extractors.

These are initialized internally by KeyMgrBuilder::build, using the values collected using inventory.

Implementations

impl KeyMgr

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

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: ToEncodableKey>( &self, entry: &KeystoreEntry<'_> ) -> Result<Option<K>>

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>

where K: ToEncodableKey, K::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>

where K: ToEncodableKey, K::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: ToEncodableKey>( &self, key: K, key_spec: &dyn KeySpecifier, selector: KeystoreSelector<'_> ) -> Result<Option<K>>

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: ToEncodableKey>( &self, key_spec: &dyn KeySpecifier, selector: KeystoreSelector<'_> ) -> Result<Option<K>>

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<()>>

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<'_>>>

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) -> StdResult<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.

fn get_from_store<'a, K: ToEncodableKey>( &self, key_spec: &dyn KeySpecifier, key_type: &KeyType, stores: impl Iterator<Item = &'a Box<dyn Keystore>> ) -> Result<Option<K>>

Attempt to retrieve a key from one of the specified stores.

See KeyMgr::get for more details.

fn all_stores(&self) -> impl Iterator<Item = &Box<dyn Keystore>>

Return an iterator over all configured stores.

fn select_keystore( &self, selector: &KeystoreSelector<'_> ) -> Result<&Box<dyn Keystore>>

Return the Keystore matching the specified selector.

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

fn find_keystore(&self, id: &KeystoreId) -> Result<&Box<dyn Keystore>>

Return the Keystore with the specified id.

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