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


-- | Hybrid Public Key Encryption defined in RFC9180
@package hpke
@version 0.4.0


-- | DHKEM as an instance of <tt>crypton</tt>'s <a>KEM</a> 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 <tt>crypton</tt> 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 <tt>crypton</tt> 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 <tt>tls</tt> rather than in <tt>crypton</tt>.
--   
--   Only <tt>Encap</tt> and <tt>Decap</tt> are instance methods. DHKEM
--   also has <tt>AuthEncap</tt> and <tt>AuthDecap</tt>, 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.
--   <a>setupBaseS</a> with a sender key is the way to those, through the
--   mode of section 5.1.3.
module Crypto.HPKE.DHKEM

-- | DHKEM(P-256, HKDF-SHA256).
data DHKEM_P256

-- | DHKEM(P-384, HKDF-SHA384).
data DHKEM_P384

-- | DHKEM(P-521, HKDF-SHA512).
data DHKEM_P521

-- | DHKEM(X25519, HKDF-SHA256).
data DHKEM_X25519

-- | DHKEM(X448, HKDF-SHA512).
data DHKEM_X448
class KEM kem where {
    type EncapsulationKey kem;
    type DecapsulationKey kem;
    type Ciphertext kem;
    type Coins kem;
}
generateKeyPair :: (KEM kem, MonadRandom m) => proxy kem -> m (EncapsulationKey kem, DecapsulationKey kem)
encapsulate :: (KEM kem, MonadRandom m) => proxy kem -> EncapsulationKey kem -> m (CryptoFailable (Ciphertext kem, SharedSecret))
encapsulateWith :: KEM kem => proxy kem -> EncapsulationKey kem -> Coins kem -> CryptoFailable (Ciphertext kem, SharedSecret)
decapsulate :: KEM kem => proxy kem -> DecapsulationKey kem -> Ciphertext kem -> CryptoFailable SharedSecret

-- | What HPKE needs of a KEM beyond what <tt>crypton</tt>'s <a>KEM</a>
--   class says.
--   
--   RFC 9180 section 4.1 gives DHKEM four operations and the class has
--   room for two: <tt>Encap</tt> is <a>encapsulate</a>, <tt>Decap</tt> is
--   <a>decapsulate</a>. <tt>AuthEncap</tt> and <tt>AuthDecap</tt> 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 <a>setupS</a> can be written once for every KEM.
class (KEM kem, EncapsulationKey kem ~ EncodedPublicKey, DecapsulationKey kem ~ EncodedSecretKey, Ciphertext kem ~ EncodedPublicKey, Coins kem ~ EncodedSecretKey) => HPKEKEM kem

-- | Draw what <a>encapsulate</a> 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.
generateCoins :: (HPKEKEM kem, MonadRandom m) => proxy kem -> m EncodedSecretKey

-- | <tt>AuthEncap</tt> of section 4.1, with the ephemeral key supplied.
authEncapWith :: HPKEKEM kem => proxy kem -> EncodedSecretKey -> EncodedPublicKey -> EncodedSecretKey -> Either HPKEError (EncodedPublicKey, SharedSecret)

-- | <tt>AuthDecap</tt> 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.
authDecap :: HPKEKEM kem => proxy kem -> EncodedPublicKey -> EncodedSecretKey -> EncodedPublicKey -> Either HPKEError SharedSecret

