Struct KeyMgr 

pub struct KeyMgr {
    primary_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 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).

Fields

primary_store: Box<dyn Keystore>

The primary 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::item_type().

pub fn get_cert_entry<S: KeyCertificateSpecifier + for<'a> TryFrom<&'a KeyPath, Error = KeyPathError>, K: ToEncodableKey, C: ToEncodableCert<K>>( &self, entry: &KeystoreEntry<'_>, signing_key_spec: &dyn KeySpecifier, ) -> Result<Option<C>>

Retrieve the specified keystore certificate entry and the corresponding subject and signing keys, deserializing the subject key as K::Key, the cert as C::Cert, and the signing key as C::SigningKey.

The S type parameter is the KeyCertificateSpecifier of the certificate.

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 item type of the KeystoreEntry does not match C::item_type(), or if the certificate is not valid according to ToEncodableCert::validate, or if the ArtiPath of the entry cannot be converted to a certificate specifier of type S.

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 get_from<K: ToEncodableKey>( &self, key_spec: &dyn KeySpecifier, keystore_id: &KeystoreId, ) -> Result<Option<K>>

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

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

Returns an error if the specified keystore does not exist.

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

Validates the integrity of a KeystoreEntry.

This retrieves the key corresponding to the provided KeystoreEntry, and checks if its contents are valid (i.e. that the key can be parsed). The KeyPath of the entry is further validated using describe.

Returns Ok(()) if the specified keystore entry is valid, and Err otherwise.

NOTE: If the specified entry does not exist, this will only validate its KeyPath.

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 remove_unchecked( &self, raw_id: &str, keystore_id: &KeystoreId, ) -> Result<()>

Remove the specified keystore entry.

Similar to KeyMgr::remove_entry, except this method accepts both recognized and unrecognized entries, identified by a raw id (in the form of a &str) and a KeystoreId.

Returns an error if the entry could not be removed, or if the entry doesn’t exist.

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.

NOTE: This function only returns the recognized entries that match the provided pattern. The unrecognized entries (i.e. those that do not have a valid KeyPath) will be filtered out, even if they match the specified pattern.

pub fn list_by_id( &self, id: &KeystoreId, ) -> Result<Vec<KeystoreEntryResult<KeystoreEntry<'_>>>>

List keys and certificates of the specified keystore.

pub fn list(&self) -> Result<Vec<KeystoreEntryResult<KeystoreEntry<'_>>>>

List keys and certificates of all the keystores.

pub fn list_keystores(&self) -> Vec<KeystoreId>

List all the configured keystore.

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

Describe the specified key.

Returns None 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_raw<'a, K: ItemType>( &self, key_spec: &dyn KeySpecifier, key_type: &KeystoreItemType, stores: impl Iterator<Item = &'a Box<dyn Keystore>>, ) -> Result<Option<K>>

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

Returns the <K as ToEncodableKey>::Key representation of the key.

See KeyMgr::get for more details.

fn get_cert_from_store<'a, K: ToEncodableKey, C: ToEncodableCert<K>>( &self, cert_spec: &dyn KeySpecifier, cert_type: &KeystoreItemType, signing_cert_spec: &dyn KeySpecifier, subject_cert_spec: &dyn KeySpecifier, stores: impl Iterator<Item = &'a Box<dyn Keystore>>, ) -> Result<Option<C>>

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

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

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

See KeyMgr::get for more details.

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

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

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, signing_key_spec: &dyn KeySpecifier, 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>,

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

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

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 primary 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 primary keystore or the ID of one of the configured secondary stores.

fn get_cert_signing_key<K, C>( &self, signing_key_spec: &dyn KeySpecifier, ) -> Result<C::SigningKey>

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

Get the signing key of the certificate described by spec.

Returns a KeystoreCorruptionError::MissingSigningKey error if the signing key doesn’t exist in any of the keystores.

fn insert_cert<K, C>( &self, cert: C, cert_spec: &dyn KeySpecifier, selector: KeystoreSelector<'_>, ) -> Result<()>

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

Insert cert into the Keystore specified by selector.

If the key already exists in the specified key store, it will be overwritten.