Struct tor_keymgr::KeyMgr

pub struct KeyMgr { /* private fields */ }

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 - get(), get_with_type() - 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 a TOCTOU race).

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_with_type<K: ToEncodableKey>( &self, key_spec: &dyn KeySpecifier, key_type: &KeyType ) -> 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.

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 a TOCTOU race.

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

Insert key into the Keystore specified by selector.

If the key already exists, it is overwritten.

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

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 Ok(None) if the key does not exist in the requested keystore. Returns Ok(Some(()) if the key was successfully removed.

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

pub fn remove_with_type( &self, key_spec: &dyn KeySpecifier, key_type: &KeyType, selector: KeystoreSelector<'_> ) -> Result<Option<()>>

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

Like KeyMgr::remove, except this function takes an explicit &KeyType argument instead of obtaining it from the specified type’s ToEncodableKey implementation.

pub fn list_matching( &self, pat: &KeyPathPattern ) -> Result<Vec<(KeyPath, KeyType)>>

Return 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 KeyInfoExtractors is able to parse the specified KeyPath.

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