3 /* nettle, low-level cryptographics library
5 * Copyright (C) 2013 Niels Möller
7 * The nettle library is free software; you can redistribute it and/or modify
8 * it under the terms of the GNU Lesser General Public License as published by
9 * the Free Software Foundation; either version 2.1 of the License, or (at your
10 * option) any later version.
12 * The nettle library is distributed in the hope that it will be useful, but
13 * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
14 * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public
15 * License for more details.
17 * You should have received a copy of the GNU Lesser General Public License
18 * along with the nettle library; see the file COPYING.LIB. If not, write to
19 * the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
23 /* Development of Nettle's ECC support was funded by the .SE Internet Fund. */
25 #ifndef NETTLE_ECC_H_INCLUDED
26 #define NETTLE_ECC_H_INCLUDED
30 #include "nettle-types.h"
37 #define ecc_point_init nettle_ecc_point_init
38 #define ecc_point_clear nettle_ecc_point_clear
39 #define ecc_point_set nettle_ecc_point_set
40 #define ecc_point_get nettle_ecc_point_get
41 #define ecc_point_mul nettle_ecc_point_mul
42 #define ecc_point_mul_g nettle_ecc_point_mul_g
43 #define ecc_scalar_init nettle_ecc_scalar_init
44 #define ecc_scalar_clear nettle_ecc_scalar_clear
45 #define ecc_scalar_set nettle_ecc_scalar_set
46 #define ecc_scalar_get nettle_ecc_scalar_get
47 #define ecc_scalar_random nettle_ecc_scalar_random
48 #define ecc_point_mul nettle_ecc_point_mul
49 #define ecc_size nettle_ecc_size
50 #define ecc_size_a nettle_ecc_size_a
51 #define ecc_size_j nettle_ecc_size_j
52 #define ecc_a_to_a_itch nettle_ecc_a_to_a_itch
53 #define ecc_a_to_a nettle_ecc_a_to_a
54 #define ecc_a_to_j nettle_ecc_a_to_j
55 #define ecc_j_to_a_itch nettle_ecc_j_to_a_itch
56 #define ecc_j_to_a nettle_ecc_j_to_a
57 #define ecc_dup_ja_itch nettle_ecc_dup_ja_itch
58 #define ecc_dup_ja nettle_ecc_dup_ja
59 #define ecc_dup_jj_itch nettle_ecc_dup_jj_itch
60 #define ecc_dup_jj nettle_ecc_dup_jj
61 #define ecc_add_jja_itch nettle_ecc_add_jja_itch
62 #define ecc_add_jja nettle_ecc_add_jja
63 #define ecc_add_jjj_itch nettle_ecc_add_jjj_itch
64 #define ecc_add_jjj nettle_ecc_add_jjj
65 #define ecc_mul_g_itch nettle_ecc_mul_g_itch
66 #define ecc_mul_g nettle_ecc_mul_g
67 #define ecc_mul_a_itch nettle_ecc_mul_a_itch
68 #define ecc_mul_a nettle_ecc_mul_a
72 /* High level interface, for ECDSA, DH, etc */
74 /* Represents a point on the ECC curve */
76 const struct ecc_curve
*ecc
;
77 /* Allocated using the same allocation function as GMP. */
81 /* Represents a non-zero scalar, an element of Z_q^*, where q is the
82 group order of the curve. */
84 const struct ecc_curve
*ecc
;
85 /* Allocated using the same allocation function as GMP. */
90 ecc_point_init(struct ecc_point
*p
, const struct ecc_curve
*ecc
);
92 ecc_point_clear(struct ecc_point
*p
);
94 /* Fails and returns zero if the point is not on the curve. */
96 ecc_point_set(struct ecc_point
*p
, const mpz_t x
, const mpz_t y
);
98 ecc_point_get(const struct ecc_point
*p
, mpz_t x
, mpz_t y
);
101 ecc_scalar_init(struct ecc_scalar
*s
,
102 const struct ecc_curve
*ecc
);
104 ecc_scalar_clear(struct ecc_scalar
*s
);
106 /* Fails and returns zero if the scalar is not in the proper range. */
108 ecc_scalar_set(struct ecc_scalar
*s
, const mpz_t z
);
110 ecc_scalar_get(const struct ecc_scalar
*s
, mpz_t z
);
111 /* Generates a random scalar, suitable as an ECDSA private key or a
114 ecc_scalar_random(struct ecc_scalar
*s
,
115 void *random_ctx
, nettle_random_func
* random
);
117 /* Computes r = n p */
119 ecc_point_mul(struct ecc_point
*r
, const struct ecc_scalar
*n
,
120 const struct ecc_point
*p
);
122 /* Computes r = n g */
124 ecc_point_mul_g(struct ecc_point
*r
, const struct ecc_scalar
*n
);
127 /* Low-level interface */
129 /* Points on a curve are represented as arrays of mp_limb_t. For some
130 curves, point coordinates are represented in montgomery form. We
131 use either affine coordinates x,y, or Jacobian coordinates X, Y, Z,
132 where x = X/Z^2 and y = X/Z^2.
134 Since we use additive notation for the groups, the infinity point
135 on the curve is denoted 0. The infinity point can be represented
136 with x = y = 0 in affine coordinates, and Z = 0 in Jacobian
137 coordinates. However, note that most of the ECC functions do *not*
138 support infinity as an input or output.
141 /* FIXME: Also provided some compile time constants? */
143 /* Returns the size of a single coordinate. */
144 mp_size_t
ecc_size(const struct ecc_curve
*ecc
);
146 /* Size of a point, using affine coordinates x, y. */
147 mp_size_t
ecc_size_a(const struct ecc_curve
*ecc
);
149 /* Size of a point, using jacobian coordinates X, Y and Z. */
150 mp_size_t
ecc_size_j(const struct ecc_curve
*ecc
);
152 /* FIXME: Rename the low-level (and side-channel silent) functions to
153 _ecc_*, and provide public ecc_* functions which handle the
154 infinity points properly? */
156 /* Converts the affine coordinates of a point into montgomery form, if
157 used for this curve. */
158 mp_size_t
ecc_a_to_a_itch(const struct ecc_curve
*ecc
);
160 ecc_a_to_a(const struct ecc_curve
*ecc
,
161 mp_limb_t
* r
, const mp_limb_t
* p
,
162 mp_limb_t
* scratch
);
164 /* Converts a point P in affine coordinates into a point R in jacobian
165 coordinates. If INITIAL is non-zero, and the curve uses montgomery
166 coordinates, also convert coordinates to montgomery form. */
168 ecc_a_to_j(const struct ecc_curve
*ecc
,
169 int initial
, mp_limb_t
* r
, const mp_limb_t
* p
);
171 /* Converts a point P in jacobian coordinates into a point R in affine
172 coordinates. If FLAGS has bit 0 set, and the curve uses montgomery
173 coordinates, also undo the montgomery conversion. If flags has bit
174 1 set, produce x coordinate only. */
175 mp_size_t
ecc_j_to_a_itch(const struct ecc_curve
*ecc
);
177 ecc_j_to_a(const struct ecc_curve
*ecc
,
179 mp_limb_t
* r
, const mp_limb_t
* p
,
180 mp_limb_t
* scratch
);
182 /* Group operations */
185 /* Point doubling, with jacobian output and affine input. Corner
186 cases: Correctly sets R = 0 (r_Z = 0) if p = 0 or 2p = 0. */
187 mp_size_t
ecc_dup_ja_itch(const struct ecc_curve
*ecc
);
189 ecc_dup_ja(const struct ecc_curve
*ecc
,
190 mp_limb_t
* r
, const mp_limb_t
* p
,
191 mp_limb_t
* scratch
);
193 /* Point doubling, with jacobian input and output. Corner cases:
194 Correctly sets R = 0 (r_Z = 0) if p = 0 or 2p = 0. */
195 mp_size_t
ecc_dup_jj_itch(const struct ecc_curve
*ecc
);
197 ecc_dup_jj(const struct ecc_curve
*ecc
,
198 mp_limb_t
* r
, const mp_limb_t
* p
,
199 mp_limb_t
* scratch
);
202 /* Point addition, with jacobian output, one jacobian input and one
203 affine input. Corner cases: Fails for the cases
205 P = Q != 0 Duplication of non-zero point
206 P = 0, Q != 0 or P != 0, Q = 0 One input zero
208 Correctly gives R = 0 if P = Q = 0 or P = -Q. */
209 mp_size_t
ecc_add_jja_itch(const struct ecc_curve
*ecc
);
211 ecc_add_jja(const struct ecc_curve
*ecc
,
212 mp_limb_t
* r
, const mp_limb_t
* p
,
213 const mp_limb_t
* q
, mp_limb_t
* scratch
);
215 /* Point addition with Jacobian input and output. */
216 mp_size_t
ecc_add_jjj_itch(const struct ecc_curve
*ecc
);
218 ecc_add_jjj(const struct ecc_curve
*ecc
,
219 mp_limb_t
* r
, const mp_limb_t
* p
,
220 const mp_limb_t
* q
, mp_limb_t
* scratch
);
223 /* Computes N * the group generator. N is an array of ecc_size()
224 limbs. It must be in the range 0 < N < group order, then R != 0,
225 and the algorithm can work without any intermediate values getting
227 mp_size_t
ecc_mul_g_itch(const struct ecc_curve
*ecc
);
229 ecc_mul_g(const struct ecc_curve
*ecc
, mp_limb_t
* r
,
230 const mp_limb_t
* np
, mp_limb_t
* scratch
);
232 /* Computes N * P. The scalar N is the same as for ecc_mul_g. P is a
233 non-zero point on the curve, in affine coordinates. Pass a non-zero
234 INITIAL if the point coordinates have not previously been converted
235 to Montgomery representation. Output R is a non-zero point, in
236 Jacobian coordinates. */
237 mp_size_t
ecc_mul_a_itch(const struct ecc_curve
*ecc
);
239 ecc_mul_a(const struct ecc_curve
*ecc
,
240 int initial
, mp_limb_t
* r
,
241 const mp_limb_t
* np
, const mp_limb_t
* p
,
242 mp_limb_t
* scratch
);
247 #endif /* NETTLE_ECC_H_INCLUDED */