Botan  2.8.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 <botan/mac.h>
19 #include <memory>
20 #include <string>
21 #include <vector>
22 
23 namespace Botan {
24 
25 class RandomNumberGenerator;
26 
27 enum 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
32  SINGLE_HASH_MODE = 1,
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,
68  PointGFp::Compression_Type compression_type, ECIES_Flags flags);
69 
70  ECIES_KA_Params(const ECIES_KA_Params&) = default;
71  ECIES_KA_Params& operator=(const ECIES_KA_Params&) = default;
72  virtual ~ECIES_KA_Params() = default;
73 
74  inline const EC_Group& domain() const
75  {
76  return m_domain;
77  }
78 
79  inline size_t secret_length() const
80  {
81  return m_length;
82  }
83 
84  inline bool single_hash_mode() const
85  {
87  }
88 
89  inline bool cofactor_mode() const
90  {
92  }
93 
94  inline bool old_cofactor_mode() const
95  {
97  }
98 
99  inline bool check_mode() const
100  {
101  return (m_flags & ECIES_Flags::CHECK_MODE) == ECIES_Flags::CHECK_MODE;
102  }
103 
105  {
106  return m_compression_mode;
107  }
108 
109  const std::string& kdf_spec() const
110  {
111  return m_kdf_spec;
112  }
113 
114  private:
115  const EC_Group m_domain;
116  const std::string m_kdf_spec;
117  const size_t m_length;
118  const PointGFp::Compression_Type m_compression_mode;
119  const ECIES_Flags m_flags;
120  };
121 
122 
124  {
125  public:
126  /**
127  * @param domain ec domain parameters of the involved ec keys
128  * @param kdf_spec name of the key derivation function
129  * @param dem_algo_spec name of the data encryption method
130  * @param dem_key_len length of the key used for the data encryption method
131  * @param mac_spec name of the message authentication code
132  * @param mac_key_len length of the key used for the message authentication code
133  */
134  ECIES_System_Params(const EC_Group& domain, const std::string& kdf_spec, const std::string& dem_algo_spec,
135  size_t dem_key_len, const std::string& mac_spec, size_t mac_key_len);
136 
137  /**
138  * @param domain ec domain parameters of the involved ec keys
139  * @param kdf_spec name of the key derivation function
140  * @param dem_algo_spec name of the data encryption method
141  * @param dem_key_len length of the key used for the data encryption method
142  * @param mac_spec name of the message authentication code
143  * @param mac_key_len length of the key used for the message authentication code
144  * @param compression_type format of encoded keys (affects the secret derivation if single_hash_mode is used)
145  * @param flags options, see documentation of ECIES_Flags
146  */
147  ECIES_System_Params(const EC_Group& domain, const std::string& kdf_spec, const std::string& dem_algo_spec,
148  size_t dem_key_len, const std::string& mac_spec, size_t mac_key_len,
149  PointGFp::Compression_Type compression_type, ECIES_Flags flags);
150 
151  ECIES_System_Params(const ECIES_System_Params&) = default;
152  ECIES_System_Params& operator=(const ECIES_System_Params&) = default;
153  virtual ~ECIES_System_Params() = default;
154 
155  /// creates an instance of the message authentication code
156  std::unique_ptr<MessageAuthenticationCode> create_mac() const;
157 
158  /// creates an instance of the data encryption method
159  std::unique_ptr<Cipher_Mode> create_cipher(Botan::Cipher_Dir direction) const;
160 
161  /// returns the length of the key used by the data encryption method
162  inline size_t dem_keylen() const
163  {
164  return m_dem_keylen;
165  }
166 
167  /// returns the length of the key used by the message authentication code
168  inline size_t mac_keylen() const
169  {
170  return m_mac_keylen;
171  }
172 
173  private:
174  const std::string m_dem_spec;
175  const size_t m_dem_keylen;
176  const std::string m_mac_spec;
177  const size_t m_mac_keylen;
178  };
179 
180 
181 /**
182 * ECIES secret derivation according to ISO 18033-2
183 */
185  {
186  public:
187  /**
188  * @param private_key the (ephemeral) private key which is used to derive the secret
189  * @param ecies_params settings for ecies
190  * @param for_encryption disable cofactor mode if the secret will be used for encryption
191  * (according to ISO 18033 cofactor mode is only used during decryption)
192  * @param rng the RNG to use
193  */
194  ECIES_KA_Operation(const PK_Key_Agreement_Key& private_key,
195  const ECIES_KA_Params& ecies_params,
196  bool for_encryption,
197  RandomNumberGenerator& rng);
198 
199  /**
200  * Performs a key agreement with the provided keys and derives the secret from the result
201  * @param eph_public_key_bin the encoded (ephemeral) public key which belongs to the used (ephemeral) private key
202  * @param other_public_key_point public key point of the other party
203  */
204  SymmetricKey derive_secret(const std::vector<uint8_t>& eph_public_key_bin,
205  const PointGFp& other_public_key_point) const;
206 
207  private:
208  const PK_Key_Agreement m_ka;
209  const ECIES_KA_Params m_params;
210  };
211 
212 
213 /**
214 * ECIES Encryption according to ISO 18033-2
215 */
217  {
218  public:
219  /**
220  * @param private_key the (ephemeral) private key which is used for the key agreement
221  * @param ecies_params settings for ecies
222  * @param rng random generator to use
223  */
224  ECIES_Encryptor(const PK_Key_Agreement_Key& private_key,
225  const ECIES_System_Params& ecies_params,
226  RandomNumberGenerator& rng);
227 
228  /**
229  * Creates an ephemeral private key which is used for the key agreement
230  * @param rng random generator used during private key generation
231  * @param ecies_params settings for ecies
232  */
233  ECIES_Encryptor(RandomNumberGenerator& rng, const ECIES_System_Params& ecies_params);
234 
235  /// Set the public key of the other party
236  inline void set_other_key(const Botan::PointGFp& public_point)
237  {
238  m_other_point = public_point;
239  }
240 
241  /// Set the initialization vector for the data encryption method
243  {
244  m_iv = iv;
245  }
246 
247  /// Set the label which is appended to the input for the message authentication code
248  inline void set_label(const std::string& label)
249  {
250  m_label = std::vector<uint8_t>(label.begin(), label.end());
251  }
252 
253  private:
254  std::vector<uint8_t> enc(const uint8_t data[], size_t length, RandomNumberGenerator&) const override;
255 
256  size_t maximum_input_size() const override;
257 
258  size_t ciphertext_length(size_t ptext_len) const override;
259 
260  const ECIES_KA_Operation m_ka;
261  const ECIES_System_Params m_params;
262  std::unique_ptr<MessageAuthenticationCode> m_mac;
263  std::unique_ptr<Cipher_Mode> m_cipher;
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  size_t plaintext_length(size_t ctext_len) const override;
302 
303  const ECIES_KA_Operation m_ka;
304  const ECIES_System_Params m_params;
305  std::unique_ptr<MessageAuthenticationCode> m_mac;
306  std::unique_ptr<Cipher_Mode> m_cipher;
308  std::vector<uint8_t> m_label;
309  };
310 
311 }
312 
313 #endif
ECIES_Flags operator&(ECIES_Flags a, ECIES_Flags b)
Definition: ecies.h:49
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:27
bool check_mode() const
Definition: ecies.h:99
PointGFp::Compression_Type compression_type() const
Definition: ecies.h:104
(decryption only) if set: test if the (ephemeral) public key is on the curve
int(* final)(unsigned char *, CTX *)
#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:162
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:109
void set_initialization_vector(const InitializationVector &iv)
Set the initialization vector for the data encryption method.
Definition: ecies.h:242
bool single_hash_mode() const
Definition: ecies.h:84
bool cofactor_mode() const
Definition: ecies.h:89
size_t mac_keylen() const
returns the length of the key used by the message authentication code
Definition: ecies.h:168
void set_label(const std::string &label)
Set the label which is appended to the input for the message authentication code. ...
Definition: ecies.h:248
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:94
const EC_Group & domain() const
Definition: ecies.h:74
Cipher_Dir
Definition: cipher_mode.h:23
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:236
size_t secret_length() const
Definition: ecies.h:79
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:44