Botan 3.9.0
Crypto and TLS for C&
hybrid_kem_ops.h
Go to the documentation of this file.
1/**
2* Abstraction for a combined KEM encryptors and decryptors.
3*
4* (C) 2024 Jack Lloyd
5* 2024 Fabian Albert, René Meusel - Rohde & Schwarz Cybersecurity
6*
7* Botan is released under the Simplified BSD License (see license.txt)
8*/
9
10#ifndef BOTAN_HYBRID_KEM_OPS_H_
11#define BOTAN_HYBRID_KEM_OPS_H_
12
13#include <botan/pk_algs.h>
14#include <botan/pubkey.h>
15#include <botan/internal/pk_ops_impl.h>
16#include <botan/internal/stl_util.h>
17
18#include <memory>
19#include <vector>
20
21namespace Botan {
22
23/**
24 * @brief Abstract interface for a KEM encryption operation for KEM combiners.
25 *
26 * Multiple public keys are used to encapsulate shared secrets. These shared
27 * secrets (and maybe the ciphertexts and public keys) are combined using the
28 * KEM combiner to derive the final shared secret.
29 *
30 */
32 public:
33 KEM_Encryption_with_Combiner(const std::vector<std::unique_ptr<Public_Key>>& public_keys,
34 std::string_view provider);
35
36 void kem_encrypt(std::span<uint8_t> out_encapsulated_key,
37 std::span<uint8_t> out_shared_key,
39 size_t desired_shared_key_len,
40 std::span<const uint8_t> salt) final;
41
42 /// The default implementation returns the sum of the encapsulated key lengths of the underlying KEMs.
43 size_t encapsulated_key_length() const override { return m_encapsulated_key_length; }
44
45 protected:
46 /**
47 * @brief Defines how multiple ciphertexts are combined into a single ciphertext.
48 *
49 * The default implementation concatenates the ciphertexts.
50 *
51 * @param out_ciphertext The output buffer for the combined ciphertext
52 * @param ciphertexts The ciphertexts to combine
53 * @param salt The salt. In this default implementation the salt must be empty.
54 */
55 virtual void combine_ciphertexts(std::span<uint8_t> out_ciphertext,
56 const std::vector<std::vector<uint8_t>>& ciphertexts,
57 std::span<const uint8_t> salt);
58
59 /**
60 * @brief Describes how the shared secrets are combined to derive the final shared secret.
61 *
62 * @param out_shared_secret the output buffer for the shared secret
63 * @param shared_secrets a list of shared secrets coreesponding to the public keys
64 * @param ciphertexts a list of encapsulated shared secrets
65 * @param desired_shared_key_len the desired shared key length
66 * @param salt the salt (input of kem_encrypt)
67 */
68 virtual void combine_shared_secrets(std::span<uint8_t> out_shared_secret,
69 const std::vector<secure_vector<uint8_t>>& shared_secrets,
70 const std::vector<std::vector<uint8_t>>& ciphertexts,
71 size_t desired_shared_key_len,
72 std::span<const uint8_t> salt) = 0;
73
74 std::vector<PK_KEM_Encryptor>& encryptors() { return m_encryptors; }
75
76 const std::vector<PK_KEM_Encryptor>& encryptors() const { return m_encryptors; }
77
78 private:
79 std::vector<PK_KEM_Encryptor> m_encryptors;
80 size_t m_encapsulated_key_length;
81};
82
83/**
84 * @brief Abstract interface for a KEM decryption operation for KEM combiners.
85 *
86 * Multiple private keys are used to decapsulate shared secrets from a combined
87 * ciphertext (concatenated in most cases). These shared
88 * secrets (and maybe the ciphertexts and public keys) are combined using the
89 * KEM combiner to derive the final shared secret.
90 */
92 public:
93 KEM_Decryption_with_Combiner(const std::vector<std::unique_ptr<Private_Key>>& private_keys,
95 std::string_view provider);
96
97 void kem_decrypt(std::span<uint8_t> out_shared_key,
98 std::span<const uint8_t> encapsulated_key,
99 size_t desired_shared_key_len,
100 std::span<const uint8_t> salt) final;
101
102 /// The default implementation returns the sum of the encapsulated key lengths of the underlying KEMs.
103 size_t encapsulated_key_length() const override { return m_encapsulated_key_length; }
104
105 protected:
106 /**
107 * @brief Defines how the individual ciphertexts are extracted from the combined ciphertext.
108 *
109 * The default implementation splits concatenated ciphertexts.
110 * @param concat_ciphertext The combined ciphertext
111 * @returns The individual ciphertexts
112 */
113 virtual std::vector<std::vector<uint8_t>> split_ciphertexts(std::span<const uint8_t> concat_ciphertext);
114
115 /**
116 * @brief Describes how the shared secrets are combined to derive the final shared secret.
117 *
118 * @param out_shared_secret the output buffer for the shared secret
119 * @param shared_secrets a list of shared secrets coreesponding to the public keys
120 * @param ciphertexts the list of encapsulated shared secrets
121 * @param desired_shared_key_len the desired shared key length
122 * @param salt the salt (input of kem_decrypt)
123 */
124 virtual void combine_shared_secrets(std::span<uint8_t> out_shared_secret,
125 const std::vector<secure_vector<uint8_t>>& shared_secrets,
126 const std::vector<std::vector<uint8_t>>& ciphertexts,
127 size_t desired_shared_key_len,
128 std::span<const uint8_t> salt) = 0;
129
130 std::vector<PK_KEM_Decryptor>& decryptors() { return m_decryptors; }
131
132 const std::vector<PK_KEM_Decryptor>& decryptors() const { return m_decryptors; }
133
134 private:
135 std::vector<PK_KEM_Decryptor> m_decryptors;
136 size_t m_encapsulated_key_length;
137};
138
139} // namespace Botan
140
141#endif // BOTAN_HYBRID_KEM_OPS_H_
std::vector< PK_KEM_Decryptor > & decryptors()
const std::vector< PK_KEM_Decryptor > & decryptors() const
void kem_decrypt(std::span< uint8_t > out_shared_key, std::span< const uint8_t > encapsulated_key, size_t desired_shared_key_len, std::span< const uint8_t > salt) final
KEM_Decryption_with_Combiner(const std::vector< std::unique_ptr< Private_Key > > &private_keys, RandomNumberGenerator &rng, std::string_view provider)
size_t encapsulated_key_length() const override
The default implementation returns the sum of the encapsulated key lengths of the underlying KEMs.
virtual void combine_shared_secrets(std::span< uint8_t > out_shared_secret, const std::vector< secure_vector< uint8_t > > &shared_secrets, const std::vector< std::vector< uint8_t > > &ciphertexts, size_t desired_shared_key_len, std::span< const uint8_t > salt)=0
Describes how the shared secrets are combined to derive the final shared secret.
virtual std::vector< std::vector< uint8_t > > split_ciphertexts(std::span< const uint8_t > concat_ciphertext)
Defines how the individual ciphertexts are extracted from the combined ciphertext.
KEM_Encryption_with_Combiner(const std::vector< std::unique_ptr< Public_Key > > &public_keys, std::string_view provider)
std::vector< PK_KEM_Encryptor > & encryptors()
virtual void combine_ciphertexts(std::span< uint8_t > out_ciphertext, const std::vector< std::vector< uint8_t > > &ciphertexts, std::span< const uint8_t > salt)
Defines how multiple ciphertexts are combined into a single ciphertext.
void kem_encrypt(std::span< uint8_t > out_encapsulated_key, std::span< uint8_t > out_shared_key, RandomNumberGenerator &rng, size_t desired_shared_key_len, std::span< const uint8_t > salt) final
const std::vector< PK_KEM_Encryptor > & encryptors() const
size_t encapsulated_key_length() const override
The default implementation returns the sum of the encapsulated key lengths of the underlying KEMs.
virtual void combine_shared_secrets(std::span< uint8_t > out_shared_secret, const std::vector< secure_vector< uint8_t > > &shared_secrets, const std::vector< std::vector< uint8_t > > &ciphertexts, size_t desired_shared_key_len, std::span< const uint8_t > salt)=0
Describes how the shared secrets are combined to derive the final shared secret.
std::vector< T, secure_allocator< T > > secure_vector
Definition secmem.h:69