License	BSD-3-Clause
Maintainer	Olivier Chéron <olivier.cheron@gmail.com>
Stability	provisional
Portability	unknown
Safe Haskell	None
Language	Haskell2010

Crypto.PubKey.ML_KEM

Contents

Operations
Parameter sets
Conversions and checks

Description

Module-Lattice-based Key-Encapsulation Mechanism (ML-KEM), defined in FIPS 203.

Synopsis

data EncapsulationKey a
data DecapsulationKey a
data Ciphertext a
data SharedSecret a
generate :: (ParamSet a, MonadRandom m) => proxy a -> m (EncapsulationKey a, DecapsulationKey a)
generateOpen :: (ParamSet a, ByteArray d, ByteArray z, MonadRandom m) => proxy a -> m (EncapsulationKey a, DecapsulationKey a, d, z)
generateWith :: (ParamSet a, ByteArrayAccess d, ByteArrayAccess z) => proxy a -> d -> z -> Maybe (EncapsulationKey a, DecapsulationKey a)
encapsulate :: (ParamSet a, MonadRandom m) => EncapsulationKey a -> m (SharedSecret a, Ciphertext a)
encapsulateWith :: (ParamSet a, ByteArrayAccess m) => EncapsulationKey a -> m -> Maybe (SharedSecret a, Ciphertext a)
decapsulate :: ParamSet a => DecapsulationKey a -> Ciphertext a -> SharedSecret a
class KnownNat (K a) => ParamSet a
data ML_KEM_512
data ML_KEM_768
data ML_KEM_1024
class Decode (obj :: Type -> Type) where
- decode :: (ParamSet a, ByteArrayAccess ba) => proxy a -> ba -> Maybe (obj a)
class Encode (obj :: Type -> Type) where
- encode :: ByteArray ba => obj a -> ba
toPublic :: DecapsulationKey a -> EncapsulationKey a
checkKeyPair :: (ParamSet a, MonadRandom m) => (EncapsulationKey a, DecapsulationKey a) -> m Bool

Documentation

data EncapsulationKey a Source #

An ML-KEM encapsulation key, aka public key.

Instances

Instances details

Decode EncapsulationKey Source #
Instance details Defined in Internal Methods decode :: (ParamSet a, ByteArrayAccess ba) => proxy a -> ba -> Maybe (EncapsulationKey a) Source #
Encode EncapsulationKey Source #
Instance details Defined in Internal Methods encode :: ByteArray ba => EncapsulationKey a -> ba Source #
NFData (EncapsulationKey a) Source #
Instance details Defined in Internal Methods rnf :: EncapsulationKey a -> ()
Show (EncapsulationKey a) Source #
Instance details Defined in Internal Methods showsPrec :: Int -> EncapsulationKey a -> ShowS show :: EncapsulationKey a -> String showList :: [EncapsulationKey a] -> ShowS
Eq (EncapsulationKey a) Source #
Instance details Defined in Internal Methods (==) :: EncapsulationKey a -> EncapsulationKey a -> Bool (/=) :: EncapsulationKey a -> EncapsulationKey a -> Bool

data DecapsulationKey a Source #

An ML-KEM decapsulation key, aka private key.

Instances

Instances details

Decode DecapsulationKey Source #
Instance details Defined in Internal Methods decode :: (ParamSet a, ByteArrayAccess ba) => proxy a -> ba -> Maybe (DecapsulationKey a) Source #
Encode DecapsulationKey Source #
Instance details Defined in Internal Methods encode :: ByteArray ba => DecapsulationKey a -> ba Source #
NFData (DecapsulationKey a) Source #
Instance details Defined in Internal Methods rnf :: DecapsulationKey a -> ()
Show (DecapsulationKey a) Source #
Instance details Defined in Internal Methods showsPrec :: Int -> DecapsulationKey a -> ShowS show :: DecapsulationKey a -> String showList :: [DecapsulationKey a] -> ShowS
Eq (DecapsulationKey a) Source #
Instance details Defined in Internal Methods (==) :: DecapsulationKey a -> DecapsulationKey a -> Bool (/=) :: DecapsulationKey a -> DecapsulationKey a -> Bool

