bouncycastle_core/

traits.rs

//! Provides simplified abstracted APIs over classes of cryptographic primitives, such as Hash, KDF, etc.

use crate::errors::*;
use crate::key_material::KeyMaterialTrait;
use core::fmt::{Debug, Display};
use core::marker::Sized;

// Imports needed for docs
#[allow(unused_imports)]
use crate::key_material::KeyMaterial;
#[allow(unused_imports)]
use crate::key_material::KeyType;
// end of imports needed for docs

/// Metadata about a cryptographic algorithm.
pub trait Algorithm {
    /// String name for the algorithm, used consistently across the library.
    const ALG_NAME: &'static str;
    /// Maximum security strength supported by the algorithm.
    /// In other words, this algorithm can produce outputs up to this security strength,
    /// but may produce outputs with lower security strength, for example, if asked to truncate.
    const MAX_SECURITY_STRENGTH: SecurityStrength;
}

/// Some algorithms have an assigned OID.
pub trait AlgorithmOID {
    /// The OID in component form -- each u32 is one OID component.
    const OID: &'static [u32];
    /// The OID in its DER-encoded form.
    const OID_DER: &'static [u8];
}

// todo -- split all the SymmetricCipher traits into Encryptor and Decryptor
/// The basic one-shot encrypt and decrypt that all types of symmetric ciphers must implement.
/// These are meant to be simple, easy to use, secure, and fool-proof APIs, but they may result in
/// ciphertexts that are incompatible with other implementations as ciphers in more complex modes, such
/// as AEADs or stream ciphers may need to stick extra data either at the beginning or end of the ciphertext.
/// See the documentation of the underlying implementation for more details.
pub trait SymmetricCipher<const KEY_LEN: usize, const INIT_DATA_LEN: usize>: Algorithm {
    #[cfg(feature = "std")]
    /// A one-shot API to encrypt some plaintext with the given key.
    /// This function returns the ciphertext as a `Vec<u8>`, and therefore is only available when compiling with std.
    /// Returns a tuple containing the initialization data and the ciphertext.
    /// This is not available if building for no_std.
    fn encrypt(
        key: &KeyMaterial<KEY_LEN>,
        plaintext: &[u8],
    ) -> Result<([u8; INIT_DATA_LEN], Vec<u8>), SymmetricCipherError>;
    /// A one-shot API to encrypt some plaintext with the given key.
    /// This function takes a reference to the output buffer for the ciphertext, and is therefore available in no_std.
    /// See the documentation for the underlying implementation for details on providing a ciphertext buffer of sufficient size;
    /// typically the ciphertext is the same length as the plaintext, but some ciphers may have an expansion factor or require
    /// extra space for a nonce or tag.
    /// Returns a tuple containing the initialization data and the number of bytes written to the ciphertext buffer.
    fn encrypt_out(
        key: &KeyMaterial<KEY_LEN>,
        plaintext: &[u8],
        ciphertext: &mut [u8],
    ) -> Result<([u8; INIT_DATA_LEN], usize), SymmetricCipherError>;
    #[cfg(feature = "std")]
    /// A one-shot API to decrypt some ciphertext with the given key.
    /// This function returns the ciphertext as a `Vec<u8>`, and therefore is only available when compiling with std.
    /// This is not available if building for no_std.
    fn decrypt(
        key: &KeyMaterial<KEY_LEN>,
        init_data: [u8; INIT_DATA_LEN],
        ciphertext: &[u8],
    ) -> Result<Vec<u8>, SymmetricCipherError>;
    /// A one-shot API to decrypt some ciphertext with the given key.
    /// This function takes a reference to the output buffer for the plaintext, and is therefore available in no_std.
    /// See the documentation for the underlying implementation for details on providing a plaintext buffer of sufficient size;
    /// typically the ciphertext is the same length as the plaintext, but some ciphers may have an expansion factor or require
    /// extra space for a nonce or tag.
    /// Returns a tuple containing the initialization data and the number of bytes written to the plaintext buffer.
    fn decrypt_out(
        key: &KeyMaterial<KEY_LEN>,
        init_data: [u8; INIT_DATA_LEN],
        ciphertext: &[u8],
        plaintext: &mut [u8],
    ) -> Result<usize, SymmetricCipherError>;
}

/// The basic functions of a block cipher.
/// This trait allows for a block cipher to generate initialization data, such as an Initialization Vector (IV) or Counter (CTR)
/// which is not technically part of the ciphertext, but must be transmitted along with the ciphertext in order for the
/// recipient to perform successful decryption. The length of the initialization data is specified by the implementing struct
/// via the `INIT_DATA_LEN` constant.
/// In order for these one-shot APIs to be usable securely in all contexts, the init data will be generated
/// securely by the block cipher implementation and returned along with the ciphertext, and there is no API for the
/// user to provide the init data. If you require this functionality, see the documentation for the underlying implementation.
pub trait BlockCipher<const KEY_LEN: usize, const INIT_DATA_LEN: usize, const BLOCK_LEN: usize>:
    SymmetricCipher<KEY_LEN, INIT_DATA_LEN> + Sized
{
    /// Constructor that begins a flow of the streaming API for encrypting one block at a time.
    /// Allows for the implementation to return init data such as an IV which is generated prior to encrypting the first block.
    fn do_encrypt_init(
        key: &KeyMaterial<KEY_LEN>,
    ) -> Result<(Self, [u8; INIT_DATA_LEN]), SymmetricCipherError>;
    /// Encrypts a single block of plaintext.
    fn do_encrypt_block(
        &mut self,
        plaintext: &[u8; BLOCK_LEN],
    ) -> Result<[u8; BLOCK_LEN], SymmetricCipherError>;
    /// Encrypts a single block of plaintext and writes the ciphertext to the provided buffer.
    fn do_encrypt_block_out(
        &mut self,
        plaintext: &[u8; BLOCK_LEN],
        ciphertext: &mut [u8; BLOCK_LEN],
    ) -> Result<usize, SymmetricCipherError>;
    /// Encrypts the final block of plaintext.
    fn do_encrypt_final(
        &mut self,
        plaintext: &[u8; BLOCK_LEN],
    ) -> Result<[u8; BLOCK_LEN], SymmetricCipherError>;
    /// Encrypts the final block of plaintext and writes the ciphertext to the provided buffer.
    fn do_encrypt_final_out(
        &mut self,
        plaintext: &[u8; BLOCK_LEN],
        ciphertext: &mut [u8; BLOCK_LEN],
    ) -> Result<usize, SymmetricCipherError>;
    /// Constructor that begins a flow of the streaming API for decryption one block at a time.
    fn do_decrypt_init(
        key: &KeyMaterial<KEY_LEN>,
        init_data: &[u8; INIT_DATA_LEN],
    ) -> Result<Self, SymmetricCipherError>;
    /// Decrypts a single block of ciphertext.
    fn do_decrypt_block(
        &mut self,
        ciphertext: &[u8; BLOCK_LEN],
    ) -> Result<[u8; BLOCK_LEN], SymmetricCipherError>;
    /// Decrypts a single block of ciphertext and writes the plaintext to the provided buffer.
    fn do_decrypt_block_out(
        &mut self,
        ciphertext: &[u8; BLOCK_LEN],
        plaintext: &mut [u8; BLOCK_LEN],
    ) -> Result<usize, SymmetricCipherError>;
    /// Decrypts the final block of ciphertext.
    /// This is the decryption counterpart to [`BlockCipher::do_encrypt_final`] and is where an
    /// implementation validates and strips any padding (or otherwise finalizes the flow).
    fn do_decrypt_final(
        &mut self,
        ciphertext: &[u8; BLOCK_LEN],
    ) -> Result<[u8; BLOCK_LEN], SymmetricCipherError>;
    /// Decrypts the final block of ciphertext and writes the plaintext to the provided buffer.
    fn do_decrypt_final_out(
        &mut self,
        ciphertext: &[u8; BLOCK_LEN],
        plaintext: &mut [u8; BLOCK_LEN],
    ) -> Result<usize, SymmetricCipherError>;
}