-- | The encapsulation key a decapsulation key belongs to.
toEncapsulationKey :: HPKEKEM kem => proxy kem -> EncodedSecretKey -> Either HPKEError EncodedPublicKey
newtype SharedSecret
SharedSecret :: ScrubbedBytes -> SharedSecret
instance Crypto.HPKE.KEM.HPKEKEM Crypto.HPKE.DHKEM.DHKEM_P256
instance Crypto.HPKE.KEM.HPKEKEM Crypto.HPKE.DHKEM.DHKEM_P384
instance Crypto.HPKE.KEM.HPKEKEM Crypto.HPKE.DHKEM.DHKEM_P521
instance Crypto.HPKE.KEM.HPKEKEM Crypto.HPKE.DHKEM.DHKEM_X25519
instance Crypto.HPKE.KEM.HPKEKEM Crypto.HPKE.DHKEM.DHKEM_X448
instance Crypto.HPKE.DHKEM.HPKEKEMRegistered Crypto.HPKE.DHKEM.DHKEM_P256
instance Crypto.HPKE.DHKEM.HPKEKEMRegistered Crypto.HPKE.DHKEM.DHKEM_P384
instance Crypto.HPKE.DHKEM.HPKEKEMRegistered Crypto.HPKE.DHKEM.DHKEM_P521
instance Crypto.HPKE.DHKEM.HPKEKEMRegistered Crypto.HPKE.DHKEM.DHKEM_X25519
instance Crypto.HPKE.DHKEM.HPKEKEMRegistered Crypto.HPKE.DHKEM.DHKEM_X448
instance Crypto.KEM.KEM Crypto.HPKE.DHKEM.DHKEM_P256
instance Crypto.KEM.KEM Crypto.HPKE.DHKEM.DHKEM_P384
instance Crypto.KEM.KEM Crypto.HPKE.DHKEM.DHKEM_P521
instance Crypto.KEM.KEM Crypto.HPKE.DHKEM.DHKEM_X25519
instance Crypto.KEM.KEM Crypto.HPKE.DHKEM.DHKEM_X448

module Crypto.HPKE.Internal
data HPKEMap
HPKEMap :: [(KEM_ID, KEMAlg)] -> [(KDF_ID, KDFHash)] -> [(AEAD_ID, AEADCipher)] -> HPKEMap
[kemMap] :: HPKEMap -> [(KEM_ID, KEMAlg)]
[kdfMap] :: HPKEMap -> [(KDF_ID, KDFHash)]
[cipherMap] :: HPKEMap -> [(AEAD_ID, AEADCipher)]
defaultHPKEMap :: HPKEMap
setupS :: HPKEMap -> Mode -> KEM_ID -> KDF_ID -> AEAD_ID -> Maybe EncodedSecretKey -> Maybe EncodedSecretKey -> EncodedPublicKey -> Info -> PSK -> PSK_ID -> IO (EncodedPublicKey, ContextS)
setupR :: HPKEMap -> Mode -> KEM_ID -> KDF_ID -> AEAD_ID -> EncodedSecretKey -> Maybe EncodedPublicKey -> EncodedPublicKey -> Info -> PSK -> PSK_ID -> IO ContextR

-- | A KEM that HPKE can run over, with its identity forgotten, for the
--   table that turns a <tt>KEM_ID</tt> into one.
data KEMAlg
KEMAlg :: Proxy kem -> KEMAlg
data KDFHash
KDFHash :: h -> KDFHash
data AEADCipher
AEADCipher :: Proxy a -> AEADCipher
class Aead a
sealA :: Aead a => Proxy a -> Key -> Seal
openA :: Aead a => Proxy a -> Key -> Open
nK :: Aead a => Proxy a -> Int
nN :: Aead a => Proxy a -> Int
nT :: Aead a => Proxy a -> Int
class KDF h
labeledExtract :: KDF h => Suite -> Salt -> Label -> IKM -> PRK h

-- | RFC 9180 section 5.3 allows an output of at most <tt>255 * Nh</tt>
--   octets, which is also what HKDF's counter can reach. A longer one is
--   refused here rather than left to the HKDF underneath, whose way of
--   saying so is an exception.
labeledExpand :: KDF h => Suite -> PRK h -> Label -> Info -> Int -> Either HPKEError Key

