Botan 3.14.1
Crypto and TLS for C&
Botan::HPKE Namespace Reference

Namespaces

namespace  detail

Classes

class  AEAD_Id
class  KDF_Id
class  KEM_Id
class  KEM_Ops
class  Private_Key
class  PSK
class  Public_Key
class  Recipient_Context
class  Sender_Context
class  Suite

Enumerations

enum class  AEAD_Code : uint16_t { AES_128_GCM = 0x0001 , AES_256_GCM = 0x0002 , ChaCha20Poly1305 = 0x0003 , ExportOnly = 0xFFFF }
enum class  KDF_Code : uint16_t { HKDF_SHA256 = 0x0001 , HKDF_SHA384 = 0x0002 , HKDF_SHA512 = 0x0003 }
enum class  KEM_Code : uint16_t {
  DHKEM_P256 = 0x0010 , DHKEM_P384 = 0x0011 , DHKEM_P521 = 0x0012 , DHKEM_X25519 = 0x0020 ,
  DHKEM_X448 = 0x0021
}
enum class  Mode : uint8_t { Base = 0x00 , PSK = 0x01 , Auth = 0x02 , AuthPSK = 0x03 }
 The four HPKE modes, with their codepoints from RFC 9180 Section 5. More...

Functions

secure_vector< uint8_t > labeled_expand (std::string_view hash, std::span< const uint8_t > suite_id, std::span< const uint8_t > prk, std::string_view label, std::span< const uint8_t > info, size_t length)
secure_vector< uint8_t > labeled_extract (std::string_view hash, std::span< const uint8_t > suite_id, std::span< const uint8_t > salt, std::string_view label, std::span< const uint8_t > ikm)

Enumeration Type Documentation

◆ AEAD_Code

enum class Botan::HPKE::AEAD_Code : uint16_t
strong

HPKE AEAD identifiers (RFC 9180 Section 7.3)

Enumerator
AES_128_GCM 
AES_256_GCM 
ChaCha20Poly1305 
ExportOnly 

Definition at line 58 of file hpke.h.

58 : uint16_t {
59 AES_128_GCM = 0x0001,
60 AES_256_GCM = 0x0002,
61 ChaCha20Poly1305 = 0x0003,
62 ExportOnly = 0xFFFF,
63};

◆ KDF_Code

enum class Botan::HPKE::KDF_Code : uint16_t
strong

HPKE KDF identifiers (RFC 9180 Section 7.2)

Enumerator
HKDF_SHA256 
HKDF_SHA384 
HKDF_SHA512 

Definition at line 49 of file hpke.h.

49 : uint16_t /* NOLINT(*-enum-size) */ {
50 HKDF_SHA256 = 0x0001,
51 HKDF_SHA384 = 0x0002,
52 HKDF_SHA512 = 0x0003,
53};

◆ KEM_Code

enum class Botan::HPKE::KEM_Code : uint16_t
strong

HPKE KEM identifiers

These codepoints match the IANA "HPKE KEM Identifiers" registry established by RFC 9180 Section 7.1.

Enumerator
DHKEM_P256 
DHKEM_P384 
DHKEM_P521 
DHKEM_X25519 
DHKEM_X448 

Definition at line 38 of file hpke.h.

38 : uint16_t /* NOLINT(*-enum-size) */ {
39 DHKEM_P256 = 0x0010, // DHKEM(P-256, HKDF-SHA256)
40 DHKEM_P384 = 0x0011, // DHKEM(P-384, HKDF-SHA384)
41 DHKEM_P521 = 0x0012, // DHKEM(P-521, HKDF-SHA512)
42 DHKEM_X25519 = 0x0020, // DHKEM(X25519, HKDF-SHA256)
43 DHKEM_X448 = 0x0021, // DHKEM(X448, HKDF-SHA512)
44};

◆ Mode

enum class Botan::HPKE::Mode : uint8_t
strong