data Ciphertext a Source #

The ciphertext produced by the encapsulation function and consumed by the decapsulation function.

Instances

Instances details

Decode Ciphertext Source #
Instance details Defined in Internal Methods decode :: (ParamSet a, ByteArrayAccess ba) => proxy a -> ba -> Maybe (Ciphertext a) Source #
NFData (Ciphertext a) Source #
Instance details Defined in Internal Methods rnf :: Ciphertext a -> ()
Show (Ciphertext a) Source #
Instance details Defined in Internal Methods showsPrec :: Int -> Ciphertext a -> ShowS show :: Ciphertext a -> String showList :: [Ciphertext a] -> ShowS
Eq (Ciphertext a) Source #
Instance details Defined in Internal Methods (==) :: Ciphertext a -> Ciphertext a -> Bool (/=) :: Ciphertext a -> Ciphertext a -> Bool
ByteArrayAccess (Ciphertext a) Source #
Instance details Defined in Internal Methods length :: Ciphertext a -> Int withByteArray :: Ciphertext a -> (Ptr p -> IO a0) -> IO a0 copyByteArrayToPtr :: Ciphertext a -> Ptr p -> IO ()

data SharedSecret a Source #

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

Instances

Instances details

Decode SharedSecret Source #
Instance details Defined in Internal Methods decode :: (ParamSet a, ByteArrayAccess ba) => proxy a -> ba -> Maybe (SharedSecret a) Source #
NFData (SharedSecret a) Source #
Instance details Defined in Internal Methods rnf :: SharedSecret a -> ()
Show (SharedSecret a) Source #
Instance details Defined in Internal Methods showsPrec :: Int -> SharedSecret a -> ShowS show :: SharedSecret a -> String showList :: [SharedSecret a] -> ShowS
Eq (SharedSecret a) Source #
Instance details Defined in Internal Methods (==) :: SharedSecret a -> SharedSecret a -> Bool (/=) :: SharedSecret a -> SharedSecret a -> Bool
ByteArrayAccess (SharedSecret a) Source #
Instance details Defined in Internal Methods length :: SharedSecret a -> Int withByteArray :: SharedSecret a -> (Ptr p -> IO a0) -> IO a0 copyByteArrayToPtr :: SharedSecret a -> Ptr p -> IO ()

Operations

generate :: (ParamSet a, MonadRandom m) => proxy a -> m (EncapsulationKey a, DecapsulationKey a) Source #

Generate an ML-KEM key pair from a random seed.

generateOpen :: (ParamSet a, ByteArray d, ByteArray z, MonadRandom m) => proxy a -> m (EncapsulationKey a, DecapsulationKey a, d, z) Source #

Generate a random seed (d, z) and the expanded key pair, returning everything. This is Algorithm 19b introduced in Section 7 of RFC 9935.

Later use generateWith to re-expand a seed value (d, z) that has been recovered from storage.

generateWith :: (ParamSet a, ByteArrayAccess d, ByteArrayAccess z) => proxy a -> d -> z -> Maybe (EncapsulationKey a, DecapsulationKey a) Source #

Generate an ML-KEM key pair from the specified seed (d, z). Length of inputs must be 32 bytes.

encapsulate :: (ParamSet a, MonadRandom m) => EncapsulationKey a -> m (SharedSecret a, Ciphertext a) Source #

Generate a shared secret key and an associated ciphertext using randomness.

encapsulateWith :: (ParamSet a, ByteArrayAccess m) => EncapsulationKey a -> m -> Maybe (SharedSecret a, Ciphertext a) Source #

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.

decapsulate :: ParamSet a => DecapsulationKey a -> Ciphertext a -> SharedSecret a Source #

Return the shared secret for a given ciphertext. Does implicit rejection in the event the ciphertext or encapsulation key have been tampered with.

Parameter sets

class KnownNat (K a) => ParamSet a Source #

The class of ML-KEM parameter sets.

Minimal complete definition

getParams

Instances

Instances details

