hpke
Safe HaskellNone
LanguageHaskell2010

Crypto.HPKE.DHKEM

Description

DHKEM as an instance of crypton's KEM class.

RFC 9180 section 4.1 builds a key encapsulation mechanism out of a Diffie-Hellman group: the exchange's output goes through HKDF with the ephemeral and the recipient public keys as context, under labels that name the ciphersuite. That construction, and not the bare exchange, is what a KEM is, which is why crypton has the class and no instance for the groups themselves.

There is one type per suite RFC 9180 registers, and no way to spell anything else. The group does not pick the suite on its own -- the hash and the registered code point are part of what the shared secret is derived from -- but the registry lists each group exactly once, so naming the group names all three.

The instance is here rather than in crypton because those labels carry the HPKE ciphersuite identifier and the protocol's own version string, which is the same reason TLS 1.3's labelled HKDF lives in tls rather than in crypton.

Only Encap and Decap are instance methods. DHKEM also has AuthEncap and AuthDecap, in that same section 4.1, where a static sender key contributes a second Diffie-Hellman and its public key joins the context; they take an argument the class has no room for, so they are not here. setupBaseS with a sender key is the way to those, through the mode of section 5.1.3.

Synopsis

The suites RFC 9180 registers

data DHKEM_P256 Source #

DHKEM(P-256, HKDF-SHA256).

Instances

Instances details
KEM DHKEM_P256 Source #

The keys and the encapsulated value are the serialized forms of RFC 9180 section 4, which is what travels and what this package's other entry points already speak. The coins are the sender's ephemeral secret key, skE, which is what the appendix A vectors fix.

Instance details

Defined in Crypto.HPKE.DHKEM

HPKEKEM DHKEM_P256 Source #

DHKEM has all four operations of RFC 9180 section 4.1, so the authenticated pair is defined rather than left to refuse.

Instance details

Defined in Crypto.HPKE.DHKEM

type Ciphertext DHKEM_P256 Source # 
Instance details

Defined in Crypto.HPKE.DHKEM

type Coins DHKEM_P256 Source # 
Instance details

Defined in Crypto.HPKE.DHKEM

type DecapsulationKey DHKEM_P256 Source # 
Instance details

Defined in Crypto.HPKE.DHKEM

type EncapsulationKey DHKEM_P256 Source # 
Instance details

Defined in Crypto.HPKE.DHKEM

data DHKEM_P384 Source #

DHKEM(P-384, HKDF-SHA384).

Instances

Instances details
KEM DHKEM_P384 Source # 
Instance details

Defined in Crypto.HPKE.DHKEM

HPKEKEM DHKEM_P384 Source # 
Instance details

Defined in Crypto.HPKE.DHKEM

type Ciphertext DHKEM_P384 Source # 
Instance details

Defined in Crypto.HPKE.DHKEM

type Coins DHKEM_P384 Source # 
Instance details

Defined in Crypto.HPKE.DHKEM

type DecapsulationKey DHKEM_P384 Source # 
Instance details

Defined in Crypto.HPKE.DHKEM

type EncapsulationKey DHKEM_P384 Source # 
Instance details

Defined in Crypto.HPKE.DHKEM

data DHKEM_P521 Source #

DHKEM(P-521, HKDF-SHA512).

Instances

Instances details
KEM DHKEM_P521 Source # 
Instance details

Defined in Crypto.HPKE.DHKEM

HPKEKEM DHKEM_P521 Source # 
Instance details

Defined in Crypto.HPKE.DHKEM

type Ciphertext DHKEM_P521 Source # 
Instance details

Defined in Crypto.HPKE.DHKEM

type Coins DHKEM_P521 Source # 
Instance details

Defined in Crypto.HPKE.DHKEM

type DecapsulationKey DHKEM_P521 Source # 
Instance details

Defined in Crypto.HPKE.DHKEM

type EncapsulationKey DHKEM_P521 Source # 
Instance details