-- | What HPKE needs of a KEM beyond what <tt>crypton</tt>'s <a>KEM</a>
--   class says.
--   
--   RFC 9180 section 4.1 gives DHKEM four operations and the class has
--   room for two: <tt>Encap</tt> is <a>encapsulate</a>, <tt>Decap</tt> is
--   <a>decapsulate</a>. <tt>AuthEncap</tt> and <tt>AuthDecap</tt> 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 <a>setupS</a> can be written once for every KEM.
class (KEM kem, EncapsulationKey kem ~ EncodedPublicKey, DecapsulationKey kem ~ EncodedSecretKey, Ciphertext kem ~ EncodedPublicKey, Coins kem ~ EncodedSecretKey) => HPKEKEM kem

-- | Draw what <a>encapsulate</a> 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.
generateCoins :: (HPKEKEM kem, MonadRandom m) => proxy kem -> m EncodedSecretKey

-- | <tt>AuthEncap</tt> of section 4.1, with the ephemeral key supplied.
authEncapWith :: HPKEKEM kem => proxy kem -> EncodedSecretKey -> EncodedPublicKey -> EncodedSecretKey -> Either HPKEError (EncodedPublicKey, SharedSecret)

-- | <tt>AuthDecap</tt> 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.
authDecap :: HPKEKEM kem => proxy kem -> EncodedPublicKey -> EncodedSecretKey -> EncodedPublicKey -> Either HPKEError SharedSecret

-- | The encapsulation key a decapsulation key belongs to.
toEncapsulationKey :: HPKEKEM kem => proxy kem -> EncodedSecretKey -> Either HPKEError EncodedPublicKey
data Mode
ModeBase :: Mode
ModePsk :: Mode
ModeAuth :: Mode
ModeAuthPsk :: Mode
type PublicKey group = Point group
type SecretKey group = Scalar group
type Seal = Nonce -> AAD -> PlainText -> Either HPKEError CipherText
type Open = Nonce -> AAD -> CipherText -> Either HPKEError PlainText
type Nonce = ByteString
type Suite = ByteString
type Salt = ByteString
type Label = ByteString
type IKM = ByteString

-- | Generating a pair of public key and secret key based on <a>KEM_ID</a>.
genKeyPair :: HPKEMap -> KEM_ID -> IO (EncodedPublicKey, EncodedSecretKey)

-- | The public key that goes with a secret key, for the KEM named by the
--   <a>KEM_ID</a>. A receiver authenticating a sender is given the
--   sender's public key; this is how the sender arrives at one to publish.
toPublicKey :: HPKEMap -> KEM_ID -> EncodedSecretKey -> Either HPKEError EncodedPublicKey


-- | Hybrid Public Key Encryption (RFC9180).
module Crypto.HPKE

-- | ID for key encapsulation mechanism.
newtype KEM_ID
KEM_ID :: Word16 -> KEM_ID
[fromKEM_ID] :: KEM_ID -> Word16
pattern DHKEM_P256_HKDF_SHA256 :: KEM_ID
pattern DHKEM_P384_HKDF_SHA384 :: KEM_ID
pattern DHKEM_P521_HKDF_SHA512 :: KEM_ID
pattern DHKEM_X25519_HKDF_SHA256 :: KEM_ID
pattern DHKEM_X448_HKDF_SHA512 :: KEM_ID

-- | ID for key derivation function.
newtype KDF_ID
KDF_ID :: Word16 -> KDF_ID
[fromKDF_ID] :: KDF_ID -> Word16
pattern HKDF_SHA256 :: KDF_ID
pattern HKDF_SHA384 :: KDF_ID
pattern HKDF_SHA512 :: KDF_ID

-- | ID for authenticated encryption with additional data
newtype AEAD_ID
AEAD_ID :: Word16 -> AEAD_ID
[fromAEAD_ID] :: AEAD_ID -> Word16
pattern AES_128_GCM :: AEAD_ID
pattern AES_256_GCM :: AEAD_ID
pattern ChaCha20Poly1305 :: AEAD_ID

-- | Setting up base/auth mode for a sender. This throws <a>HPKEError</a>.
setupBaseS :: KEM_ID -> KDF_ID -> AEAD_ID -> Maybe EncodedSecretKey -> Maybe EncodedSecretKey -> EncodedPublicKey -> Info -> IO (EncodedPublicKey, ContextS)

