include/nettle/ecc.h

0001 /* ecc.h
0002
0003    Copyright (C) 2013 Niels Möller
0004
0005    This file is part of GNU Nettle.
0006
0007    GNU Nettle is free software: you can redistribute it and/or
0008    modify it under the terms of either:
0009
0010      * the GNU Lesser General Public License as published by the Free
0011        Software Foundation; either version 3 of the License, or (at your
0012        option) any later version.
0013
0014    or
0015
0016      * the GNU General Public License as published by the Free
0017        Software Foundation; either version 2 of the License, or (at your
0018        option) any later version.
0019
0020    or both in parallel, as here.
0021
0022    GNU Nettle is distributed in the hope that it will be useful,
0023    but WITHOUT ANY WARRANTY; without even the implied warranty of
0024    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
0025    General Public License for more details.
0026
0027    You should have received copies of the GNU General Public License and
0028    the GNU Lesser General Public License along with this program.  If
0029    not, see http://www.gnu.org/licenses/.
0030 */
0031
0032 /* Development of Nettle's ECC support was funded by the .SE Internet Fund. */
0033
0034 #ifndef NETTLE_ECC_H_INCLUDED
0035 #define NETTLE_ECC_H_INCLUDED
0036
0037 #include "nettle-types.h"
0038 #include "bignum.h"
0039
0040 #ifdef __cplusplus
0041 extern "C" {
0042 #endif
0043
0044 /* Name mangling */
0045 #define ecc_point_init nettle_ecc_point_init
0046 #define ecc_point_clear nettle_ecc_point_clear
0047 #define ecc_point_set nettle_ecc_point_set
0048 #define ecc_point_get nettle_ecc_point_get
0049 #define ecc_point_mul nettle_ecc_point_mul
0050 #define ecc_point_mul_g nettle_ecc_point_mul_g
0051 #define ecc_scalar_init nettle_ecc_scalar_init
0052 #define ecc_scalar_clear nettle_ecc_scalar_clear
0053 #define ecc_scalar_set nettle_ecc_scalar_set
0054 #define ecc_scalar_get nettle_ecc_scalar_get
0055 #define ecc_scalar_random nettle_ecc_scalar_random
0056 #define ecc_point_mul nettle_ecc_point_mul
0057 #define ecc_bit_size nettle_ecc_bit_size
0058 #define ecc_size nettle_ecc_size
0059 #define ecc_size_a nettle_ecc_size_a
0060 #define ecc_size_j nettle_ecc_size_j
0061
0062 struct ecc_curve;
0063
0064 /* High level interface, for ECDSA, DH, etc */
0065
0066 /* Represents a point on the ECC curve */
0067 struct ecc_point
0068 {
0069   const struct ecc_curve *ecc;
0070   /* Allocated using the same allocation function as GMP. */
0071   mp_limb_t *p;
0072 };
0073
0074 /* Represents a non-zero scalar, an element of Z_q^*, where q is the
0075    group order of the curve. */
0076 struct ecc_scalar
0077 {
0078   const struct ecc_curve *ecc;
0079   /* Allocated using the same allocation function as GMP. */
0080   mp_limb_t *p;
0081 };
0082
0083 void
0084 ecc_point_init (struct ecc_point *p, const struct ecc_curve *ecc);
0085 void
0086 ecc_point_clear (struct ecc_point *p);
0087
0088 /* Fails and returns zero if the point is not on the curve. */
0089 int
0090 ecc_point_set (struct ecc_point *p, const mpz_t x, const mpz_t y);
0091 void
0092 ecc_point_get (const struct ecc_point *p, mpz_t x, mpz_t y);
0093
0094 void
0095 ecc_scalar_init (struct ecc_scalar *s, const struct ecc_curve *ecc);
0096 void
0097 ecc_scalar_clear (struct ecc_scalar *s);
0098
0099 /* Fails and returns zero if the scalar is not in the proper range. */
0100 int
0101 ecc_scalar_set (struct ecc_scalar *s, const mpz_t z);
0102 void
0103 ecc_scalar_get (const struct ecc_scalar *s, mpz_t z);
0104 /* Generates a random scalar, suitable as an ECDSA private key or a
0105    ECDH exponent. */
0106 void
0107 ecc_scalar_random (struct ecc_scalar *s,
0108            void *random_ctx, nettle_random_func *random);
0109
0110 /* Computes r = n p */
0111 void
0112 ecc_point_mul (struct ecc_point *r, const struct ecc_scalar *n,
0113            const struct ecc_point *p);
0114
0115 /* Computes r = n g */
0116 void
0117 ecc_point_mul_g (struct ecc_point *r, const struct ecc_scalar *n);
0118
0119
0120 /* Low-level interface */
0121
0122 /* Points on a curve are represented as arrays of mp_limb_t, with
0123    curve-specific representation. For the secp curves, we use Jacobian
0124    coordinates (possibly in Montgomery form for mod multiplication).
0125    For curve25519 we use homogeneous coordinates on an equivalent
0126    Edwards curve. The suffix "_h" denotes this internal
0127    representation.
0128
0129    Since we use additive notation for the groups, the infinity point
0130    on the curve is denoted 0. The infinity point can be represented
0131    with x = y = 0 in affine coordinates, and Z = 0 in Jacobian
0132    coordinates. However, note that most of the ECC functions do *not*
0133    support infinity as an input or output.
0134 */
0135
0136 /* Returns the bit size of a single coordinate (and of the prime p). */
0137 unsigned
0138 ecc_bit_size (const struct ecc_curve *ecc);
0139
0140 /* Returns the size of a single coordinate. */
0141 mp_size_t
0142 ecc_size (const struct ecc_curve *ecc);
0143
0144 /* Size of a point, using affine coordinates x, y. */
0145 mp_size_t
0146 ecc_size_a (const struct ecc_curve *ecc);
0147
0148 /* Size of a point, using jacobian coordinates X, Y and Z. */
0149 mp_size_t
0150 ecc_size_j (const struct ecc_curve *ecc);
0151
0152 /* FIXME: Define a generic ecc_dup, ecc_add, for any type of curve. Do
0153    they need to handle infinity points? */
0154
0155 #ifdef __cplusplus
0156 }
0157 #endif
0158
0159 #endif /* NETTLE_ECC_H_INCLUDED */