Botan 3.9.0
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 : uint8_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
116
117 virtual ~ECIES_KA_Params() = default;
118
119 const EC_Group& group() const { return m_group; }
120
121 size_t secret_length() const { return m_length; }
122
123 bool single_hash_mode() const { return m_single_hash_mode; }
124
125 // TODO(Botan4) remove this when cofactor support is removed
126 bool cofactor_mode() const { return m_cofactor_mode; }
127
128 // TODO(Botan4) remove this when cofactor support is removed
129 bool old_cofactor_mode() const { return m_old_cofactor_mode; }
130
131 // TODO(Botan4) remove this when cofactor support is removed
132 bool check_mode() const { return m_check_mode; }
133
134 EC_Point_Format point_format() const { return m_point_format; }
135
136 const std::string& kdf() const { return m_kdf; }
137
138 BOTAN_DEPRECATED("Use kdf") const std::string& kdf_spec() const { return kdf(); }
139
140 BOTAN_DEPRECATED("Use group") const EC_Group& domain() const { return group(); }
141
142 BOTAN_DEPRECATED("Use point_format") EC_Point_Format compression_type() const { return point_format(); }
143
144 private:
145 const EC_Group m_group;
146 const std::string m_kdf;
147 const size_t m_length;
148 const EC_Point_Format m_point_format;
149 const bool m_single_hash_mode;
150 const bool m_check_mode; // TODO(Botan4) remove this field
151 const bool m_cofactor_mode; // TODO(Botan4) remove this field
152 const bool m_old_cofactor_mode; // TODO(Botan4) remove this field
153};
154
156 public:
157 /**
158 * @param group ec domain parameters of the involved ec keys
159 * @param kdf_spec name of the key derivation function
160 * @param dem_algo_spec name of the data encryption method
161 * @param dem_key_len length of the key used for the data encryption method
162 * @param mac_spec name of the message authentication code
163 * @param mac_key_len length of the key used for the message authentication code
164 */
166 std::string_view kdf_spec,
167 std::string_view dem_algo_spec,
168 size_t dem_key_len,
169 std::string_view mac_spec,
170 size_t mac_key_len,
172 bool single_hash_mode = false);
173
174 /**
175 * @param group ec domain parameters of the involved ec keys
176 * @param kdf_spec name of the key derivation function
177 * @param dem_algo_spec name of the data encryption method
178 * @param dem_key_len length of the key used for the data encryption method
179 * @param mac_spec name of the message authentication code
180 * @param mac_key_len length of the key used for the message authentication code
181 * @param point_format format of encoded keys (affects the secret derivation if single_hash_mode is used)
182 * @param flags options, see documentation of ECIES_Flags
183 *
184 * This constructor makes sense only if you are using the CofactorMode or
185 * OldCofactorMode flags. Support for cofactors in EC_Group is deprecated
186 * and will be removed in Botan4.
187 *
188 * TODO(Botan4) remove this constructor when cofactor support is removed
189 */
190 BOTAN_DEPRECATED("Prefer other constructor, see header comment")
192 std::string_view kdf_spec,
193 std::string_view dem_algo_spec,
194 size_t dem_key_len,
195 std::string_view mac_spec,
196 size_t mac_key_len,
198 ECIES_Flags flags);
199
204 ~ECIES_System_Params() override = default;
205
206 /// creates an instance of the message authentication code
207 std::unique_ptr<MessageAuthenticationCode> create_mac() const;
208
209 /// creates an instance of the data encryption method
210 std::unique_ptr<Cipher_Mode> create_cipher(Cipher_Dir direction) const;
211
212 /// returns the length of the key used by the data encryption method
213 size_t dem_keylen() const { return m_dem_keylen; }
214
215 /// returns the length of the key used by the message authentication code
216 size_t mac_keylen() const { return m_mac_keylen; }
217
218 private:
219 const std::string m_dem_spec;
220 const size_t m_dem_keylen;
221 const std::string m_mac_spec;
222 const size_t m_mac_keylen;
223};
224
225/**
226* ECIES secret derivation according to ISO 18033-2
227*/
229 public:
230 /**
231 * @param private_key the (ephemeral) private key which is used to derive the secret
232 * @param ecies_params settings for ecies
233 * @param for_encryption disable cofactor mode if the secret will be used for encryption
234 * (according to ISO 18033 cofactor mode is only used during decryption)
235 * @param rng the RNG to use
236 */
237 ECIES_KA_Operation(const PK_Key_Agreement_Key& private_key,
238 const ECIES_KA_Params& ecies_params,
239 bool for_encryption,
241
242#if defined(BOTAN_HAS_LEGACY_EC_POINT)
243 /**
244 * Performs a key agreement with the provided keys and derives the secret from the result
245 * @param eph_public_key_bin the encoded (ephemeral) public key which belongs to the used (ephemeral) private key
246 * @param other_public_key_point public key point of the other party
247 */
248 SymmetricKey derive_secret(const std::vector<uint8_t>& eph_public_key_bin,
249 const EC_Point& other_public_key_point) const;
250#endif
251
252 /**
253 * Performs a key agreement with the provided keys and derives the secret from the result
254 * @param eph_public_key_bin the encoded (ephemeral) public key which belongs to the used (ephemeral) private key
255 * @param other_public_key_point public key point of the other party
256 */
257 SymmetricKey derive_secret(std::span<const uint8_t> eph_public_key_bin,
258 const EC_AffinePoint& other_public_key_point) const;
259
260 private:
261 const PK_Key_Agreement m_ka;
262 const ECIES_KA_Params m_params;
263};
264
265/**
266* ECIES Encryption according to ISO 18033-2
267*/
269 public:
270 /**
271 * @param private_key the (ephemeral) private key which is used for the key agreement
272 * @param ecies_params settings for ecies
273 * @param rng random generator to use
274 */
275 ECIES_Encryptor(const PK_Key_Agreement_Key& private_key,
276 const ECIES_System_Params& ecies_params,
278
279 /**
280 * Creates an ephemeral private key which is used for the key agreement
281 * @param rng random generator used during private key generation
282 * @param ecies_params settings for ecies
283 */
285
286#if defined(BOTAN_HAS_LEGACY_EC_POINT)
287 /// Set the public key of the other party
288 void set_other_key(const EC_Point& public_point) {
289 m_other_point = EC_AffinePoint(m_params.group(), public_point);
290 }
291#endif
292
293 /// Set the public key of the other party
294 void set_other_key(const EC_AffinePoint& pt) { m_other_point = pt; }
295
296 /// Set the initialization vector for the data encryption method
297 void set_initialization_vector(const InitializationVector& iv) { m_iv = iv; }
298
299 /// Set the label which is appended to the input for the message authentication code
300 void set_label(std::string_view label) { m_label.assign(label.begin(), label.end()); }
301
302 private:
303 std::vector<uint8_t> enc(const uint8_t data[], size_t length, RandomNumberGenerator& rng) const override;
304
305 size_t maximum_input_size() const override;
306
307 size_t ciphertext_length(size_t ptext_len) const override;
308
309 const ECIES_KA_Operation m_ka;
310 const ECIES_System_Params m_params;
311 std::unique_ptr<MessageAuthenticationCode> m_mac;
312 std::unique_ptr<Cipher_Mode> m_cipher;
313 std::vector<uint8_t> m_eph_public_key_bin;
315 std::optional<EC_AffinePoint> m_other_point;
316 std::vector<uint8_t> m_label;
317};
318
319/**
320* ECIES Decryption according to ISO 18033-2
321*/
323 public:
324 /**
325 * @param private_key the private key which is used for the key agreement
326 * @param ecies_params settings for ecies
327 * @param rng the random generator to use
328 */
329 ECIES_Decryptor(const PK_Key_Agreement_Key& private_key,
330 const ECIES_System_Params& ecies_params,
332
333 /// Set the initialization vector for the data encryption method
334 void set_initialization_vector(const InitializationVector& iv) { m_iv = iv; }
335
336 /// Set the label which is appended to the input for the message authentication code
337 void set_label(std::string_view label) { m_label = std::vector<uint8_t>(label.begin(), label.end()); }
338
339 private:
340 secure_vector<uint8_t> do_decrypt(uint8_t& valid_mask, const uint8_t in[], size_t in_len) const override;
341
342 size_t plaintext_length(size_t ctext_len) const override;
343
344 const ECIES_KA_Operation m_ka;
345 const ECIES_System_Params m_params;
346 std::unique_ptr<MessageAuthenticationCode> m_mac;
347 std::unique_ptr<Cipher_Mode> m_cipher;
349 std::vector<uint8_t> m_label;
350};
351
352} // namespace Botan
353
354#endif
#define BOTAN_PUBLIC_API(maj, min)
Definition api.h:21
#define BOTAN_DEPRECATED(msg)
Definition api.h:73
void set_label(std::string_view label)
Set the label which is appended to the input for the message authentication code.
Definition ecies.h:337
void set_initialization_vector(const InitializationVector &iv)
Set the initialization vector for the data encryption method.
Definition ecies.h:334
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:294
ECIES_Encryptor(const PK_Key_Agreement_Key &private_key, const ECIES_System_Params &ecies_params, RandomNumberGenerator &rng)
Definition ecies.cpp:281
void set_initialization_vector(const InitializationVector &iv)
Set the initialization vector for the data encryption method.
Definition ecies.h:297
void set_label(std::string_view label)
Set the label which is appended to the input for the message authentication code.
Definition ecies.h:300
ECIES_KA_Operation(const PK_Key_Agreement_Key &private_key, const ECIES_KA_Params &ecies_params, bool for_encryption, RandomNumberGenerator &rng)
Definition ecies.cpp:129
SymmetricKey derive_secret(std::span< const uint8_t > eph_public_key_bin, const EC_AffinePoint &other_public_key_point) const
Definition ecies.cpp:178
ECIES_KA_Params(const ECIES_KA_Params &)=default
bool check_mode() const
Definition ecies.h:132
size_t secret_length() const
Definition ecies.h:121
bool old_cofactor_mode() const
Definition ecies.h:129
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:226
EC_Point_Format compression_type() const
Definition ecies.h:142
bool cofactor_mode() const
Definition ecies.h:126
virtual ~ECIES_KA_Params()=default
bool single_hash_mode() const
Definition ecies.h:123
const std::string & kdf_spec() const
Definition ecies.h:138
const EC_Group & group() const
Definition ecies.h:119
const std::string & kdf() const
Definition ecies.h:136
ECIES_KA_Params & operator=(ECIES_KA_Params &&)=delete
const EC_Group & domain() const
Definition ecies.h:140
EC_Point_Format point_format() const
Definition ecies.h:134
ECIES_KA_Params & operator=(const ECIES_KA_Params &)=delete
ECIES_KA_Params(ECIES_KA_Params &&)=default
ECIES_System_Params(ECIES_System_Params &&)=default
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:213
ECIES_System_Params & operator=(ECIES_System_Params &&)=delete
size_t mac_keylen() const
returns the length of the key used by the message authentication code
Definition ecies.h:216
std::unique_ptr< Cipher_Mode > create_cipher(Cipher_Dir direction) const
creates an instance of the data encryption method
Definition ecies.cpp:274
std::unique_ptr< MessageAuthenticationCode > create_mac() const
creates an instance of the message authentication code
Definition ecies.cpp:270
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:256
PK_Decryptor()=default
PK_Encryptor()=default
ASN1_Type operator|(ASN1_Type x, ASN1_Type y)
Definition asn1_obj.h:74
OctetString SymmetricKey
Definition symkey.h:140
@ NONE
Definition filter.h:167
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
OctetString InitializationVector
Definition symkey.h:145
std::vector< T, secure_allocator< T > > secure_vector
Definition secmem.h:69
ECIES_Flags operator&(ECIES_Flags a, ECIES_Flags b)
Definition ecies.h:70