-- | Setting up base/auth mode for a receiver with its key pair. This
--   throws <a>HPKEError</a>.
setupBaseR :: KEM_ID -> KDF_ID -> AEAD_ID -> EncodedSecretKey -> Maybe EncodedPublicKey -> EncodedPublicKey -> Info -> IO ContextR

-- | Setting up psk/auth_psk mode for a sender. This throws
--   <a>HPKEError</a>.
setupPSKS :: KEM_ID -> KDF_ID -> AEAD_ID -> Maybe EncodedSecretKey -> Maybe EncodedSecretKey -> EncodedPublicKey -> Info -> PSK -> PSK_ID -> IO (EncodedPublicKey, ContextS)

-- | Setting up psk/auth_psk mode for a receiver with its key pair. This
--   throws <a>HPKEError</a>.
setupPSKR :: KEM_ID -> KDF_ID -> AEAD_ID -> EncodedSecretKey -> Maybe EncodedPublicKey -> EncodedPublicKey -> Info -> PSK -> PSK_ID -> IO ContextR

-- | Encryption. This throws <a>HPKEError</a>. Safe to call from multiple
--   threads: each call gets its own nonce.
seal :: ContextS -> AAD -> PlainText -> IO CipherText

-- | Decryption. This throws <a>HPKEError</a>. The sequence number advances
--   only when decryption succeeds.
open :: ContextR -> AAD -> CipherText -> IO PlainText

-- | Exporting secret.
--   
--   RFC 9180 section 5.3 allows a length of at most <tt>255 * Nh</tt>,
--   where <tt>Nh</tt> is the output of the KDF's hash; a longer one is
--   <a>Left</a> <a>ExportError</a>.
exportS :: ContextS -> Info -> Int -> Either HPKEError Key

-- | Exporting secret.
--   
--   RFC 9180 section 5.3 allows a length of at most <tt>255 * Nh</tt>,
--   where <tt>Nh</tt> is the output of the KDF's hash; a longer one is
--   <a>Left</a> <a>ExportError</a>.
exportR :: ContextR -> Info -> Int -> Either HPKEError Key

-- | Context for senders.
data ContextS

-- | Context for receivers.
data ContextR

-- | Encoded secret key.
newtype EncodedSecretKey
EncodedSecretKey :: ByteString -> EncodedSecretKey

-- | Encoded public key.
newtype EncodedPublicKey
EncodedPublicKey :: ByteString -> EncodedPublicKey
newtype SharedSecret
SharedSecret :: ScrubbedBytes -> SharedSecret

-- | Information string.
type Info = ByteString

-- | Pre-shared key.
type PSK = ByteString

-- | ID for pre-shared key.
type PSK_ID = ByteString

-- | Additional authenticated data for AEAD.
type AAD = ByteString

-- | Plain text.
type PlainText = ByteString

-- | Cipher text (including a authentication tag)
type CipherText = ByteString

-- | Encryption key.
type Key = ByteString

-- | Errors for HPKE
data HPKEError
ValidationError :: String -> HPKEError
DeserializeError :: String -> HPKEError
EncapError :: String -> HPKEError
DecapError :: String -> HPKEError

-- | Original
SealError :: String -> HPKEError
OpenError :: String -> HPKEError
MessageLimitReachedError :: String -> HPKEError
DeriveKeyPairError :: String -> HPKEError

-- | Original
KeyScheduleError :: String -> HPKEError

-- | Original. An export longer than the <tt>255 * Nh</tt> that RFC 9180
--   section 5.3 allows.
ExportError :: String -> HPKEError
Unsupported :: String -> HPKEError

-- | Length of "enc", aka sender's public key. <a>Nothing</a> for a KEM not
--   registered in RFC 9180.
nEnc :: KEM_ID -> Maybe Int

-- | Length of AEAD tag. <a>Nothing</a> for an AEAD not registered in RFC
--   9180.
nTag :: AEAD_ID -> Maybe Int
