Botan  2.7.0
Crypto and TLS for C++11
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 <memory>
19 #include <string>
20 #include <vector>
21 #include <limits>
22 
23 namespace Botan {
24 
25 class MessageAuthenticationCode;
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
40 
41  /// (decryption only) if set: test if the (ephemeral) public key is on the curve
42  CHECK_MODE = 8
43  };
44 
46  {
47  return static_cast<ECIES_Flags>(static_cast<uint32_t>(a) | static_cast<uint32_t>(b));
48  }
49 
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 */
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  {
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  {
102  return (m_flags & ECIES_Flags::CHECK_MODE) == ECIES_Flags::CHECK_MODE;
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,
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 */
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 */
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
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;
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 */
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
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;
304  std::vector<uint8_t> m_label;
305  };
306 
307 }
308 
309 #endif
ECIES_Flags operator&(ECIES_Flags a, ECIES_Flags b)
Definition: ecies.h:50
OctetString InitializationVector
Definition: symkey.h:141
void set_initialization_vector(const InitializationVector &iv)
Set the initialization vector for the data encryption method.
Definition: ecies.h:287
ECIES_Flags
Definition: ecies.h:28
bool check_mode() const
Definition: ecies.h:100
PointGFp::Compression_Type compression_type() const
Definition: ecies.h:105
(decryption only) if set: test if the (ephemeral) public key is on the curve
#define BOTAN_PUBLIC_API(maj, min)
Definition: compiler.h:27
Flags flags(Flag flags)
Definition: p11.h:858
size_t dem_keylen() const
returns the length of the key used by the data encryption method
Definition: ecies.h:163
if set: prefix the input of the (ecdh) key agreement with the encoded (ephemeral) public key ...
const std::string & kdf_spec() const
Definition: ecies.h:110
void set_initialization_vector(const InitializationVector &iv)
Set the initialization vector for the data encryption method.
Definition: ecies.h:243
bool single_hash_mode() const
Definition: ecies.h:85
bool cofactor_mode() const
Definition: ecies.h:90
size_t mac_keylen() const
returns the length of the key used by the message authentication code
Definition: ecies.h:169
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
Definition: alg_id.cpp:13
if set: use ecdhc instead of ecdh
(decryption only) if set: use cofactor multiplication during (ecdh) key agreement ...
bool old_cofactor_mode() const
Definition: ecies.h:95
const EC_Group & domain() const
Definition: ecies.h:75
Cipher_Dir
Definition: cipher_mode.h:24
std::vector< T, secure_allocator< T > > secure_vector
Definition: secmem.h:88
void set_other_key(const Botan::PointGFp &public_point)
Set the public key of the other party.
Definition: ecies.h:237
size_t secret_length() const
Definition: ecies.h:80
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
ECIES_Flags operator|(ECIES_Flags a, ECIES_Flags b)
Definition: ecies.h:45