Struct KeyMgr

pub struct KeyMgr { /* private fields */ }

Available on crate feature keymgr only.

A key manager that acts as a frontend to a primary 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 primary 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).

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::item_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<'_>, overwrite: bool, ) -> Result<Option<K>>

Insert key into the Keystore 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 the provided key.

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 primary 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 primary 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.

pub fn get_key_and_cert<K, C>( &self, spec: &dyn KeyCertificateSpecifier, ) -> Result<Option<(K, C)>>

where K: ToEncodableKey, C: ToEncodableCert<K>,

Available on crate feature experimental-api only.

Read the specified key and certificate from one of the key stores, deserializing the subject key as K::Key, the cert as C::Cert, and the signing key as C::SigningKey.

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

This function validates the certificate using ToEncodableCert::validate, returning an error if it is invalid or missing.

pub fn get_or_generate_key_and_cert<K, C>( &self, spec: &dyn KeyCertificateSpecifier, make_certificate: impl FnOnce(&K, &<C as ToEncodableCert<K>>::SigningKey) -> C, selector: KeystoreSelector<'_>, rng: &mut dyn KeygenRng, ) -> Result<(K, C)>

where K: ToEncodableKey, K::Key: Keygen, C: ToEncodableCert<K>,

Available on crate feature experimental-api only.

Like KeyMgr::get_key_and_cert, except this function also generates the subject key and its corresponding certificate if they don’t already exist.

If the key certificate is missing, it will be generated from the subject key and signing key using the provided make_certificate callback.

Generates the missing key and/or certificate as follows:

| Subject Key exists | Signing Key exists | Cert exists | Action                                 |
|--------------------|--------------------|-------------|----------------------------------------|
| Y                  | Y                  | Y           | Validate cert, return key and cert     |
|                    |                    |             | if valid, error otherwise              |
|--------------------|--------------------|-------------|----------------------------------------|
| N                  | Y                  | N           | Generate subject key and               |
|                    |                    |             | a new cert signed with signing key     |
|--------------------|--------------------|-------------|----------------------------------------|
| Y                  | Y                  | N           | Generate cert signed with signing key  |
|--------------------|--------------------|-------------|----------------------------------------|
| Y                  | N                  | N           | Error - cannot validate cert           |
|                    |                    |             | if signing key is not available        |
|--------------------|--------------------|-------------|----------------------------------------|
| Y/N                | N                  | N           | Error - cannot generate cert           |
|                    |                    |             | if signing key is not available        |
|--------------------|--------------------|-------------|----------------------------------------|
| N                  | Y/N                | Y           | Error - subject key was removed?       |
|                    |                    |             | (we found the cert,                    |
|                    |                    |             | but the subject key is missing)        |