//! Code for managing multiple [`Keystore`](crate::Keystore)s.

//!

//! See the [`KeyMgr`] docs for more details.

use crate::{

    ArtiPath, BoxedKeystore, KeyCertificateSpecifier, KeyPath, KeyPathError, KeyPathInfo,

    KeyPathInfoExtractor, KeyPathPattern, KeySpecifier, KeystoreCorruptionError, KeystoreId,

    KeystoreSelector, Result,

};

use itertools::Itertools;

use std::iter;

use std::result::Result as StdResult;

use tor_error::{bad_api_usage, internal, into_bad_api_usage};

use tor_key_forge::{

    ItemType, Keygen, KeygenRng, KeystoreItemType, ToEncodableCert, ToEncodableKey,

};

/// A key manager that acts as a frontend to a primary [`Keystore`](crate::Keystore) and

/// any number of secondary [`Keystore`](crate::Keystore)s.

///

/// 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()`](KeyMgr::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`][crate::Keystore::contains]

/// the specified key (and thus suffers from a TOCTOU race).

#[builder(pattern = "owned", build_fn(private, name = "build_unvalidated"))]

pub struct KeyMgr {

    /// The primary key store.

    primary_store: BoxedKeystore,

    /// The secondary key stores.

    #[builder(default, setter(custom))]

    secondary_stores: Vec<BoxedKeystore>,

    /// The key info extractors.

    ///

    /// These are initialized internally by [`KeyMgrBuilder::build`], using the values collected

    /// using `inventory`.

    #[builder(default, setter(skip))]

    key_info_extractors: Vec<&'static dyn KeyPathInfoExtractor>,

}

/// A keystore entry descriptor.

///

/// This identifies a key entry from a specific keystore.

/// The key entry can be retrieved, using [`KeyMgr::get_entry`],

/// or removed, using [`KeyMgr::remove_entry`].

///

/// Returned from [`KeyMgr::list_matching`].

#[derive(Clone, Debug, PartialEq, amplify::Getters)]

pub struct KeystoreEntry<'a> {

    /// The [`KeyPath`] of the key.

    key_path: KeyPath,

    /// The [`KeystoreItemType`] of the key.

    key_type: KeystoreItemType,

    /// The [`KeystoreId`] that of the keystore where the key was found.

    #[getter(as_copy)]

    keystore_id: &'a KeystoreId,

}

impl KeyMgrBuilder {

    /// Construct a [`KeyMgr`] from this builder.

        use itertools::Itertools as _;

}

// TODO: auto-generate using define_list_builder_accessors/define_list_builder_helper

// when that becomes possible.

//

// See https://gitlab.torproject.org/tpo/core/arti/-/merge_requests/1760#note_2969841

impl KeyMgrBuilder {

    /// Access the being-built list of secondary stores (resolving default)

    ///

    /// If the field has not yet been set or accessed, the default list will be

    /// constructed and a mutable reference to the now-defaulted list of builders

    /// will be returned.

    /// Set the whole list (overriding the default)

    /// Inspect the being-built list (with default unresolved)

    ///

    /// If the list has not yet been set, or accessed, `&None` is returned.

    /// Mutably access the being-built list (with default unresolved)

    ///

    /// If the list has not yet been set, or accessed, `&mut None` is returned.

}

