1 /* ecc.h 2 3 Copyright (C) 2013 Niels Möller 4 5 This file is part of GNU Nettle. 6 7 GNU Nettle is free software: you can redistribute it and/or 8 modify it under the terms of either: 9 10 * the GNU Lesser General Public License as published by the Free 11 Software Foundation; either version 3 of the License, or (at your 12 option) any later version. 13 14 or 15 16 * the GNU General Public License as published by the Free 17 Software Foundation; either version 2 of the License, or (at your 18 option) any later version. 19 20 or both in parallel, as here. 21 22 GNU Nettle is distributed in the hope that it will be useful, 23 but WITHOUT ANY WARRANTY; without even the implied warranty of 24 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 25 General Public License for more details. 26 27 You should have received copies of the GNU General Public License and 28 the GNU Lesser General Public License along with this program. If 29 not, see http://www.gnu.org/licenses/. 30 */ 31 32 /* Development of Nettle's ECC support was funded by the .SE Internet Fund. */ 33 34 #ifndef NETTLE_ECC_H_INCLUDED 35 #define NETTLE_ECC_H_INCLUDED 36 37 #include "nettle-types.h" 38 #include "bignum.h" 39 40 #ifdef __cplusplus 41 extern "C" { 42 #endif 43 44 /* Name mangling */ 45 #define ecc_point_init nettle_ecc_point_init 46 #define ecc_point_clear nettle_ecc_point_clear 47 #define ecc_point_set nettle_ecc_point_set 48 #define ecc_point_get nettle_ecc_point_get 49 #define ecc_point_mul nettle_ecc_point_mul 50 #define ecc_point_mul_g nettle_ecc_point_mul_g 51 #define ecc_scalar_init nettle_ecc_scalar_init 52 #define ecc_scalar_clear nettle_ecc_scalar_clear 53 #define ecc_scalar_set nettle_ecc_scalar_set 54 #define ecc_scalar_get nettle_ecc_scalar_get 55 #define ecc_scalar_random nettle_ecc_scalar_random 56 #define ecc_point_mul nettle_ecc_point_mul 57 #define ecc_bit_size nettle_ecc_bit_size 58 #define ecc_size nettle_ecc_size 59 #define ecc_size_a nettle_ecc_size_a 60 #define ecc_size_j nettle_ecc_size_j 61 62 struct ecc_curve; 63 64 /* High level interface, for ECDSA, DH, etc */ 65 66 /* Represents a point on the ECC curve */ 67 struct ecc_point 68 { 69 const struct ecc_curve *ecc; 70 /* Allocated using the same allocation function as GMP. */ 71 mp_limb_t *p; 72 }; 73 74 /* Represents a non-zero scalar, an element of Z_q^*, where q is the 75 group order of the curve. */ 76 struct ecc_scalar 77 { 78 const struct ecc_curve *ecc; 79 /* Allocated using the same allocation function as GMP. */ 80 mp_limb_t *p; 81 }; 82 83 void 84 ecc_point_init (struct ecc_point *p, const struct ecc_curve *ecc); 85 void 86 ecc_point_clear (struct ecc_point *p); 87 88 /* Fails and returns zero if the point is not on the curve. */ 89 int 90 ecc_point_set (struct ecc_point *p, const mpz_t x, const mpz_t y); 91 void 92 ecc_point_get (const struct ecc_point *p, mpz_t x, mpz_t y); 93 94 void 95 ecc_scalar_init (struct ecc_scalar *s, const struct ecc_curve *ecc); 96 void 97 ecc_scalar_clear (struct ecc_scalar *s); 98 99 /* Fails and returns zero if the scalar is not in the proper range. */ 100 int 101 ecc_scalar_set (struct ecc_scalar *s, const mpz_t z); 102 void 103 ecc_scalar_get (const struct ecc_scalar *s, mpz_t z); 104 /* Generates a random scalar, suitable as an ECDSA private key or a 105 ECDH exponent. */ 106 void 107 ecc_scalar_random (struct ecc_scalar *s, 108 void *random_ctx, nettle_random_func *random); 109 110 /* Computes r = n p */ 111 void 112 ecc_point_mul (struct ecc_point *r, const struct ecc_scalar *n, 113 const struct ecc_point *p); 114 115 /* Computes r = n g */ 116 void 117 ecc_point_mul_g (struct ecc_point *r, const struct ecc_scalar *n); 118 119 120 /* Low-level interface */ 121 122 /* Points on a curve are represented as arrays of mp_limb_t, with 123 curve-specific representation. For the secp curves, we use Jacobian 124 coordinates (possibly in Montgomery form for mod multiplication). 125 For curve25519 we use homogeneous coordinates on an equivalent 126 Edwards curve. The suffix "_h" denotes this internal 127 representation. 128 129 Since we use additive notation for the groups, the infinity point 130 on the curve is denoted 0. The infinity point can be represented 131 with x = y = 0 in affine coordinates, and Z = 0 in Jacobian 132 coordinates. However, note that most of the ECC functions do *not* 133 support infinity as an input or output. 134 */ 135 136 /* Returns the bit size of a single coordinate (and of the prime p). */ 137 unsigned 138 ecc_bit_size (const struct ecc_curve *ecc); 139 140 /* Returns the size of a single coordinate. */ 141 mp_size_t 142 ecc_size (const struct ecc_curve *ecc); 143 144 /* Size of a point, using affine coordinates x, y. */ 145 mp_size_t 146 ecc_size_a (const struct ecc_curve *ecc); 147 148 /* Size of a point, using jacobian coordinates X, Y and Z. */ 149 mp_size_t 150 ecc_size_j (const struct ecc_curve *ecc); 151 152 /* FIXME: Define a generic ecc_dup, ecc_add, for any type of curve. Do 153 they need to handle infinity points? */ 154 155 #ifdef __cplusplus 156 } 157 #endif 158 159 #endif /* NETTLE_ECC_H_INCLUDED */ 160