/// The basic functions of an Authenticated Encryption with Addititional Data cipher.
pub trait AEADCipher<const KEY_LEN: usize, const NONCE_LEN: usize, const TAG_LEN: usize>:
    SymmetricCipher<KEY_LEN, NONCE_LEN> + Sized
{
    #[cfg(feature = "std")]
    /// A one-shot API to encrypt some plaintext with the given key.
    /// A distinguishing feature of AEAD ciphers is the ability to provide additional authenticated data (AAD)
    /// that is not encrypted but is protected by the authentication tag; ie it can be sent along with the ciphertext
    /// and any tampering with it will result in the decryption operation failing the tag check.
    /// This function returns the ciphertext as a `Vec<u8>`, and therefore is only available when compiling with std.
    /// Returns a tuple containing a generated nonce, the ciphertext and the tag.
    fn aead_encrypt(
        key: &KeyMaterial<KEY_LEN>,
        aad: &[u8],
        plaintext: &[u8],
    ) -> Result<([u8; NONCE_LEN], Vec<u8>, [u8; TAG_LEN]), SymmetricCipherError>;
    /// A one-shot API to encrypt some plaintext with the given key.
    /// A distinguishing feature of AEAD ciphers is the ability to provide additional authenticated data (AAD)
    /// that is not encrypted but is protected by the authentication tag; ie it can be sent along with the ciphertext
    /// and any tampering with it will result in the decryption operation failing the tag check.
    /// Returns a tuple containing the randomly-generated nonce, number of bytes written to the ciphertext buffer, and the tag.
    /// If you need a deterministic mode where you feed in the nonce, use the streaming API of [`BlockCipher`]
    /// or [`StreamCipher`] as appropriate and feed the nonce into the IV field.
    fn aead_encrypt_out(
        key: &KeyMaterial<KEY_LEN>,
        aad: &[u8],
        plaintext: &[u8],
        ciphertext: &mut [u8],
    ) -> Result<([u8; NONCE_LEN], usize, [u8; TAG_LEN]), SymmetricCipherError>;
    /// All AEAD ciphers will also be either a [`BlockCipher`] or a [`StreamCipher`], and so will already
    /// have a streaming API.
    /// This allows you to finish either style of streaming API flow with AEAD specific do_final()
    /// that computes and returns the authentication tag.
    fn do_aead_encrypt_final(self) -> Result<[u8; TAG_LEN], SymmetricCipherError>;
    #[cfg(feature = "std")]
    /// A one-shot API to decrypt some ciphertext with the given key.
    /// This function returns the ciphertext as a `Vec<u8>`, and therefore is only available when compiling with std.
    fn aead_decrypt(
        key: &KeyMaterial<KEY_LEN>,
        nonce: &[u8; NONCE_LEN],
        aad: &[u8],
        ciphertext: &[u8],
        tag: &[u8; TAG_LEN],
    ) -> Result<Vec<u8>, SymmetricCipherError>;
    /// A one-shot API to decrypt some ciphertext with the given key.
    /// This function takes a reference to the output buffer for the plaintext, and is therefore available in no_std.
    /// See the documentation for the underlying implementation for details on providing a plaintext buffer of sufficient size;
    /// typically the ciphertext is the same length as the plaintext, but some ciphers may have an expansion factor or require
    /// extra space for a nonce or tag.
    /// Returns the number of bytes written to the plaintext buffer.
    fn aead_decrypt_out(
        key: &KeyMaterial<KEY_LEN>,
        nonce: &[u8; NONCE_LEN],
        aad: &[u8],
        ciphertext: &[u8],
        tag: &[u8; TAG_LEN],
        plaintext: &mut [u8],
    ) -> Result<usize, SymmetricCipherError>;
    /// All AEAD ciphers will also be either a [`BlockCipher`] or a [`StreamCipher`], and so will already
    /// have a streaming API.
    /// This allows you to finish either style of streaming API flow with AEAD specific do_final()
    /// that computes and returns the authentication tag.
    fn do_aead_decrypt_final(self, tag: &[u8; TAG_LEN]) -> Result<(), SymmetricCipherError>;
}

/// The basic functions of a stream cipher, which differ from those of a block cipher only in that
/// a stream cipher is assumed to have no underlying block size tied to the implementation, and so the caller gets to specify
/// the block size for the streaming APIs.
pub trait StreamCipher<const KEY_LEN: usize, const INIT_DATA_LEN: usize>:
    SymmetricCipher<KEY_LEN, INIT_DATA_LEN> + Sized
{
    /// Constructor that begins a flow of the streaming API for encrypting one block at a time.
    /// Allows for the implementation to return init data such as an IV which is generated prior to encrypting the first block.
    fn do_stream_encrypt_init(
        key: &KeyMaterial<KEY_LEN>,
    ) -> Result<(Self, [u8; INIT_DATA_LEN]), SymmetricCipherError>;
    /// Encrypts a single block of plaintext.
    fn do_stream_encrypt_block<const BLOCK_LEN: usize>(
        &mut self,
        plaintext: &[u8; BLOCK_LEN],
    ) -> Result<[u8; BLOCK_LEN], SymmetricCipherError>;
    /// Encrypts a single block of plaintext and writes the ciphertext to the provided buffer.
    fn do_stream_encrypt_block_out<const BLOCK_LEN: usize>(
        &mut self,
        plaintext: &[u8; BLOCK_LEN],
        ciphertext: &mut [u8; BLOCK_LEN],
    ) -> Result<usize, SymmetricCipherError>;
    /// Encrypts the final block of plaintext.
    fn do_stream_encrypt_final<const BLOCK_LEN: usize>(
        &mut self,
        plaintext: &[u8; BLOCK_LEN],
    ) -> Result<[u8; BLOCK_LEN], SymmetricCipherError>;
    /// Encrypts the final block of plaintext and writes the ciphertext to the provided buffer.
    fn do_stream_encrypt_final_out<const BLOCK_LEN: usize>(
        &mut self,
        plaintext: &[u8; BLOCK_LEN],
        ciphertext: &mut [u8; BLOCK_LEN],
    ) -> Result<usize, SymmetricCipherError>;
    /// Constructor that begins a flow of the streaming API for decryption one block at a time.
    fn do_stream_decrypt_init(
        key: &KeyMaterial<KEY_LEN>,
        init_data: &[u8; INIT_DATA_LEN],
    ) -> Result<Self, SymmetricCipherError>;
    /// Decrypts a single block of ciphertext.
    fn do_stream_decrypt_block<const BLOCK_LEN: usize>(
        &mut self,
        ciphertext: &[u8; BLOCK_LEN],
    ) -> Result<[u8; BLOCK_LEN], SymmetricCipherError>;
    /// Decrypts a single block of ciphertext and writes the plaintext to the provided buffer.
    fn do_stream_decrypt_block_out<const BLOCK_LEN: usize>(
        &mut self,
        ciphertext: &[u8; BLOCK_LEN],
        plaintext: &mut [u8; BLOCK_LEN],
    ) -> Result<usize, SymmetricCipherError>;
}

