Botan 2.1.0 Crypto and TLS for C++11

- Main Page
- Namespaces
- Classes
- Files

- File List
- File Members

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/kdf.h>
14 #include <botan/cipher_mode.h>
15 #include <botan/mac.h>
16 #include <botan/point_gfp.h>
17 #include <botan/pubkey.h>
18 #include <botan/secmem.h>
19 #include <botan/symkey.h>
20 #include <memory>
21 #include <string>
22 #include <vector>
23
24 namespace Botan {
25
26 class RandomNumberGenerator;
27
28 enum class ECIES_Flags : uint32_t
29 {
30 NONE = 0,
31
32 /// if set: prefix the input of the (ecdh) key agreement with the encoded (ephemeral) public key
33 SINGLE_HASH_MODE = 1,
34
35 /// (decryption only) if set: use cofactor multiplication during (ecdh) key agreement
36 COFACTOR_MODE = 2,
37
38 /// if set: use ecdhc instead of ecdh
39 OLD_COFACTOR_MODE = 4,
40
41 /// (decryption only) if set: test if the (ephemeral) public key is on the curve
42 CHECK_MODE = 8
43 };
44
45 inline ECIES_Flags operator |(ECIES_Flags a, ECIES_Flags b)
46 {
47 return static_cast<ECIES_Flags>(static_cast<uint32_t>(a) | static_cast<uint32_t>(b));
48 }
49
50 inline ECIES_Flags operator &(ECIES_Flags a, ECIES_Flags b)
51 {
52 return static_cast<ECIES_Flags>(static_cast<uint32_t>(a) & static_cast<uint32_t>(b));
53 }
54
55 /**
56 * Parameters for ECIES secret derivation
57 */
58 class BOTAN_DLL ECIES_KA_Params
59 {
60 public:
61 /**
62 * @param domain ec domain parameters of the involved ec keys
63 * @param kdf_spec name of the key derivation function
64 * @param length length of the secret to be derived
65 * @param compression_type format of encoded keys (affects the secret derivation if single_hash_mode is used)
66 * @param flags options, see documentation of ECIES_Flags
67 */
68 ECIES_KA_Params(const EC_Group& domain, const std::string& kdf_spec, size_t length,
69 PointGFp::Compression_Type compression_type, ECIES_Flags flags);
70
71 ECIES_KA_Params(const ECIES_KA_Params&) = default;
72 ECIES_KA_Params& operator=(const ECIES_KA_Params&) = default;
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 {
87 return (m_flags & ECIES_Flags::SINGLE_HASH_MODE) == ECIES_Flags::SINGLE_HASH_MODE;
88 }
89
90 inline bool cofactor_mode() const
91 {
92 return (m_flags & ECIES_Flags::COFACTOR_MODE) == ECIES_Flags::COFACTOR_MODE;
93 }
94
95 inline bool old_cofactor_mode() const
96 {
97 return (m_flags & ECIES_Flags::OLD_COFACTOR_MODE) == ECIES_Flags::OLD_COFACTOR_MODE;
98 }
99
100 inline bool check_mode() const
101 {
102 return (m_flags & ECIES_Flags::CHECK_MODE) == ECIES_Flags::CHECK_MODE;
103 }
104
105 inline PointGFp::Compression_Type compression_type() const
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
124 class BOTAN_DLL ECIES_System_Params : public ECIES_KA_Params
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,
150 PointGFp::Compression_Type compression_type, ECIES_Flags flags);
151
152 ECIES_System_Params(const ECIES_System_Params&) = default;
153 ECIES_System_Params& operator=(const ECIES_System_Params&) = default;
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 */
185 class BOTAN_DLL ECIES_KA_Operation
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,
198 RandomNumberGenerator& rng);
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 */
217 class BOTAN_DLL ECIES_Encryptor : public PK_Encryptor
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,
227 RandomNumberGenerator& rng);
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 */
234 ECIES_Encryptor(RandomNumberGenerator& rng, const ECIES_System_Params& ecies_params);
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
243 inline void set_initialization_vector(const InitializationVector& iv)
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 inline size_t maximum_input_size() const override
258 {
259 return std::numeric_limits<size_t>::max();
260 }
261
262 const ECIES_KA_Operation m_ka;
263 const ECIES_System_Params m_params;
264 std::vector<uint8_t> m_eph_public_key_bin;
265 InitializationVector m_iv;
266 PointGFp m_other_point;
267 std::vector<uint8_t> m_label;
268 };
269
270
271 /**
272 * ECIES Decryption according to ISO 18033-2
273 */
274 class BOTAN_DLL ECIES_Decryptor : public PK_Decryptor
275 {
276 public:
277 /**
278 * @param private_key the private key which is used for the key agreement
279 * @param ecies_params settings for ecies
280 * @param rng the random generator to use
281 */
282 ECIES_Decryptor(const PK_Key_Agreement_Key& private_key,
283 const ECIES_System_Params& ecies_params,
284 RandomNumberGenerator& rng);
285
286 /// Set the initialization vector for the data encryption method
287 inline void set_initialization_vector(const InitializationVector& iv)
288 {
289 m_iv = iv;
290 }
291
292 /// Set the label which is appended to the input for the message authentication code
293 inline void set_label(const std::string& label)
294 {
295 m_label = std::vector<uint8_t>(label.begin(), label.end());
296 }
297
298 private:
299 secure_vector<uint8_t> do_decrypt(uint8_t& valid_mask, const uint8_t in[], size_t in_len) const override;
300
301 const ECIES_KA_Operation m_ka;
302 const ECIES_System_Params m_params;
303 InitializationVector m_iv;
304 std::vector<uint8_t> m_label;
305 };
306
307 }
308
309 #endif
Botan::InitializationVector
OctetString InitializationVector
Definition: symkey.h:141
Botan::ECIES_System_Params
Definition: ecies.h:124
Botan::ECIES_Decryptor::set_initialization_vector
void set_initialization_vector(const InitializationVector &iv)
Set the initialization vector for the data encryption method.
Definition: ecies.h:287
Botan::OctetString
Definition: symkey.h:19
Botan::ECIES_Flags
ECIES_Flags
Definition: ecies.h:28
Botan::PointGFp
Definition: point_gfp.h:41
Botan::RandomNumberGenerator
Definition: rng.h:25
Botan::ECIES_Flags::CHECK_MODE
(decryption only) if set: test if the (ephemeral) public key is on the curve
Botan::PKCS11::flags
Flags flags(Flag flags)
Definition: p11.h:858
Botan::ECIES_Flags::SINGLE_HASH_MODE
if set: prefix the input of the (ecdh) key agreement with the encoded (ephemeral) public key ...
Botan::ECIES_System_Params::dem_keylen
size_t dem_keylen() const
returns the length of the key used by the data encryption method
Definition: ecies.h:163
Botan::ECIES_KA_Params::single_hash_mode
bool single_hash_mode() const
Definition: ecies.h:85
Botan::ECIES_Flags::NONE
Botan::PointGFp::Compression_Type
Compression_Type
Definition: point_gfp.h:44
Botan::ECIES_KA_Params::domain
const EC_Group & domain() const
Definition: ecies.h:75
Botan::ECIES_Encryptor::set_initialization_vector
void set_initialization_vector(const InitializationVector &iv)
Set the initialization vector for the data encryption method.
Definition: ecies.h:243
Botan::ECIES_KA_Params::check_mode
bool check_mode() const
Definition: ecies.h:100
Botan::secure_vector
std::vector< T, secure_allocator< T >> secure_vector
Definition: secmem.h:121
Botan::ECIES_KA_Params::secret_length
size_t secret_length() const
Definition: ecies.h:80
Botan::ECIES_Encryptor::set_label
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
Botan::ECIES_KA_Operation
Definition: ecies.h:185
Botan::operator&
ECIES_Flags operator&(ECIES_Flags a, ECIES_Flags b)
Definition: ecies.h:50
Botan::ECIES_System_Params::mac_keylen
size_t mac_keylen() const
returns the length of the key used by the message authentication code
Definition: ecies.h:169
Botan
Definition: alg_id.cpp:13
Botan::ECIES_KA_Params::cofactor_mode
bool cofactor_mode() const
Definition: ecies.h:90
Botan::ECIES_Flags::OLD_COFACTOR_MODE
if set: use ecdhc instead of ecdh
Botan::ECIES_Encryptor
Definition: ecies.h:217
Botan::ECIES_Flags::COFACTOR_MODE
(decryption only) if set: use cofactor multiplication during (ecdh) key agreement ...
Botan::CT::max
T max(T a, T b)
Definition: ct_utils.h:173
Botan::EC_Group
Definition: ec_group.h:31
Botan::PK_Key_Agreement
Definition: pubkey.h:400
Botan::PK_Key_Agreement_Key
Definition: pk_keys.h:271
Botan::ECIES_KA_Params::kdf_spec
const std::string & kdf_spec() const
Definition: ecies.h:110
Botan::ECIES_KA_Params
Definition: ecies.h:58
Botan::ECIES_KA_Params::compression_type
PointGFp::Compression_Type compression_type() const
Definition: ecies.h:105
Botan::Cipher_Dir
Cipher_Dir
Definition: cipher_mode.h:212
Botan::ECIES_Encryptor::set_other_key
void set_other_key(const Botan::PointGFp &public_point)
Set the public key of the other party.
Definition: ecies.h:237
Botan::ECIES_Decryptor::set_label
void set_label(const std::string &label)
Set the label which is appended to the input for the message authentication code. ...
Definition: ecies.h:293
Botan::ECIES_Decryptor
Definition: ecies.h:274
Botan::PK_Decryptor
Definition: pubkey.h:85
Botan::operator|
ECIES_Flags operator|(ECIES_Flags a, ECIES_Flags b)
Definition: ecies.h:45
Botan::PK_Encryptor
Definition: pubkey.h:35
Botan::ECIES_KA_Params::old_cofactor_mode
bool old_cofactor_mode() const
Definition: ecies.h:95