The four HPKE modes, with their codepoints from RFC 9180 Section 5.

Enumerator
Base 
PSK 
Auth 
AuthPSK 

Definition at line 440 of file hpke.h.

440 : uint8_t {
441 Base = 0x00,
442 PSK = 0x01,
443 Auth = 0x02,
444 AuthPSK = 0x03,
445};

Function Documentation

◆ labeled_expand()

BOTAN_TEST_API secure_vector< uint8_t > Botan::HPKE::labeled_expand ( std::string_view hash,
std::span< const uint8_t > suite_id,
std::span< const uint8_t > prk,
std::string_view label,
std::span< const uint8_t > info,
size_t length )

LabeledExpand from RFC 9180 Section 4

Definition at line 65 of file hpke_kem.cpp.

70 {
71 // See RFC 9180 Section 4
72 BOTAN_ARG_CHECK(length <= 0xFFFF, "HPKE LabeledExpand output length too large");
73
74 if(length == 0) {
75 return {};
76 }
77
78 const HKDF_Expand kdf(MessageAuthenticationCode::create_or_throw(fmt("HMAC({})", hash)));
79
80 const auto labeled_info = concat<std::vector<uint8_t>>(store_be(static_cast<uint16_t>(length)),
81 as_span_of_bytes(std::string_view("HPKE-v1")),
82 suite_id,
83 as_span_of_bytes(label),
84 info);
85
86 return kdf.derive_key<secure_vector<uint8_t>>(length, prk, std::span<const uint8_t>{}, labeled_info);
87}
#define BOTAN_ARG_CHECK(expr, msg)
Definition assert.h:33
static std::unique_ptr< MessageAuthenticationCode > create_or_throw(std::string_view algo_spec, std::string_view provider="")
Definition mac.cpp:142
std::span< const uint8_t > as_span_of_bytes(const char *s, size_t len)
Definition mem_utils.h:59
std::string fmt(std::string_view format, const T &... args)
Definition fmt.h:53
constexpr auto concat(Rs &&... ranges)
Definition concat_util.h:95
std::vector< T, secure_allocator< T > > secure_vector
Definition secmem.h:128
constexpr auto store_be(ParamTs &&... params)
Definition loadstor.h:745

References Botan::as_span_of_bytes(), BOTAN_ARG_CHECK, Botan::concat(), Botan::MessageAuthenticationCode::create_or_throw(), Botan::KDF::derive_key(), Botan::fmt(), and Botan::store_be().

◆ labeled_extract()

BOTAN_TEST_API secure_vector< uint8_t > Botan::HPKE::labeled_extract ( std::string_view hash,
std::span< const uint8_t > suite_id,
std::span< const uint8_t > salt,
std::string_view label,
std::span< const uint8_t > ikm )

LabeledExtract from RFC 9180 Section 4

hash is a Botan hash function name eg "SHA-256"; suite_id is either the KEM suite_id ("KEM" || kem_id) or the full HPKE suite_id ("HPKE" || kem_id || kdf_id || aead_id) depending on the caller.

Definition at line 49 of file hpke_kem.cpp.

53 {
54 // See RFC 9180 Section 4
55 auto prf = MessageAuthenticationCode::create_or_throw(fmt("HMAC({})", hash));
56 const size_t nh = prf->output_length();
57 const HKDF_Extract kdf(std::move(prf));
58
59 const auto labeled_ikm = concat<secure_vector<uint8_t>>(
60 as_span_of_bytes(std::string_view("HPKE-v1")), suite_id, as_span_of_bytes(label), ikm);
61
62 return kdf.derive_key<secure_vector<uint8_t>>(nh, labeled_ikm, salt, std::span<const uint8_t>{});
63}

References Botan::as_span_of_bytes(), Botan::concat(), Botan::MessageAuthenticationCode::create_or_throw(), Botan::KDF::derive_key(), and Botan::fmt().