Struct tor_keymgr::KeyMgr

pub struct KeyMgr { /* private fields */ }

Available on crate feature keymgr only.

A key manager with several Keystores.

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

Implementations

impl KeyMgr

pub fn new( default_store: impl Keystore, secondary_stores: Vec<Box<dyn Keystore>> ) -> Self

Create a new KeyMgr with a default Keystore and zero or more secondary Keystores.

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

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 computed using the provided derive function and inserts it into the specified keystore, returning the newly inserted value.

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.

pub fn generate<K>( &self, key_spec: &dyn KeySpecifier, selector: KeystoreSelector<'_>, rng: &mut dyn KeygenRng, overwrite: bool ) -> Result<Option<()>>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.

Returns Ok(Some(()) if a new key was created, and Ok(None) otherwise.

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 generate_with_derived<SK, PK>( &self, keypair_key_spec: &dyn KeySpecifier, public_key_spec: &dyn KeySpecifier, selector: KeystoreSelector<'_>, derive_pub: impl FnMut(&SK::Key) -> PK, rng: &mut dyn KeygenRng, overwrite: bool ) -> Result<Option<()>>where SK: ToEncodableKey, SK::Key: Keygen, PK: EncodableKey + PartialEq,

Generate a new keypair of type SK and the corresponding public key of type PK, and insert them into the key store specified by selector.

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

If overwrite is false and the keypair already exists in the keystore, but the corresponding public key does not, ththe public key will be derived from the existing keypair and inserted into the keystore.

If overwrite is false and the keypair does not exist in the keystore, but its corresponding public key does, this will not generate a fresh keypair.

Returns Ok(Some(()) if a new keypair was created, and Ok(None) otherwise.

NOTE: If the keypair and its corresponding public key already exist in the keystore, this function checks if they match. If they do not, it returns an error.

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_with_derived depends on whether the selected key store contains the specified keypair, 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.

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 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 list_matching<M>( &self, pat: &KeyPathPatternSet, derive_meta: impl Fn(&KeyPath, &[KeyPathRange]) -> Result<M> ) -> Result<Vec<(KeyPath, KeyType, M)>>

Return the keys matching the specified KeyPathPatternSet.

NOTE: This searches for matching keys in all keystores.