1 /**********************************************************************
2 * Copyright (c) 2014 Pieter Wuille *
3 * Distributed under the MIT software license, see the accompanying *
4 * file COPYING or http://www.opensource.org/licenses/mit-license.php.*
5 **********************************************************************/
7 #ifndef SECP256K1_SCALAR_IMPL_H
8 #define SECP256K1_SCALAR_IMPL_H
13 #if defined HAVE_CONFIG_H
14 #include "libsecp256k1-config.h"
17 #if defined(EXHAUSTIVE_TEST_ORDER)
18 #include "scalar_low_impl.h"
19 #elif defined(SECP256K1_WIDEMUL_INT128)
20 #include "scalar_4x64_impl.h"
21 #elif defined(SECP256K1_WIDEMUL_INT64)
22 #include "scalar_8x32_impl.h"
24 #error "Please select wide multiplication implementation"
27 static const secp256k1_scalar secp256k1_scalar_one = SECP256K1_SCALAR_CONST(0, 0, 0, 0, 0, 0, 0, 1);
28 static const secp256k1_scalar secp256k1_scalar_zero = SECP256K1_SCALAR_CONST(0, 0, 0, 0, 0, 0, 0, 0);
31 static void secp256k1_scalar_get_num(secp256k1_num *r, const secp256k1_scalar *a) {
33 secp256k1_scalar_get_b32(c, a);
34 secp256k1_num_set_bin(r, c, 32);
37 /** secp256k1 curve order, see secp256k1_ecdsa_const_order_as_fe in ecdsa_impl.h */
38 static void secp256k1_scalar_order_get_num(secp256k1_num *r) {
39 #if defined(EXHAUSTIVE_TEST_ORDER)
40 static const unsigned char order[32] = {
44 0,0,0,0,0,0,0,EXHAUSTIVE_TEST_ORDER
47 static const unsigned char order[32] = {
48 0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,
49 0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFE,
50 0xBA,0xAE,0xDC,0xE6,0xAF,0x48,0xA0,0x3B,
51 0xBF,0xD2,0x5E,0x8C,0xD0,0x36,0x41,0x41
54 secp256k1_num_set_bin(r, order, 32);
58 static int secp256k1_scalar_set_b32_seckey(secp256k1_scalar *r, const unsigned char *bin) {
60 secp256k1_scalar_set_b32(r, bin, &overflow);
61 return (!overflow) & (!secp256k1_scalar_is_zero(r));
64 static void secp256k1_scalar_inverse(secp256k1_scalar *r, const secp256k1_scalar *x) {
65 #if defined(EXHAUSTIVE_TEST_ORDER)
68 for (i = 0; i < EXHAUSTIVE_TEST_ORDER; i++)
69 if ((i * *x) % EXHAUSTIVE_TEST_ORDER == 1)
71 /* If this VERIFY_CHECK triggers we were given a noninvertible scalar (and thus
72 * have a composite group order; fix it in exhaustive_tests.c). */
73 VERIFY_CHECK(*r != 0);
78 /* First compute xN as x ^ (2^N - 1) for some values of N,
79 * and uM as x ^ M for some values of M. */
80 secp256k1_scalar x2, x3, x6, x8, x14, x28, x56, x112, x126;
81 secp256k1_scalar u2, u5, u9, u11, u13;
83 secp256k1_scalar_sqr(&u2, x);
84 secp256k1_scalar_mul(&x2, &u2, x);
85 secp256k1_scalar_mul(&u5, &u2, &x2);
86 secp256k1_scalar_mul(&x3, &u5, &u2);
87 secp256k1_scalar_mul(&u9, &x3, &u2);
88 secp256k1_scalar_mul(&u11, &u9, &u2);
89 secp256k1_scalar_mul(&u13, &u11, &u2);
91 secp256k1_scalar_sqr(&x6, &u13);
92 secp256k1_scalar_sqr(&x6, &x6);
93 secp256k1_scalar_mul(&x6, &x6, &u11);
95 secp256k1_scalar_sqr(&x8, &x6);
96 secp256k1_scalar_sqr(&x8, &x8);
97 secp256k1_scalar_mul(&x8, &x8, &x2);
99 secp256k1_scalar_sqr(&x14, &x8);
100 for (i = 0; i < 5; i++) {
101 secp256k1_scalar_sqr(&x14, &x14);
103 secp256k1_scalar_mul(&x14, &x14, &x6);
105 secp256k1_scalar_sqr(&x28, &x14);
106 for (i = 0; i < 13; i++) {
107 secp256k1_scalar_sqr(&x28, &x28);
109 secp256k1_scalar_mul(&x28, &x28, &x14);
111 secp256k1_scalar_sqr(&x56, &x28);
112 for (i = 0; i < 27; i++) {
113 secp256k1_scalar_sqr(&x56, &x56);
115 secp256k1_scalar_mul(&x56, &x56, &x28);
117 secp256k1_scalar_sqr(&x112, &x56);
118 for (i = 0; i < 55; i++) {
119 secp256k1_scalar_sqr(&x112, &x112);
121 secp256k1_scalar_mul(&x112, &x112, &x56);
123 secp256k1_scalar_sqr(&x126, &x112);
124 for (i = 0; i < 13; i++) {
125 secp256k1_scalar_sqr(&x126, &x126);
127 secp256k1_scalar_mul(&x126, &x126, &x14);
129 /* Then accumulate the final result (t starts at x126). */
131 for (i = 0; i < 3; i++) {
132 secp256k1_scalar_sqr(t, t);
134 secp256k1_scalar_mul(t, t, &u5); /* 101 */
135 for (i = 0; i < 4; i++) { /* 0 */
136 secp256k1_scalar_sqr(t, t);
138 secp256k1_scalar_mul(t, t, &x3); /* 111 */
139 for (i = 0; i < 4; i++) { /* 0 */
140 secp256k1_scalar_sqr(t, t);
142 secp256k1_scalar_mul(t, t, &u5); /* 101 */
143 for (i = 0; i < 5; i++) { /* 0 */
144 secp256k1_scalar_sqr(t, t);
146 secp256k1_scalar_mul(t, t, &u11); /* 1011 */
147 for (i = 0; i < 4; i++) {
148 secp256k1_scalar_sqr(t, t);
150 secp256k1_scalar_mul(t, t, &u11); /* 1011 */
151 for (i = 0; i < 4; i++) { /* 0 */
152 secp256k1_scalar_sqr(t, t);
154 secp256k1_scalar_mul(t, t, &x3); /* 111 */
155 for (i = 0; i < 5; i++) { /* 00 */
156 secp256k1_scalar_sqr(t, t);
158 secp256k1_scalar_mul(t, t, &x3); /* 111 */
159 for (i = 0; i < 6; i++) { /* 00 */
160 secp256k1_scalar_sqr(t, t);
162 secp256k1_scalar_mul(t, t, &u13); /* 1101 */
163 for (i = 0; i < 4; i++) { /* 0 */
164 secp256k1_scalar_sqr(t, t);
166 secp256k1_scalar_mul(t, t, &u5); /* 101 */
167 for (i = 0; i < 3; i++) {
168 secp256k1_scalar_sqr(t, t);
170 secp256k1_scalar_mul(t, t, &x3); /* 111 */
171 for (i = 0; i < 5; i++) { /* 0 */
172 secp256k1_scalar_sqr(t, t);
174 secp256k1_scalar_mul(t, t, &u9); /* 1001 */
175 for (i = 0; i < 6; i++) { /* 000 */
176 secp256k1_scalar_sqr(t, t);
178 secp256k1_scalar_mul(t, t, &u5); /* 101 */
179 for (i = 0; i < 10; i++) { /* 0000000 */
180 secp256k1_scalar_sqr(t, t);
182 secp256k1_scalar_mul(t, t, &x3); /* 111 */
183 for (i = 0; i < 4; i++) { /* 0 */
184 secp256k1_scalar_sqr(t, t);
186 secp256k1_scalar_mul(t, t, &x3); /* 111 */
187 for (i = 0; i < 9; i++) { /* 0 */
188 secp256k1_scalar_sqr(t, t);
190 secp256k1_scalar_mul(t, t, &x8); /* 11111111 */
191 for (i = 0; i < 5; i++) { /* 0 */
192 secp256k1_scalar_sqr(t, t);
194 secp256k1_scalar_mul(t, t, &u9); /* 1001 */
195 for (i = 0; i < 6; i++) { /* 00 */
196 secp256k1_scalar_sqr(t, t);
198 secp256k1_scalar_mul(t, t, &u11); /* 1011 */
199 for (i = 0; i < 4; i++) {
200 secp256k1_scalar_sqr(t, t);
202 secp256k1_scalar_mul(t, t, &u13); /* 1101 */
203 for (i = 0; i < 5; i++) {
204 secp256k1_scalar_sqr(t, t);
206 secp256k1_scalar_mul(t, t, &x2); /* 11 */
207 for (i = 0; i < 6; i++) { /* 00 */
208 secp256k1_scalar_sqr(t, t);
210 secp256k1_scalar_mul(t, t, &u13); /* 1101 */
211 for (i = 0; i < 10; i++) { /* 000000 */
212 secp256k1_scalar_sqr(t, t);
214 secp256k1_scalar_mul(t, t, &u13); /* 1101 */
215 for (i = 0; i < 4; i++) {
216 secp256k1_scalar_sqr(t, t);
218 secp256k1_scalar_mul(t, t, &u9); /* 1001 */
219 for (i = 0; i < 6; i++) { /* 00000 */
220 secp256k1_scalar_sqr(t, t);
222 secp256k1_scalar_mul(t, t, x); /* 1 */
223 for (i = 0; i < 8; i++) { /* 00 */
224 secp256k1_scalar_sqr(t, t);
226 secp256k1_scalar_mul(r, t, &x6); /* 111111 */
229 SECP256K1_INLINE static int secp256k1_scalar_is_even(const secp256k1_scalar *a) {
230 return !(a->d[0] & 1);
234 static void secp256k1_scalar_inverse_var(secp256k1_scalar *r, const secp256k1_scalar *x) {
235 #if defined(USE_SCALAR_INV_BUILTIN)
236 secp256k1_scalar_inverse(r, x);
237 #elif defined(USE_SCALAR_INV_NUM)
240 secp256k1_scalar t = *x;
241 secp256k1_scalar_get_b32(b, &t);
242 secp256k1_num_set_bin(&n, b, 32);
243 secp256k1_scalar_order_get_num(&m);
244 secp256k1_num_mod_inverse(&n, &n, &m);
245 secp256k1_num_get_bin(b, 32, &n);
246 secp256k1_scalar_set_b32(r, b, NULL);
247 /* Verify that the inverse was computed correctly, without GMP code. */
248 secp256k1_scalar_mul(&t, &t, r);
249 CHECK(secp256k1_scalar_is_one(&t));
251 #error "Please select scalar inverse implementation"
255 #ifdef USE_ENDOMORPHISM
256 /* These parameters are generated using sage/gen_exhaustive_groups.sage. */
257 #if defined(EXHAUSTIVE_TEST_ORDER)
258 # if EXHAUSTIVE_TEST_ORDER == 13
259 # define EXHAUSTIVE_TEST_LAMBDA 9
260 # elif EXHAUSTIVE_TEST_ORDER == 199
261 # define EXHAUSTIVE_TEST_LAMBDA 92
263 # error No known lambda for the specified exhaustive test group order.
267 * Find k1 and k2 given k, such that k1 + k2 * lambda == k mod n; unlike in the
268 * full case we don't bother making k1 and k2 be small, we just want them to be
269 * nontrivial to get full test coverage for the exhaustive tests. We therefore
270 * (arbitrarily) set k2 = k + 5 and k1 = k - k2 * lambda.
272 static void secp256k1_scalar_split_lambda(secp256k1_scalar *r1, secp256k1_scalar *r2, const secp256k1_scalar *a) {
273 *r2 = (*a + 5) % EXHAUSTIVE_TEST_ORDER;
274 *r1 = (*a + (EXHAUSTIVE_TEST_ORDER - *r2) * EXHAUSTIVE_TEST_LAMBDA) % EXHAUSTIVE_TEST_ORDER;
278 * The Secp256k1 curve has an endomorphism, where lambda * (x, y) = (beta * x, y), where
279 * lambda is {0x53,0x63,0xad,0x4c,0xc0,0x5c,0x30,0xe0,0xa5,0x26,0x1c,0x02,0x88,0x12,0x64,0x5a,
280 * 0x12,0x2e,0x22,0xea,0x20,0x81,0x66,0x78,0xdf,0x02,0x96,0x7c,0x1b,0x23,0xbd,0x72}
282 * Both lambda and beta are primitive cube roots of unity. That is lamba^3 == 1 mod n and
283 * beta^3 == 1 mod p, where n is the curve order and p is the field order.
285 * Futhermore, because (X^3 - 1) = (X - 1)(X^2 + X + 1), the primitive cube roots of unity are
286 * roots of X^2 + X + 1. Therefore lambda^2 + lamba == -1 mod n and beta^2 + beta == -1 mod p.
287 * (The other primitive cube roots of unity are lambda^2 and beta^2 respectively.)
289 * Let l = -1/2 + i*sqrt(3)/2, the complex root of X^2 + X + 1. We can define a ring
290 * homomorphism phi : Z[l] -> Z_n where phi(a + b*l) == a + b*lambda mod n. The kernel of phi
291 * is a lattice over Z[l] (considering Z[l] as a Z-module). This lattice is generated by a
292 * reduced basis {a1 + b1*l, a2 + b2*l} where
294 * - a1 = {0x30,0x86,0xd2,0x21,0xa7,0xd4,0x6b,0xcd,0xe8,0x6c,0x90,0xe4,0x92,0x84,0xeb,0x15}
295 * - b1 = -{0xe4,0x43,0x7e,0xd6,0x01,0x0e,0x88,0x28,0x6f,0x54,0x7f,0xa9,0x0a,0xbf,0xe4,0xc3}
296 * - a2 = {0x01,0x14,0xca,0x50,0xf7,0xa8,0xe2,0xf3,0xf6,0x57,0xc1,0x10,0x8d,0x9d,0x44,0xcf,0xd8}
297 * - b2 = {0x30,0x86,0xd2,0x21,0xa7,0xd4,0x6b,0xcd,0xe8,0x6c,0x90,0xe4,0x92,0x84,0xeb,0x15}
299 * "Guide to Elliptic Curve Cryptography" (Hankerson, Menezes, Vanstone) gives an algorithm
300 * (algorithm 3.74) to find k1 and k2 given k, such that k1 + k2 * lambda == k mod n, and k1
301 * and k2 have a small size.
303 * The algorithm computes c1 = round(b2 * k / n) and c2 = round((-b1) * k / n), and gives
304 * k1 = k - (c1*a1 + c2*a2) and k2 = -(c1*b1 + c2*b2). Instead, we use modular arithmetic, and
305 * compute k - k2 * lambda (mod n) which is equivalent to k1 (mod n), avoiding the need for
306 * the constants a1 and a2.
308 * g1, g2 are precomputed constants used to replace division with a rounded multiplication
309 * when decomposing the scalar for an endomorphism-based point multiplication.
311 * The possibility of using precomputed estimates is mentioned in "Guide to Elliptic Curve
312 * Cryptography" (Hankerson, Menezes, Vanstone) in section 3.5.
314 * The derivation is described in the paper "Efficient Software Implementation of Public-Key
315 * Cryptography on Sensor Networks Using the MSP430X Microcontroller" (Gouvea, Oliveira, Lopez),
316 * Section 4.3 (here we use a somewhat higher-precision estimate):
318 * g1 = round(2^384 * b2/d)
319 * g2 = round(2^384 * (-b1)/d)
321 * (Note that d is also equal to the curve order, n, here because [a1,b1] and [a2,b2]
322 * can be found as outputs of the Extended Euclidean Algorithm on inputs n and lambda).
324 * The function below splits k into r1 and r2, such that
325 * - r1 + lambda * r2 == k (mod n)
326 * - either r1 < 2^128 or -r1 mod n < 2^128
327 * - either r2 < 2^128 or -r2 mod n < 2^128
332 * - epsilon1 = 2^256 * |g1/2^384 - b2/d|
333 * - epsilon2 = 2^256 * |g2/2^384 - (-b1)/d|
334 * - c1 = round(k*g1/2^384)
335 * - c2 = round(k*g2/2^384)
337 * Lemma 1: |c1 - k*b2/d| < 2^-1 + epsilon1
341 * |c1 - k*g1/2^384 + k*g1/2^384 - k*b2/d|
342 * <= {triangle inequality}
343 * |c1 - k*g1/2^384| + |k*g1/2^384 - k*b2/d|
345 * |c1 - k*g1/2^384| + k*|g1/2^384 - b2/d|
346 * < {rounding in c1 and 0 <= k < 2^256}
347 * 2^-1 + 2^256 * |g1/2^384 - b2/d|
348 * = {definition of epsilon1}
351 * Lemma 2: |c2 - k*(-b1)/d| < 2^-1 + epsilon2
355 * |c2 - k*g2/2^384 + k*g2/2^384 - k*(-b1)/d|
356 * <= {triangle inequality}
357 * |c2 - k*g2/2^384| + |k*g2/2^384 - k*(-b1)/d|
359 * |c2 - k*g2/2^384| + k*|g2/2^384 - (-b1)/d|
360 * < {rounding in c2 and 0 <= k < 2^256}
361 * 2^-1 + 2^256 * |g2/2^384 - (-b1)/d|
362 * = {definition of epsilon2}
366 * - k1 = k - c1*a1 - c2*a2
367 * - k2 = - c1*b1 - c2*b2
369 * Lemma 3: |k1| < (a1 + a2 + 1)/2 < 2^128
372 * = {definition of k1}
373 * |k - c1*a1 - c2*a2|
374 * = {(a1*b2 - b1*a2)/n = 1}
375 * |k*(a1*b2 - b1*a2)/n - c1*a1 - c2*a2|
377 * |a1*(k*b2/n - c1) + a2*(k*(-b1)/n - c2)|
378 * <= {triangle inequality}
379 * a1*|k*b2/n - c1| + a2*|k*(-b1)/n - c2|
380 * < {Lemma 1 and Lemma 2}
381 * a1*(2^-1 + epslion1) + a2*(2^-1 + epsilon2)
382 * < {rounding up to an integer}
384 * < {rounding up to a power of 2}
387 * Lemma 4: |k2| < (-b1 + b2)/2 + 1 < 2^128
390 * = {definition of k2}
392 * = {(b1*b2 - b1*b2)/n = 0}
393 * |k*(b1*b2 - b1*b2)/n - c1*b1 - c2*b2|
395 * |b1*(k*b2/n - c1) + b2*(k*(-b1)/n - c2)|
396 * <= {triangle inequality}
397 * (-b1)*|k*b2/n - c1| + b2*|k*(-b1)/n - c2|
398 * < {Lemma 1 and Lemma 2}
399 * (-b1)*(2^-1 + epslion1) + b2*(2^-1 + epsilon2)
400 * < {rounding up to an integer}
402 * < {rounding up to a power of 2}
407 * - r1 = k - r2*lambda mod n.
409 * Notice that r1 is defined such that r1 + r2 * lambda == k (mod n).
411 * Lemma 5: r1 == k1 mod n.
414 * == {definition of r1 and r2}
416 * == {definition of k2}
417 * k - (- c1*b1 - c2*b2)*lambda
419 * k + c1*b1*lambda + c2*b2*lambda
420 * == {a1 + b1*lambda == 0 mod n and a2 + b2*lambda == 0 mod n}
422 * == {definition of k1}
425 * From Lemma 3, Lemma 4, Lemma 5 and the definition of r2, we can conclude that
427 * - either r1 < 2^128 or -r1 mod n < 2^128
428 * - either r2 < 2^128 or -r2 mod n < 2^128.
433 static void secp256k1_scalar_split_lambda(secp256k1_scalar *r1, secp256k1_scalar *r2, const secp256k1_scalar *k) {
434 secp256k1_scalar c1, c2;
435 static const secp256k1_scalar minus_lambda = SECP256K1_SCALAR_CONST(
436 0xAC9C52B3UL, 0x3FA3CF1FUL, 0x5AD9E3FDUL, 0x77ED9BA4UL,
437 0xA880B9FCUL, 0x8EC739C2UL, 0xE0CFC810UL, 0xB51283CFUL
439 static const secp256k1_scalar minus_b1 = SECP256K1_SCALAR_CONST(
440 0x00000000UL, 0x00000000UL, 0x00000000UL, 0x00000000UL,
441 0xE4437ED6UL, 0x010E8828UL, 0x6F547FA9UL, 0x0ABFE4C3UL
443 static const secp256k1_scalar minus_b2 = SECP256K1_SCALAR_CONST(
444 0xFFFFFFFFUL, 0xFFFFFFFFUL, 0xFFFFFFFFUL, 0xFFFFFFFEUL,
445 0x8A280AC5UL, 0x0774346DUL, 0xD765CDA8UL, 0x3DB1562CUL
447 static const secp256k1_scalar g1 = SECP256K1_SCALAR_CONST(
448 0x3086D221UL, 0xA7D46BCDUL, 0xE86C90E4UL, 0x9284EB15UL,
449 0x3DAA8A14UL, 0x71E8CA7FUL, 0xE893209AUL, 0x45DBB031UL
451 static const secp256k1_scalar g2 = SECP256K1_SCALAR_CONST(
452 0xE4437ED6UL, 0x010E8828UL, 0x6F547FA9UL, 0x0ABFE4C4UL,
453 0x221208ACUL, 0x9DF506C6UL, 0x1571B4AEUL, 0x8AC47F71UL
455 VERIFY_CHECK(r1 != k);
456 VERIFY_CHECK(r2 != k);
457 /* these _var calls are constant time since the shift amount is constant */
458 secp256k1_scalar_mul_shift_var(&c1, k, &g1, 384);
459 secp256k1_scalar_mul_shift_var(&c2, k, &g2, 384);
460 secp256k1_scalar_mul(&c1, &c1, &minus_b1);
461 secp256k1_scalar_mul(&c2, &c2, &minus_b2);
462 secp256k1_scalar_add(r2, &c1, &c2);
463 secp256k1_scalar_mul(r1, r2, &minus_lambda);
464 secp256k1_scalar_add(r1, r1, k);
469 #endif /* SECP256K1_SCALAR_IMPL_H */