Botan 3.8.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 <string_view>
23#include <vector>
24
25#if defined(BOTAN_HAS_LEGACY_EC_POINT)
26 #include <botan/ec_point.h>
27#endif
28
29namespace Botan {
30
32
33/**
34* Flags controlling ECIES operation
35*
36* Two of the flags are related to how cofactors are handled.
37* Support for cofactors is deprecated and will be removed in Botan4.
38*
39* The CheckMode flag is completely ignored; we always check that the point is
40* valid.
41*
42* TODO(Botan4) remove this enum
43*/
44enum class ECIES_Flags : uint32_t {
45 None = 0,
46 /// if set: prefix the input of the (ecdh) key agreement with the encoded (ephemeral) public key
48 /// (decryption only) if set: use cofactor multiplication during (ecdh) key agreement
49 /// This only matters if the curve has a cofactor
51 /// if set: use ecdhc instead of ecdh.
52 /// This only matters if the curve has a cofactor
54 /// (decryption only) if set: test if the (ephemeral) public key is on the curve
55 /// Note that we actually ignore this flag and always check the key
57
58 NONE BOTAN_DEPRECATED("Use None") = None,
63};
64
66 // NOLINTNEXTLINE(clang-analyzer-optin.core.EnumCastOutOfRange)
67 return static_cast<ECIES_Flags>(static_cast<uint32_t>(a) | static_cast<uint32_t>(b));
68}
69
71 return static_cast<ECIES_Flags>(static_cast<uint32_t>(a) & static_cast<uint32_t>(b));
72}
73
74/**
75* Parameters for ECIES secret derivation
76*/
78 public:
79 /**
80 * @param group ec domain parameters of the involved ec keys
81 * @param kdf_spec name of the key derivation function
82 * @param length length of the secret to be derived
83 * @param point_format format of encoded keys (affects the secret derivation if single_hash_mode is used)
84 * @param single_hash_mode prefix the KDF input with the ephemeral public key (recommended)
85 */
87 std::string_view kdf_spec,
88 size_t length,
90 bool single_hash_mode = true);
91
92 /**
93 * @param group ec domain parameters of the involved ec keys
94 * @param kdf_spec name of the key derivation function
95 * @param length length of the secret to be derived
96 * @param point_format format of encoded keys (affects the secret derivation if single_hash_mode is used)
97 * @param flags options, see documentation of ECIES_Flags
98 *
99 * This constructor makes sense only if you are using the CofactorMode or
100 * OldCofactorMode flags. Support for cofactors in EC_Group is deprecated
101 * and will be removed in Botan4.
102 *
103 * TODO(Botan4) remove this constructor when cofactor support is removed
104 */
105 BOTAN_DEPRECATED("Prefer other constructor, see header comment")
107 std::string_view kdf_spec,
108 size_t length,
110 ECIES_Flags flags);
111
114
115 virtual ~ECIES_KA_Params() = default;
116
117 const EC_Group& group() const { return m_group; }
118
119 size_t secret_length() const { return m_length; }
120
121 bool single_hash_mode() const { return m_single_hash_mode; }
122
123 // TODO(Botan4) remove this when cofactor support is removed
124 bool cofactor_mode() const { return m_cofactor_mode; }
125
126 // TODO(Botan4) remove this when cofactor support is removed
127 bool old_cofactor_mode() const { return m_old_cofactor_mode; }
128
129 // TODO(Botan4) remove this when cofactor support is removed
130 bool check_mode() const { return m_check_mode; }
131
132 EC_Point_Format point_format() const { return m_point_format; }
133
134 const std::string& kdf() const { return m_kdf; }
135
136 BOTAN_DEPRECATED("Use kdf") const std::string& kdf_spec() const { return kdf(); }
137
138 BOTAN_DEPRECATED("Use group") const EC_Group& domain() const { return group(); }
139
140 BOTAN_DEPRECATED("Use point_format") EC_Point_Format compression_type() const { return point_format(); }
141
142 private:
143 const EC_Group m_group;
144 const std::string m_kdf;
145 const size_t m_length;
146 const EC_Point_Format m_point_format;
147 const bool m_single_hash_mode;
148 const bool m_check_mode; // TODO(Botan4) remove this field
149 const bool m_cofactor_mode; // TODO(Botan4) remove this field
150 const bool m_old_cofactor_mode; // TODO(Botan4) remove this field
151};
152
154 public:
155 /**
156 * @param group ec domain parameters of the involved ec keys
157 * @param kdf_spec name of the key derivation function
158 * @param dem_algo_spec name of the data encryption method
159 * @param dem_key_len length of the key used for the data encryption method
160 * @param mac_spec name of the message authentication code
161 * @param mac_key_len length of the key used for the message authentication code
162 */
164 std::string_view kdf_spec,
165 std::string_view dem_algo_spec,
166 size_t dem_key_len,
167 std::string_view mac_spec,
168 size_t mac_key_len,
170 bool single_hash_mode = false);
171
172 /**
173 * @param group ec domain parameters of the involved ec keys
174 * @param kdf_spec name of the key derivation function
175 * @param dem_algo_spec name of the data encryption method
176 * @param dem_key_len length of the key used for the data encryption method
177 * @param mac_spec name of the message authentication code
178 * @param mac_key_len length of the key used for the message authentication code
179 * @param point_format format of encoded keys (affects the secret derivation if single_hash_mode is used)
180 * @param flags options, see documentation of ECIES_Flags
181 *
182 * This constructor makes sense only if you are using the CofactorMode or
183 * OldCofactorMode flags. Support for cofactors in EC_Group is deprecated
184 * and will be removed in Botan4.
185 *
186 * TODO(Botan4) remove this constructor when cofactor support is removed
187 */
188 BOTAN_DEPRECATED("Prefer other constructor, see header comment")
190 std::string_view kdf_spec,
191 std::string_view dem_algo_spec,
192 size_t dem_key_len,
193 std::string_view mac_spec,
194 size_t mac_key_len,
196 ECIES_Flags flags);
197
200 ~ECIES_System_Params() override = default;
201
202 /// creates an instance of the message authentication code
203 std::unique_ptr<MessageAuthenticationCode> create_mac() const;
204
205 /// creates an instance of the data encryption method
206 std::unique_ptr<Cipher_Mode> create_cipher(Cipher_Dir direction) const;
207
208 /// returns the length of the key used by the data encryption method
209 size_t dem_keylen() const { return m_dem_keylen; }
210
211 /// returns the length of the key used by the message authentication code
212 size_t mac_keylen() const { return m_mac_keylen; }
213
214 private:
215 const std::string m_dem_spec;
216 const size_t m_dem_keylen;
217 const std::string m_mac_spec;
218 const size_t m_mac_keylen;
219};
220
221/**
222* ECIES secret derivation according to ISO 18033-2
223*/
225 public:
226 /**
227 * @param private_key the (ephemeral) private key which is used to derive the secret
228 * @param ecies_params settings for ecies
229 * @param for_encryption disable cofactor mode if the secret will be used for encryption
230 * (according to ISO 18033 cofactor mode is only used during decryption)
231 * @param rng the RNG to use
232 */
233 ECIES_KA_Operation(const PK_Key_Agreement_Key& private_key,
234 const ECIES_KA_Params& ecies_params,
235 bool for_encryption,
237
238#if defined(BOTAN_HAS_LEGACY_EC_POINT)
239 /**
240 * Performs a key agreement with the provided keys and derives the secret from the result
241 * @param eph_public_key_bin the encoded (ephemeral) public key which belongs to the used (ephemeral) private key
242 * @param other_public_key_point public key point of the other party
243 */
244 SymmetricKey derive_secret(const std::vector<uint8_t>& eph_public_key_bin,
245 const EC_Point& other_public_key_point) const;
246#endif
247
248 /**
249 * Performs a key agreement with the provided keys and derives the secret from the result
250 * @param eph_public_key_bin the encoded (ephemeral) public key which belongs to the used (ephemeral) private key
251 * @param other_public_key_point public key point of the other party
252 */
253 SymmetricKey derive_secret(std::span<const uint8_t> eph_public_key_bin,
254 const EC_AffinePoint& other_public_key_point) const;
255
256 private:
257 const PK_Key_Agreement m_ka;
258 const ECIES_KA_Params m_params;
259};
260
261/**
262* ECIES Encryption according to ISO 18033-2
263*/
265 public:
266 /**
267 * @param private_key the (ephemeral) private key which is used for the key agreement
268 * @param ecies_params settings for ecies
269 * @param rng random generator to use
270 */
271 ECIES_Encryptor(const PK_Key_Agreement_Key& private_key,
272 const ECIES_System_Params& ecies_params,
274
275 /**
276 * Creates an ephemeral private key which is used for the key agreement
277 * @param rng random generator used during private key generation
278 * @param ecies_params settings for ecies
279 */
281
282#if defined(BOTAN_HAS_LEGACY_EC_POINT)
283 /// Set the public key of the other party
284 void set_other_key(const EC_Point& public_point) {
285 m_other_point = EC_AffinePoint(m_params.group(), public_point);
286 }
287#endif
288
289 /// Set the public key of the other party
290 void set_other_key(const EC_AffinePoint& pt) { m_other_point = pt; }
291
292 /// Set the initialization vector for the data encryption method
293 void set_initialization_vector(const InitializationVector& iv) { m_iv = iv; }
294
295 /// Set the label which is appended to the input for the message authentication code
296 void set_label(std::string_view label) { m_label.assign(label.begin(), label.end()); }
297
298 private:
299 std::vector<uint8_t> enc(const uint8_t data[], size_t length, RandomNumberGenerator&) const override;
300
301 size_t maximum_input_size() const override;
302
303 size_t ciphertext_length(size_t ptext_len) const override;
304
305 const ECIES_KA_Operation m_ka;
306 const ECIES_System_Params m_params;
307 std::unique_ptr<MessageAuthenticationCode> m_mac;
308 std::unique_ptr<Cipher_Mode> m_cipher;
309 std::vector<uint8_t> m_eph_public_key_bin;
311 std::optional<EC_AffinePoint> m_other_point;
312 std::vector<uint8_t> m_label;
313};
314
315/**
316* ECIES Decryption according to ISO 18033-2
317*/
319 public:
320 /**
321 * @param private_key the private key which is used for the key agreement
322 * @param ecies_params settings for ecies
323 * @param rng the random generator to use
324 */
325 ECIES_Decryptor(const PK_Key_Agreement_Key& private_key,
326 const ECIES_System_Params& ecies_params,
328
329 /// Set the initialization vector for the data encryption method
330 void set_initialization_vector(const InitializationVector& iv) { m_iv = iv; }
331
332 /// Set the label which is appended to the input for the message authentication code
333 void set_label(std::string_view label) { m_label = std::vector<uint8_t>(label.begin(), label.end()); }
334
335 private:
336 secure_vector<uint8_t> do_decrypt(uint8_t& valid_mask, const uint8_t in[], size_t in_len) const override;
337
338 size_t plaintext_length(size_t ctext_len) const override;
339
340 const ECIES_KA_Operation m_ka;
341 const ECIES_System_Params m_params;
342 std::unique_ptr<MessageAuthenticationCode> m_mac;
343 std::unique_ptr<Cipher_Mode> m_cipher;
345 std::vector<uint8_t> m_label;
346};
347
348} // namespace Botan
349
350#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:333
void set_initialization_vector(const InitializationVector &iv)
Set the initialization vector for the data encryption method.
Definition ecies.h:330
ECIES_Decryptor(const PK_Key_Agreement_Key &private_key, const ECIES_System_Params &ecies_params, RandomNumberGenerator &rng)
Definition ecies.cpp:351
void set_other_key(const EC_AffinePoint &pt)
Set the public key of the other party.
Definition ecies.h:290
ECIES_Encryptor(const PK_Key_Agreement_Key &private_key, const ECIES_System_Params &ecies_params, RandomNumberGenerator &rng)
Definition ecies.cpp:278
void set_initialization_vector(const InitializationVector &iv)
Set the initialization vector for the data encryption method.
Definition ecies.h:293
void set_label(std::string_view label)
Set the label which is appended to the input for the message authentication code.
Definition ecies.h:296
ECIES_KA_Operation(const PK_Key_Agreement_Key &private_key, const ECIES_KA_Params &ecies_params, bool for_encryption, RandomNumberGenerator &rng)
Definition ecies.cpp:126
SymmetricKey derive_secret(std::span< const uint8_t > eph_public_key_bin, const EC_AffinePoint &other_public_key_point) const
Definition ecies.cpp:175
ECIES_KA_Params(const ECIES_KA_Params &)=default
bool check_mode() const
Definition ecies.h:130
size_t secret_length() const
Definition ecies.h:119
bool old_cofactor_mode() const
Definition ecies.h:127
ECIES_KA_Params(const EC_Group &group, std::string_view kdf_spec, size_t length, EC_Point_Format point_format=EC_Point_Format::Uncompressed, bool single_hash_mode=true)
Definition ecies.cpp:223
EC_Point_Format compression_type() const
Definition ecies.h:140
bool cofactor_mode() const
Definition ecies.h:124
virtual ~ECIES_KA_Params()=default
bool single_hash_mode() const
Definition ecies.h:121
const std::string & kdf_spec() const
Definition ecies.h:136
const EC_Group & group() const
Definition ecies.h:117
const std::string & kdf() const
Definition ecies.h:134
const EC_Group & domain() const
Definition ecies.h:138
EC_Point_Format point_format() const
Definition ecies.h:132
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:209
size_t mac_keylen() const
returns the length of the key used by the message authentication code
Definition ecies.h:212
std::unique_ptr< Cipher_Mode > create_cipher(Cipher_Dir direction) const
creates an instance of the data encryption method
Definition ecies.cpp:271
std::unique_ptr< MessageAuthenticationCode > create_mac() const
creates an instance of the message authentication code
Definition ecies.cpp:267
ECIES_System_Params & operator=(const ECIES_System_Params &)=delete
ECIES_System_Params(const EC_Group &group, std::string_view kdf_spec, std::string_view dem_algo_spec, size_t dem_key_len, std::string_view mac_spec, size_t mac_key_len, EC_Point_Format point_format=EC_Point_Format::Uncompressed, bool single_hash_mode=false)
Definition ecies.cpp:253
PK_Decryptor()=default
PK_Encryptor()=default
ASN1_Type operator|(ASN1_Type x, ASN1_Type y)
Definition asn1_obj.h:75
OctetString SymmetricKey
Definition symkey.h:140
OctetString InitializationVector
Definition symkey.h:145
ECIES_Flags
Definition ecies.h:44
@ SingleHashMode
if set: prefix the input of the (ecdh) key agreement with the encoded (ephemeral) public key
Definition ecies.h:47
std::vector< T, secure_allocator< T > > secure_vector
Definition secmem.h:65
@ NONE
Definition filter.h:164
ECIES_Flags operator&(ECIES_Flags a, ECIES_Flags b)
Definition ecies.h:70