/// A hash function is a cryptographic primitive that takes an input of any length and produces a fixed-size output.
/// Formally: `H: {0,1}^* -> {0,1}^n`.
/// A cryptographic hash function will typically satisfy several security properties, including:
/// * Collision resistance: finding two inputs that yield the same output is computationally difficult.
/// * Preimage resistance: from a given output, finding an input that generates it is computationally difficult.
/// * Second preimage resistance: given an input, finding another input that yields the same output is computationally difficult.
pub trait Hash: Algorithm + Default {
    /// The size of the internal block in bits -- needed by functions such as HMAC to compute security parameters.
    fn block_bitlen(&self) -> usize;

    /// The size of the output in bytes.
    fn output_len(&self) -> usize;

    /// A static one-shot API that hashes the provided data.
    /// `data` can be of any length, including zero bytes.
    fn hash(self, data: &[u8]) -> Vec<u8>;

    /// A static one-shot API that hashes the provided data into the provided output slice.
    /// `data` can be of any length, including zero bytes.
    /// The entire output buffer is zeroized before the hash output is written.
    /// The return value is the number of bytes written.
    fn hash_out(self, data: &[u8], output: &mut [u8]) -> usize;

    /// Provide a chunk of data to be absorbed into the hashes.
    /// `data` can be of any length, including zero bytes.
    /// do_update() is intended to be used as part of a streaming interface, and so may by called multiple times.
    fn do_update(&mut self, data: &[u8]);

    /// Finish absorbing input and produce the hashes output.
    /// Consumes self, so this must be the final call to this object.
    fn do_final(self) -> Vec<u8>;

    /// Finish absorbing input and produce the hashes output.
    /// Consumes self, so this must be the final call to this object.
    ///
    /// If the provided buffer is smaller than the hash's output length, the output will be truncated.
    /// If the provided buffer is larger than the hash's output length, the output  will be placed in
    /// the first [`Hash::output_len`] bytes.
    /// The entire output buffer is zeroized before the hash output is written, so any bytes past
    /// [`Hash::output_len`] will be 0.
    ///
    /// The return value is the number of bytes written.
    fn do_final_out(self, output: &mut [u8]) -> usize;

    /// The same as [`Hash::do_final`], but allows for supplying a partial byte as the last input.
    /// Assumes that the input is in the least significant bits (big endian).
    fn do_final_partial_bits(
        self,
        partial_byte: u8,
        num_partial_bits: usize,
    ) -> Result<Vec<u8>, HashError>;

    /// The same as [`Hash::do_final_out`], but allows for supplying a partial byte as the last input.
    /// Assumes that the input is in the least significant bits (big endian).
    /// will be placed in the first [`Hash::output_len`] bytes.
    /// The entire output buffer is zeroized before the hash output is written.
    /// The return value is the number of bytes written.
    fn do_final_partial_bits_out(
        self,
        partial_byte: u8,
        num_partial_bits: usize,
        output: &mut [u8],
    ) -> Result<usize, HashError>;

    /// Returns the maximum security strength that this KDF is capable of supporting, based on the underlying primitives.
    fn max_security_strength(&self) -> SecurityStrength;
}

/// Standard parameters for a hash function.
pub trait HashAlgParams: Algorithm {
    /// The fixed output length of the hash function.
    const OUTPUT_LEN: usize;
    /// The internal block length of the hash function, which is often used as a meta-parameter for
    /// determining the security strength of the hash function since this limits the internal
    /// collision resistance of the hash function.
    const BLOCK_LEN: usize;
}

/// A Key Derivation Function (KDF) is a function that takes in one or more input key and some unstructured
/// additional input, and uses them to produces a derived key.
pub trait KDF: Default {
    /// Implementations of this function are capable of deriving an output key from an input key,
    /// assuming that they have been properly initialized.
    ///
    /// # Entropy Conversion rules
    /// Implementations SHOULD act on a KeyMaterial of any [`KeyType`] and will generally
    /// return a KeyMaterial of the same type
    ///
    /// ex.:
    ///
    ///   * [`KeyType::Unknown`] -> [`KeyType::Unknown`])
    ///   * [`KeyType::CryptographicRandom`] -> [`KeyType::CryptographicRandom`])
    ///   * [`KeyType::SymmetricCipherKey`] -> [`KeyType::SymmetricCipherKey`])
    ///
    /// If provided with an input key, even if it is [`KeyType::CryptographicRandom`], but that
    /// contains less key material than the internal block size of the KDF, then the KDF
    /// will not be considered properly seeded, and the output [`KeyMaterial`] will be set to
    /// [`KeyType::Unknown`] -- for example, seeding SHA3-256 with a [`KeyMaterial`] containing
    /// only 128 bits of key material.
    ///
    /// An implementation can, and in most cases SHOULD, return a [`HashError`] if provided
    /// with a [`KeyMaterial`] of type [`KeyType::Zeroized`].
    ///
    /// # Additional Input
    /// The `additional_input` parameter is used in deriving the key, but is not credited with any entropy,
    /// and therefore does not affect the type of the output [`KeyMaterial`].
    /// This corresponds directly to `FixedInfo` as defined in NIST SP 800-56C.
    /// The `additional_input` parameter can be empty by passing in `&[0u8; 0]`.
    ///
    /// Output length: this function will create a KeyMaterial populated with the default output length
    /// of the underlying hash primitive.
    fn derive_key(
        self,
        key: &impl KeyMaterialTrait,
        additional_input: &[u8],
    ) -> Result<Box<dyn KeyMaterialTrait>, KDFError>;

    /// Same as [`KDF::derive_key`], but fills the provided output [`KeyMaterial`].
    ///
    /// Output length: this function will behave differently depending on the underlying hash primitive;
    /// some, such as SHA2 or SHA3 will produce a fixed-length output, while others, such as SHAKE or HKDF,
    /// will fill the provided KeyMaterial to capacity and require you to truncate it afterward
    /// using [`KeyMaterialTrait::set_key_len`].
    fn derive_key_out(
        self,
        key: &impl KeyMaterialTrait,
        additional_input: &[u8],
        output_key: &mut impl KeyMaterialTrait,
    ) -> Result<usize, KDFError>;

