8#include <botan/internal/hpke_kem.h>
10#include <botan/ec_apoint.h>
11#include <botan/ec_group.h>
12#include <botan/ec_scalar.h>
13#include <botan/ecdh.h>
14#include <botan/exceptn.h>
16#include <botan/pubkey.h>
18#include <botan/internal/concat_util.h>
19#include <botan/internal/fmt.h>
20#include <botan/internal/hkdf.h>
21#include <botan/internal/loadstor.h>
22#include <botan/internal/mem_utils.h>
27#if defined(BOTAN_HAS_X25519)
28 #include <botan/x25519.h>
31#if defined(BOTAN_HAS_X448)
32 #include <botan/x448.h>
35#if defined(BOTAN_HAS_ECDSA)
36 #include <botan/ecdsa.h>
43std::string kem_name(
KEM_Id kem) {
44 return kem.to_string().value_or(std::to_string(kem.wire_code()));
50 std::span<const uint8_t> suite_id,
51 std::span<const uint8_t> salt,
52 std::string_view label,
53 std::span<const uint8_t> ikm) {
56 const size_t nh = prf->output_length();
66 std::span<const uint8_t> suite_id,
67 std::span<const uint8_t> prk,
68 std::string_view label,
69 std::span<const uint8_t> info,
72 BOTAN_ARG_CHECK(length <= 0xFFFF,
"HPKE LabeledExpand output length too large");
119std::vector<uint8_t> kem_suite_id(
KEM_Id kem) {
122 return {
'K',
'E',
'M',
static_cast<uint8_t
>(code >> 8),
static_cast<uint8_t
>(code & 0xFF)};
125enum class DH_Group : uint8_t { P256, P384, P521, X25519, X448 };
128template <
bool is_private,
typename PrivateT,
typename PublicT>
129using select_key_t = std::conditional_t<is_private, PrivateT, PublicT>;
136void clamp_scalar(DH_Group group, std::span<uint8_t> sk) {
137 if(group == DH_Group::X25519) {
142 }
else if(group == DH_Group::X448) {
149class DHKEM final :
public KEM_Ops {
151 DHKEM(KEM_Id
id, DH_Group group, std::string_view hash, std::string_view curve, uint8_t candidate_mask) :
155 m_nh(MessageAuthenticationCode::create_or_throw(
fmt(
"HMAC({})", hash))->output_length()),
156 m_candidate_mask(candidate_mask),
157 m_suite_id(kem_suite_id(id)) {
159 m_ec_group = EC_Group::from_name(curve);
164 bool supports_auth()
const override {
return true; }
166 Encapsulation encap(
const Botan::Public_Key& pkR, RandomNumberGenerator& rng)
const override {
168 const auto skE = generate_key(rng);
169 return encap_impl(pkR, *skE, rng);
172 Encapsulation encap_with_ephemeral(
const Botan::Public_Key& pkR,
173 const Botan::Private_Key& skE,
174 RandomNumberGenerator& rng)
const override {
175 BOTAN_ARG_CHECK(is_dhkem_private_key(skE),
"Ephemeral key does not match the KEM");
176 return encap_impl(pkR, skE, rng);
180 const Botan::Private_Key& skR,
181 RandomNumberGenerator& rng)
const override {
183 check_public_encoding(enc);
185 const auto pkRm = serialize_public(skR);
186 const auto dh_value = dh(skR, enc, rng);
188 return extract_and_expand(dh_value, kem_context);
191 Encapsulation auth_encap(
const Botan::Public_Key& pkR,
192 const Botan::Private_Key& skS,
193 RandomNumberGenerator& rng)
const override {
195 const auto skE = generate_key(rng);
196 return auth_encap_impl(pkR, skS, *skE, rng);
199 Encapsulation auth_encap_with_ephemeral(
const Botan::Public_Key& pkR,
200 const Botan::Private_Key& skS,
201 const Botan::Private_Key& skE,
202 RandomNumberGenerator& rng)
const override {
203 BOTAN_ARG_CHECK(is_dhkem_private_key(skE),
"Ephemeral key does not match the KEM");
204 return auth_encap_impl(pkR, skS, skE, rng);
208 const Botan::Private_Key& skR,
209 const Botan::Public_Key& pkS,
210 RandomNumberGenerator& rng)
const override {
212 check_public_encoding(enc);
214 const auto pkRm = serialize_public(skR);
215 const auto pkSm = serialize_public(pkS);
220 return extract_and_expand(dh_value, kem_context);
223 std::unique_ptr<Botan::Private_Key> generate_key(RandomNumberGenerator& rng)
const override {
225 return this->derive_key_pair(rng.random_vec(kem_id().private_key_length()));
228 std::unique_ptr<Botan::Private_Key> derive_key_pair(std::span<const uint8_t> ikm)
const override {
230 const size_t nsk = kem_id().private_key_length();
233 BOTAN_ARG_CHECK(ikm.size() >= std::min(nsk, m_nh),
"HPKE DeriveKeyPair ikm too short");
235 const auto dkp_prk =
labeled_extract(m_hash, m_suite_id, {},
"dkp_prk", ikm);
238#if defined(BOTAN_HAS_X25519)
239 case DH_Group::X25519: {
240 auto sk =
labeled_expand(m_hash, m_suite_id, dkp_prk,
"sk", {}, nsk);
241 clamp_scalar(m_group, sk);
242 return std::make_unique<X25519_PrivateKey>(sk);
245#if defined(BOTAN_HAS_X448)
246 case DH_Group::X448: {
247 auto sk =
labeled_expand(m_hash, m_suite_id, dkp_prk,
"sk", {}, nsk);
248 clamp_scalar(m_group, sk);
249 return std::make_unique<X448_PrivateKey>(sk);
254 case DH_Group::P521: {
255 const auto& group = ec_group();
256 for(uint16_t counter = 0; counter != 256; ++counter) {
257 const std::array<uint8_t, 1> counter_octet{
static_cast<uint8_t
>(counter)};
258 auto candidate =
labeled_expand(m_hash, m_suite_id, dkp_prk,
"candidate", counter_octet, nsk);
259 candidate[0] &= m_candidate_mask;
262 scalar.has_value() && scalar->is_nonzero()) {
263 return std::make_unique<ECDH_PrivateKey>(group, *scalar);
267 throw Internal_Error(
"HPKE DeriveKeyPair rejection sampling failed");
270 throw Not_Implemented(
"HPKE DHKEM group not available");
274 std::unique_ptr<Botan::Public_Key> deserialize_public(std::span<const uint8_t> bytes)
const override {
276 check_public_encoding(bytes);
279#if defined(BOTAN_HAS_X25519)
280 case DH_Group::X25519:
281 return std::make_unique<X25519_PublicKey>(bytes);
283#if defined(BOTAN_HAS_X448)
285 return std::make_unique<X448_PublicKey>(bytes);
289 case DH_Group::P521: {
290 const auto& group = ec_group();
293 return std::make_unique<ECDH_PublicKey>(group, *point);
295 throw Decoding_Error(
"HPKE DHKEM public key is not a valid point");
298 throw Not_Implemented(
"HPKE DHKEM group not available");
302 std::unique_ptr<Botan::Private_Key> deserialize_private(std::span<const uint8_t> bytes)
const override {
304 if(bytes.size() != kem_id().private_key_length()) {
305 throw Decoding_Error(
fmt(
"Invalid private key length for HPKE KEM {}", kem_name(kem_id())));
309#if defined(BOTAN_HAS_X25519)
310 case DH_Group::X25519: {
312 clamp_scalar(m_group, sk);
313 return std::make_unique<X25519_PrivateKey>(sk);
316#if defined(BOTAN_HAS_X448)
317 case DH_Group::X448: {
319 clamp_scalar(m_group, sk);
320 return std::make_unique<X448_PrivateKey>(sk);
325 case DH_Group::P521: {
326 const auto& group = ec_group();
328 scalar.has_value() && scalar->is_nonzero()) {
329 return std::make_unique<ECDH_PrivateKey>(group, *scalar);
331 throw Decoding_Error(
"HPKE DHKEM private key is out of range");
334 throw Not_Implemented(
"HPKE DHKEM group not available");
338 std::vector<uint8_t> serialize_public(
const Botan::Public_Key& key)
const override {
340 if(
const auto* ecdh =
dynamic_cast<const ECDH_PublicKey*
>(&key)) {
354 clamp_scalar(m_group, bytes);
358 std::unique_ptr<Botan::Public_Key> adopt_public(std::unique_ptr<Botan::Public_Key> key)
const override {
359 return adopt_key(std::move(key));
362 std::unique_ptr<Botan::Private_Key> adopt_private(std::unique_ptr<Botan::Private_Key> key)
const override {
363 return adopt_key(std::move(key));
372 template <
typename KeyT>
373 std::unique_ptr<KeyT> adopt_key(std::unique_ptr<KeyT> key)
const {
374 constexpr bool is_private = std::is_same_v<KeyT, Botan::Private_Key>;
377#if defined(BOTAN_HAS_X25519)
378 case DH_Group::X25519:
379 if(
dynamic_cast<const select_key_t<is_private, X25519_PrivateKey, X25519_PublicKey>*
>(key.get()) !=
385#if defined(BOTAN_HAS_X448)
387 if(
dynamic_cast<const select_key_t<is_private, X448_PrivateKey, X448_PublicKey>*
>(key.get()) !=
396 if(
const auto* ecdh =
397 dynamic_cast<const select_key_t<is_private, ECDH_PrivateKey, ECDH_PublicKey>*
>(key.get())) {
398 check_ec_group(ecdh->domain());
401#if defined(BOTAN_HAS_ECDSA)
407 if(
const auto* ecdsa =
408 dynamic_cast<const select_key_t<is_private, ECDSA_PrivateKey, ECDSA_PublicKey>*
>(key.get())) {
409 check_ec_group(ecdsa->domain());
410 if constexpr(is_private) {
411 return std::make_unique<ECDH_PrivateKey>(ec_group(), ecdsa->_private_key());
413 return std::make_unique<ECDH_PublicKey>(ec_group(), ecdsa->public_ec_point());
422 throw Invalid_Argument(
423 fmt(
"Key of type {} cannot be used with HPKE KEM {}", key->algo_name(), kem_name(kem_id())));
426 const EC_Group& ec_group()
const {
431 void check_ec_group(
const EC_Group& group)
const {
432 if(group != ec_group()) {
433 throw Invalid_Argument(
fmt(
"EC key on curve {} cannot be used with HPKE KEM {}",
434 group.get_curve_oid().to_formatted_string(),
435 kem_name(kem_id())));
440 bool is_dhkem_private_key(
const Botan::Private_Key& key)
const {
442#if defined(BOTAN_HAS_X25519)
443 case DH_Group::X25519:
444 return dynamic_cast<const X25519_PrivateKey*
>(&key) !=
nullptr;
446#if defined(BOTAN_HAS_X448)
448 return dynamic_cast<const X448_PrivateKey*
>(&key) !=
nullptr;
452 case DH_Group::P521: {
453 const auto* ecdh =
dynamic_cast<const ECDH_PrivateKey*
>(&key);
454 return ecdh !=
nullptr && ecdh->domain() == ec_group();
461 bool is_nist_curve()
const {
462 return m_group == DH_Group::P256 || m_group == DH_Group::P384 || m_group == DH_Group::P521;
470 void check_public_encoding(std::span<const uint8_t> bytes)
const {
471 if(bytes.size() != kem_id().public_key_length()) {
472 throw Decoding_Error(
fmt(
"Invalid public key length for HPKE KEM {}", kem_name(kem_id())));
474 if(is_nist_curve() && bytes[0] != 0x04) {
475 throw Decoding_Error(
"HPKE requires uncompressed EC point encoding");
479 Encapsulation encap_impl(
const Botan::Public_Key& pkR,
480 const Botan::Private_Key& skE,
481 RandomNumberGenerator& rng)
const {
483 const auto pkRm = serialize_public(pkR);
484 const auto dh_value = dh(skE, pkRm, rng);
486 auto enc = serialize_public(skE);
488 auto shared_secret = extract_and_expand(dh_value, kem_context);
489 return {std::move(enc), std::move(shared_secret)};
492 Encapsulation auth_encap_impl(
const Botan::Public_Key& pkR,
493 const Botan::Private_Key& skS,
494 const Botan::Private_Key& skE,
495 RandomNumberGenerator& rng)
const {
497 const auto pkRm = serialize_public(pkR);
498 const auto pkSm = serialize_public(skS);
499 auto enc = serialize_public(skE);
504 auto shared_secret = extract_and_expand(dh_value, kem_context);
505 return {std::move(enc), std::move(shared_secret)};
516 std::span<const uint8_t> peer,
517 RandomNumberGenerator& rng)
const {
519 const PK_Key_Agreement ka(sk, rng,
"Raw");
520 return ka.derive_key(0, peer).bits_of();
524 std::span<const uint8_t> kem_context)
const {
526 const auto eae_prk =
labeled_extract(m_hash, m_suite_id, {},
"eae_prk", dh_value);
528 m_hash, m_suite_id, eae_prk,
"shared_secret", kem_context, kem_id().shared_secret_length());
534 uint8_t m_candidate_mask;
535 std::vector<uint8_t> m_suite_id;
536 std::optional<EC_Group> m_ec_group;
539bool hmac_available(std::string_view hash) {
550 return std::make_unique<DHKEM>(kem, DH_Group::P256,
"SHA-256",
"secp256r1", 0xFF);
556 return std::make_unique<DHKEM>(kem, DH_Group::P384,
"SHA-384",
"secp384r1", 0xFF);
562 return std::make_unique<DHKEM>(kem, DH_Group::P521,
"SHA-512",
"secp521r1", 0x01);
567#if defined(BOTAN_HAS_X25519)
568 if(hmac_available(
"SHA-256")) {
569 return std::make_unique<DHKEM>(kem, DH_Group::X25519,
"SHA-256",
"", 0x00);
575#if defined(BOTAN_HAS_X448)
576 if(hmac_available(
"SHA-512")) {
577 return std::make_unique<DHKEM>(kem, DH_Group::X448,
"SHA-512",
"", 0x00);
586 throw Not_Implemented(
fmt(
"HPKE KEM {} is not available in this build", kem_name(kem)));
#define BOTAN_ASSERT_NOMSG(expr)
#define BOTAN_ARG_CHECK(expr, msg)
static std::optional< EC_AffinePoint > deserialize(const EC_Group &group, std::span< const uint8_t > bytes)
static bool supports_named_group(std::string_view name)
static std::optional< EC_Scalar > deserialize(const EC_Group &group, std::span< const uint8_t > bytes)
constexpr KEM_Code code() const
constexpr uint16_t wire_code() const
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
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.
static std::unique_ptr< const KEM_Ops > create(KEM_Id kem)
virtual Encapsulation encap_with_ephemeral(const Botan::Public_Key &pkR, const Botan::Private_Key &skE, RandomNumberGenerator &rng) const
virtual Encapsulation auth_encap_with_ephemeral(const Botan::Public_Key &pkR, const Botan::Private_Key &skS, const Botan::Private_Key &skE, RandomNumberGenerator &rng) const
T derive_key(size_t key_len, const uint8_t secret[], size_t secret_len, const uint8_t salt[], size_t salt_len, const uint8_t label[]=nullptr, size_t label_len=0) const
static std::unique_ptr< MessageAuthenticationCode > create_or_throw(std::string_view algo_spec, std::string_view provider="")
static std::unique_ptr< MessageAuthenticationCode > create(std::string_view algo_spec, std::string_view provider="")
virtual secure_vector< uint8_t > raw_private_key_bits() const
virtual std::vector< uint8_t > raw_public_key_bits() const =0
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
constexpr auto store_be(ParamTs &&... params)