Defined in Crypto.HPKE.DHKEM

data DHKEM_X25519 Source #

DHKEM(X25519, HKDF-SHA256).

Instances

Instances details
KEM DHKEM_X25519 Source # 
Instance details

Defined in Crypto.HPKE.DHKEM

HPKEKEM DHKEM_X25519 Source # 
Instance details

Defined in Crypto.HPKE.DHKEM

type Ciphertext DHKEM_X25519 Source # 
Instance details

Defined in Crypto.HPKE.DHKEM

type Coins DHKEM_X25519 Source # 
Instance details

Defined in Crypto.HPKE.DHKEM

type DecapsulationKey DHKEM_X25519 Source # 
Instance details

Defined in Crypto.HPKE.DHKEM

type EncapsulationKey DHKEM_X25519 Source # 
Instance details

Defined in Crypto.HPKE.DHKEM

data DHKEM_X448 Source #

DHKEM(X448, HKDF-SHA512).

Instances

Instances details
KEM DHKEM_X448 Source # 
Instance details

Defined in Crypto.HPKE.DHKEM

HPKEKEM DHKEM_X448 Source # 
Instance details

Defined in Crypto.HPKE.DHKEM

type Ciphertext DHKEM_X448 Source # 
Instance details

Defined in Crypto.HPKE.DHKEM

type Coins DHKEM_X448 Source # 
Instance details

Defined in Crypto.HPKE.DHKEM

type DecapsulationKey DHKEM_X448 Source # 
Instance details

Defined in Crypto.HPKE.DHKEM

type EncapsulationKey DHKEM_X448 Source # 
Instance details

Defined in Crypto.HPKE.DHKEM

The classes they implement

class KEM kem where #

Associated Types

type EncapsulationKey kem #

type DecapsulationKey kem #

type Ciphertext kem #

type Coins kem #

Methods

generateKeyPair :: MonadRandom m => proxy kem -> m (EncapsulationKey kem, DecapsulationKey kem) #

encapsulate :: MonadRandom m => proxy kem -> EncapsulationKey kem -> m (CryptoFailable (Ciphertext kem, SharedSecret)) #

encapsulateWith :: proxy kem -> EncapsulationKey kem -> Coins kem -> CryptoFailable (Ciphertext kem, SharedSecret) #

decapsulate :: proxy kem -> DecapsulationKey kem -> Ciphertext kem -> CryptoFailable SharedSecret #

Instances

Instances details
KEM MLKEM1024 # 
Instance details

Defined in Crypto.PubKey.MLKEM

Associated Types

type EncapsulationKey MLKEM1024 
Instance details

Defined in Crypto.PubKey.MLKEM

type EncapsulationKey MLKEM1024 = MLKEMEncapsulationKey MLKEM1024
type DecapsulationKey MLKEM1024 
Instance details

Defined in Crypto.PubKey.MLKEM

type DecapsulationKey MLKEM1024 = MLKEMDecapsulationKey MLKEM1024
type Ciphertext MLKEM1024 
Instance details

Defined in Crypto.PubKey.MLKEM

type Ciphertext MLKEM1024 = MLKEMCiphertext MLKEM1024
type Coins MLKEM1024 
Instance details

Defined in Crypto.PubKey.MLKEM

type Coins MLKEM1024 = ScrubbedBytes

Methods

generateKeyPair :: MonadRandom m => proxy MLKEM1024 -> m (EncapsulationKey MLKEM1024, DecapsulationKey MLKEM1024) #

encapsulate :: MonadRandom m => proxy MLKEM1024 -> EncapsulationKey MLKEM1024 -> m (CryptoFailable (Ciphertext MLKEM1024, SharedSecret)) #

encapsulateWith :: proxy MLKEM1024 -> EncapsulationKey MLKEM1024 -> Coins MLKEM1024 -> CryptoFailable (Ciphertext MLKEM1024, SharedSecret) #