inventory::collect!(&'static dyn crate::KeyPathInfoExtractor);

impl KeyMgr {

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

            // If the key_spec is the specifier for the public part of a keypair,

            // try getting the pair and extracting the public portion from it.

    /// 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()`.

    /// 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()`](KeyMgr::get) and

    /// [`generate()`](KeyMgr::generate).

        }

    /// 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`](crate::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`][crate::Keystore::contains] the specified key, and thus suffers from a TOCTOU race.

    //

    // TODO (#1119): can we make this less racy without a lock? Perhaps we should say we'll always

    // overwrite any existing keys.

    //

    // TODO: consider replacing the overwrite boolean with a GenerateOptions type

    // (sort of like std::fs::OpenOptions)

        } else {

        }

    /// Insert `key` into the [`Keystore`](crate::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.

        } else {

        }

    /// Remove the key identified by `key_spec` from the [`Keystore`](crate::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.

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

    //

    // TODO: We should be consistent and return the removed key.

    //

    // This probably will involve changing the return type of Keystore::remove

    // to Result<Option<ErasedKey>>.

    /// Return the keystore entry descriptors of the keys matching the specified [`KeyPathPattern`].

    ///

    /// NOTE: This searches for matching keys in _all_ keystores.

    /// Describe the specified key.

    ///

    /// Returns [`KeyPathError::Unrecognized`] if none of the registered

    /// [`KeyPathInfoExtractor`]s is able to parse the specified [`KeyPath`].

    ///

    /// This function uses the [`KeyPathInfoExtractor`]s registered using

    /// [`register_key_info_extractor`](crate::register_key_info_extractor),

    /// or by [`DefaultKeySpecifier`](crate::derive_deftly_template_KeySpecifier).

        }

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

                Ok(None) => {

                    // The key doesn't exist in this store, so we check the next one...

                }

                }

            };

            // Found it! Now try to downcast it to the right type (this should _not_ fail)...

        }

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

    ///

    /// See [`KeyMgr::get`] for more details.

        };

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

    ///

    // Note: the behavior of this function is a bit inconsistent with

    // get_or_generate_key_and_cert: here, if the cert is absent but

    // its subject key is not, we return Ok(None).

    // In get_or_generate_key_and_cert, OTOH< we return an error in that case

    // (because we can't possibly generate the missing subject key

    // without overwriting the cert of the missing key).

    ///

    /// This function validates the certificate using [`ToEncodableCert::validate`],

    /// returning an error if it is invalid or missing.

    #[cfg(feature = "experimental-api")]

        // Get the subject key...

        else {

        };

        else {

        };

        // Finally, get the signing key and validate the cert

    /// 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:

    ///

    /// ```text

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

    /// ```

    ///

    //

    // Note; the table above isn't a markdown table because CommonMark-flavor markdown

    // doesn't support multiline text in tables. Even if we trim down the text,

    // the resulting markdown table would be pretty unreadable in raw form

    // (it would have several excessively long lines, over 120 chars in len).

    #[cfg(feature = "experimental-api")]

            (Some(_), None) => {

            }

        }

        };

            None => {

            }

        };

    /// Return an iterator over all configured stores.

    /// Return the [`Keystore`](crate::Keystore) matching the specified `selector`.

    ///

    /// Returns an error if the selected keystore is not the primary keystore or one of the

    /// configured secondary stores.

        }

    /// Return the [`Keystore`](crate::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.

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

    #[cfg(feature = "experimental-api")]

        };

        else {

        };

    /// Insert `cert` into the [`Keystore`](crate::Keystore) specified by `selector`.

    ///

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

    ///

    // NOTE: if we ever make this public we should rethink/improve its API.

    // TODO: maybe fold this into insert() somehow?

}

#[cfg(test)]

mod tests {

    // @@ begin test lint list maintained by maint/add_warning @@

    #![allow(clippy::bool_assert_comparison)]

    #![allow(clippy::clone_on_copy)]

    #![allow(clippy::dbg_macro)]

    #![allow(clippy::mixed_attributes_style)]

    #![allow(clippy::print_stderr)]

    #![allow(clippy::print_stdout)]

    #![allow(clippy::single_char_pattern)]

    #![allow(clippy::unwrap_used)]

    #![allow(clippy::unchecked_duration_subtraction)]

    #![allow(clippy::useless_vec)]

    #![allow(clippy::needless_pass_by_value)]

    //! <!-- @@ end test lint list maintained by maint/add_warning @@ -->

    use super::*;

    use crate::{ArtiPath, ArtiPathUnavailableError, KeyPath};

    use std::collections::HashMap;

    use std::result::Result as StdResult;

    use std::str::FromStr;

    use std::sync::RwLock;

    use std::time::{Duration, SystemTime};

    use tor_basic_utils::test_rng::testing_rng;

    use tor_cert::CertifiedKey;

    use tor_cert::Ed25519Cert;

    use tor_key_forge::{

        CertData, EncodableItem, ErasedKey, InvalidCertError, KeyType, KeystoreItem,

    };

    use tor_llcrypto::pk::ed25519::{self, Ed25519PublicKey as _};

