Botan  2.7.0
Crypto and TLS for C++11
ec_group.h
Go to the documentation of this file.
1 /*
2 * ECC Domain Parameters
3 *
4 * (C) 2007 Falko Strenzke, FlexSecure GmbH
5 * 2008-2010 Jack Lloyd
6 *
7 * Botan is released under the Simplified BSD License (see license.txt)
8 */
9 
10 #ifndef BOTAN_ECC_DOMAIN_PARAMETERS_H_
11 #define BOTAN_ECC_DOMAIN_PARAMETERS_H_
12 
13 #include <botan/point_gfp.h>
14 #include <botan/asn1_oid.h>
15 #include <memory>
16 #include <set>
17 
18 namespace Botan {
19 
20 /**
21 * This class represents elliptic curce domain parameters
22 */
27 };
28 
29 class CurveGFp;
30 
31 class EC_Group_Data;
32 class EC_Group_Data_Map;
33 
34 /**
35 * Class representing an elliptic curve
36 *
37 * The internal representation is stored in a shared_ptr, so copying an
38 * EC_Group is inexpensive.
39 */
40 class BOTAN_PUBLIC_API(2,0) EC_Group final
41  {
42  public:
43 
44  /**
45  * Construct Domain paramers from specified parameters
46  * @param curve elliptic curve
47  * @param base_point a base point
48  * @param order the order of the base point
49  * @param cofactor the cofactor
50  */
51  BOTAN_DEPRECATED("Use version taking all BigInts")
52  EC_Group(const CurveGFp& curve,
53  const PointGFp& base_point,
54  const BigInt& order,
55  const BigInt& cofactor) :
56  EC_Group(curve.get_p(),
57  curve.get_a(),
58  curve.get_b(),
59  base_point.get_affine_x(),
60  base_point.get_affine_y(),
61  order,
62  cofactor) {}
63 
64  /**
65  * Construct Domain paramers from specified parameters
66  * @param p the elliptic curve p
67  * @param a the elliptic curve a param
68  * @param b the elliptic curve b param
69  * @param base_x the x coordinate of the base point
70  * @param base_y the y coordinate of the base point
71  * @param order the order of the base point
72  * @param cofactor the cofactor
73  * @param oid an optional OID used to identify this curve
74  */
75  EC_Group(const BigInt& p,
76  const BigInt& a,
77  const BigInt& b,
78  const BigInt& base_x,
79  const BigInt& base_y,
80  const BigInt& order,
81  const BigInt& cofactor,
82  const OID& oid = OID());
83 
84  /**
85  * Decode a BER encoded ECC domain parameter set
86  * @param ber_encoding the bytes of the BER encoding
87  */
88  explicit EC_Group(const std::vector<uint8_t>& ber_encoding);
89 
90  /**
91  * Create an EC domain by OID (or throw if unknown)
92  * @param oid the OID of the EC domain to create
93  */
94  explicit EC_Group(const OID& oid);
95 
96  /**
97  * Create an EC domain from PEM encoding (as from PEM_encode), or
98  * from an OID name (eg "secp256r1", or "1.2.840.10045.3.1.7")
99  * @param pem_or_oid PEM-encoded data, or an OID
100  */
101  explicit EC_Group(const std::string& pem_or_oid);
102 
103  /**
104  * Create an uninitialized EC_Group
105  */
106  EC_Group();
107 
108  ~EC_Group();
109 
110  /**
111  * Create the DER encoding of this domain
112  * @param form of encoding to use
113  * @returns bytes encododed as DER
114  */
115  std::vector<uint8_t> DER_encode(EC_Group_Encoding form) const;
116 
117  /**
118  * Return the PEM encoding (always in explicit form)
119  * @return string containing PEM data
120  */
121  std::string PEM_encode() const;
122 
123  /**
124  * Return domain parameter curve
125  * @result domain parameter curve
126  */
127  BOTAN_DEPRECATED("Avoid CurveGFp") const CurveGFp& get_curve() const;
128 
129  /**
130  * Return if a == -3 mod p
131  */
132  bool a_is_minus_3() const;
133 
134  /**
135  * Return if a == 0 mod p
136  */
137  bool a_is_zero() const;
138 
139  /**
140  * Return the size of p in bits (same as get_p().bits())
141  */
142  size_t get_p_bits() const;
143 
144  /**
145  * Return the size of p in bits (same as get_p().bytes())
146  */
147  size_t get_p_bytes() const;
148 
149  /**
150  * Return the size of group order in bits (same as get_order().bits())
151  */
152  size_t get_order_bits() const;
153 
154  /**
155  * Return the size of p in bytes (same as get_order().bytes())
156  */
157  size_t get_order_bytes() const;
158 
159  /**
160  * Return the prime modulus of the field
161  */
162  const BigInt& get_p() const;
163 
164  /**
165  * Return the a parameter of the elliptic curve equation
166  */
167  const BigInt& get_a() const;
168 
169  /**
170  * Return the b parameter of the elliptic curve equation
171  */
172  const BigInt& get_b() const;
173 
174  /**
175  * Return group base point
176  * @result base point
177  */
178  const PointGFp& get_base_point() const;
179 
180  /**
181  * Return the x coordinate of the base point
182  */
183  const BigInt& get_g_x() const;
184 
185  /**
186  * Return the y coordinate of the base point
187  */
188  const BigInt& get_g_y() const;
189 
190  /**
191  * Return the order of the base point
192  * @result order of the base point
193  */
194  const BigInt& get_order() const;
195 
196  /*
197  * Reduce x modulo the order
198  */
199  BigInt mod_order(const BigInt& x) const;
200 
201  /*
202  * Return inverse of x modulo the order
203  */
204  BigInt inverse_mod_order(const BigInt& x) const;
205 
206  /*
207  * Reduce (x*x) modulo the order
208  */
209  BigInt square_mod_order(const BigInt& x) const;
210 
211  /*
212  * Reduce (x*y) modulo the order
213  */
214  BigInt multiply_mod_order(const BigInt& x, const BigInt& y) const;
215 
216  /*
217  * Reduce (x*y*z) modulo the order
218  */
219  BigInt multiply_mod_order(const BigInt& x, const BigInt& y, const BigInt& z) const;
220 
221  /**
222  * Return the cofactor
223  * @result the cofactor
224  */
225  const BigInt& get_cofactor() const;
226 
227  /**
228  * Check if y is a plausible point on the curve
229  *
230  * In particular, checks that it is a point on the curve, not infinity,
231  * and that it has order matching the group.
232  */
233  bool verify_public_element(const PointGFp& y) const;
234 
235  /**
236  * Return the OID of these domain parameters
237  * @result the OID as a string
238  */
239  std::string BOTAN_DEPRECATED("Use get_curve_oid") get_oid() const { return get_curve_oid().as_string(); }
240 
241  /**
242  * Return the OID of these domain parameters
243  * @result the OID
244  */
245  const OID& get_curve_oid() const;
246 
247  /**
248  * Return a point on this curve with the affine values x, y
249  */
250  PointGFp point(const BigInt& x, const BigInt& y) const;
251 
252  /**
253  * Multi exponentiate. Not constant time.
254  * @return base_point*x + pt*y
255  */
256  PointGFp point_multiply(const BigInt& x, const PointGFp& pt, const BigInt& y) const;
257 
258  /**
259  * Blinded point multiplication, attempts resistance to side channels
260  * @param k the scalar
261  * @param rng a random number generator
262  * @param ws a temp workspace
263  * @return base_point*k
264  */
265  PointGFp blinded_base_point_multiply(const BigInt& k,
267  std::vector<BigInt>& ws) const;
268 
269  /**
270  * Blinded point multiplication, attempts resistance to side channels
271  * Returns just the x coordinate of the point
272  *
273  * @param k the scalar
274  * @param rng a random number generator
275  * @param ws a temp workspace
276  * @return x coordinate of base_point*k
277  */
278  BigInt blinded_base_point_multiply_x(const BigInt& k,
280  std::vector<BigInt>& ws) const;
281 
282  /**
283  * Blinded point multiplication, attempts resistance to side channels
284  * @param point input point
285  * @param k the scalar
286  * @param rng a random number generator
287  * @param ws a temp workspace
288  * @return point*k
289  */
290  PointGFp blinded_var_point_multiply(const PointGFp& point,
291  const BigInt& k,
293  std::vector<BigInt>& ws) const;
294 
295  /**
296  * Return a random scalar ie an integer in [1,order)
297  */
298  BigInt random_scalar(RandomNumberGenerator& rng) const;
299 
300  /**
301  * Return the zero (or infinite) point on this curve
302  */
303  PointGFp zero_point() const;
304 
305  PointGFp OS2ECP(const uint8_t bits[], size_t len) const;
306 
307  template<typename Alloc>
308  PointGFp OS2ECP(const std::vector<uint8_t, Alloc>& vec) const
309  {
310  return this->OS2ECP(vec.data(), vec.size());
311  }
312 
313  bool initialized() const { return (m_data != nullptr); }
314 
315  /**
316  * Verify EC_Group domain
317  * @returns true if group is valid. false otherwise
318  */
319  bool verify_group(RandomNumberGenerator& rng,
320  bool strong = false) const;
321 
322  bool operator==(const EC_Group& other) const;
323 
324  /**
325  * Return PEM representation of named EC group
326  * Deprecated: Use EC_Group(name).PEM_encode() if this is needed
327  */
328  static std::string BOTAN_DEPRECATED("See header comment") PEM_for_named_group(const std::string& name);
329 
330  /**
331  * Return a set of known named EC groups
332  */
333  static const std::set<std::string>& known_named_groups();
334 
335  /*
336  * For internal use only
337  */
338  static std::shared_ptr<EC_Group_Data> EC_group_info(const OID& oid);
339 
340  static size_t clear_registered_curve_data();
341 
342  private:
343  static EC_Group_Data_Map& ec_group_data();
344 
345  static std::shared_ptr<EC_Group_Data> BER_decode_EC_group(const uint8_t bits[], size_t len);
346 
347  static std::shared_ptr<EC_Group_Data>
348  load_EC_group_info(const char* p,
349  const char* a,
350  const char* b,
351  const char* g_x,
352  const char* g_y,
353  const char* order,
354  const OID& oid);
355 
356  // Member data
357  const EC_Group_Data& data() const;
358  std::shared_ptr<EC_Group_Data> m_data;
359  };
360 
361 inline bool operator!=(const EC_Group& lhs,
362  const EC_Group& rhs)
363  {
364  return !(lhs == rhs);
365  }
366 
367 // For compatibility with 1.8
369 
370 }
371 
372 #endif
#define BOTAN_PUBLIC_API(maj, min)
Definition: compiler.h:27
PointGFp OS2ECP(const std::vector< uint8_t, Alloc > &vec) const
Definition: ec_group.h:308
Definition: bigint.h:796
bool initialized() const
Definition: ec_group.h:313
EC_Group EC_Domain_Params
Definition: ec_group.h:368
std::string PEM_encode(const Private_Key &key)
Definition: pkcs8.cpp:148
Definition: alg_id.cpp:13
EC_Group_Encoding
Definition: ec_group.h:23
bool operator==(const AlgorithmIdentifier &a1, const AlgorithmIdentifier &a2)
Definition: alg_id.cpp:75
PointGFp OS2ECP(const uint8_t data[], size_t data_len, const CurveGFp &curve)
Definition: point_gfp.cpp:663