decapsulate :: proxy MLKEM1024 -> DecapsulationKey MLKEM1024 -> Ciphertext MLKEM1024 -> CryptoFailable SharedSecret #

KEM MLKEM512 # 
Instance details

Defined in Crypto.PubKey.MLKEM

Associated Types

type EncapsulationKey MLKEM512 
Instance details

Defined in Crypto.PubKey.MLKEM

type EncapsulationKey MLKEM512 = MLKEMEncapsulationKey MLKEM512
type DecapsulationKey MLKEM512 
Instance details

Defined in Crypto.PubKey.MLKEM

type DecapsulationKey MLKEM512 = MLKEMDecapsulationKey MLKEM512
type Ciphertext MLKEM512 
Instance details

Defined in Crypto.PubKey.MLKEM

type Ciphertext MLKEM512 = MLKEMCiphertext MLKEM512
type Coins MLKEM512 
Instance details

Defined in Crypto.PubKey.MLKEM

type Coins MLKEM512 = ScrubbedBytes

Methods

generateKeyPair :: MonadRandom m => proxy MLKEM512 -> m (EncapsulationKey MLKEM512, DecapsulationKey MLKEM512) #

encapsulate :: MonadRandom m => proxy MLKEM512 -> EncapsulationKey MLKEM512 -> m (CryptoFailable (Ciphertext MLKEM512, SharedSecret)) #

encapsulateWith :: proxy MLKEM512 -> EncapsulationKey MLKEM512 -> Coins MLKEM512 -> CryptoFailable (Ciphertext MLKEM512, SharedSecret) #

decapsulate :: proxy MLKEM512 -> DecapsulationKey MLKEM512 -> Ciphertext MLKEM512 -> CryptoFailable SharedSecret #

KEM MLKEM768 # 
Instance details

Defined in Crypto.PubKey.MLKEM

Associated Types

type EncapsulationKey MLKEM768 
Instance details

Defined in Crypto.PubKey.MLKEM

type EncapsulationKey MLKEM768 = MLKEMEncapsulationKey MLKEM768
type DecapsulationKey MLKEM768 
Instance details

Defined in Crypto.PubKey.MLKEM

type DecapsulationKey MLKEM768 = MLKEMDecapsulationKey MLKEM768
type Ciphertext MLKEM768 
Instance details

Defined in Crypto.PubKey.MLKEM

type Ciphertext MLKEM768 = MLKEMCiphertext MLKEM768
type Coins MLKEM768 
Instance details

Defined in Crypto.PubKey.MLKEM

type Coins MLKEM768 = ScrubbedBytes

Methods

generateKeyPair :: MonadRandom m => proxy MLKEM768 -> m (EncapsulationKey MLKEM768, DecapsulationKey MLKEM768) #

encapsulate :: MonadRandom m => proxy MLKEM768 -> EncapsulationKey MLKEM768 -> m (CryptoFailable (Ciphertext MLKEM768, SharedSecret)) #

encapsulateWith :: proxy MLKEM768 -> EncapsulationKey MLKEM768 -> Coins MLKEM768 -> CryptoFailable (Ciphertext MLKEM768, SharedSecret) #

decapsulate :: proxy MLKEM768 -> DecapsulationKey MLKEM768 -> Ciphertext MLKEM768 -> CryptoFailable SharedSecret #

KEM DHKEM_P256 Source #

The keys and the encapsulated value are the serialized forms of RFC 9180 section 4, which is what travels and what this package's other entry points already speak. The coins are the sender's ephemeral secret key, skE, which is what the appendix A vectors fix.

Instance details

Defined in Crypto.HPKE.DHKEM

KEM DHKEM_P384 Source # 
Instance details

Defined in Crypto.HPKE.DHKEM

KEM DHKEM_P521 Source # 
Instance details

Defined in Crypto.HPKE.DHKEM

KEM DHKEM_X25519 Source # 
Instance details

Defined in Crypto.HPKE.DHKEM