    use tor_llcrypto::rng::FakeEntropicRng;

    /// Metadata structure for tracking key operations in tests.

    #[derive(Clone, Debug, PartialEq)]

    struct KeyMetadata {

        /// The identifier for the item (e.g., "coot", "moorhen").

        item_id: String,

        /// The keystore from which the item was retrieved.

        ///

        /// Set by `Keystore::get`.

        retrieved_from: Option<KeystoreId>,

        /// Whether the item was generated via `Keygen::generate`.

        is_generated: bool,

    }

    /// Metadata structure for tracking certificate operations in tests.

    #[derive(Clone, Debug, PartialEq)]

    struct CertMetadata {

        /// The identifier for the subject key (e.g., "coot").

        subject_key_id: String,

        /// The identifier for the signing key (e.g., "moorhen").

        signing_key_id: String,

        /// The keystore from which the certificate was retrieved.

        ///

        /// Set by `Keystore::get`.

        retrieved_from: Option<KeystoreId>,

        /// Whether the certificate was freshly generated (i.e. returned from the "or generate"

        /// branch of `get_or_generate()`) or retrieved from a keystore.

        is_generated: bool,

    }

    /// Metadata structure for tracking item operations in tests.

    #[derive(Clone, Debug, PartialEq, derive_more::From)]

    enum ItemMetadata {

        /// Metadata about a key.

        Key(KeyMetadata),

        /// Metadata about a certificate.

        Cert(CertMetadata),

    }

    impl ItemMetadata {

        /// Get the item ID.

        ///

        /// For keys, this returns the key's ID.

        /// For certificates, this returns a formatted string identifying the subject key.

        fn item_id(&self) -> &str {

            match self {

                ItemMetadata::Key(k) => &k.item_id,

                ItemMetadata::Cert(c) => &c.subject_key_id,

            }

        }

        /// Get retrieved_from.

        fn retrieved_from(&self) -> Option<&KeystoreId> {

            match self {

                ItemMetadata::Key(k) => k.retrieved_from.as_ref(),

                ItemMetadata::Cert(c) => c.retrieved_from.as_ref(),

            }

        }

        /// Get is_generated.

        fn is_generated(&self) -> bool {

            match self {

                ItemMetadata::Key(k) => k.is_generated,

                ItemMetadata::Cert(c) => c.is_generated,

            }

        }

        /// Set the retrieved_from field to the specified keystore ID.

        fn set_retrieved_from(&mut self, id: KeystoreId) {

            match self {

                ItemMetadata::Key(meta) => meta.retrieved_from = Some(id),

                ItemMetadata::Cert(meta) => meta.retrieved_from = Some(id),

            }

        }

        /// Returns a reference to key metadata if this is a Key variant.

        fn as_key(&self) -> Option<&KeyMetadata> {

            match self {

                ItemMetadata::Key(meta) => Some(meta),

                _ => None,

            }

        }

        /// Returns a reference to certificate metadata if this is a Cert variant.

        fn as_cert(&self) -> Option<&CertMetadata> {

            match self {

                ItemMetadata::Cert(meta) => Some(meta),

                _ => None,

            }

        }

    }

    /// The type of "key" stored in the test key stores.

    #[derive(Clone, Debug)]

    struct TestItem {

        /// The underlying key.

        item: KeystoreItem,

        /// Metadata about the key.

        meta: ItemMetadata,

    }

    /// A "certificate" used for testing purposes.

    #[derive(Clone, Debug)]

    struct AlwaysValidCert(TestItem);

    /// The corresponding fake public key type.

    #[derive(Clone, Debug)]

    struct TestPublicKey {

        /// The underlying key.

        key: KeystoreItem,

    }

    impl From<TestItem> for TestPublicKey {

        fn from(tk: TestItem) -> TestPublicKey {

            TestPublicKey { key: tk.item }

        }

    }

    impl TestItem {

        /// Create a new test key with the specified metadata.

        fn new(item_id: &str) -> Self {

            let mut rng = testing_rng();

            TestItem {

                item: ed25519::Keypair::generate(&mut rng)

                    .as_keystore_item()

                    .unwrap(),

                meta: ItemMetadata::Key(KeyMetadata {

                    item_id: item_id.to_string(),

                    retrieved_from: None,

                    is_generated: false,

                }),

            }

        }

    }

