Botan 3.7.1
Crypto and TLS for C&
ecies.h
Go to the documentation of this file.
1/*
2* ECIES
3* (C) 2016 Philipp Weber
4* 2025 Jack Lloyd
5*
6* Botan is released under the Simplified BSD License (see license.txt)
7*/
8
9#ifndef BOTAN_ECIES_H_
10#define BOTAN_ECIES_H_
11
12#include <botan/cipher_mode.h>
13#include <botan/ec_apoint.h>
14#include <botan/ec_group.h>
15#include <botan/mac.h>
16#include <botan/pubkey.h>
17#include <botan/secmem.h>
18#include <botan/symkey.h>
19#include <memory>
20#include <optional>
21#include <string>
22#include <vector>
23
24#if defined(BOTAN_HAS_LEGACY_EC_POINT)
25 #include <botan/ec_point.h>
26#endif
27
28namespace Botan {
29
30class RandomNumberGenerator;
31
32enum class ECIES_Flags : uint32_t {
33 None = 0,
34 /// if set: prefix the input of the (ecdh) key agreement with the encoded (ephemeral) public key
36 /// (decryption only) if set: use cofactor multiplication during (ecdh) key agreement
37 CofactorMode = 2,
38 /// if set: use ecdhc instead of ecdh
40 /// (decryption only) if set: test if the (ephemeral) public key is on the curve
41 CheckMode = 8,
42
43 NONE BOTAN_DEPRECATED("Use None") = None,
44 SINGLE_HASH_MODE BOTAN_DEPRECATED("Use SingleHashMode") = SingleHashMode,
45 COFACTOR_MODE BOTAN_DEPRECATED("Use CofactorMode") = CofactorMode,
46 OLD_COFACTOR_MODE BOTAN_DEPRECATED("Use OldCofactorMode") = OldCofactorMode,
47 CHECK_MODE BOTAN_DEPRECATED("Use CheckMode") = CheckMode,
48};
49
51 // NOLINTNEXTLINE(clang-analyzer-optin.core.EnumCastOutOfRange)
52 return static_cast<ECIES_Flags>(static_cast<uint32_t>(a) | static_cast<uint32_t>(b));
53}
54
56 return static_cast<ECIES_Flags>(static_cast<uint32_t>(a) & static_cast<uint32_t>(b));
57}
58
59/**
60* Parameters for ECIES secret derivation
61*/
63 public:
64 /**
65 * @param domain ec domain parameters of the involved ec keys
66 * @param kdf_spec name of the key derivation function
67 * @param length length of the secret to be derived
68 * @param compression_type format of encoded keys (affects the secret derivation if single_hash_mode is used)
69 * @param flags options, see documentation of ECIES_Flags
70 */
71 ECIES_KA_Params(const EC_Group& domain,
72 std::string_view kdf_spec,
73 size_t length,
74 EC_Point_Format compression_type,
75 ECIES_Flags flags);
76
79
80 virtual ~ECIES_KA_Params() = default;
81
82 inline const EC_Group& domain() const { return m_domain; }
83
84 inline size_t secret_length() const { return m_length; }
85
86 inline bool single_hash_mode() const {
87 return (m_flags & ECIES_Flags::SingleHashMode) == ECIES_Flags::SingleHashMode;
88 }
89
90 inline bool cofactor_mode() const { return (m_flags & ECIES_Flags::CofactorMode) == ECIES_Flags::CofactorMode; }
91
92 inline bool old_cofactor_mode() const {
93 return (m_flags & ECIES_Flags::OldCofactorMode) == ECIES_Flags::OldCofactorMode;
94 }
95
96 inline bool check_mode() const { return (m_flags & ECIES_Flags::CheckMode) == ECIES_Flags::CheckMode; }
97
98 inline EC_Point_Format compression_type() const { return m_compression_mode; }
99
100 const std::string& kdf_spec() const { return m_kdf_spec; }
101
102 private:
103 const EC_Group m_domain;
104 const std::string m_kdf_spec;
105 const size_t m_length;
106 const EC_Point_Format m_compression_mode;
107 const ECIES_Flags m_flags;
108};
109
111 public:
112 /**
113 * @param domain ec domain parameters of the involved ec keys
114 * @param kdf_spec name of the key derivation function
115 * @param dem_algo_spec name of the data encryption method
116 * @param dem_key_len length of the key used for the data encryption method
117 * @param mac_spec name of the message authentication code
118 * @param mac_key_len length of the key used for the message authentication code
119 */
120 ECIES_System_Params(const EC_Group& domain,
121 std::string_view kdf_spec,
122 std::string_view dem_algo_spec,
123 size_t dem_key_len,
124 std::string_view mac_spec,
125 size_t mac_key_len);
126
127 /**
128 * @param domain ec domain parameters of the involved ec keys
129 * @param kdf_spec name of the key derivation function
130 * @param dem_algo_spec name of the data encryption method
131 * @param dem_key_len length of the key used for the data encryption method
132 * @param mac_spec name of the message authentication code
133 * @param mac_key_len length of the key used for the message authentication code
134 * @param compression_type format of encoded keys (affects the secret derivation if single_hash_mode is used)
135 * @param flags options, see documentation of ECIES_Flags
136 */
137 ECIES_System_Params(const EC_Group& domain,
138 std::string_view kdf_spec,
139 std::string_view dem_algo_spec,
140 size_t dem_key_len,
141 std::string_view mac_spec,
142 size_t mac_key_len,
143 EC_Point_Format compression_type,
144 ECIES_Flags flags);
145
148 ~ECIES_System_Params() override = default;
149
150 /// creates an instance of the message authentication code
151 std::unique_ptr<MessageAuthenticationCode> create_mac() const;
152
153 /// creates an instance of the data encryption method
154 std::unique_ptr<Cipher_Mode> create_cipher(Cipher_Dir direction) const;
155
156 /// returns the length of the key used by the data encryption method
157 inline size_t dem_keylen() const { return m_dem_keylen; }
158
159 /// returns the length of the key used by the message authentication code
160 inline size_t mac_keylen() const { return m_mac_keylen; }
161
162 private:
163 const std::string m_dem_spec;
164 const size_t m_dem_keylen;
165 const std::string m_mac_spec;
166 const size_t m_mac_keylen;
167};
168
169/**
170* ECIES secret derivation according to ISO 18033-2
171*
172* TODO(Botan4) hide this
173*/
175 public:
176 /**
177 * @param private_key the (ephemeral) private key which is used to derive the secret
178 * @param ecies_params settings for ecies
179 * @param for_encryption disable cofactor mode if the secret will be used for encryption
180 * (according to ISO 18033 cofactor mode is only used during decryption)
181 * @param rng the RNG to use
182 */
183 BOTAN_DEPRECATED("Deprecated no replacement")
184 ECIES_KA_Operation(const PK_Key_Agreement_Key& private_key,
185 const ECIES_KA_Params& ecies_params,
186 bool for_encryption,
188
189#if defined(BOTAN_HAS_LEGACY_EC_POINT)
190 /**
191 * Performs a key agreement with the provided keys and derives the secret from the result
192 * @param eph_public_key_bin the encoded (ephemeral) public key which belongs to the used (ephemeral) private key
193 * @param other_public_key_point public key point of the other party
194 */
195 SymmetricKey derive_secret(const std::vector<uint8_t>& eph_public_key_bin,
196 const EC_Point& other_public_key_point) const;
197#endif
198
199 /**
200 * Performs a key agreement with the provided keys and derives the secret from the result
201 * @param eph_public_key_bin the encoded (ephemeral) public key which belongs to the used (ephemeral) private key
202 * @param other_public_key_point public key point of the other party
203 */
204 SymmetricKey derive_secret(std::span<const uint8_t> eph_public_key_bin,
205 const EC_AffinePoint& other_public_key_point) const;
206
207 private:
208 const PK_Key_Agreement m_ka;
209 const ECIES_KA_Params m_params;
210};
211
212/**
213* ECIES Encryption according to ISO 18033-2
214*/
216 public:
217 /**
218 * @param private_key the (ephemeral) private key which is used for the key agreement
219 * @param ecies_params settings for ecies
220 * @param rng random generator to use
221 */
222 ECIES_Encryptor(const PK_Key_Agreement_Key& private_key,
223 const ECIES_System_Params& ecies_params,
225
226 /**
227 * Creates an ephemeral private key which is used for the key agreement
228 * @param rng random generator used during private key generation
229 * @param ecies_params settings for ecies
230 */
232
233#if defined(BOTAN_HAS_LEGACY_EC_POINT)
234 /// Set the public key of the other party
235 inline void set_other_key(const EC_Point& public_point) {
236 m_other_point = EC_AffinePoint(m_params.domain(), public_point);
237 }
238#endif
239
240 /// Set the public key of the other party
241 void set_other_key(const EC_AffinePoint& pt) { m_other_point = pt; }
242
243 /// Set the initialization vector for the data encryption method
244 void set_initialization_vector(const InitializationVector& iv) { m_iv = iv; }
245
246 /// Set the label which is appended to the input for the message authentication code
247 void set_label(std::string_view label) { m_label.assign(label.begin(), label.end()); }
248
249 private:
250 std::vector<uint8_t> enc(const uint8_t data[], size_t length, RandomNumberGenerator&) const override;
251
252 size_t maximum_input_size() const override;
253
254 size_t ciphertext_length(size_t ptext_len) const override;
255
256 const ECIES_KA_Operation m_ka;
257 const ECIES_System_Params m_params;
258 std::unique_ptr<MessageAuthenticationCode> m_mac;
259 std::unique_ptr<Cipher_Mode> m_cipher;
260 std::vector<uint8_t> m_eph_public_key_bin;
262 std::optional<EC_AffinePoint> m_other_point;
263 std::vector<uint8_t> m_label;
264};
265
266/**
267* ECIES Decryption according to ISO 18033-2
268*/
270 public:
271 /**
272 * @param private_key the private key which is used for the key agreement
273 * @param ecies_params settings for ecies
274 * @param rng the random generator to use
275 */
276 ECIES_Decryptor(const PK_Key_Agreement_Key& private_key,
277 const ECIES_System_Params& ecies_params,
279
280 /// Set the initialization vector for the data encryption method
281 inline void set_initialization_vector(const InitializationVector& iv) { m_iv = iv; }
282
283 /// Set the label which is appended to the input for the message authentication code
284 inline void set_label(std::string_view label) { m_label = std::vector<uint8_t>(label.begin(), label.end()); }
285
286 private:
287 secure_vector<uint8_t> do_decrypt(uint8_t& valid_mask, const uint8_t in[], size_t in_len) const override;
288
289 size_t plaintext_length(size_t ctext_len) const override;
290
291 const ECIES_KA_Operation m_ka;
292 const ECIES_System_Params m_params;
293 std::unique_ptr<MessageAuthenticationCode> m_mac;
294 std::unique_ptr<Cipher_Mode> m_cipher;
296 std::vector<uint8_t> m_label;
297};
298
299} // namespace Botan
300
301#endif
#define BOTAN_PUBLIC_API(maj, min)
Definition api.h:19
#define BOTAN_DEPRECATED(msg)
Definition api.h:59
void set_label(std::string_view label)
Set the label which is appended to the input for the message authentication code.
Definition ecies.h:284
void set_initialization_vector(const InitializationVector &iv)
Set the initialization vector for the data encryption method.
Definition ecies.h:281
void set_other_key(const EC_AffinePoint &pt)
Set the public key of the other party.
Definition ecies.h:241
void set_initialization_vector(const InitializationVector &iv)
Set the initialization vector for the data encryption method.
Definition ecies.h:244
void set_label(std::string_view label)
Set the label which is appended to the input for the message authentication code.
Definition ecies.h:247
ECIES_KA_Params(const ECIES_KA_Params &)=default
bool check_mode() const
Definition ecies.h:96
size_t secret_length() const
Definition ecies.h:84
bool old_cofactor_mode() const
Definition ecies.h:92
EC_Point_Format compression_type() const
Definition ecies.h:98
bool cofactor_mode() const
Definition ecies.h:90
virtual ~ECIES_KA_Params()=default
bool single_hash_mode() const
Definition ecies.h:86
const std::string & kdf_spec() const
Definition ecies.h:100
const EC_Group & domain() const
Definition ecies.h:82
ECIES_KA_Params & operator=(const ECIES_KA_Params &)=delete
ECIES_System_Params(const ECIES_System_Params &)=default
~ECIES_System_Params() override=default
size_t dem_keylen() const
returns the length of the key used by the data encryption method
Definition ecies.h:157
size_t mac_keylen() const
returns the length of the key used by the message authentication code
Definition ecies.h:160
ECIES_System_Params & operator=(const ECIES_System_Params &)=delete
int(* final)(unsigned char *, CTX *)
ASN1_Type operator|(ASN1_Type x, ASN1_Type y)
Definition asn1_obj.h:75
ECIES_Flags
Definition ecies.h:32
@ CofactorMode
(decryption only) if set: use cofactor multiplication during (ecdh) key agreement
@ OldCofactorMode
if set: use ecdhc instead of ecdh
@ CheckMode
(decryption only) if set: test if the (ephemeral) public key is on the curve
@ SingleHashMode
if set: prefix the input of the (ecdh) key agreement with the encoded (ephemeral) public key
const SIMD_8x32 & b
std::vector< T, secure_allocator< T > > secure_vector
Definition secmem.h:61
@ NONE
Definition filter.h:165
ECIES_Flags operator&(ECIES_Flags a, ECIES_Flags b)
Definition ecies.h:55