KEM DHKEM_X448 Source # 
Instance details

Defined in Crypto.HPKE.DHKEM

class (KEM kem, EncapsulationKey kem ~ EncodedPublicKey, DecapsulationKey kem ~ EncodedSecretKey, Ciphertext kem ~ EncodedPublicKey, Coins kem ~ EncodedSecretKey) => HPKEKEM kem where Source #

What HPKE needs of a KEM beyond what crypton's KEM class says.

RFC 9180 section 4.1 gives DHKEM four operations and the class has room for two: Encap is encapsulate, Decap is decapsulate. AuthEncap and AuthDecap take a static sender key, which the class has no argument for, so they are here. They default to refusing, which is what a KEM with no authenticated mode -- any post-quantum one -- should do.

The equalities pin the four associated types to the serialized forms of section 4, which is what travels and what this package's entry points take, so that setupS can be written once for every KEM.

Minimal complete definition

toEncapsulationKey

Methods

generateCoins :: MonadRandom m => proxy kem -> m EncodedSecretKey Source #

Draw what encapsulate would have drawn, so that the authenticated forms can generate their ephemeral key the same way.

For every KEM here the coins are a secret key, so the default is to draw a key pair and keep the half that is one.

authEncapWith Source #

Arguments

:: proxy kem 
-> EncodedSecretKey

skS, the sender's static key

-> EncodedPublicKey
pkR
-> EncodedSecretKey
skE
-> Either HPKEError (EncodedPublicKey, SharedSecret) 

AuthEncap of section 4.1, with the ephemeral key supplied.

authDecap Source #

Arguments

:: proxy kem 
-> EncodedPublicKey

pkS, the sender's static public key

-> EncodedSecretKey
skR
-> EncodedPublicKey
enc
-> Either HPKEError SharedSecret 

AuthDecap of section 4.1. The sender is named by its public key: a receiver does not have the other side's secret key, and asking for one would be asking for the wrong thing.

toEncapsulationKey :: proxy kem -> EncodedSecretKey -> Either HPKEError EncodedPublicKey Source #

The encapsulation key a decapsulation key belongs to.

Instances

Instances details
HPKEKEM DHKEM_P256 Source #

DHKEM has all four operations of RFC 9180 section 4.1, so the authenticated pair is defined rather than left to refuse.

Instance details

Defined in Crypto.HPKE.DHKEM

HPKEKEM DHKEM_P384 Source # 
Instance details

Defined in Crypto.HPKE.DHKEM

HPKEKEM DHKEM_P521 Source # 
Instance details

Defined in Crypto.HPKE.DHKEM

HPKEKEM DHKEM_X25519 Source # 
Instance details

Defined in Crypto.HPKE.DHKEM

HPKEKEM DHKEM_X448 Source # 
Instance details

Defined in Crypto.HPKE.DHKEM

newtype SharedSecret #

Constructors

SharedSecret ScrubbedBytes 

Instances

Instances details
NFData SharedSecret # 
Instance details

Defined in Crypto.KEM

Methods

rnf :: SharedSecret -> ()

Monoid SharedSecret # 
Instance details

Defined in Crypto.KEM

Semigroup SharedSecret # 
Instance details

Defined in Crypto.KEM

Eq SharedSecret # 
Instance details

Defined in Crypto.KEM

Methods

(==) :: SharedSecret -> SharedSecret -> Bool

(/=) :: SharedSecret -> SharedSecret -> Bool

Show SharedSecret # 
Instance details

Defined in Crypto.KEM

Methods

showsPrec :: Int -> SharedSecret -> ShowS

show :: SharedSecret -> String

showList :: [SharedSecret] -> ShowS

ByteArrayAccess SharedSecret # 
Instance details

Defined in Crypto.KEM

Methods

length :: SharedSecret -> Int

withByteArray :: SharedSecret -> (Ptr p -> IO a) -> IO a

copyByteArrayToPtr :: SharedSecret -> Ptr p -> IO ()