    impl Keygen for TestItem {

        fn generate(mut rng: &mut dyn KeygenRng) -> tor_key_forge::Result<Self>

        where

            Self: Sized,

        {

            Ok(TestItem {

                item: ed25519::Keypair::generate(&mut rng).as_keystore_item()?,

                meta: ItemMetadata::Key(KeyMetadata {

                    item_id: "generated_test_key".to_string(),

                    retrieved_from: None,

                    is_generated: true,

                }),

            })

        }

    }

    impl ItemType for TestItem {

        fn item_type() -> KeystoreItemType

        where

            Self: Sized,

        {

            // Dummy value

            KeyType::Ed25519Keypair.into()

        }

    }

    impl EncodableItem for TestItem {

        fn as_keystore_item(&self) -> tor_key_forge::Result<KeystoreItem> {

            Ok(self.item.clone())

        }

    }

    impl ToEncodableKey for TestItem {

        type Key = Self;

        type KeyPair = Self;

        fn to_encodable_key(self) -> Self::Key {

            self

        }

        fn from_encodable_key(key: Self::Key) -> Self {

            key

        }

    }

    impl ItemType for TestPublicKey {

        fn item_type() -> KeystoreItemType

        where

            Self: Sized,

        {

            KeyType::Ed25519PublicKey.into()

        }

    }

    impl EncodableItem for TestPublicKey {

        fn as_keystore_item(&self) -> tor_key_forge::Result<KeystoreItem> {

            Ok(self.key.clone())

        }

    }

    impl ToEncodableKey for TestPublicKey {

        type Key = Self;

        type KeyPair = TestItem;

        fn to_encodable_key(self) -> Self::Key {

            self

        }

        fn from_encodable_key(key: Self::Key) -> Self {

            key

        }

    }

    impl ToEncodableCert<TestItem> for AlwaysValidCert {

        type ParsedCert = TestItem;

        type EncodableCert = TestItem;

        type SigningKey = TestItem;

        fn validate(

            cert: Self::ParsedCert,

            _subject: &TestItem,

            _signed_with: &Self::SigningKey,

        ) -> StdResult<Self, InvalidCertError> {

            // AlwaysValidCert is always valid

            Ok(Self(cert))

        }

        /// Convert this cert to a type that implements [`EncodableKey`].

        fn to_encodable_cert(self) -> Self::EncodableCert {

            self.0

        }

    }

    macro_rules! impl_keystore {

        ($name:tt, $id:expr) => {

            struct $name {

                inner: RwLock<HashMap<(ArtiPath, KeystoreItemType), TestItem>>,

                id: KeystoreId,

            }

            impl Default for $name {

                fn default() -> Self {

                    Self {

                        inner: Default::default(),

                        id: KeystoreId::from_str($id).unwrap(),

                    }

                }

            }

            #[allow(dead_code)] // this is only dead code for Keystore1

            impl $name {

                fn new_boxed() -> BoxedKeystore {

                    Box::<Self>::default()

                }

            }

            impl crate::Keystore for $name {

                fn contains(

                    &self,

                    key_spec: &dyn KeySpecifier,

                    item_type: &KeystoreItemType,

                ) -> Result<bool> {

                    Ok(self

                        .inner

                        .read()

                        .unwrap()

                        .contains_key(&(key_spec.arti_path().unwrap(), item_type.clone())))

                }

                fn id(&self) -> &KeystoreId {

                    &self.id

                }

                fn get(

                    &self,

                    key_spec: &dyn KeySpecifier,

                    item_type: &KeystoreItemType,

                ) -> Result<Option<ErasedKey>> {

                    Ok(self

                        .inner

                        .read()

                        .unwrap()

                        .get(&(key_spec.arti_path().unwrap(), item_type.clone()))

                        .map(|k| {

                            let mut k = k.clone();

                            k.meta.set_retrieved_from(self.id().clone());

                            Box::new(k) as Box<dyn ItemType>

                        }))

                }

                fn insert(

                    &self,

                    key: &dyn EncodableItem,

                    key_spec: &dyn KeySpecifier,

                ) -> Result<()> {

                    let key = key.downcast_ref::<TestItem>().unwrap();

                    let item = key.as_keystore_item()?;

                    let meta = key.meta.clone();

                    let item_type = item.item_type()?;

                    let key = TestItem { item, meta };

                    self.inner

                        .write()

                        .unwrap()

                        .insert((key_spec.arti_path().unwrap(), item_type), key);

                    Ok(())

                }

                fn remove(

                    &self,

                    key_spec: &dyn KeySpecifier,

                    item_type: &KeystoreItemType,

                ) -> Result<Option<()>> {

                    Ok(self

                        .inner

                        .write()

                        .unwrap()

                        .remove(&(key_spec.arti_path().unwrap(), item_type.clone()))

                        .map(|_| ()))

                }

                fn list(&self) -> Result<Vec<(KeyPath, KeystoreItemType)>> {

                    Ok(self

                        .inner

                        .read()

                        .unwrap()

                        .iter()

                        .map(|((arti_path, item_type), _)| {

                            (KeyPath::Arti(arti_path.clone()), item_type.clone())

                        })

                        .collect())

                }

            }

        };

    }

