ecc.h 9.89 KB
Newer Older
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
/* ecc.h

   Copyright (C) 2013 Niels Möller

   This file is part of GNU Nettle.

   GNU Nettle is free software: you can redistribute it and/or
   modify it under the terms of either:

     * the GNU Lesser General Public License as published by the Free
       Software Foundation; either version 3 of the License, or (at your
       option) any later version.

   or

     * the GNU General Public License as published by the Free
       Software Foundation; either version 2 of the License, or (at your
       option) any later version.

   or both in parallel, as here.

   GNU Nettle is distributed in the hope that it will be useful,
   but WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
   General Public License for more details.

   You should have received copies of the GNU General Public License and
   the GNU Lesser General Public License along with this program.  If
   not, see http://www.gnu.org/licenses/.
*/
Niels Möller's avatar
Niels Möller committed
31

32
/* Development of Nettle's ECC support was funded by the .SE Internet Fund. */
Niels Möller's avatar
Niels Möller committed
33 34 35 36

#ifndef NETTLE_ECC_H_INCLUDED
#define NETTLE_ECC_H_INCLUDED

37
#include "nettle-types.h"
38
#include "bignum.h"
39

Niels Möller's avatar
Niels Möller committed
40 41 42 43 44
#ifdef __cplusplus
extern "C" {
#endif

/* Name mangling */
45 46 47 48
#define ecc_point_init nettle_ecc_point_init
#define ecc_point_clear nettle_ecc_point_clear
#define ecc_point_set nettle_ecc_point_set
#define ecc_point_get nettle_ecc_point_get
49 50
#define ecc_point_mul nettle_ecc_point_mul
#define ecc_point_mul_g nettle_ecc_point_mul_g
51 52 53 54 55 56
#define ecc_scalar_init nettle_ecc_scalar_init
#define ecc_scalar_clear nettle_ecc_scalar_clear
#define ecc_scalar_set nettle_ecc_scalar_set
#define ecc_scalar_get nettle_ecc_scalar_get
#define ecc_scalar_random nettle_ecc_scalar_random
#define ecc_point_mul nettle_ecc_point_mul
Niels Möller's avatar
Niels Möller committed
57
#define ecc_bit_size nettle_ecc_bit_size
Niels Möller's avatar
Niels Möller committed
58 59 60 61 62 63
#define ecc_size nettle_ecc_size
#define ecc_size_a nettle_ecc_size_a
#define ecc_size_j nettle_ecc_size_j
#define ecc_a_to_j nettle_ecc_a_to_j
#define ecc_j_to_a_itch nettle_ecc_j_to_a_itch
#define ecc_j_to_a nettle_ecc_j_to_a
64 65
#define ecc_eh_to_a_itch nettle_ecc_eh_to_a_itch
#define ecc_eh_to_a nettle_ecc_eh_to_a
66 67
#define ecc_a_to_eh_itch nettle_ecc_a_to_eh_itch
#define ecc_a_to_eh nettle_ecc_a_to_eh
Niels Möller's avatar
Niels Möller committed
68 69 70 71 72 73
#define ecc_dup_jj_itch nettle_ecc_dup_jj_itch
#define ecc_dup_jj nettle_ecc_dup_jj
#define ecc_add_jja_itch nettle_ecc_add_jja_itch
#define ecc_add_jja nettle_ecc_add_jja
#define ecc_add_jjj_itch nettle_ecc_add_jjj_itch
#define ecc_add_jjj nettle_ecc_add_jjj
74 75
#define ecc_dup_eh_itch nettle_ecc_dup_eh_itch
#define ecc_dup_eh nettle_ecc_dup_eh
Niels Möller's avatar
Niels Möller committed
76 77
#define ecc_add_eh_itch nettle_ecc_add_eh_itch
#define ecc_add_eh nettle_ecc_add_eh
78 79
#define ecc_add_ehh_itch nettle_ecc_add_ehh_itch
#define ecc_add_ehh nettle_ecc_add_ehh
Niels Möller's avatar
Niels Möller committed
80 81 82 83
#define ecc_mul_g_itch nettle_ecc_mul_g_itch
#define ecc_mul_g nettle_ecc_mul_g
#define ecc_mul_a_itch nettle_ecc_mul_a_itch
#define ecc_mul_a nettle_ecc_mul_a
84 85
#define ecc_mul_g_eh_itch nettle_ecc_mul_g_eh_itch
#define ecc_mul_g_eh nettle_ecc_mul_g_eh
86 87
#define ecc_mul_a_eh_itch nettle_ecc_mul_a_eh_itch
#define ecc_mul_a_eh nettle_ecc_mul_a_eh
Niels Möller's avatar
Niels Möller committed
88 89 90

struct ecc_curve;

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
/* High level interface, for ECDSA, DH, etc */

/* Represents a point on the ECC curve */
struct ecc_point
{
  const struct ecc_curve *ecc;
  /* Allocated using the same allocation function as GMP. */
  mp_limb_t *p;
};

/* Represents a non-zero scalar, an element of Z_q^*, where q is the
   group order of the curve. */
struct ecc_scalar
{
  const struct ecc_curve *ecc;
  /* Allocated using the same allocation function as GMP. */
  mp_limb_t *p;
};

void
ecc_point_init (struct ecc_point *p, const struct ecc_curve *ecc);
void
ecc_point_clear (struct ecc_point *p);

/* Fails and returns zero if the point is not on the curve. */
int
ecc_point_set (struct ecc_point *p, const mpz_t x, const mpz_t y);
void
ecc_point_get (const struct ecc_point *p, mpz_t x, mpz_t y);

void
ecc_scalar_init (struct ecc_scalar *s, const struct ecc_curve *ecc);
void
ecc_scalar_clear (struct ecc_scalar *s);

/* Fails and returns zero if the scalar is not in the proper range. */
int
ecc_scalar_set (struct ecc_scalar *s, const mpz_t z);
void
ecc_scalar_get (const struct ecc_scalar *s, mpz_t z);
/* Generates a random scalar, suitable as an ECDSA private key or a
   ECDH exponent. */
void
ecc_scalar_random (struct ecc_scalar *s,
		   void *random_ctx, nettle_random_func *random);

/* Computes r = n p */
void
ecc_point_mul (struct ecc_point *r, const struct ecc_scalar *n,
	       const struct ecc_point *p);

142 143 144 145
/* Computes r = n g */
void
ecc_point_mul_g (struct ecc_point *r, const struct ecc_scalar *n);

146 147 148

/* Low-level interface */
  
Niels Möller's avatar
Niels Möller committed
149 150 151 152 153 154 155 156 157 158 159 160
/* Points on a curve are represented as arrays of mp_limb_t. For some
   curves, point coordinates are represented in montgomery form. We
   use either affine coordinates x,y, or Jacobian coordinates X, Y, Z,
   where x = X/Z^2 and y = X/Z^2.

   Since we use additive notation for the groups, the infinity point
   on the curve is denoted 0. The infinity point can be represented
   with x = y = 0 in affine coordinates, and Z = 0 in Jacobian
   coordinates. However, note that most of the ECC functions do *not*
   support infinity as an input or output.
*/

Niels Möller's avatar
Niels Möller committed
161 162 163
/* Returns the bit size of a single coordinate (and of the prime p). */
unsigned
ecc_bit_size (const struct ecc_curve *ecc);
Niels Möller's avatar
Niels Möller committed
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

/* Returns the size of a single coordinate. */
mp_size_t
ecc_size (const struct ecc_curve *ecc);

/* Size of a point, using affine coordinates x, y. */
mp_size_t
ecc_size_a (const struct ecc_curve *ecc);

/* Size of a point, using jacobian coordinates X, Y and Z. */
mp_size_t
ecc_size_j (const struct ecc_curve *ecc);

/* FIXME: Rename the low-level (and side-channel silent) functions to
   _ecc_*, and provide public ecc_* functions which handle the
   infinity points properly? */

/* Converts a point P in affine coordinates into a point R in jacobian
   coordinates. If INITIAL is non-zero, and the curve uses montgomery
   coordinates, also convert coordinates to montgomery form. */
void
ecc_a_to_j (const struct ecc_curve *ecc,
	    int initial,
	    mp_limb_t *r, const mp_limb_t *p);

/* Converts a point P in jacobian coordinates into a point R in affine
   coordinates. If FLAGS has bit 0 set, and the curve uses montgomery
   coordinates, also undo the montgomery conversion. If flags has bit
   1 set, produce x coordinate only. */
mp_size_t
ecc_j_to_a_itch (const struct ecc_curve *ecc);
void
ecc_j_to_a (const struct ecc_curve *ecc,
	    int flags,
	    mp_limb_t *r, const mp_limb_t *p,
	    mp_limb_t *scratch);

201 202
/* Converts a point P on an Edwards curve to affine coordinates on
   the corresponding Montgomery curve. */
Niels Möller's avatar
Niels Möller committed
203 204

mp_size_t
205
ecc_eh_to_a_itch (const struct ecc_curve *ecc);
Niels Möller's avatar
Niels Möller committed
206
void
207 208 209 210 211
ecc_eh_to_a (const struct ecc_curve *ecc,
	     int flags,
	     mp_limb_t *r, const mp_limb_t *p,
	     mp_limb_t *scratch);

212 213 214 215 216 217 218
mp_size_t
ecc_a_to_eh_itch (const struct ecc_curve *ecc);
void
ecc_a_to_eh (const struct ecc_curve *ecc,
	     mp_limb_t *r, const mp_limb_t *p,
	     mp_limb_t *scratch);

219
/* Group operations */
Niels Möller's avatar
Niels Möller committed
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

/* Point doubling, with jacobian input and output. Corner cases:
   Correctly sets R = 0 (r_Z = 0) if p = 0 or 2p = 0. */
mp_size_t
ecc_dup_jj_itch (const struct ecc_curve *ecc);
void
ecc_dup_jj (const struct ecc_curve *ecc,
	    mp_limb_t *r, const mp_limb_t *p,
	    mp_limb_t *scratch);


/* Point addition, with jacobian output, one jacobian input and one
   affine input. Corner cases: Fails for the cases

     P = Q != 0                       Duplication of non-zero point
     P = 0, Q != 0 or P != 0, Q = 0   One input zero
   
     Correctly gives R = 0 if P = Q = 0 or P = -Q. */
mp_size_t
ecc_add_jja_itch (const struct ecc_curve *ecc);
void
ecc_add_jja (const struct ecc_curve *ecc,
	     mp_limb_t *r, const mp_limb_t *p, const mp_limb_t *q,
	     mp_limb_t *scratch);

/* Point addition with Jacobian input and output. */
mp_size_t
ecc_add_jjj_itch (const struct ecc_curve *ecc);
void
ecc_add_jjj (const struct ecc_curve *ecc,
	     mp_limb_t *r, const mp_limb_t *p, const mp_limb_t *q,
	     mp_limb_t *scratch);

253 254 255 256 257 258 259 260 261
/* FIXME: Use a generic ecc_dup, ecc_add, for any type of curve. */
/* Point doubling on an Edwards curve, with homogeneous
   cooordinates. */
mp_size_t
ecc_dup_eh_itch (const struct ecc_curve *ecc);
void
ecc_dup_eh (const struct ecc_curve *ecc,
	    mp_limb_t *r, const mp_limb_t *p,
	    mp_limb_t *scratch);
Niels Möller's avatar
Niels Möller committed
262

Niels Möller's avatar
Niels Möller committed
263 264 265 266 267 268 269
mp_size_t
ecc_add_eh_itch (const struct ecc_curve *ecc);
void
ecc_add_eh (const struct ecc_curve *ecc,
	    mp_limb_t *r, const mp_limb_t *p, const mp_limb_t *q,
	    mp_limb_t *scratch);

270 271 272 273 274 275 276
mp_size_t
ecc_add_ehh_itch (const struct ecc_curve *ecc);
void
ecc_add_ehh (const struct ecc_curve *ecc,
	     mp_limb_t *r, const mp_limb_t *p, const mp_limb_t *q,
	     mp_limb_t *scratch);

Niels Möller's avatar
Niels Möller committed
277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299
/* Computes N * the group generator. N is an array of ecc_size()
   limbs. It must be in the range 0 < N < group order, then R != 0,
   and the algorithm can work without any intermediate values getting
   to zero. */ 
mp_size_t
ecc_mul_g_itch (const struct ecc_curve *ecc);
void
ecc_mul_g (const struct ecc_curve *ecc, mp_limb_t *r,
	   const mp_limb_t *np, mp_limb_t *scratch);

/* Computes N * P. The scalar N is the same as for ecc_mul_g. P is a
   non-zero point on the curve, in affine coordinates. Pass a non-zero
   INITIAL if the point coordinates have not previously been converted
   to Montgomery representation. Output R is a non-zero point, in
   Jacobian coordinates. */
mp_size_t
ecc_mul_a_itch (const struct ecc_curve *ecc);
void
ecc_mul_a (const struct ecc_curve *ecc,
	   int initial, mp_limb_t *r,
	   const mp_limb_t *np, const mp_limb_t *p,
	   mp_limb_t *scratch);

300 301 302 303 304 305
mp_size_t
ecc_mul_g_eh_itch (const struct ecc_curve *ecc);
void
ecc_mul_g_eh (const struct ecc_curve *ecc, mp_limb_t *r,
	      const mp_limb_t *np, mp_limb_t *scratch);

306
mp_size_t
307
ecc_mul_a_eh_itch (const struct ecc_curve *ecc);
308
void
309 310 311 312
ecc_mul_a_eh (const struct ecc_curve *ecc,
	      mp_limb_t *r,
	      const mp_limb_t *np, const mp_limb_t *p,
	      mp_limb_t *scratch);
313 314


Niels Möller's avatar
Niels Möller committed
315 316 317 318 319
#ifdef __cplusplus
}
#endif

#endif /* NETTLE_ECC_H_INCLUDED */