1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
|
Elliptic Curve Operations
============================
In addition to high level operations for signatures, key agreement,
and message encryption using elliptic curve cryptography, the library
contains lower level interfaces for performing operations such as
elliptic curve point multiplication.
Only curves over prime fields are supported.
Many of these functions take a workspace, either a vector of words or
a vector of BigInts. These are used to minimize memory allocations
during common operations.
.. warning::
You should only use these interfaces if you know what you are doing.
.. cpp:class:: EC_Group
.. cpp:function:: EC_Group(const OID& oid)
Initialize an ``EC_Group`` using an OID referencing the curve
parameters.
.. cpp:function:: EC_Group(const std::string& name)
Initialize an ``EC_Group`` using a name or OID (for example
"secp256r1", or "1.2.840.10045.3.1.7")
.. cpp:function:: EC_Group(const BigInt& p, \
const BigInt& a, \
const BigInt& b, \
const BigInt& base_x, \
const BigInt& base_y, \
const BigInt& order, \
const BigInt& cofactor, \
const OID& oid = OID())
Initialize an elliptic curve group from the relevant parameters. This
is used for example to create custom (application-specific) curves.
.. cpp:function:: EC_Group(const std::vector<uint8_t>& ber_encoding)
Initialize an ``EC_Group`` by decoding a DER encoded parameter block.
.. cpp:function:: std::vector<uint8_t> DER_encode(EC_Group_Encoding form) const
Return the DER encoding of this group.
.. cpp:function:: std::string PEM_encode() const
Return the PEM encoding of this group (base64 of DER encoding plus
header/trailer).
.. cpp:function:: bool a_is_minus_3() const
Return true if the ``a`` parameter is congruent to -3 mod p.
.. cpp:function:: bool a_is_zero() const
Return true if the ``a`` parameter is congruent to 0 mod p.
.. cpp:function:: size_t get_p_bits() const
Return size of the prime in bits.
.. cpp:function:: size_t get_p_bytes() const
Return size of the prime in bytes.
.. cpp:function:: size_t get_order_bits() const
Return size of the group order in bits.
.. cpp:function:: size_t get_order_bytes() const
Return size of the group order in bytes.
.. cpp:function:: const BigInt& get_p() const
Return the prime modulus.
.. cpp:function:: const BigInt& get_a() const
Return the ``a`` parameter of the elliptic curve equation.
.. cpp:function:: const BigInt& get_b() const
Return the ``b`` parameter of the elliptic curve equation.
.. cpp:function:: const PointGFp& get_base_point() const
Return the groups base point element.
.. cpp:function:: const BigInt& get_g_x() const
Return the x coordinate of the base point element.
.. cpp:function:: const BigInt& get_g_y() const
Return the y coordinate of the base point element.
.. cpp:function:: const BigInt& get_order() const
Return the order of the group generated by the base point.
.. cpp:function:: const BigInt& get_cofactor() const
Return the cofactor of the curve. In most cases this will be 1.
.. cpp:function:: BigInt mod_order(const BigInt& x) const
Reduce argument ``x`` modulo the curve order.
.. cpp:function:: BigInt inverse_mod_order(const BigInt& x) const
Return inverse of argument ``x`` modulo the curve order.
.. cpp:function:: BigInt multiply_mod_order(const BigInt& x, const BigInt& y) const
Multiply ``x`` and ``y`` and reduce the result modulo the curve order.
.. cpp:function:: bool verify_public_element(const PointGFp& y) const
Return true if ``y`` seems to be a valid group element.
.. cpp:function:: const OID& get_curve_oid() const
Return the OID used to identify the curve. May be empty.
.. cpp:function:: PointGFp point(const BigInt& x, const BigInt& y) const
Create and return a point with affine elements ``x`` and ``y``. Note
this function *does not* verify that ``x`` and ``y`` satisfy the curve
equation.
.. cpp:function:: PointGFp point_multiply(const BigInt& x, const PointGFp& pt, const BigInt& y) const
Multi-exponentiation. Returns base_point*x + pt*y. Not constant time.
(Ordinarily used for signature verification.)
.. cpp:function:: PointGFp blinded_base_point_multiply(const BigInt& k, \
RandomNumberGenerator& rng, \
std::vector<BigInt>& ws) const
Return ``base_point*k`` in a way that attempts to resist side channels.
.. cpp:function:: BigInt blinded_base_point_multiply_x(const BigInt& k, \
RandomNumberGenerator& rng, \
std::vector<BigInt>& ws) const
Like `blinded_base_point_multiply` but returns only the x coordinate.
.. cpp:function:: PointGFp blinded_var_point_multiply(const PointGFp& point, \
const BigInt& k, \
RandomNumberGenerator& rng, \
std::vector<BigInt>& ws) const
Return ``point*k`` in a way that attempts to resist side channels.
.. cpp:function:: BigInt random_scalar(RandomNumberGenerator& rng) const
Return a random scalar (ie an integer between 1 and the group order).
.. cpp:function:: PointGFp zero_point() const
Return the zero point (aka the point at infinity).
.. cpp:function:: PointGFp OS2ECP(const uint8_t bits[], size_t len) const
Decode a point from the binary encoding. This function verifies that
the decoded point is a valid element on the curve.
.. cpp:function:: bool verify_group(RandomNumberGenerator& rng, bool strong = false) const
Attempt to verify the group seems valid.
.. cpp:function:: static const std::set<std::string>& known_named_groups()
Return a list of known groups, ie groups for which ``EC_Group(name)``
will succeed.
.. cpp:class:: PointGFp
Stores elliptic curve points in Jacobian representation.
.. cpp:function:: std::vector<uint8_t> encode(PointGFp::Compression_Type format) const
Encode a point in a way that can later be decoded with `EC_Group::OS2ECP`.
.. cpp:function:: PointGFp& operator+=(const PointGFp& rhs)
Point addition.
.. cpp:function:: PointGFp& operator-=(const PointGFp& rhs)
Point subtraction.
.. cpp:function:: PointGFp& operator*=(const BigInt& scalar)
Point multiplication using Montgomery ladder.
.. warning::
Prefer the blinded functions in ``EC_Group``
.. cpp:function:: PointGFp& negate()
Negate this point.
.. cpp:function:: BigInt get_affine_x() const
Return the affine ``x`` coordinate of the point.
.. cpp:function:: BigInt get_affine_y() const
Return the affine ``y`` coordinate of the point.
.. cpp:function:: void force_affine()
Convert the point to its equivalent affine coordinates. Throws
if this is the point at infinity.
.. cpp:function:: static void force_all_affine(std::vector<PointGFp>& points, \
secure_vector<word>& ws)
Force several points to be affine at once. Uses Montgomery's
trick to reduce number of inversions required, so this is much
faster than calling ``force_affine`` on each point in sequence.
.. cpp:function:: bool is_affine() const
Return true if this point is in affine coordinates.
.. cpp:function:: bool is_zero() const
Return true if this point is zero (aka point at infinity).
.. cpp:function:: bool on_the_curve() const
Return true if this point is on the curve.
.. cpp:function:: void randomize_repr(RandomNumberGenerator& rng)
Randomize the point representation.
.. cpp:function:: bool operator==(const PointGFp& other) const
Point equality. This compares the affine representations.
.. cpp:function:: void add(const PointGFp& other, std::vector<BigInt>& workspace)
Point addition, taking a workspace.
.. cpp:function:: void add_affine(const PointGFp& other, std::vector<BigInt>& workspace)
Mixed (Jacobian+affine) addition, taking a workspace.
.. warning::
This function assumes that ``other`` is affine, if this is
not correct the result will be invalid.
.. cpp:function:: void mult2(std::vector<BigInt>& workspace)
Point doubling.
.. cpp:function:: void mult2i(size_t i, std::vector<BigInt>& workspace)
Repeated point doubling.
.. cpp:function:: PointGFp plus(const PointGFp& other, std::vector<BigInt>& workspace) const
Point addition, returning the result.
.. cpp:function:: PointGFp double_of(std::vector<BigInt>& workspace) const
Point doubling, returning the result.
.. cpp:function:: PointGFp zero() const
Return the point at infinity
|