    /// Meant to be used for hybrid key establishment schemes or other spit-key scenarios where multiple
    /// keys need to be combined into a single key of the same length.
    ///
    /// This function can also be used to mix a KeyMaterial of low entropy with one of full entropy to
    /// produce a new full entropy key. For the purposes of determining whether enough input key material
    /// was provided, the lengths of all full-entropy input keys are added together.
    ///
    /// Implementations that are not safe to be used as a split-key PRF MAY still implement this function
    /// and return a result, but SHOULD set the entropy level of the returned key appropriately; for example
    /// a KDF that is only full-entropy when keyed in the first input SHOULD return a full entropy key
    /// only if the first input is full entropy.
    ///
    /// Implementations can, and in most cases SHOULD, return a [`KeyMaterial`] of the same type as the
    /// strongest key, and SHOULD throw a [`HashError`] if all input keys are zeroized.
    /// For example output a [`KeyType::CryptographicRandom`] key whenever any one of
    /// the input keys is a [`KeyType::CryptographicRandom`] key.
    /// As another example, combining a [`KeyType::Unknown`] key with a [`KeyType::MACKey`] key
    /// should return a [`KeyType::MACKey`].
    ///
    /// Output length: this function will create a KeyMaterial populated with the default output length
    /// of the underlying hash primitive.
    fn derive_key_from_multiple(
        self,
        keys: &[&impl KeyMaterialTrait],
        additional_input: &[u8],
    ) -> Result<Box<dyn KeyMaterialTrait>, KDFError>;

    /// Same as [`KDF::derive_key`], but fills the provided output [`KeyMaterial`].
    ///
    /// Output length: this function will behave differently depending on the underlying hash primitive;
    /// some, such as SHA2 or SHA3 will produce a fixed-length output, while others, such as SHAKE or HKDF,
    /// will fill the provided KeyMaterial to capacity and require you to truncate it afterward
    /// by using [`KeyMaterialTrait::set_key_len`].
    fn derive_key_from_multiple_out(
        self,
        keys: &[&impl KeyMaterialTrait],
        additional_input: &[u8],
        output_key: &mut impl KeyMaterialTrait,
    ) -> Result<usize, KDFError>;

    /// Returns the maximum security strength that this KDF is capable of supporting, based on the underlying primitives.
    fn max_security_strength(&self) -> SecurityStrength;
}

/// A Key Encapsulation Mechanism (KEM) is defined as a set of three operations:
/// key generation, encapsulation, and decapsulation.
///
/// This trait represents the encapsulation operation performed by the holder of the public key.
/// Decapsulation operations are performed by the corresponding [`KEMDecapsulator`] trait, and key
/// generation is provided as an inherent associated function directly on the algorithm struct.
/// There are several reasons for this split: first is architectural; some complex algorithms may
/// benefit from having the encapsulation and decapsulation implementations split into separate modules.
/// Second is for compliance: sometimes a policy soft-deprecates an algorithm so that new ciphertexts
/// can no longer be created, but existing ciphertexts can still be decapsulated. Splitting the traits
/// makes this policy easier to enforce.
///
/// The arrays used to encode public keys, ciphertexts, and shared secrets are statically-sized
/// because this allows us to safely remove runtime checks for array lengths, which overall reduces
/// the fallibility of the library. This design choice could make this trait complicated to apply
/// to a KEM algorithm that does not have fixed sizes for the encodings of these objects.
pub trait KEMEncapsulator<
    PK: KEMPublicKey<PK_LEN>,
    const PK_LEN: usize,
    const CT_LEN: usize,
    const SS_LEN: usize,
>: Sized
{
    /// Performs an encapsulation against the given public key.
    /// Sources randomness from the library's default OS-backed RNG.
    /// Returns the ciphertext and derived shared secret.
    fn encaps(pk: &PK) -> Result<(KeyMaterial<SS_LEN>, [u8; CT_LEN]), KEMError>;
    /// Performs an encapsulation against the given public key.
    /// Sources randomness from the provided RNG.
    /// Returns the ciphertext and derived shared secret.
    fn encaps_rng(
        pk: &PK,
        rng: &mut dyn RNG,
    ) -> Result<(KeyMaterial<SS_LEN>, [u8; CT_LEN]), KEMError>;
}

/// A Key Encapsulation Mechanism (KEM) is defined as a set of three operations:
/// key generation, encapsulation, and decapsulation.
///
/// This trait represents the decapsulation operation performed by the holder of the private key.
/// Encapsulation operations are performed by the corresponding [`KEMEncapsulator`] trait, and key
/// generation is provided as an inherent associated function directly on the algorithm struct.
/// There are several reasons for this split: first is architectural; some complex algorithms may
/// benefit from having the encapsulation and decapsulation implementations split into separate modules.
/// Second is for compliance: sometimes a policy soft-deprecates an algorithm so that new ciphertexts
/// can no longer be created, but existing ciphertexts can still be decapsulated. Splitting the traits
/// makes this policy easier to enforce.
///
/// The arrays used to encode private keys, ciphertexts, and shared secrets are statically-sized
/// because this allows us to safely remove runtime checks for array lengths, which overall reduces
/// the fallibility of the library. This design choice could make this trait complicated to apply
/// to a KEM algorithm that does not have fixed sizes for the encodings of these objects.
pub trait KEMDecapsulator<
    SK: KEMPrivateKey<SK_LEN>,
    const SK_LEN: usize,
    const CT_LEN: usize,
    const SS_LEN: usize,
>: Sized
{
    /// Performs a decapsulation of the given ciphertext.
    /// Returns the derived shared secret.
    fn decaps(sk: &SK, ct: &[u8]) -> Result<KeyMaterial<SS_LEN>, KEMError>;
}

// todo: could the public and private key types impl Into<T: AsRef<[u8]>> and From<T: AsRef<[u8]>>
// todo: that automatically call the encode and from_bytes() ?

/// A public key for a KEM algorithm, often denoted "pk".
pub trait KEMPublicKey<const PK_LEN: usize>:
    PartialEq + Eq + Clone + Debug + Display + Sized
{
    /// Write it out to bytes in its standard encoding.
    fn encode(&self) -> [u8; PK_LEN];
    /// Write it out to bytes in its standard encoding.
    /// The entire output buffer is zeroized before the encoding is written.
    fn encode_out(&self, out: &mut [u8; PK_LEN]) -> usize;
    /// Read it in from bytes in its standard encoding.
    fn from_bytes(bytes: &[u8]) -> Result<Self, KEMError>;
}

/// A private key for a KEM algorithm, often denoted "sk" (for "secret key").
pub trait KEMPrivateKey<const SK_LEN: usize>: PartialEq + Eq + Clone + Sized {
    /// Write it out to bytes in its standard encoding.
    fn encode(&self) -> [u8; SK_LEN];
    /// Write it out to bytes in its standard encoding.
    /// The entire output buffer is zeroized before the encoding is written.
    fn encode_out(&self, out: &mut [u8; SK_LEN]) -> usize;
    /// Read it in from bytes in its standard encoding.
    fn from_bytes(bytes: &[u8]) -> Result<Self, KEMError>;
}

