-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Module-Lattice-based Key-Encapsulation Mechanism (ML-KEM) implemented
--   in Haskell.
@package mlkem
@version 0.2.1.0


-- | Module-Lattice-based Key-Encapsulation Mechanism (ML-KEM), defined in
--   <a>FIPS 203</a>.
module Crypto.PubKey.ML_KEM

-- | An ML-KEM encapsulation key, aka public key.
data EncapsulationKey a

-- | An ML-KEM decapsulation key, aka private key.
data DecapsulationKey a

-- | The ciphertext produced by the encapsulation function and consumed by
--   the decapsulation function.
data Ciphertext a

-- | A shared secret returned by the encapsulation and decapsulation
--   functions. Length is 32 bytes for all defined parameter sets.
data SharedSecret a

-- | Generate an ML-KEM key pair from a random seed.
generate :: (ParamSet a, MonadRandom m) => proxy a -> m (EncapsulationKey a, DecapsulationKey a)

-- | Generate a random seed (d, z) and the expanded key pair, returning
--   everything. This is Algorithm 19b introduced in Section 7 of <a>RFC
--   9935</a>.
--   
--   Later use <a>generateWith</a> to re-expand a seed value (d, z) that
--   has been recovered from storage.
generateOpen :: (ParamSet a, ByteArray d, ByteArray z, MonadRandom m) => proxy a -> m (EncapsulationKey a, DecapsulationKey a, d, z)

-- | Generate an ML-KEM key pair from the specified seed (d, z). Length of
--   inputs must be 32 bytes.
generateWith :: (ParamSet a, ByteArrayAccess d, ByteArrayAccess z) => proxy a -> d -> z -> Maybe (EncapsulationKey a, DecapsulationKey a)

-- | Generate a shared secret key and an associated ciphertext using
--   randomness.
encapsulate :: (ParamSet a, MonadRandom m) => EncapsulationKey a -> m (SharedSecret a, Ciphertext a)

-- | Generate a shared secret key and an associated ciphertext using a
--   specified random input. This byte array must be 32 bytes and not
--   repeated with other encapsulations. For testing purposes.
encapsulateWith :: (ParamSet a, ByteArrayAccess m) => EncapsulationKey a -> m -> Maybe (SharedSecret a, Ciphertext a)

-- | Return the shared secret for a given ciphertext. Does implicit
--   rejection in the event the ciphertext or encapsulation key have been
--   tampered with.
decapsulate :: ParamSet a => DecapsulationKey a -> Ciphertext a -> SharedSecret a

-- | The class of ML-KEM parameter sets.
class KnownNat K a => ParamSet a

-- | ML-KEM-512 (security category 1)
data ML_KEM_512

-- | ML-KEM-768 (security category 3)
data ML_KEM_768

-- | ML-KEM-1024 (security category 5)
data ML_KEM_1024

-- | Utility class to deserialize ML-KEM objects from byte arrays.
class Decode (obj :: Type -> Type)

-- | Deserializes an object from a sequence of bytes.
decode :: (Decode obj, ParamSet a, ByteArrayAccess ba) => proxy a -> ba -> Maybe (obj a)

-- | Utility class to serialize ML-KEM objects to byte arrays.
class Encode (obj :: Type -> Type)

-- | Serializes an object to a sequence of bytes.
encode :: (Encode obj, ByteArray ba) => obj a -> ba

-- | Returns the encapsulation key embedded in the given decapsulation key.
--   Note that they may not necessarily match when the decapsulation key
--   was decoded from an untrusted source.
toPublic :: DecapsulationKey a -> EncapsulationKey a

-- | Try to detect corruptions in a pair of keys. Note that this does not
--   fully guarantee that the key pair was properly generated. Returns
--   <tt>True</tt> when the key pair is found valid.
checkKeyPair :: (ParamSet a, MonadRandom m) => (EncapsulationKey a, DecapsulationKey a) -> m Bool
instance Internal.ParamSet Crypto.PubKey.ML_KEM.ML_KEM_1024
instance Internal.ParamSet Crypto.PubKey.ML_KEM.ML_KEM_512
instance Internal.ParamSet Crypto.PubKey.ML_KEM.ML_KEM_768
instance GHC.Internal.Show.Show Crypto.PubKey.ML_KEM.ML_KEM_1024
instance GHC.Internal.Show.Show Crypto.PubKey.ML_KEM.ML_KEM_512
instance GHC.Internal.Show.Show Crypto.PubKey.ML_KEM.ML_KEM_768
