Botan 3.14.1
Crypto and TLS for C&
hpke_kem.h
Go to the documentation of this file.
1/*
2* HPKE KEM abstraction (RFC 9180 Section 7.1)
3* (C) 2026 Jack Lloyd
4*
5* Botan is released under the Simplified BSD License (see license.txt)
6*/
7
8#ifndef BOTAN_HPKE_KEM_H_
9#define BOTAN_HPKE_KEM_H_
10
11#include <botan/hpke.h>
12#include <botan/pk_keys.h>
13
14namespace Botan::HPKE {
15
16/**
17* LabeledExtract from RFC 9180 Section 4
18*
19* @p hash is a Botan hash function name eg "SHA-256"; @p suite_id is
20* either the KEM suite_id ("KEM" || kem_id) or the full HPKE suite_id
21* ("HPKE" || kem_id || kdf_id || aead_id) depending on the caller.
22*/
24 std::span<const uint8_t> suite_id,
25 std::span<const uint8_t> salt,
26 std::string_view label,
27 std::span<const uint8_t> ikm);
28
29/**
30* LabeledExpand from RFC 9180 Section 4
31*/
33 std::span<const uint8_t> suite_id,
34 std::span<const uint8_t> prk,
35 std::string_view label,
36 std::span<const uint8_t> info,
37 size_t length);
38
39/**
40* Internal interface for the KEM operations HPKE requires
41*
42* Implemented by DHKEM (RFC 9180 Section 4.1) over the key agreement algorithms.
43*/
45 public:
47 std::vector<uint8_t> enc;
49 };
50
51 /**
52 * Create the operations for a KEM
53 *
54 * Throws Not_Implemented if the codepoint is unknown or the required
55 * algorithms are not available in this build.
56 */
57 static std::unique_ptr<const KEM_Ops> create(KEM_Id kem);
58
59 virtual ~KEM_Ops() = default;
60 KEM_Ops(const KEM_Ops&) = delete;
61 KEM_Ops& operator=(const KEM_Ops&) = delete;
62 KEM_Ops(KEM_Ops&&) = delete;
64
65 KEM_Id kem_id() const { return m_kem; }
66
67 // See RFC 9180 Section 7.1.5
68 virtual bool supports_auth() const { return false; }
69
70 virtual Encapsulation encap(const Botan::Public_Key& pkR, RandomNumberGenerator& rng) const = 0;
71
72 virtual secure_vector<uint8_t> decap(std::span<const uint8_t> enc,
73 const Botan::Private_Key& skR,
74 RandomNumberGenerator& rng) const = 0;
75
76 /// Only supported if supports_auth(); the default implementations throw
78 const Botan::Private_Key& skS,
79 RandomNumberGenerator& rng) const;
80
81 virtual secure_vector<uint8_t> auth_decap(std::span<const uint8_t> enc,
82 const Botan::Private_Key& skR,
83 const Botan::Public_Key& pkS,
84 RandomNumberGenerator& rng) const;
85
86 /**
87 * Deterministic encapsulation with a caller-provided ephemeral key,
88 * for known-answer testing of DHKEMs. The default implementation throws.
89 */
91 const Botan::Private_Key& skE,
92 RandomNumberGenerator& rng) const;
93
94 /**
95 * Deterministic authenticated encapsulation with a caller-provided
96 * ephemeral key, for known-answer testing of DHKEMs. The default
97 * implementation throws.
98 */
100 const Botan::Private_Key& skS,
101 const Botan::Private_Key& skE,
102 RandomNumberGenerator& rng) const;
103
104 virtual std::unique_ptr<Botan::Private_Key> generate_key(RandomNumberGenerator& rng) const = 0;
105
106 virtual std::unique_ptr<Botan::Private_Key> derive_key_pair(std::span<const uint8_t> ikm) const = 0;
107
108 virtual std::unique_ptr<Botan::Public_Key> deserialize_public(std::span<const uint8_t> bytes) const = 0;
109
110 virtual std::unique_ptr<Botan::Private_Key> deserialize_private(std::span<const uint8_t> bytes) const = 0;
111
112 virtual std::vector<uint8_t> serialize_public(const Botan::Public_Key& key) const = 0;
113
115
116 /**
117 * Adopt an existing key for use with this KEM
118 *
119 * Returns the key itself if it is of the type the KEM operates on, or
120 * an equivalent key of that type (for the NIST curves, an ECDSA key is
121 * converted to ECDH). Throws Invalid_Argument for any other key, or if
122 * the key's group does not match the KEM.
123 */
124 virtual std::unique_ptr<Botan::Public_Key> adopt_public(std::unique_ptr<Botan::Public_Key> key) const = 0;
125
126 virtual std::unique_ptr<Botan::Private_Key> adopt_private(std::unique_ptr<Botan::Private_Key> key) const = 0;
127
128 protected:
129 explicit KEM_Ops(KEM_Id kem) : m_kem(kem) {}
130
131 private:
132 KEM_Id m_kem;
133};
134
135} // namespace Botan::HPKE
136
137#endif
#define BOTAN_TEST_API
Definition api.h:41
virtual std::unique_ptr< Botan::Public_Key > adopt_public(std::unique_ptr< Botan::Public_Key > key) const =0
KEM_Ops & operator=(KEM_Ops &&)=delete
virtual std::vector< uint8_t > serialize_public(const Botan::Public_Key &key) const =0
KEM_Ops(const KEM_Ops &)=delete
virtual secure_vector< uint8_t > auth_decap(std::span< const uint8_t > enc, const Botan::Private_Key &skR, const Botan::Public_Key &pkS, RandomNumberGenerator &rng) const
Definition hpke_kem.cpp:96
virtual std::unique_ptr< Botan::Public_Key > deserialize_public(std::span< const uint8_t > bytes) const =0
virtual bool supports_auth() const
Definition hpke_kem.h:68
virtual std::unique_ptr< Botan::Private_Key > generate_key(RandomNumberGenerator &rng) const =0
KEM_Ops & operator=(const KEM_Ops &)=delete
virtual Encapsulation auth_encap(const Botan::Public_Key &pkR, const Botan::Private_Key &skS, RandomNumberGenerator &rng) const
Only supported if supports_auth(); the default implementations throw.
Definition hpke_kem.cpp:89
static std::unique_ptr< const KEM_Ops > create(KEM_Id kem)
Definition hpke_kem.cpp:545
virtual Encapsulation encap_with_ephemeral(const Botan::Public_Key &pkR, const Botan::Private_Key &skE, RandomNumberGenerator &rng) const
Definition hpke_kem.cpp:104
KEM_Ops(KEM_Ops &&)=delete
virtual std::unique_ptr< Botan::Private_Key > adopt_private(std::unique_ptr< Botan::Private_Key > key) const =0
virtual std::unique_ptr< Botan::Private_Key > derive_key_pair(std::span< const uint8_t > ikm) const =0
virtual Encapsulation encap(const Botan::Public_Key &pkR, RandomNumberGenerator &rng) const =0
KEM_Id kem_id() const
Definition hpke_kem.h:65
virtual std::unique_ptr< Botan::Private_Key > deserialize_private(std::span< const uint8_t > bytes) const =0
virtual secure_vector< uint8_t > decap(std::span< const uint8_t > enc, const Botan::Private_Key &skR, RandomNumberGenerator &rng) const =0
KEM_Ops(KEM_Id kem)
Definition hpke_kem.h:129
virtual Encapsulation auth_encap_with_ephemeral(const Botan::Public_Key &pkR, const Botan::Private_Key &skS, const Botan::Private_Key &skE, RandomNumberGenerator &rng) const
Definition hpke_kem.cpp:110
virtual secure_vector< uint8_t > serialize_private(const Botan::Private_Key &key) const =0
virtual ~KEM_Ops()=default
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)
Definition hpke_kem.cpp:49
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)
Definition hpke_kem.cpp:65
std::vector< T, secure_allocator< T > > secure_vector
Definition secmem.h:128
std::vector< uint8_t > enc
Definition hpke_kem.h:47
secure_vector< uint8_t > shared_secret
Definition hpke_kem.h:48