/// A Message Authentication Code algorithm is a keyed hash function that behaves somewhat like a symmetric signature function.
/// A MAC algorithm takes in a key and some data, and produces a MAC (message authentication code) that
/// can be used to verify the integrity of data.
///
/// This trait provides one-shot functions [`MAC::mac`], [`MAC::mac_out`], and [`MAC::verify`].
/// It also provides streaming functions [`MAC::do_update`], [`MAC::do_final`], [`MAC::do_final_out`],
/// and [`MAC::do_verify_final`].
/// The workflow is that a MAC object is initialized with a key with [`MAC::new`] -- or [`MAC::new_allow_weak_key`] if you
/// need to disable the library's safety mechanism to prevent the use of weak keys -- then data is
/// processed into one or more calls to [`MAC::do_update`],
/// after that the object can either create a MAC with [`MAC::do_final`] or [`MAC::do_final_out`] (which are final functions, and so consume the object),
/// or the object can be used to verify a MAC.
///
/// For varifying an existing MAC, it is functionally equivalent to use the provided [`MAC::verify`] and [`MAC::do_verify_final`]
/// function or to compute a new MAC and compare it to the existing MAC, however the provided verification functions
/// use constant-time comparison to avoid cryptographic timing attacks whereby an attacker could learn
/// the bytes of the MAC value under some conditions. Therefore, it is highly recommended to use the provided verification functions.
///
/// Note that the MAC key is not represented in this trait because it is provided to the MAC algorithm
/// as part of its new functions.
///
/// MACs do not implement Default because they do not have a sensible no-args constructor.
pub trait MAC: Sized {
    /// Create a new MAC instance with the given key.
    ///
    /// This is a common constructor whether creating or verifying a MAC value.
    ///
    /// Key / Salt is optional, which is indicated by providing an uninitialized KeyMaterial object of length zero,
    /// the capacity is irrelevant, so KeyMateriol256::new() or KeyMaterial_internal::<0>::new() would both count as an absent salt.
    ///
    /// # Note about the security strength of the provided key:
    /// If you initialize the MAC with a key that is tagged at a lower [`SecurityStrength`] than the
    /// underlying hash function then [`MAC::new`] will fail with the following error:
    /// ```text
    /// MACError::KeyMaterialError(KeyMaterialError::SecurityStrength("HMAC::init(): provided key has a lower security strength than the instantiated HMAC")
    /// ```
    /// There are situations in which it is completely reasonable and secure to provide low-entropy
    /// (and sometimes all-zero) keys / salts; for these cases we have provided [`MAC::new_allow_weak_key`].
    fn new(key: &impl KeyMaterialTrait) -> Result<Self, MACError>;

    /// Create a new HMAC instance with the given key.
    ///
    /// This constructor completely ignores the [`SecurityStrength`] tag on the input key and will "just work".
    /// This should be used if you really do need to use a weak key, such as an all-zero salt,
    /// but use of this constructor is discouraged and you should really be asking yourself why you need it;
    /// in most cases it indicates that your key is not long enough to support the security level of this
    /// HMAC instance, or the key was derived using algorithms at a lower security level, etc.
    fn new_allow_weak_key(key: &impl KeyMaterialTrait) -> Result<Self, MACError>;

    /// The size of the output in bytes.
    fn output_len(&self) -> usize;

    /// One-shot API that computes a MAC for the provided data.
    /// `data` can be of any length, including zero bytes.
    ///
    /// Note about the security strength of the provided key:
    /// If the provided key is tagged at a lower [`SecurityStrength`] than the instantiated MAC algorithm,
    /// this will fail with an error:
    /// ```text
    /// MACError::KeyMaterialError(KeyMaterialError::SecurityStrength("HMAC::init(): provided key has a lower security strength than the instantiated HMAC")
    /// ```
    fn mac(self, data: &[u8]) -> Vec<u8>;

    /// One-shot API that computes a MAC for the provided data and writes it into the provided output slice.
    /// `data` can be of any length, including zero bytes.
    ///
    /// Depending on the underlying MAC implementation, NIST may require that the library enforce
    /// a minimum length on the mac output value. See documentation for the underlying implementation
    /// to see conditions under which it throws [`MACError::InvalidLength`].
    ///
    /// The entire output buffer is zeroized before the MAC value is written.
    fn mac_out(self, data: &[u8], out: &mut [u8]) -> Result<usize, MACError>;

    /// One-shot API that verifies a MAC for the provided data.
    /// `data` can be of any length, including zero bytes.
    ///
    /// Internally, this will re-compute the MAC value and then compare it to the provided mac value
    /// using constant-time comparison. It is highly encouraged to use this utility function instead of
    /// comparing mac values for equality yourself.
    ///
    /// Returns a bool to indicate successful verification of the provided mac value.
    /// The provided mac value must be an exact match, including length; for example a mac value
    /// which has been truncated, or which contains extra bytes at the end is considered to not be a match
    /// and will return false.
    fn verify(self, data: &[u8], mac: &[u8]) -> bool;

    /// Provide a chunk of data to be absorbed into the MAC.
    /// `data` can be of any length, including zero bytes.
    /// do_update() is intended to be used as part of a streaming interface, and so may by called multiple times.
    fn do_update(&mut self, data: &[u8]);

    /// Finish absorbing input and produce the MAC value.
    fn do_final(self) -> Vec<u8>;

    /// Depending on the underlying MAC implementation, NIST may require that the library enforce
    /// a minimum length on the mac output value. See documentation for the underlying implementation
    /// to see conditions under which it throws [`MACError::InvalidLength`].
    ///
    /// The entire output buffer is zeroized before the MAC value is written.
    fn do_final_out(self, out: &mut [u8]) -> Result<usize, MACError>;

    /// Internally, this will re-compute the MAC value and then compare it to the provided mac value
    /// using constant-time comparison. It is highly encouraged to use this utility function instead of
    /// comparing mac values for equality yourself.
    ///
    /// Returns a bool to indicate successful verification of the provided mac value.
    /// The provided mac value must be an exact match, including length; for example a mac value
    /// which has been truncated, or which contains extra bytes at the end is considered to not be a match
    /// and will return false.
    fn do_verify_final(self, mac: &[u8]) -> bool;

    /// Returns the maximum security strength that this KDF is capable of supporting, based on the underlying primitives.
    fn max_security_strength(&self) -> SecurityStrength;
}

/// A general indicator used across the library for marking the security level of a cryptographic primitive,
/// and for tracking the security level of the algorithms that interacted with a given piece of data.
/// For example, if a KDF at the 128-bit security strength is used to produce a 512-bit key, that key
/// will also be tagged as having a 128-bit security strength.
///
/// Some functions across the library may reject or behave differently based on the security strength
/// of the inputs they are given. For example a `keygen_from_seed()` may reject a seed taged at a lower
/// security strength than the one required by the algorithm, or it may proceed, but lower its own
/// advertised security strength accordingly -- each cryptographic primitive may have additional detail.
// Dev note: The explicit `#[repr(u8)]` discriminants are the stable on-the-wire encoding used by
// `SerializableState` implementations (see the corresponding `TryFrom<u8>` impl below).
// If additional strength levels are added in the future, they can be placed into the enum in
// any order, but should use currently unassigned values (unless you're doing this on a MAJOR or MINOR
// release as a breaking change).
#[derive(Eq, PartialEq, PartialOrd, Clone, Copy, Debug)]
#[repr(u8)]
pub enum SecurityStrength {
    ///
    None = 0,
    ///
    _112bit = 1,
    ///
    _128bit = 2,
    ///
    _192bit = 3,
    ///
    _256bit = 4,
}

