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