ParamSet ML_KEM_1024 Source #
Instance details Defined in Crypto.PubKey.ML_KEM Methods getParams :: proxy ML_KEM_1024 -> Params (K ML_KEM_1024)
ParamSet ML_KEM_512 Source #
Instance details Defined in Crypto.PubKey.ML_KEM Methods getParams :: proxy ML_KEM_512 -> Params (K ML_KEM_512)
ParamSet ML_KEM_768 Source #
Instance details Defined in Crypto.PubKey.ML_KEM Methods getParams :: proxy ML_KEM_768 -> Params (K ML_KEM_768)

data ML_KEM_512 Source #

ML-KEM-512 (security category 1)

Instances

Instances details

Show ML_KEM_512 Source #
Instance details Defined in Crypto.PubKey.ML_KEM Methods showsPrec :: Int -> ML_KEM_512 -> ShowS show :: ML_KEM_512 -> String showList :: [ML_KEM_512] -> ShowS
ParamSet ML_KEM_512 Source #
Instance details Defined in Crypto.PubKey.ML_KEM Methods getParams :: proxy ML_KEM_512 -> Params (K ML_KEM_512)

data ML_KEM_768 Source #

ML-KEM-768 (security category 3)

Instances

Instances details

Show ML_KEM_768 Source #
Instance details Defined in Crypto.PubKey.ML_KEM Methods showsPrec :: Int -> ML_KEM_768 -> ShowS show :: ML_KEM_768 -> String showList :: [ML_KEM_768] -> ShowS
ParamSet ML_KEM_768 Source #
Instance details Defined in Crypto.PubKey.ML_KEM Methods getParams :: proxy ML_KEM_768 -> Params (K ML_KEM_768)

data ML_KEM_1024 Source #

ML-KEM-1024 (security category 5)

Instances

Instances details

Show ML_KEM_1024 Source #
Instance details Defined in Crypto.PubKey.ML_KEM Methods showsPrec :: Int -> ML_KEM_1024 -> ShowS show :: ML_KEM_1024 -> String showList :: [ML_KEM_1024] -> ShowS
ParamSet ML_KEM_1024 Source #
Instance details Defined in Crypto.PubKey.ML_KEM Methods getParams :: proxy ML_KEM_1024 -> Params (K ML_KEM_1024)

Conversions and checks

class Decode (obj :: Type -> Type) where Source #

Utility class to deserialize ML-KEM objects from byte arrays.

Methods

decode :: (ParamSet a, ByteArrayAccess ba) => proxy a -> ba -> Maybe (obj a) Source #

Deserializes an object from a sequence of bytes.

Instances

Instances details

Decode Ciphertext Source #
Instance details Defined in Internal Methods decode :: (ParamSet a, ByteArrayAccess ba) => proxy a -> ba -> Maybe (Ciphertext a) Source #
Decode DecapsulationKey Source #
Instance details Defined in Internal Methods decode :: (ParamSet a, ByteArrayAccess ba) => proxy a -> ba -> Maybe (DecapsulationKey a) Source #
Decode EncapsulationKey Source #
Instance details Defined in Internal Methods decode :: (ParamSet a, ByteArrayAccess ba) => proxy a -> ba -> Maybe (EncapsulationKey a) Source #
Decode SharedSecret Source #
Instance details Defined in Internal Methods decode :: (ParamSet a, ByteArrayAccess ba) => proxy a -> ba -> Maybe (SharedSecret a) Source #

class Encode (obj :: Type -> Type) where Source #

Utility class to serialize ML-KEM objects to byte arrays.

Methods

encode :: ByteArray ba => obj a -> ba Source #

Serializes an object to a sequence of bytes.

Instances

Instances details

Encode DecapsulationKey Source #
Instance details Defined in Internal Methods encode :: ByteArray ba => DecapsulationKey a -> ba Source #
Encode EncapsulationKey Source #
Instance details Defined in Internal Methods encode :: ByteArray ba => EncapsulationKey a -> ba Source #

toPublic :: DecapsulationKey a -> EncapsulationKey a Source #

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.

checkKeyPair :: (ParamSet a, MonadRandom m) => (EncapsulationKey a, DecapsulationKey a) -> m Bool Source #

Try to detect corruptions in a pair of keys. Note that this does not fully guarantee that the key pair was properly generated. Returns True when the key pair is found valid.