impl TryFrom<u8> for SecurityStrength {
    type Error = SuspendableError;

    /// Inverse of `self as u8`; rejects unrecognized discriminants with [`SuspendableError::InvalidData`].
    fn try_from(value: u8) -> Result<Self, Self::Error> {
        Ok(match value {
            0 => Self::None,
            1 => Self::_112bit,
            2 => Self::_128bit,
            3 => Self::_192bit,
            4 => Self::_256bit,
            _ => return Err(SuspendableError::InvalidData),
        })
    }
}

impl SecurityStrength {
    /// Rounds down to the closest supported security strength.
    /// For example, 120-bits is rounded down to 112-bit.
    pub fn from_bits(bits: usize) -> Self {
        if bits < 112 {
            Self::None
        } else if bits < 128 {
            Self::_112bit
        } else if bits < 192 {
            Self::_128bit
        } else if bits < 256 {
            Self::_192bit
        } else {
            Self::_256bit
        }
    }

    /// Rounds down to the closest supported security strength.
    /// For example, 15 bytes (120-bits) is rounded down to 112-bit.
    pub fn from_bytes(bytes: usize) -> Self {
        Self::from_bits(bytes * 8)
    }

    /// Outputs the security strength in bits for easier computation.
    pub fn as_int(&self) -> u32 {
        match self {
            Self::None => 0,
            Self::_112bit => 112,
            Self::_128bit => 128,
            Self::_192bit => 192,
            Self::_256bit => 256,
        }
    }
}

/// An interface for random number generation.
/// This interface is meant to be simpler and more ergonomic than the interfaces provided by the
/// `rng` crate, but that one should
/// be used by applications that intend to submit to FIPS certification as it more closely aligns with the
/// requirements of SP 800-90A.
/// Note: this interface produces bytes. If you want a [`KeyMaterialTrait`], then use [`KeyMaterial::from_rng`].
///
/// Implementors are expected to also implement [`Default`] (default-construction should produce a
/// securely OS-seeded instance), but this is intentionally *not* a supertrait bound: requiring
/// `Default` would make `RNG` not dyn-compatible, and `&mut dyn RNG` is needed so RNG instances
/// can be handed around as trait objects.
pub trait RNG {
    // TODO: add back once we figure out streaming interaction with entropy sources.
    // fn add_seed_bytes(&mut self, additional_seed: &[u8]) -> Result<(), RNGError>;

    /// Provide additional key material to be mixed in to the existing RNG instance.
    /// The exact behaviour will be implementation-specific, but this is intended for injecting
    /// additional entropy, not as the primary method of seeding the RNG.
    fn add_seed_keymaterial(
        &mut self,
        additional_seed: &dyn KeyMaterialTrait,
    ) -> Result<(), RNGError>;
    /// Returns the next random 32-bit integer.
    fn next_int(&mut self) -> Result<u32, RNGError>;

    /// Returns the number of requested bytes.
    fn next_bytes(&mut self, len: usize) -> Result<Vec<u8>, RNGError>;

    /// Returns the number of bytes written.
    /// The entire output buffer is zeroized before the random bytes are written.
    fn next_bytes_out(&mut self, out: &mut [u8]) -> Result<usize, RNGError>;

    /// Fill the provided [`KeyMaterial`] with random bytes.
    fn fill_keymaterial_out(&mut self, out: &mut dyn KeyMaterialTrait) -> Result<usize, RNGError>;

    /// Returns the Security Strength of this RNG.
    // todo: we should do a refactor to make [Algorithm] be a `security_strength()` function instead of constant,
    //      then have `RNG: Algorithm`, then delete this function.
    fn security_strength(&self) -> SecurityStrength;
}

/// Allows a stateful object to suspend its operation by serializing its state into a byte array
///so that it can be resumed later, potentially from a different host.
///
/// This is intended for situations where an object is being used through its streaming API
/// (do_update, do_final) and the operation wants to be paused to a cache, for example while waiting
/// for network IO.
///
/// This is not intended as a mechanism to clone the state of an object since in most cases `.clone()`
/// will be more straightforward.
///
/// The serialized state MAY contain short-term sensitive values such as nonces or IVs,
/// but it MUST NOT include a serialized private key.
/// Keyed algorithms MUST instead impl
/// [`SuspendableKeyed`] which requires the key to be supplied independently at the time of deserialization.
pub trait Suspendable<const SERIALIZED_STATE_LEN: usize>: Sized {
    /// Suspend operation by serializing out the state of the object.
    ///
    /// Note that this consumes `self` to prevent accidentally continuing to use the object after serialization.
    /// If you want to do this intentionally, then you will need to clone the object before serializing it.
    ///
    /// The serialized state MUST include a prefix indicating the version of the library that serialized it.
    fn suspend(self) -> [u8; SERIALIZED_STATE_LEN];

    /// Resume operation from a serialized state.
    ///
    /// Deserializers SHOULD check the version and reject serialized states from incompatible versions
    /// (including rejecting serializations from a future version of the library).
    /// For example, if a given object made a breaking change to its serialization in version 1.2.3, then its
    /// deserializer should reject serialized states from that version or older.
    fn from_suspended(state: [u8; SERIALIZED_STATE_LEN]) -> Result<Self, SuspendableError>;
}

/// Similar to [`Suspendable`] in that it allows a stateful object to suspend its operation by
/// serializing its state into a byte array so that it can be resumed later, potentially from a different host.
///
/// The difference is that this trait is for keyed algorithms -- MACs, symmetric ciphers, signatures, etc --
/// which require a private key in order to resume successfully.
/// For security reasons, the private key is not included in the serialized state
/// and must be provided separately as part of the deserialization process.
pub trait SuspendableKeyed<const SERIALIZED_STATE_LEN: usize>: Sized {
    /// The type of key that must be re-supplied to resume this object.
    type Key: ?Sized;

    /// Suspend operation by serializing out the state of the object.
    ///
    /// Note that this consumes `self` to prevent accidentally continuing to use the object after serialization.
    /// If you want to do this intentionally, then you will need to clone the object before serializing it.
    ///
    /// The serialized state MUST include a prefix indicating the version of the library that serialized it.
    fn suspend(self) -> [u8; SERIALIZED_STATE_LEN];

    /// Resume operation from a serialized state and the key.
    ///
    /// Deserializers SHOULD check the version and reject serialized states from incompatible versions
    /// (including rejecting serializations from a future version of the library).
    /// For example, if a given object made a breaking change to its serialization in version 1.2.3, then its
    /// deserializer should reject serialized states from that version or older.
    fn from_suspended(
        state: [u8; SERIALIZED_STATE_LEN],
        key: &Self::Key,
    ) -> Result<Self, SuspendableError>;
}