    macro_rules! impl_specifier {

        ($name:tt, $id:expr) => {

            struct $name;

            impl KeySpecifier for $name {

                fn arti_path(&self) -> StdResult<ArtiPath, ArtiPathUnavailableError> {

                    Ok(ArtiPath::new($id.into()).map_err(|e| tor_error::internal!("{e}"))?)

                }

                fn ctor_path(&self) -> Option<crate::CTorPath> {

                    None

                }

                fn keypair_specifier(&self) -> Option<Box<dyn KeySpecifier>> {

                    None

                }

            }

        };

    }

    impl_keystore!(Keystore1, "keystore1");

    impl_keystore!(Keystore2, "keystore2");

    impl_keystore!(Keystore3, "keystore3");

    impl_specifier!(TestKeySpecifier1, "spec1");

    impl_specifier!(TestKeySpecifier2, "spec2");

    impl_specifier!(TestKeySpecifier3, "spec3");

    impl_specifier!(TestKeySpecifier4, "spec4");

    impl_specifier!(TestPublicKeySpecifier1, "pub-spec1");

    /// Create a test `KeystoreEntry`.

    fn entry_descriptor(specifier: impl KeySpecifier, keystore_id: &KeystoreId) -> KeystoreEntry {

        KeystoreEntry {

            key_path: specifier.arti_path().unwrap().into(),

            key_type: TestItem::item_type(),

            keystore_id,

        }

    }

    #[test]

    #[allow(clippy::cognitive_complexity)]

