package hpke

  1. Overview
  2. Docs

Module Hpke.Draft_hpke_04Source

The successor of RFC 9180 as draft-ietf-hpke-hpke-04 specifies it, with the one-stage SHA-3 KDFs of draft-ietf-hpke-pq-05, Section 5.

This is a separate, versioned module, so that Rfc9180 keeps its wire behavior: nothing here changes what an Rfc9180 function does. The draft is not yet an RFC, and this module follows revision 04 of it; a later revision that changes the wire gets a module of its own.

The draft is RFC 9180 without the Auth and AuthPSK modes, and with a second kind of KDF. With an HKDF a suite runs the RFC 9180 Base and PSK modes unchanged, so its keys, encapsulations, ciphertexts and exports are those of Rfc9180. With a one-stage KDF, SHAKE128 or SHAKE256, the key schedule derives the key, base nonce and exporter secret in one call of LabeledDerive, and so does Sender.export. Every KEM works with every KDF, those of the draft included. TurboSHAKE128 and TurboSHAKE256 (0x0012 and 0x0013) are not provided yet.

Keys, KEMs, AEADs, PSKs, errors and contexts are those of the rest of the library. Private_key.to_bytes clamps X25519 and X448 keys, where the draft serializes them unclamped; both describe the same key pair.

With a one-stage KDF, info, a PSK and its identifier may each hold at most 65535 bytes (Section 7.2.1), and a longer one is Error.t.Invalid_length. An export may be up to 65535 bytes long.

Sourcemodule Kdf : sig ... end
Sourcemodule Suite : sig ... end
Sourcemodule Sender = Rfc9180.Sender
Sourcemodule Receiver = Rfc9180.Receiver
Sourcetype 'capability sender_setup = 'capability Rfc9180.sender_setup = {
  1. encapsulated_key : string;
  2. context : 'capability Sender.t;
}
Sourcetype ciphertext = Rfc9180.ciphertext = {
  1. encapsulated_key : string;
  2. ciphertext : string;
}
Sourceval setup_base_sender : rng:Mirage_crypto_rng.g -> 'capability Suite.t -> recipient:Public_key.t -> info:string -> ('capability sender_setup, Error.t) result

As Rfc9180.setup_base_sender. Returns Error.t.Key_mismatch unless the suite and the key share one KEM.

Sourceval setup_base_receiver : 'capability Suite.t -> recipient:Private_key.t -> encapsulated_key:string -> info:string -> ('capability Receiver.t, Error.t) result

As Rfc9180.setup_base_receiver.

Sourceval setup_psk_sender : rng:Mirage_crypto_rng.g -> 'capability Suite.t -> recipient:Public_key.t -> psk:Psk.t -> info:string -> ('capability sender_setup, Error.t) result

As Rfc9180.setup_psk_sender.

Sourceval setup_psk_receiver : 'capability Suite.t -> recipient:Private_key.t -> psk:Psk.t -> encapsulated_key:string -> info:string -> ('capability Receiver.t, Error.t) result

As Rfc9180.setup_psk_receiver.

Sourceval seal_base : rng:Mirage_crypto_rng.g -> Suite.encryption Suite.t -> recipient:Public_key.t -> info:string -> aad:string -> plaintext:string -> (ciphertext, Error.t) result

As Rfc9180.seal_base.

Sourceval open_base : Suite.encryption Suite.t -> recipient:Private_key.t -> info:string -> aad:string -> ciphertext:ciphertext -> (string, Error.t) result

As Rfc9180.open_base: every failure other than Error.t.Key_mismatch is Error.t.Open_error.

Sourceval seal_psk : rng:Mirage_crypto_rng.g -> Suite.encryption Suite.t -> recipient:Public_key.t -> psk:Psk.t -> info:string -> aad:string -> plaintext:string -> (ciphertext, Error.t) result

As Rfc9180.seal_psk.

Sourceval open_psk : Suite.encryption Suite.t -> recipient:Private_key.t -> psk:Psk.t -> info:string -> aad:string -> ciphertext:ciphertext -> (string, Error.t) result

As Rfc9180.open_psk.