/// Pre-Hashed Signer is an extension to [`Signer`] that adds functionality specific to signature
/// primatives that can operate on a pre-hashed message instead of the full message.
pub trait PHSigner<
    PK: SignaturePublicKey<PK_LEN>,
    SK: SignaturePrivateKey<SK_LEN>,
    const PK_LEN: usize,
    const SK_LEN: usize,
    const SIG_LEN: usize,
    const PH_LEN: usize,
>: Signer<SK, SK_LEN, SIG_LEN>
{
    /// Produce a signature for the provided pre-hashed message and context.
    ///
    /// `ctx` accepts a zero-length byte array.
    ///
    /// A note about the `ctx` context parameter:
    /// This is a newer addition to cryptographic signature primitives. It allows for binding the
    /// signature to some external property of the application so that a signature will fail to validate
    /// if removed from its intended context.
    /// This is particularly useful at preventing content confusion attacks between data formats that
    /// have very similar data structures, for example S/MIME emails, signed PDFs, and signed executables
    /// that all use the Cryptographic Message Syntax (CMS) data format, or multiple data objects that
    /// all use the JWS data format.
    /// To be properly effective, the ctx value must not be under the control of the attacker, which generally
    /// means that it needs to be a value that is never transmitted over the wire, but rather is something
    /// known to the application by context.
    /// For example, "email" vs "pdf" would be a good choice since the application should know what it is
    /// attempting to sign or verify.
    /// The `ctx` param can also be used to bind the signed content to a transaction ID or a username,
    /// but care should be taken to ensure that an attacker attempting a
    /// content confusion attack not also cause the signed / verifier to use an incorrect transaction ID or username.
    ///
    /// Not all signature primitives will support a context value, so you may need to consult the
    /// documentation for the underlying primitive for how it handles a ctx in that case, for example, it
    /// might throw an error, ignore the provided ctx value, or append the ctx to the msg in a non-standard way.
    fn sign_ph(
        sk: &SK,
        ph: &[u8; PH_LEN],
        ctx: Option<&[u8]>,
    ) -> Result<[u8; SIG_LEN], SignatureError>;
    /// Returns the number of bytes written to the output buffer. Can be called with an oversized buffer.
    /// The entire output buffer is zeroized before the signature is written.
    fn sign_ph_out(
        sk: &SK,
        ph: &[u8; PH_LEN],
        ctx: Option<&[u8]>,
        output: &mut [u8; SIG_LEN],
    ) -> Result<usize, SignatureError>;
}

/// Pre-Hashed Signature Verifier is an extension to [`SignatureVerifier`] that adds functionality specific to signature
/// primatives that can operate on a pre-hashed message instead of the full message.
pub trait PHSignatureVerifier<
    PK: SignaturePublicKey<PK_LEN>,
    const PK_LEN: usize,
    const SIG_LEN: usize,
    const PH_LEN: usize,
>: SignatureVerifier<PK, PK_LEN, SIG_LEN>
{
    /// On success, returns Ok(())
    /// On failure, returns Err([`SignatureError::SignatureVerificationFailed`]); may also return other types of [`SignatureError`] as appropriate (such as for invalid-length inputs).
    fn verify_ph(
        pk: &PK,
        ph: &[u8; PH_LEN],
        ctx: Option<&[u8]>,
        sig: &[u8],
    ) -> Result<(), SignatureError>;
}

// todo: could the public and private key types impl Into<T: AsRef<[u8]>> and From<T: AsRef<[u8]>>
// todo: that automatically call the encode and from_bytes() ?

/// A public key for a signature algorithm, often denoted "pk".
pub trait SignaturePublicKey<const PK_LEN: usize>:
    PartialEq + Eq + Clone + Debug + Display + Sized
{
    /// Write it out to bytes in its standard encoding.
    fn encode(&self) -> [u8; PK_LEN];
    /// Write it out to bytes in its standard encoding.
    /// The entire output buffer is zeroized before the encoding is written.
    fn encode_out(&self, out: &mut [u8; PK_LEN]) -> usize;
    /// Read it in from bytes in its standard encoding.
    fn from_bytes(bytes: &[u8]) -> Result<Self, SignatureError>;
}

/// A private key for a signature algorithm, often denoted "sk" (for "secret key").
pub trait SignaturePrivateKey<const SK_LEN: usize>: PartialEq + Eq + Clone + Sized {
    /// Write it out to bytes in its standard encoding.
    fn encode(&self) -> [u8; SK_LEN];
    /// Write it out to bytes in its standard encoding.
    /// The entire output buffer is zeroized before the encoding is written.
    fn encode_out(&self, out: &mut [u8; SK_LEN]) -> usize;
    /// Read it in from bytes in its standard encoding.
    fn from_bytes(bytes: &[u8]) -> Result<Self, SignatureError>;
}

/// A digital signature algorithm is defined as a set of three operations:
/// key generation, signing, and verification.
///
/// This trait represents the operations performed by the holder of the signing private key:
/// which include signing and key generation. Verification operations are performed by the corresponding
/// [`SignatureVerifier`] trait.
/// There are several reasons for this split: first is architectural; some complex algorithms may
/// benefit from having the signature generation and verification implementations split into separate modules.
/// Second is for compliance: sometimes a policy soft-deprecates an algorithm so that new signatures
/// can no longer be created, but existing signatures can still be verified. Splitting the traits
/// makes this policy easier to enforce.
///
/// This high-level trait defines the operations over a generic signature algorithm that is assumed
/// to source all its randomness from bouncycastle's default os-backed RNG.
/// The underlying signature primitives will expose APIs that allow for specifying a specific RNG
/// or deterministic seed values.
///
/// The arrays used to encode public keys, private keys, and signature values are statically-sized
/// because this allows us to safely remove runtime checks for array lengths, which overall reduces
/// the fallibility of the library. This design choice could make this trait complicated to apply
/// to a signature algorithm that do not have fixed sizes for the encodings of these objects.
pub trait Signer<SK: SignaturePrivateKey<SK_LEN>, const SK_LEN: usize, const SIG_LEN: usize>:
    Sized
{
    /// Produce a signature for the provided message and context.
    /// Both the `msg` and `ctx` accept zero-length byte arrays.
    ///
    /// A note about the `ctx` context parameter:
    /// This is a newer addition to cryptographic signature primitives. It allows for binding the
    /// signature to some external property of the application so that a signature will fail to validate
    /// if removed from its intended context.
    /// This is particularly useful at preventing content confusion attacks between data formats that
    /// have very similar data structures, for example S/MIME emails, signed PDFs, and signed executables
    /// that all use the Cryptographic Message Syntax (CMS) data format, or multiple data objects that
    /// all use the JWS data format.
    /// To be properly effective, the ctx value must not be under the control of the attacker, which generally
    /// means that it needs to be a value that is never transmitted over the wire, but rather is something
    /// known to the application by context.
    /// For example, "email" vs "pdf" would be a good choice since the application should know what it is
    /// attempting to sign or verify.
    /// The `ctx` param can also be used to bind the signed content to a transaction ID or a username,
    /// but care should be taken to ensure that an attacker attempting a
    /// content confusion attack not also cause the signed / verifier to use an incorrect transaction ID or username.
    ///
    /// Not all signature primitives will support a context value, so you may need to consult the
    /// documentation for the underlying primitive for how it handles a ctx in that case, for example, it
    /// might throw an error, ignore the provided ctx value, or append the ctx to the msg in a non-standard way.
    fn sign(sk: &SK, msg: &[u8], ctx: Option<&[u8]>) -> Result<[u8; SIG_LEN], SignatureError>;

    /// Returns the number of bytes written to the output buffer. Can be called with an oversized buffer.
    /// The entire output buffer is zeroized before the signature is written.
    fn sign_out(
        sk: &SK,
        msg: &[u8],
        ctx: Option<&[u8]>,
        output: &mut [u8; SIG_LEN],
    ) -> Result<usize, SignatureError>;

    /* streaming signing API */
    /// Initialize a signer for streaming mode with the provided private key.
    fn sign_init(sk: &SK, ctx: Option<&[u8]>) -> Result<Self, SignatureError>;

    // todo: make this a AsRef<[u8]> ?
    /// Update the signer with the next chunk of data.
    /// This can be called multiple times.
    fn sign_update(&mut self, msg_chunk: &[u8]);

    /// Complete the signing operation. Consumes self.
    fn sign_final(self) -> Result<[u8; SIG_LEN], SignatureError>;

    /// Returns the number of bytes written to the output buffer. Can be called with an oversized buffer.
    /// The entire output buffer is zeroized before the signature is written.
    fn sign_final_out(self, output: &mut [u8; SIG_LEN]) -> Result<usize, SignatureError>;
}

