Botan  2.6.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 the size of p in bits (same as get_p().bits())
136  */
137  size_t get_p_bits() const;
138 
139  /**
140  * Return the size of p in bits (same as get_p().bytes())
141  */
142  size_t get_p_bytes() const;
143 
144  /**
145  * Return the size of group order in bits (same as get_order().bits())
146  */
147  size_t get_order_bits() const;
148 
149  /**
150  * Return the size of p in bytes (same as get_order().bytes())
151  */
152  size_t get_order_bytes() const;
153 
154  /**
155  * Return the prime modulus of the field
156  */
157  const BigInt& get_p() const;
158 
159  /**
160  * Return the a parameter of the elliptic curve equation
161  */
162  const BigInt& get_a() const;
163 
164  /**
165  * Return the b parameter of the elliptic curve equation
166  */
167  const BigInt& get_b() const;
168 
169  /**
170  * Return group base point
171  * @result base point
172  */
173  const PointGFp& get_base_point() const;
174 
175  /**
176  * Return the x coordinate of the base point
177  */
178  const BigInt& get_g_x() const;
179 
180  /**
181  * Return the y coordinate of the base point
182  */
183  const BigInt& get_g_y() const;
184 
185  /**
186  * Return the order of the base point
187  * @result order of the base point
188  */
189  const BigInt& get_order() const;
190 
191  /*
192  * Reduce x modulo the order
193  */
194  BigInt mod_order(const BigInt& x) const;
195 
196  /*
197  * Reduce (x*y) modulo the order
198  */
199  BigInt multiply_mod_order(const BigInt& x, const BigInt& y) const;
200 
201  /**
202  * Return the cofactor
203  * @result the cofactor
204  */
205  const BigInt& get_cofactor() const;
206 
207  /**
208  * Check if y is a plausible point on the curve
209  *
210  * In particular, checks that it is a point on the curve, not infinity,
211  * and that it has order matching the group.
212  */
213  bool verify_public_element(const PointGFp& y) const;
214 
215  /**
216  * Return the OID of these domain parameters
217  * @result the OID as a string
218  */
219  std::string BOTAN_DEPRECATED("Use get_curve_oid") get_oid() const { return get_curve_oid().as_string(); }
220 
221  /**
222  * Return the OID of these domain parameters
223  * @result the OID
224  */
225  const OID& get_curve_oid() const;
226 
227  /**
228  * Return a point on this curve with the affine values x, y
229  */
230  PointGFp point(const BigInt& x, const BigInt& y) const;
231 
232  /**
233  * Multi exponentiate. Not constant time.
234  * @return base_point*x + pt*y
235  */
236  PointGFp point_multiply(const BigInt& x, const PointGFp& pt, const BigInt& y) const;
237 
238  /**
239  * Blinded point multiplication, attempts resistance to side channels
240  * @param k the scalar
241  * @param rng a random number generator
242  * @param ws a temp workspace
243  * @return base_point*k
244  */
245  PointGFp blinded_base_point_multiply(const BigInt& k,
247  std::vector<BigInt>& ws) const;
248 
249  /**
250  * Blinded point multiplication, attempts resistance to side channels
251  * Returns just the x coordinate of the point
252  *
253  * @param k the scalar
254  * @param rng a random number generator
255  * @param ws a temp workspace
256  * @return x coordinate of base_point*k
257  */
258  BigInt blinded_base_point_multiply_x(const BigInt& k,
260  std::vector<BigInt>& ws) const;
261 
262  /**
263  * Blinded point multiplication, attempts resistance to side channels
264  * @param point input point
265  * @param k the scalar
266  * @param rng a random number generator
267  * @param ws a temp workspace
268  * @return point*k
269  */
270  PointGFp blinded_var_point_multiply(const PointGFp& point,
271  const BigInt& k,
273  std::vector<BigInt>& ws) const;
274 
275  /**
276  * Return a random scalar ie an integer in [1,order)
277  */
278  BigInt random_scalar(RandomNumberGenerator& rng) const;
279 
280  /**
281  * Return the zero (or infinite) point on this curve
282  */
283  PointGFp zero_point() const;
284 
285  PointGFp OS2ECP(const uint8_t bits[], size_t len) const;
286 
287  template<typename Alloc>
288  PointGFp OS2ECP(const std::vector<uint8_t, Alloc>& vec) const
289  {
290  return this->OS2ECP(vec.data(), vec.size());
291  }
292 
293  bool initialized() const { return (m_data != nullptr); }
294 
295  /**
296  * Verify EC_Group domain
297  * @returns true if group is valid. false otherwise
298  */
299  bool verify_group(RandomNumberGenerator& rng,
300  bool strong = false) const;
301 
302  bool operator==(const EC_Group& other) const;
303 
304  /**
305  * Return PEM representation of named EC group
306  * Deprecated: Use EC_Group(name).PEM_encode() if this is needed
307  */
308  static std::string BOTAN_DEPRECATED("See header comment") PEM_for_named_group(const std::string& name);
309 
310  /**
311  * Return a set of known named EC groups
312  */
313  static const std::set<std::string>& known_named_groups();
314 
315  /*
316  * For internal use only
317  */
318  static std::shared_ptr<EC_Group_Data> EC_group_info(const OID& oid);
319 
320  static size_t clear_registered_curve_data();
321 
322  private:
323  static EC_Group_Data_Map& ec_group_data();
324 
325  static std::shared_ptr<EC_Group_Data> BER_decode_EC_group(const uint8_t bits[], size_t len);
326 
327  static std::shared_ptr<EC_Group_Data>
328  load_EC_group_info(const char* p,
329  const char* a,
330  const char* b,
331  const char* g_x,
332  const char* g_y,
333  const char* order,
334  const OID& oid);
335 
336  // Member data
337  const EC_Group_Data& data() const;
338  std::shared_ptr<EC_Group_Data> m_data;
339  };
340 
341 inline bool operator!=(const EC_Group& lhs,
342  const EC_Group& rhs)
343  {
344  return !(lhs == rhs);
345  }
346 
347 // For compatibility with 1.8
349 
350 }
351 
352 #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:288
Definition: bigint.h:719
bool initialized() const
Definition: ec_group.h:293
EC_Group EC_Domain_Params
Definition: ec_group.h:348
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:653