Botan 3.3.0
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/cipher_mode.h>
12#include <botan/ec_group.h>
13#include <botan/ec_point.h>
14#include <botan/ecdh.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 <string>
21#include <vector>
22
23namespace Botan {
24
25class RandomNumberGenerator;
26
27enum class ECIES_Flags : uint32_t {
28 None = 0,
29 /// if set: prefix the input of the (ecdh) key agreement with the encoded (ephemeral) public key
31 /// (decryption only) if set: use cofactor multiplication during (ecdh) key agreement
32 CofactorMode = 2,
33 /// if set: use ecdhc instead of ecdh
35 /// (decryption only) if set: test if the (ephemeral) public key is on the curve
36 CheckMode = 8,
37
38 NONE BOTAN_DEPRECATED("Use None") = None,
39 SINGLE_HASH_MODE BOTAN_DEPRECATED("Use SingleHashMode") = SingleHashMode,
40 COFACTOR_MODE BOTAN_DEPRECATED("Use CofactorMode") = CofactorMode,
41 OLD_COFACTOR_MODE BOTAN_DEPRECATED("Use OldCofactorMode") = OldCofactorMode,
42 CHECK_MODE BOTAN_DEPRECATED("Use CheckMode") = CheckMode,
43};
44
46 return static_cast<ECIES_Flags>(static_cast<uint32_t>(a) | static_cast<uint32_t>(b));
47}
48
50 return static_cast<ECIES_Flags>(static_cast<uint32_t>(a) & static_cast<uint32_t>(b));
51}
52
53/**
54* Parameters for ECIES secret derivation
55*/
57 public:
58 /**
59 * @param domain ec domain parameters of the involved ec keys
60 * @param kdf_spec name of the key derivation function
61 * @param length length of the secret to be derived
62 * @param compression_type format of encoded keys (affects the secret derivation if single_hash_mode is used)
63 * @param flags options, see documentation of ECIES_Flags
64 */
65 ECIES_KA_Params(const EC_Group& domain,
66 std::string_view kdf_spec,
67 size_t length,
68 EC_Point_Format compression_type,
69 ECIES_Flags flags);
70
73
74 virtual ~ECIES_KA_Params() = default;
75
76 inline const EC_Group& domain() const { return m_domain; }
77
78 inline size_t secret_length() const { return m_length; }
79
80 inline bool single_hash_mode() const {
81 return (m_flags & ECIES_Flags::SingleHashMode) == ECIES_Flags::SingleHashMode;
82 }
83
84 inline bool cofactor_mode() const { return (m_flags & ECIES_Flags::CofactorMode) == ECIES_Flags::CofactorMode; }
85
86 inline bool old_cofactor_mode() const {
87 return (m_flags & ECIES_Flags::OldCofactorMode) == ECIES_Flags::OldCofactorMode;
88 }
89
90 inline bool check_mode() const { return (m_flags & ECIES_Flags::CheckMode) == ECIES_Flags::CheckMode; }
91
92 inline EC_Point_Format compression_type() const { return m_compression_mode; }
93
94 const std::string& kdf_spec() const { return m_kdf_spec; }
95
96 private:
97 const EC_Group m_domain;
98 const std::string m_kdf_spec;
99 const size_t m_length;
100 const EC_Point_Format m_compression_mode;
101 const ECIES_Flags m_flags;
102};
103
105 public:
106 /**
107 * @param domain ec domain parameters of the involved ec keys
108 * @param kdf_spec name of the key derivation function
109 * @param dem_algo_spec name of the data encryption method
110 * @param dem_key_len length of the key used for the data encryption method
111 * @param mac_spec name of the message authentication code
112 * @param mac_key_len length of the key used for the message authentication code
113 */
114 ECIES_System_Params(const EC_Group& domain,
115 std::string_view kdf_spec,
116 std::string_view dem_algo_spec,
117 size_t dem_key_len,
118 std::string_view mac_spec,
119 size_t mac_key_len);
120
121 /**
122 * @param domain ec domain parameters of the involved ec keys
123 * @param kdf_spec name of the key derivation function
124 * @param dem_algo_spec name of the data encryption method
125 * @param dem_key_len length of the key used for the data encryption method
126 * @param mac_spec name of the message authentication code
127 * @param mac_key_len length of the key used for the message authentication code
128 * @param compression_type format of encoded keys (affects the secret derivation if single_hash_mode is used)
129 * @param flags options, see documentation of ECIES_Flags
130 */
131 ECIES_System_Params(const EC_Group& domain,
132 std::string_view kdf_spec,
133 std::string_view dem_algo_spec,
134 size_t dem_key_len,
135 std::string_view mac_spec,
136 size_t mac_key_len,
137 EC_Point_Format compression_type,
138 ECIES_Flags flags);
139
142 ~ECIES_System_Params() override = default;
143
144 /// creates an instance of the message authentication code
145 std::unique_ptr<MessageAuthenticationCode> create_mac() const;
146
147 /// creates an instance of the data encryption method
148 std::unique_ptr<Cipher_Mode> create_cipher(Cipher_Dir direction) const;
149
150 /// returns the length of the key used by the data encryption method
151 inline size_t dem_keylen() const { return m_dem_keylen; }
152
153 /// returns the length of the key used by the message authentication code
154 inline size_t mac_keylen() const { return m_mac_keylen; }
155
156 private:
157 const std::string m_dem_spec;
158 const size_t m_dem_keylen;
159 const std::string m_mac_spec;
160 const size_t m_mac_keylen;
161};
162
163/**
164* ECIES secret derivation according to ISO 18033-2
165*/
167 public:
168 /**
169 * @param private_key the (ephemeral) private key which is used to derive the secret
170 * @param ecies_params settings for ecies
171 * @param for_encryption disable cofactor mode if the secret will be used for encryption
172 * (according to ISO 18033 cofactor mode is only used during decryption)
173 * @param rng the RNG to use
174 */
175 ECIES_KA_Operation(const PK_Key_Agreement_Key& private_key,
176 const ECIES_KA_Params& ecies_params,
177 bool for_encryption,
179
180 /**
181 * Performs a key agreement with the provided keys and derives the secret from the result
182 * @param eph_public_key_bin the encoded (ephemeral) public key which belongs to the used (ephemeral) private key
183 * @param other_public_key_point public key point of the other party
184 */
185 SymmetricKey derive_secret(const std::vector<uint8_t>& eph_public_key_bin,
186 const EC_Point& other_public_key_point) const;
187
188 private:
189 const PK_Key_Agreement m_ka;
190 const ECIES_KA_Params m_params;
191};
192
193/**
194* ECIES Encryption according to ISO 18033-2
195*/
197 public:
198 /**
199 * @param private_key the (ephemeral) private key which is used for the key agreement
200 * @param ecies_params settings for ecies
201 * @param rng random generator to use
202 */
203 ECIES_Encryptor(const PK_Key_Agreement_Key& private_key,
204 const ECIES_System_Params& ecies_params,
206
207 /**
208 * Creates an ephemeral private key which is used for the key agreement
209 * @param rng random generator used during private key generation
210 * @param ecies_params settings for ecies
211 */
213
214 /// Set the public key of the other party
215 inline void set_other_key(const EC_Point& public_point) { m_other_point = public_point; }
216
217 /// Set the initialization vector for the data encryption method
218 inline void set_initialization_vector(const InitializationVector& iv) { m_iv = iv; }
219
220 /// Set the label which is appended to the input for the message authentication code
221 inline void set_label(std::string_view label) { m_label = std::vector<uint8_t>(label.begin(), label.end()); }
222
223 private:
224 std::vector<uint8_t> enc(const uint8_t data[], size_t length, RandomNumberGenerator&) const override;
225
226 size_t maximum_input_size() const override;
227
228 size_t ciphertext_length(size_t ptext_len) const override;
229
230 const ECIES_KA_Operation m_ka;
231 const ECIES_System_Params m_params;
232 std::unique_ptr<MessageAuthenticationCode> m_mac;
233 std::unique_ptr<Cipher_Mode> m_cipher;
234 std::vector<uint8_t> m_eph_public_key_bin;
236 EC_Point m_other_point;
237 std::vector<uint8_t> m_label;
238};
239
240/**
241* ECIES Decryption according to ISO 18033-2
242*/
244 public:
245 /**
246 * @param private_key the private key which is used for the key agreement
247 * @param ecies_params settings for ecies
248 * @param rng the random generator to use
249 */
250 ECIES_Decryptor(const PK_Key_Agreement_Key& private_key,
251 const ECIES_System_Params& ecies_params,
253
254 /// Set the initialization vector for the data encryption method
255 inline void set_initialization_vector(const InitializationVector& iv) { m_iv = iv; }
256
257 /// Set the label which is appended to the input for the message authentication code
258 inline void set_label(std::string_view label) { m_label = std::vector<uint8_t>(label.begin(), label.end()); }
259
260 private:
261 secure_vector<uint8_t> do_decrypt(uint8_t& valid_mask, const uint8_t in[], size_t in_len) const override;
262
263 size_t plaintext_length(size_t ctext_len) const override;
264
265 const ECIES_KA_Operation m_ka;
266 const ECIES_System_Params m_params;
267 std::unique_ptr<MessageAuthenticationCode> m_mac;
268 std::unique_ptr<Cipher_Mode> m_cipher;
270 std::vector<uint8_t> m_label;
271};
272
273} // namespace Botan
274
275#endif
void set_label(std::string_view label)
Set the label which is appended to the input for the message authentication code.
Definition ecies.h:258
void set_initialization_vector(const InitializationVector &iv)
Set the initialization vector for the data encryption method.
Definition ecies.h:255
void set_other_key(const EC_Point &public_point)
Set the public key of the other party.
Definition ecies.h:215
void set_initialization_vector(const InitializationVector &iv)
Set the initialization vector for the data encryption method.
Definition ecies.h:218
void set_label(std::string_view label)
Set the label which is appended to the input for the message authentication code.
Definition ecies.h:221
ECIES_KA_Params(const ECIES_KA_Params &)=default
bool check_mode() const
Definition ecies.h:90
size_t secret_length() const
Definition ecies.h:78
bool old_cofactor_mode() const
Definition ecies.h:86
EC_Point_Format compression_type() const
Definition ecies.h:92
bool cofactor_mode() const
Definition ecies.h:84
virtual ~ECIES_KA_Params()=default
bool single_hash_mode() const
Definition ecies.h:80
const std::string & kdf_spec() const
Definition ecies.h:94
const EC_Group & domain() const
Definition ecies.h:76
ECIES_KA_Params & operator=(const ECIES_KA_Params &)=delete
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:151
size_t mac_keylen() const
returns the length of the key used by the message authentication code
Definition ecies.h:154
ECIES_System_Params & operator=(const ECIES_System_Params &)=delete
int(* final)(unsigned char *, CTX *)
#define BOTAN_PUBLIC_API(maj, min)
Definition compiler.h:31
#define BOTAN_DEPRECATED(msg)
Definition compiler.h:125
ASN1_Type operator|(ASN1_Type x, ASN1_Type y)
Definition asn1_obj.h:74
EC_Point_Format
Definition ec_point.h:19
ECIES_Flags
Definition ecies.h:27
@ CofactorMode
(decryption only) if set: use cofactor multiplication during (ecdh) key agreement
@ OldCofactorMode
if set: use ecdhc instead of ecdh
@ CheckMode
(decryption only) if set: test if the (ephemeral) public key is on the curve
@ SingleHashMode
if set: prefix the input of the (ecdh) key agreement with the encoded (ephemeral) public key
std::vector< T, secure_allocator< T > > secure_vector
Definition secmem.h:61
@ NONE
Definition filter.h:165
ECIES_Flags operator&(ECIES_Flags a, ECIES_Flags b)
Definition ecies.h:49