/// A digital signature algorithm is defined as a set of three operations:
/// key generation, signing, and verification.
///
/// This trait represents the verification operations performed by the holder of the verification public key.
/// Keygen and signing operations are performed by the corresponding [`Signer`] trait.
/// There are several reasons for this split: first is architectural; some complex algorithms may
/// benefit from having the signature generation and verification implementations split into separate modules.
/// Second is for compliance: sometimes a policy soft-deprecates an algorithm so that new signatures
/// can no longer be created, but existing signatures can still be verified. Splitting the traits
/// makes this policy easier to enforce.
///
/// Here we statically-size the arrays used to encode public keys, private keys, and signature values
/// because this allows us to safely remove runtime checks for array lengths, which overall reduces
/// the fallibility of the library. This design choice could make this trait complicated to apply
/// to a signature algorithm that do not have fixed sizes for the encodings of these objects.
pub trait SignatureVerifier<
    PK: SignaturePublicKey<PK_LEN>,
    const PK_LEN: usize,
    const SIG_LEN: usize,
>: Sized
{
    /// On success, returns Ok(())
    /// On failure, returns Err([`SignatureError::SignatureVerificationFailed`]); may also return other types of [`SignatureError`] as appropriate (such as for invalid-length inputs).
    fn verify(pk: &PK, msg: &[u8], ctx: Option<&[u8]>, sig: &[u8]) -> Result<(), SignatureError>;

    /// streaming verification API
    fn verify_init(pk: &PK, ctx: Option<&[u8]>) -> Result<Self, SignatureError>;

    // todo: make this a AsRef<[u8]> ?
    /// Update the verifier with the next chunk of data.
    /// This can be called multiple times.
    fn verify_update(&mut self, msg_chunk: &[u8]);

    /// On success, returns Ok(())
    /// On failure, returns Err([`SignatureError::SignatureVerificationFailed`]); may also return other types of [`SignatureError`] as appropriate (such as for invalid-length inputs).
    fn verify_final(self, sig: &[u8]) -> Result<(), SignatureError>;
}

/// Extensible Output Functions (XOFs) are similar to hash functions, except that they can produce output of arbitrary length.
/// The naming used for the functions of this trait are borrowed from the SHA3-style sponge constructions that split XOF operation
/// into two phases: an absorb phase in which an arbitrary amount of input is provided to the XOF,
/// and then a squeeze phase in which an arbitrary amount of output is extracted.
/// Once squeezing begins, no more input can be absorbed.
///
/// XOFs are _similar to_ hash functions, but are not hash functions for one technical but important reason:
/// since the amount of output to produce is not provided to the XOF in advance, it cannot be used to
/// diversify the XOF output streams.
/// In other words, the overlapping parts of their outputs will be the same!
/// For example, consider two XOFs that absorb the same input data, one that is squeezed to produce 32 bytes,
/// and the other to produce 1 kb; both outputs will be identical in their first 32 bytes.
/// This could lead to loss of security in a number of ways, for example distinguishing attacks where
/// it is sufficient for the attacker to know that two values came from the same input, even if the
/// attacker cannot learn what that input was. This is attack is often sufficient, for example,
/// to break anonymity-preserving technology.
/// Applications that require the arbitrary-length output of an XOF, but also care about these
/// distinguishing attacks should consider adding a cryptographic salt to diversify the inputs.
pub trait XOF: Default {
    /// A static one-shot API that digests the input data and produces `result_len` bytes of output.
    fn hash_xof(self, data: &[u8], result_len: usize) -> Vec<u8>;

    /// A static one-shot API that digests the input data and produces `result_len` bytes of output.
    /// Fills the provided output slice.
    /// The entire output buffer is zeroized before the output is written.
    fn hash_xof_out(self, data: &[u8], output: &mut [u8]) -> usize;

    /// Absorb some amount of input.
    fn absorb(&mut self, data: &[u8]) -> Result<(), HashError>;

    /// Switches to squeezing.
    fn absorb_last_partial_byte(
        &mut self,
        partial_byte: u8,
        num_partial_bits: usize,
    ) -> Result<(), HashError>;

    /// Can be called multiple times.
    fn squeeze(&mut self, num_bytes: usize) -> Vec<u8>;

    /// Can be called multiple times.
    /// Fills the provided output slice.
    /// The entire output buffer is zeroized before the output is written.
    fn squeeze_out(&mut self, output: &mut [u8]) -> usize;

    /// Squeezes a partial byte from the XOF.
    /// Output will be in the top `num_bits` bits of the returned u8 (ie Big Endian).
    /// This is a final call and consumes self.
    fn squeeze_partial_byte_final(self, num_bits: usize) -> Result<u8, HashError>;

    /// The same as [`XOF::squeeze_partial_byte_final`], but writes into the provided output byte.
    /// The output byte is zeroized before the result is written.
    fn squeeze_partial_byte_final_out(
        self,
        num_bits: usize,
        output: &mut u8,
    ) -> Result<(), HashError>;

    /// Returns the maximum security strength that this KDF is capable of supporting, based on the underlying primitives.
    // todo: we should do a refactor to make [Algorithm] be a `security_strength()` function instead of constant,
    //      then have `RNG: Algorithm`, then delete this function.
    fn max_security_strength(&self) -> SecurityStrength;
}