10#include <botan/exceptn.h>
12#include <botan/pk_keys.h>
14#include <botan/internal/concat_util.h>
15#include <botan/internal/fmt.h>
16#include <botan/internal/hpke_kem.h>
17#include <botan/internal/mem_utils.h>
33std::optional<KEM_Info> kem_info(
KEM_Code code) {
37 return KEM_Info{32, 65, 65, 32,
"DHKEM(P-256, HKDF-SHA256)"};
39 return KEM_Info{48, 97, 97, 48,
"DHKEM(P-384, HKDF-SHA384)"};
41 return KEM_Info{64, 133, 133, 66,
"DHKEM(P-521, HKDF-SHA512)"};
43 return KEM_Info{32, 32, 32, 32,
"DHKEM(X25519, HKDF-SHA256)"};
45 return KEM_Info{64, 56, 56, 56,
"DHKEM(X448, HKDF-SHA512)"};
50KEM_Info require_kem_info(
const KEM_Id& kem) {
51 if(
const auto info = kem_info(kem.
code())) {
63std::optional<KDF_Info> kdf_info(
KDF_Code code) {
67 return KDF_Info{32,
"SHA-256",
"HKDF-SHA256"};
69 return KDF_Info{48,
"SHA-384",
"HKDF-SHA384"};
71 return KDF_Info{64,
"SHA-512",
"HKDF-SHA512"};
76std::string kdf_hash_name(
KDF_Id kdf) {
77 if(
const auto info = kdf_info(kdf.
code())) {
91std::optional<AEAD_Info> aead_info(
AEAD_Code code) {
95 return AEAD_Info{16, 12, 16,
"AES-128-GCM",
"AES-128/GCM"};
97 return AEAD_Info{32, 12, 16,
"AES-256-GCM",
"AES-256/GCM"};
99 return AEAD_Info{32, 12, 16,
"ChaCha20Poly1305",
"ChaCha20Poly1305"};
106std::string aead_spec(
AEAD_Id aead) {
107 if(
const auto info = aead_info(aead.
code())) {
129 return require_kem_info(*this).nsecret;
133 return require_kem_info(*this).nenc;
137 return require_kem_info(*this).npk;
141 return require_kem_info(*this).nsk;
145 if(
const auto info = kem_info(m_code)) {
146 return std::string(info->name);
152 if(
const auto info = kdf_info(m_code)) {
159 if(
const auto info = kdf_info(m_code)) {
166 if(
const auto info = kdf_info(m_code)) {
167 return std::string(info->name);
176 if(
const auto info = aead_info(m_code)) {
183 if(
const auto info = aead_info(m_code)) {
190 if(
const auto info = aead_info(m_code)) {
197 if(
const auto info = aead_info(m_code)) {
205 return std::string(
"export-only");
207 if(
const auto info = aead_info(m_code)) {
208 return std::string(info->name);
214 const auto kem = m_kem.to_string();
215 const auto kdf = m_kdf.to_string();
216 const auto aead = m_aead.to_string();
227class Public_Key::Data final {
229 Data(std::shared_ptr<const KEM_Ops> ops, std::unique_ptr<const Botan::Public_Key> key) :
230 m_ops(std::move(ops)), m_key(std::move(key)), m_serialized(m_ops->serialize_public(*m_key)) {}
232 const KEM_Ops& ops()
const {
return *m_ops; }
234 const std::shared_ptr<const KEM_Ops>& ops_ptr()
const {
return m_ops; }
236 const Botan::Public_Key& key()
const {
return *m_key; }
238 const std::vector<uint8_t>& serialized()
const {
return m_serialized; }
241 std::shared_ptr<const KEM_Ops> m_ops;
242 std::unique_ptr<const Botan::Public_Key> m_key;
243 std::vector<uint8_t> m_serialized;
248 auto key = ops->deserialize_public(bytes);
249 return Public_Key(std::make_shared<Data>(std::move(ops), std::move(key)));
253 BOTAN_ARG_CHECK(key !=
nullptr,
"HPKE::Public_Key::from_key: key is null");
255 auto adopted = ops->adopt_public(std::move(key));
256 return Public_Key(std::make_shared<Data>(std::move(ops), std::move(adopted)));
260 return m_data->ops().kem_id();
264 return m_data->serialized();
268 return m_data->key();
271class Private_Key::Data final {
273 Data(std::shared_ptr<const KEM_Ops> ops, std::unique_ptr<const Botan::Private_Key> key) :
274 m_ops(std::move(ops)), m_key(std::move(key)) {}
276 const KEM_Ops& ops()
const {
return *m_ops; }
278 const std::shared_ptr<const KEM_Ops>& ops_ptr()
const {
return m_ops; }
280 const Botan::Private_Key& key()
const {
return *m_key; }
283 std::shared_ptr<const KEM_Ops> m_ops;
284 std::unique_ptr<const Botan::Private_Key> m_key;
289 auto key = ops->generate_key(rng);
290 return Private_Key(std::make_shared<Data>(std::move(ops), std::move(key)));
295 auto key = ops->derive_key_pair(ikm);
296 return Private_Key(std::make_shared<Data>(std::move(ops), std::move(key)));
301 auto key = ops->deserialize_private(bytes);
302 return Private_Key(std::make_shared<Data>(std::move(ops), std::move(key)));
306 BOTAN_ARG_CHECK(key !=
nullptr,
"HPKE::Private_Key::from_key: key is null");
308 auto adopted = ops->adopt_private(std::move(key));
309 return Private_Key(std::make_shared<Data>(std::move(ops), std::move(adopted)));
313 return m_data->ops().kem_id();
317 auto pub = m_data->key().public_key();
318 return Public_Key(std::make_shared<Public_Key::Data>(m_data->ops_ptr(), std::move(pub)));
322 return m_data->ops().serialize_private(m_data->key());
326 return m_data->key();
333PSK::PSK(std::span<const uint8_t> psk, std::span<const uint8_t> psk_id) :
334 m_psk(psk.begin(), psk.end()), m_psk_id(psk_id.begin(), psk_id.end()) {
336 BOTAN_ARG_CHECK(!m_psk.empty() && !m_psk_id.empty(),
"HPKE PSK and PSK identity must both be non-empty");
338 BOTAN_ARG_CHECK(m_psk.size() >= 32,
"HPKE PSK must be at least 32 bytes");
347class Context_Data final {
349 Context_Data(
const Suite& suite,
352 std::span<const uint8_t> shared_secret,
353 std::span<const uint8_t> info,
355 std::vector<uint8_t> enc) :
356 m_suite(suite), m_mode(mode), m_hash(kdf_hash_name(suite.
kdf())), m_enc(std::move(enc)) {
358 const auto id_octets = [](uint16_t code) {
359 return std::array<uint8_t, 2>{
static_cast<uint8_t
>(code >> 8),
static_cast<uint8_t
>(code & 0xFF)};
367 std::span<const uint8_t> psk_bytes;
368 std::span<const uint8_t> psk_id;
370 psk_bytes = psk->
secret();
374 const auto psk_id_hash =
labeled_extract(m_hash, m_suite_id, {},
"psk_id_hash", psk_id);
375 const auto info_hash =
labeled_extract(m_hash, m_suite_id, {},
"info_hash", info);
376 const std::array<uint8_t, 1> mode_octet{
static_cast<uint8_t
>(mode)};
379 const auto secret =
labeled_extract(m_hash, m_suite_id, shared_secret,
"secret", psk_bytes);
388 m_aead->set_key(key);
395 const size_t nn = m_base_nonce.size();
396 m_seq_limit = (nn >= 8) ? std::numeric_limits<uint64_t>::max() : ((uint64_t(1) << (8 * nn)) - 1);
402 Suite suite()
const {
return m_suite; }
404 Mode mode()
const {
return m_mode; }
406 const std::vector<uint8_t>& enc()
const {
return m_enc; }
408 uint64_t seq()
const {
return m_seq; }
410 template <
typename T>
411 T crypt(std::optional<uint64_t> at_seq, std::span<const uint8_t> aad, std::span<const uint8_t> msg) {
414 throw Invalid_State(
"This HPKE suite is export-only and cannot seal or open messages");
418 const uint64_t seq = at_seq.value_or(m_seq);
419 if(seq >= m_seq_limit) {
423 auto nonce = m_base_nonce;
424 for(
size_t i = 0; i != 8 && i != nonce.size(); ++i) {
425 nonce[nonce.size() - 1 - i] ^=
static_cast<uint8_t
>(seq >> (8 * i));
428 if(msg.size() < m_aead->minimum_final_size()) {
432 T buf(msg.begin(), msg.end());
434 m_aead->set_associated_data(aad);
435 m_aead->start(nonce);
446 if(!at_seq.has_value()) {
455 BOTAN_ARG_CHECK(length <= 255 * m_exporter_secret.size(),
"HPKE export length too large");
456 return labeled_expand(m_hash, m_suite_id, m_exporter_secret,
"sec", exporter_context, length);
463 std::vector<uint8_t> m_suite_id;
464 std::unique_ptr<AEAD_Mode> m_aead;
468 uint64_t m_seq_limit = 0;
469 std::vector<uint8_t> m_enc;
481Sender_Context& Sender_Context::operator=(Sender_Context&&) noexcept = default;
482Sender_Context::~Sender_Context() = default;
484Sender_Context Sender_Context::setup(
Mode mode,
490 std::span<const uint8_t> info) {
492 if(recipient_key.kem() !=
suite.
kem()) {
493 throw Invalid_Argument(
"HPKE recipient key does not match the suite's KEM");
496 const auto& ops = recipient_key.m_data->ops();
499 if(sender_identity_key != nullptr) {
500 if(sender_identity_key->kem() != suite.kem()) {
501 throw Invalid_Argument(
"HPKE sender identity key does not match the suite's KEM");
503 return ops.auth_encap(recipient_key.m_data->key(), sender_identity_key->m_data->key(), rng);
505 return ops.encap(recipient_key.m_data->key(), rng);
508 return Sender_Context(std::make_unique<detail::Context_Data>(
515 std::span<const uint8_t> info) {
517 return setup(
Mode::Base,
suite, recipient_key,
nullptr,
nullptr, rng, info);
524 std::span<const uint8_t> info) {
526 return setup(
Mode::PSK,
suite, recipient_key,
nullptr, &psk, rng, info);
533 std::span<const uint8_t> info) {
535 return setup(
Mode::Auth,
suite, recipient_key, &sender_identity_key,
nullptr, rng, info);
543 std::span<const uint8_t> info) {
545 return setup(
Mode::AuthPSK,
suite, recipient_key, &sender_identity_key, &psk, rng, info);
549 return m_data->enc();
554 return m_data->crypt<std::vector<uint8_t>>(std::nullopt, aad, ptext);
559 return m_data->export_secret(exporter_context, length);
563 return m_data->seq();
567 return m_data->mode();
571 return m_data->suite();
581Recipient_Context& Recipient_Context::operator=(Recipient_Context&&) noexcept = default;
582Recipient_Context::~Recipient_Context() = default;
584Recipient_Context Recipient_Context::setup(
Mode mode,
587 std::span<const uint8_t> enc,
591 std::span<const uint8_t> info) {
593 if(recipient_key.kem() !=
suite.
kem()) {
594 throw Invalid_Argument(
"HPKE recipient key does not match the suite's KEM");
597 const auto& ops = recipient_key.m_data->ops();
599 auto shared_secret = [&]() {
600 if(sender_identity_key != nullptr) {
601 if(sender_identity_key->kem() != suite.kem()) {
602 throw Invalid_Argument(
"HPKE sender identity key does not match the suite's KEM");
604 return ops.auth_decap(enc, recipient_key.m_data->key(), sender_identity_key->m_data->key(), rng);
606 return ops.decap(enc, recipient_key.m_data->key(), rng);
609 return Recipient_Context(std::make_unique<detail::Context_Data>(
615 std::span<const uint8_t> enc,
617 std::span<const uint8_t> info) {
619 return setup(
Mode::Base,
suite, recipient_key, enc,
nullptr,
nullptr, rng, info);
624 std::span<const uint8_t> enc,
627 std::span<const uint8_t> info) {
629 return setup(
Mode::PSK,
suite, recipient_key, enc,
nullptr, &psk, rng, info);
634 std::span<const uint8_t> enc,
637 std::span<const uint8_t> info) {
639 return setup(
Mode::Auth,
suite, recipient_key, enc, &sender_identity_key,
nullptr, rng, info);
644 std::span<const uint8_t> enc,
648 std::span<const uint8_t> info) {
650 return setup(
Mode::AuthPSK,
suite, recipient_key, enc, &sender_identity_key, &psk, rng, info);
659 std::span<const uint8_t> aad,
660 std::span<const uint8_t> ctext) {
665 size_t length)
const {
667 return m_data->export_secret(exporter_context, length);
671 return m_data->seq();
675 return m_data->mode();
679 return m_data->suite();
#define BOTAN_ARG_CHECK(expr, msg)
static std::unique_ptr< AEAD_Mode > create_or_throw(std::string_view algo, Cipher_Dir direction, std::string_view provider="")
static std::unique_ptr< AEAD_Mode > create(std::string_view algo, Cipher_Dir direction, std::string_view provider="")
constexpr uint16_t wire_code() const
std::optional< std::string > to_string() const
size_t nonce_length() const
Return the constant Nn from RFC 9180 Section 7.3, throws for invalid code points.
bool is_available() const
size_t tag_length() const
Return the constant Nt from RFC 9180 Section 7.3, throws for invalid code points.
constexpr AEAD_Code code() const
constexpr bool is_export_only() const
size_t key_length() const
Return the constant Nk from RFC 9180 Section 7.3, throws for invalid code points.
size_t output_length() const
std::optional< std::string > to_string() const
constexpr KDF_Code code() const
bool is_available() const
constexpr uint16_t wire_code() const
size_t encapsulation_length() const
Return the constant Nenc from RFC 9180 Section 7.1, throws for invalid code points.
std::optional< std::string > to_string() const
Returns std::nullopt for unknown codepoints.
bool is_available() const
True if the algorithms this KEM requires are available in this build.
constexpr KEM_Code code() const
size_t public_key_length() const
Return the constant Npk from RFC 9180 Section 7.1, throws for invalid code points.
constexpr uint16_t wire_code() const
size_t shared_secret_length() const
Return the constant Nsecret from RFC 9180 Section 7.1, throws for invalid code points.
size_t private_key_length() const
Return the constant Nsk from RFC 9180 Section 7.1, throws for invalid code points.
static std::unique_ptr< const KEM_Ops > create(KEM_Id kem)
std::span< const uint8_t > identity() const
std::span< const uint8_t > secret() const
PSK(std::span< const uint8_t > psk, std::span< const uint8_t > psk_id)
Public_Key public_key() const
The corresponding public key.
static Private_Key generate(KEM_Id kem, RandomNumberGenerator &rng)
GenerateKeyPair from RFC 9180 Section 4.
const Botan::Private_Key & underlying() const
static Private_Key derive(KEM_Id kem, std::span< const uint8_t > ikm)
static Private_Key deserialize(KEM_Id kem, std::span< const uint8_t > bytes)
static Private_Key from_key(KEM_Id kem, std::unique_ptr< Botan::Private_Key > key)
secure_vector< uint8_t > serialize() const
static Public_Key deserialize(KEM_Id kem, std::span< const uint8_t > bytes)
std::vector< uint8_t > serialize() const
SerializePublicKey from RFC 9180 Section 7.1.1.
static Public_Key from_key(KEM_Id kem, std::unique_ptr< Botan::Public_Key > key)
const Botan::Public_Key & underlying() const
secure_vector< uint8_t > open_at_sequence(uint64_t seq, std::span< const uint8_t > aad, std::span< const uint8_t > ctext)
secure_vector< uint8_t > export_secret(std::span< const uint8_t > exporter_context, size_t length) const
static Recipient_Context setup_auth(const Suite &suite, const Private_Key &recipient_key, std::span< const uint8_t > enc, const Public_Key &sender_identity_key, RandomNumberGenerator &rng, std::span< const uint8_t > info={})
secure_vector< uint8_t > open(std::span< const uint8_t > aad, std::span< const uint8_t > ctext)
uint64_t next_sequence() const
Recipient_Context(const Recipient_Context &)=delete
static Recipient_Context setup_psk(const Suite &suite, const Private_Key &recipient_key, std::span< const uint8_t > enc, RandomNumberGenerator &rng, const PSK &psk, std::span< const uint8_t > info={})
static Recipient_Context setup_auth_psk(const Suite &suite, const Private_Key &recipient_key, std::span< const uint8_t > enc, const Public_Key &sender_identity_key, RandomNumberGenerator &rng, const PSK &psk, std::span< const uint8_t > info={})
static Recipient_Context setup_base(const Suite &suite, const Private_Key &recipient_key, std::span< const uint8_t > enc, RandomNumberGenerator &rng, std::span< const uint8_t > info={})
static Sender_Context setup_psk(const Suite &suite, const Public_Key &recipient_key, RandomNumberGenerator &rng, const PSK &psk, std::span< const uint8_t > info={})
static Sender_Context setup_auth(const Suite &suite, const Public_Key &recipient_key, const Private_Key &sender_identity_key, RandomNumberGenerator &rng, std::span< const uint8_t > info={})
static Sender_Context setup_base(const Suite &suite, const Public_Key &recipient_key, RandomNumberGenerator &rng, std::span< const uint8_t > info={})
secure_vector< uint8_t > export_secret(std::span< const uint8_t > exporter_context, size_t length) const
std::vector< uint8_t > seal(std::span< const uint8_t > aad, std::span< const uint8_t > ptext)
Sender_Context(const Sender_Context &)=delete
uint64_t next_sequence() const
The sequence number the next call to seal() will use.
const std::vector< uint8_t > & encapsulated_key() const
The KEM encapsulation ("enc") to be transmitted to the recipient.
static Sender_Context setup_auth_psk(const Suite &suite, const Public_Key &recipient_key, const Private_Key &sender_identity_key, RandomNumberGenerator &rng, const PSK &psk, std::span< const uint8_t > info={})
constexpr AEAD_Id aead() const
constexpr KDF_Id kdf() const
constexpr bool is_export_only() const
std::optional< std::string > to_string() const
constexpr KEM_Id kem() const
static std::unique_ptr< MessageAuthenticationCode > create(std::string_view algo_spec, std::string_view provider="")
Mode
The four HPKE modes, with their codepoints from RFC 9180 Section 5.
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)
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)
std::span< const uint8_t > as_span_of_bytes(const char *s, size_t len)
std::string fmt(std::string_view format, const T &... args)
constexpr auto concat(Rs &&... ranges)
std::vector< T, secure_allocator< T > > secure_vector