    fn insert_and_get() {

        let mut builder = KeyMgrBuilder::default().primary_store(Box::<Keystore1>::default());

        builder

            .secondary_stores()

            .extend([Keystore2::new_boxed(), Keystore3::new_boxed()]);

        let mgr = builder.build().unwrap();

        // Insert a key into Keystore2

        let old_key = mgr

            .insert(

                TestItem::new("coot"),

                &TestKeySpecifier1,

                KeystoreSelector::Id(&KeystoreId::from_str("keystore2").unwrap()),

                true,

            )

            .unwrap();

        assert!(old_key.is_none());

        let key = mgr.get::<TestItem>(&TestKeySpecifier1).unwrap().unwrap();

        assert_eq!(key.meta.item_id(), "coot");

        assert_eq!(

            key.meta.retrieved_from(),

            Some(&KeystoreId::from_str("keystore2").unwrap())

        );

        assert_eq!(key.meta.is_generated(), false);

        // Insert a different key using the _same_ key specifier.

        let old_key = mgr

            .insert(

                TestItem::new("gull"),

                &TestKeySpecifier1,

                KeystoreSelector::Id(&KeystoreId::from_str("keystore2").unwrap()),

                true,

            )

            .unwrap()

            .unwrap();

        assert_eq!(old_key.meta.item_id(), "coot");

        assert_eq!(

            old_key.meta.retrieved_from(),

            Some(&KeystoreId::from_str("keystore2").unwrap())

        );

        assert_eq!(old_key.meta.is_generated(), false);

        // Check that the original value was overwritten:

        let key = mgr.get::<TestItem>(&TestKeySpecifier1).unwrap().unwrap();

        assert_eq!(key.meta.item_id(), "gull");

        assert_eq!(

            key.meta.retrieved_from(),

            Some(&KeystoreId::from_str("keystore2").unwrap())

        );

        assert_eq!(key.meta.is_generated(), false);

        // Insert a different key using the _same_ key specifier (overwrite = false)

        let err = mgr

            .insert(

                TestItem::new("gull"),

                &TestKeySpecifier1,

                KeystoreSelector::Id(&KeystoreId::from_str("keystore2").unwrap()),

                false,

            )

            .unwrap_err();

        assert!(matches!(err, crate::Error::KeyAlreadyExists));

        // Insert a new key into Keystore2 (overwrite = false)

        let old_key = mgr

            .insert(

                TestItem::new("penguin"),

                &TestKeySpecifier2,

                KeystoreSelector::Id(&KeystoreId::from_str("keystore2").unwrap()),

                false,

            )

            .unwrap();

        assert!(old_key.is_none());

        // Insert a key into the primary keystore

        let old_key = mgr

            .insert(

                TestItem::new("moorhen"),

                &TestKeySpecifier3,

                KeystoreSelector::Primary,

                true,

            )

            .unwrap();

        assert!(old_key.is_none());

        let key = mgr.get::<TestItem>(&TestKeySpecifier3).unwrap().unwrap();

        assert_eq!(key.meta.item_id(), "moorhen");

        assert_eq!(

            key.meta.retrieved_from(),

            Some(&KeystoreId::from_str("keystore1").unwrap())

        );

        assert_eq!(key.meta.is_generated(), false);

        // The key doesn't exist in any of the stores yet.

        assert!(mgr.get::<TestItem>(&TestKeySpecifier4).unwrap().is_none());

        // Insert the same key into all 3 key stores, in reverse order of keystore priority

        // (otherwise KeyMgr::get will return the key from the primary store for each iteration and

        // we won't be able to see the key was actually inserted in each store).

        for store in ["keystore3", "keystore2", "keystore1"] {

            let old_key = mgr

                .insert(

                    TestItem::new("cormorant"),

                    &TestKeySpecifier4,

                    KeystoreSelector::Id(&KeystoreId::from_str(store).unwrap()),

                    true,

                )

                .unwrap();

            assert!(old_key.is_none());

            // Ensure the key now exists in `store`.

            let key = mgr.get::<TestItem>(&TestKeySpecifier4).unwrap().unwrap();

            assert_eq!(key.meta.item_id(), "cormorant");

            assert_eq!(

                key.meta.retrieved_from(),

                Some(&KeystoreId::from_str(store).unwrap())

            );

            assert_eq!(key.meta.is_generated(), false);

        }

        // The key exists in all key stores, but if no keystore_id is specified, we return the

        // value from the first key store it is found in (in this case, Keystore1)

        let key = mgr.get::<TestItem>(&TestKeySpecifier4).unwrap().unwrap();

        assert_eq!(key.meta.item_id(), "cormorant");

        assert_eq!(

            key.meta.retrieved_from(),

            Some(&KeystoreId::from_str("keystore1").unwrap())

        );

        assert_eq!(key.meta.is_generated(), false);

    }

    #[test]

    fn remove() {

        let mut builder = KeyMgrBuilder::default().primary_store(Box::<Keystore1>::default());

        builder

            .secondary_stores()

            .extend([Keystore2::new_boxed(), Keystore3::new_boxed()]);

        let mgr = builder.build().unwrap();

        assert!(!mgr.secondary_stores[0]

            .contains(&TestKeySpecifier1, &TestItem::item_type())

            .unwrap());

        // Insert a key into Keystore2

        mgr.insert(

            TestItem::new("coot"),

            &TestKeySpecifier1,

            KeystoreSelector::Id(&KeystoreId::from_str("keystore2").unwrap()),

            true,

        )

        .unwrap();

        let key = mgr.get::<TestItem>(&TestKeySpecifier1).unwrap().unwrap();

        assert_eq!(key.meta.item_id(), "coot");

        assert_eq!(

            key.meta.retrieved_from(),

            Some(&KeystoreId::from_str("keystore2").unwrap())

        );

        assert_eq!(key.meta.is_generated(), false);

        // Try to remove the key from a non-existent key store

        assert!(mgr

            .remove::<TestItem>(

                &TestKeySpecifier1,

                KeystoreSelector::Id(&KeystoreId::from_str("not_an_id_we_know_of").unwrap())

            )

            .is_err());

        // The key still exists in Keystore2

        assert!(mgr.secondary_stores[0]

            .contains(&TestKeySpecifier1, &TestItem::item_type())

            .unwrap());

        // Try to remove the key from the primary key store

        assert!(mgr

            .remove::<TestItem>(&TestKeySpecifier1, KeystoreSelector::Primary)

            .unwrap()

            .is_none());

        // The key still exists in Keystore2

        assert!(mgr.secondary_stores[0]

            .contains(&TestKeySpecifier1, &TestItem::item_type())

            .unwrap());

        // Removing from Keystore2 should succeed.

        let removed_key = mgr

            .remove::<TestItem>(

                &TestKeySpecifier1,

                KeystoreSelector::Id(&KeystoreId::from_str("keystore2").unwrap()),

            )

            .unwrap()

            .unwrap();

        assert_eq!(removed_key.meta.item_id(), "coot");

        assert_eq!(

            removed_key.meta.retrieved_from(),

            Some(&KeystoreId::from_str("keystore2").unwrap())

        );

        assert_eq!(removed_key.meta.is_generated(), false);

        // The key doesn't exist in Keystore2 anymore

        assert!(!mgr.secondary_stores[0]

            .contains(&TestKeySpecifier1, &TestItem::item_type())

            .unwrap());

    }

    #[test]

    fn keygen() {

        let mut rng = FakeEntropicRng(testing_rng());

        let mgr = KeyMgrBuilder::default()

            .primary_store(Box::<Keystore1>::default())

            .build()

            .unwrap();

        mgr.insert(

            TestItem::new("coot"),

            &TestKeySpecifier1,

            KeystoreSelector::Primary,

            true,

        )

        .unwrap();

        // There is no corresponding public key entry.

        assert!(mgr

            .get::<TestPublicKey>(&TestPublicKeySpecifier1)

            .unwrap()

            .is_none());

        // Try to generate a new key (overwrite = false)

        let err = mgr

            .generate::<TestItem>(

                &TestKeySpecifier1,

                KeystoreSelector::Primary,

                &mut rng,

                false,

            )

            .unwrap_err();

        assert!(matches!(err, crate::Error::KeyAlreadyExists));

        // The previous entry was not overwritten because overwrite = false

        let key = mgr.get::<TestItem>(&TestKeySpecifier1).unwrap().unwrap();

        assert_eq!(key.meta.item_id(), "coot");

        assert_eq!(

            key.meta.retrieved_from(),

            Some(&KeystoreId::from_str("keystore1").unwrap())

        );

        assert_eq!(key.meta.is_generated(), false);

        // We don't store public keys in the keystore

        assert!(mgr

            .get::<TestPublicKey>(&TestPublicKeySpecifier1)

            .unwrap()

            .is_none());

        // Try to generate a new key (overwrite = true)

        let generated_key = mgr

            .generate::<TestItem>(

                &TestKeySpecifier1,

                KeystoreSelector::Primary,

                &mut rng,

                true,

            )

            .unwrap();

        assert_eq!(generated_key.meta.item_id(), "generated_test_key");

        // Not set in a freshly generated key, because KeyMgr::generate()

        // returns it straight away, without going through Keystore::get()

        assert_eq!(generated_key.meta.retrieved_from(), None);

        assert_eq!(generated_key.meta.is_generated(), true);

        // Retrieve the inserted key

        let retrieved_key = mgr.get::<TestItem>(&TestKeySpecifier1).unwrap().unwrap();

        assert_eq!(retrieved_key.meta.item_id(), "generated_test_key");

        assert_eq!(

            retrieved_key.meta.retrieved_from(),

            Some(&KeystoreId::from_str("keystore1").unwrap())

        );

        assert_eq!(retrieved_key.meta.is_generated(), true);

        // We don't store public keys in the keystore

        assert!(mgr

            .get::<TestPublicKey>(&TestPublicKeySpecifier1)

            .unwrap()

            .is_none());