blob: 944b7f82dba62ef72719b3bae06175d4ef3ddab6 [file] [log] [blame]
Manuel Pégourié-Gonnard39d2adb2012-10-31 09:26:55 +01001/**
2 * \file ecp.h
3 *
4 * \brief Elliptic curves over GF(p)
5 *
Manuel Pégourié-Gonnard6fb81872015-07-27 11:11:48 +02006 * Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
Manuel Pégourié-Gonnard37ff1402015-09-04 14:21:07 +02007 * SPDX-License-Identifier: Apache-2.0
8 *
9 * Licensed under the Apache License, Version 2.0 (the "License"); you may
10 * not use this file except in compliance with the License.
11 * You may obtain a copy of the License at
12 *
13 * http://www.apache.org/licenses/LICENSE-2.0
14 *
15 * Unless required by applicable law or agreed to in writing, software
16 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
17 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
18 * See the License for the specific language governing permissions and
19 * limitations under the License.
Manuel Pégourié-Gonnard39d2adb2012-10-31 09:26:55 +010020 *
Manuel Pégourié-Gonnardfe446432015-03-06 13:17:10 +000021 * This file is part of mbed TLS (https://tls.mbed.org)
Manuel Pégourié-Gonnard39d2adb2012-10-31 09:26:55 +010022 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020023#ifndef MBEDTLS_ECP_H
24#define MBEDTLS_ECP_H
Manuel Pégourié-Gonnard39d2adb2012-10-31 09:26:55 +010025
Manuel Pégourié-Gonnardbdc96762013-10-03 11:50:39 +020026#include "bignum.h"
Manuel Pégourié-Gonnard39d2adb2012-10-31 09:26:55 +010027
28/*
Manuel Pégourié-Gonnard7cfcea32012-11-05 10:06:12 +010029 * ECP error codes
Manuel Pégourié-Gonnard39d2adb2012-10-31 09:26:55 +010030 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020031#define MBEDTLS_ERR_ECP_BAD_INPUT_DATA -0x4F80 /**< Bad input parameters to function. */
32#define MBEDTLS_ERR_ECP_BUFFER_TOO_SMALL -0x4F00 /**< The buffer is too small to write to. */
33#define MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE -0x4E80 /**< Requested curve not available. */
34#define MBEDTLS_ERR_ECP_VERIFY_FAILED -0x4E00 /**< The signature is not valid. */
Manuel Pégourié-Gonnard6a8ca332015-05-28 09:33:39 +020035#define MBEDTLS_ERR_ECP_ALLOC_FAILED -0x4D80 /**< Memory allocation failed. */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020036#define MBEDTLS_ERR_ECP_RANDOM_FAILED -0x4D00 /**< Generation of random value, such as (ephemeral) key, failed. */
37#define MBEDTLS_ERR_ECP_INVALID_KEY -0x4C80 /**< Invalid private or public key. */
38#define MBEDTLS_ERR_ECP_SIG_LEN_MISMATCH -0x4C00 /**< Signature is valid but shorter than the user-supplied length. */
Manuel Pégourié-Gonnard883f3132012-11-02 09:40:25 +010039
Janos Follathb0697532016-08-18 12:38:46 +010040#if !defined(MBEDTLS_ECP_ALT)
Janos Follathc44ab972016-11-18 16:38:23 +000041/*
42 * default mbed TLS elliptic curve arithmetic implementation
43 *
44 * (in case MBEDTLS_ECP_ALT is defined then the developer has to provide an
45 * alternative implementation for the whole module and it will replace this
46 * one.)
47 */
Janos Follathb0697532016-08-18 12:38:46 +010048
Paul Bakker407a0da2013-06-27 14:29:21 +020049#ifdef __cplusplus
50extern "C" {
51#endif
52
Manuel Pégourié-Gonnard39d2adb2012-10-31 09:26:55 +010053/**
Manuel Pégourié-Gonnard70380392013-09-16 16:19:53 +020054 * Domain parameters (curve, subgroup and generator) identifiers.
55 *
56 * Only curves over prime fields are supported.
57 *
58 * \warning This library does not support validation of arbitrary domain
59 * parameters. Therefore, only well-known domain parameters from trusted
Manuel Pégourié-Gonnarde3a062b2015-05-11 18:46:47 +020060 * sources should be used. See mbedtls_ecp_group_load().
Manuel Pégourié-Gonnard70380392013-09-16 16:19:53 +020061 */
62typedef enum
63{
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020064 MBEDTLS_ECP_DP_NONE = 0,
65 MBEDTLS_ECP_DP_SECP192R1, /*!< 192-bits NIST curve */
66 MBEDTLS_ECP_DP_SECP224R1, /*!< 224-bits NIST curve */
67 MBEDTLS_ECP_DP_SECP256R1, /*!< 256-bits NIST curve */
68 MBEDTLS_ECP_DP_SECP384R1, /*!< 384-bits NIST curve */
69 MBEDTLS_ECP_DP_SECP521R1, /*!< 521-bits NIST curve */
70 MBEDTLS_ECP_DP_BP256R1, /*!< 256-bits Brainpool curve */
71 MBEDTLS_ECP_DP_BP384R1, /*!< 384-bits Brainpool curve */
72 MBEDTLS_ECP_DP_BP512R1, /*!< 512-bits Brainpool curve */
Manuel Pégourié-Gonnard07894332015-06-23 00:18:41 +020073 MBEDTLS_ECP_DP_CURVE25519, /*!< Curve25519 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020074 MBEDTLS_ECP_DP_SECP192K1, /*!< 192-bits "Koblitz" curve */
75 MBEDTLS_ECP_DP_SECP224K1, /*!< 224-bits "Koblitz" curve */
76 MBEDTLS_ECP_DP_SECP256K1, /*!< 256-bits "Koblitz" curve */
77} mbedtls_ecp_group_id;
Manuel Pégourié-Gonnard70380392013-09-16 16:19:53 +020078
79/**
Manuel Pégourié-Gonnard66153662013-12-03 14:12:26 +010080 * Number of supported curves (plus one for NONE).
81 *
82 * (Montgomery curves excluded for now.)
Manuel Pégourié-Gonnardf24b4a72013-09-23 18:14:50 +020083 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020084#define MBEDTLS_ECP_DP_MAX 12
Manuel Pégourié-Gonnardf24b4a72013-09-23 18:14:50 +020085
86/**
Manuel Pégourié-Gonnardda179e42013-09-18 15:31:24 +020087 * Curve information for use by other modules
Manuel Pégourié-Gonnard568c9cf2013-09-16 17:30:04 +020088 */
89typedef struct
90{
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020091 mbedtls_ecp_group_id grp_id; /*!< Internal identifier */
Manuel Pégourié-Gonnard797f48a2015-06-18 15:45:05 +020092 uint16_t tls_id; /*!< TLS NamedCurve identifier */
93 uint16_t bit_size; /*!< Curve size in bits */
94 const char *name; /*!< Human-friendly name */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020095} mbedtls_ecp_curve_info;
Manuel Pégourié-Gonnard568c9cf2013-09-16 17:30:04 +020096
97/**
Manuel Pégourié-Gonnard1c2782c2012-11-19 20:16:28 +010098 * \brief ECP point structure (jacobian coordinates)
Manuel Pégourié-Gonnardae180d02012-11-02 18:14:40 +010099 *
Manuel Pégourié-Gonnard1c2782c2012-11-19 20:16:28 +0100100 * \note All functions expect and return points satisfying
101 * the following condition: Z == 0 or Z == 1. (Other
102 * values of Z are used by internal functions only.)
103 * The point is zero, or "at infinity", if Z == 0.
104 * Otherwise, X and Y are its standard (affine) coordinates.
Manuel Pégourié-Gonnard39d2adb2012-10-31 09:26:55 +0100105 */
106typedef struct
107{
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200108 mbedtls_mpi X; /*!< the point's X coordinate */
109 mbedtls_mpi Y; /*!< the point's Y coordinate */
110 mbedtls_mpi Z; /*!< the point's Z coordinate */
Manuel Pégourié-Gonnard39d2adb2012-10-31 09:26:55 +0100111}
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200112mbedtls_ecp_point;
Manuel Pégourié-Gonnard39d2adb2012-10-31 09:26:55 +0100113
114/**
115 * \brief ECP group structure
116 *
Manuel Pégourié-Gonnard7a949d32013-12-05 10:26:01 +0100117 * We consider two types of curves equations:
118 * 1. Short Weierstrass y^2 = x^3 + A x + B mod P (SEC1 + RFC 4492)
Manuel Pégourié-Gonnard07894332015-06-23 00:18:41 +0200119 * 2. Montgomery, y^2 = x^3 + A x^2 + x mod P (Curve25519 + draft)
Manuel Pégourié-Gonnard7a949d32013-12-05 10:26:01 +0100120 * In both cases, a generator G for a prime-order subgroup is fixed. In the
121 * short weierstrass, this subgroup is actually the whole curve, and its
122 * cardinal is denoted by N.
Manuel Pégourié-Gonnard62aad142012-11-10 00:27:12 +0100123 *
Manuel Pégourié-Gonnarddd75c312014-03-31 11:55:42 +0200124 * In the case of Short Weierstrass curves, our code requires that N is an odd
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200125 * prime. (Use odd in mbedtls_ecp_mul() and prime in mbedtls_ecdsa_sign() for blinding.)
Manuel Pégourié-Gonnarddd75c312014-03-31 11:55:42 +0200126 *
Manuel Pégourié-Gonnard7a949d32013-12-05 10:26:01 +0100127 * In the case of Montgomery curves, we don't store A but (A + 2) / 4 which is
Paul Bakker75342a62014-04-08 17:35:40 +0200128 * the quantity actually used in the formulas. Also, nbits is not the size of N
Manuel Pégourié-Gonnard7a949d32013-12-05 10:26:01 +0100129 * but the required size for private keys.
Manuel Pégourié-Gonnard47123252012-11-10 14:44:24 +0100130 *
Manuel Pégourié-Gonnardc9727702013-09-16 18:56:28 +0200131 * If modp is NULL, reduction modulo P is done using a generic algorithm.
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200132 * Otherwise, it must point to a function that takes an mbedtls_mpi in the range
Manuel Pégourié-Gonnardc9727702013-09-16 18:56:28 +0200133 * 0..2^(2*pbits)-1 and transforms it in-place in an integer of little more
134 * than pbits, so that the integer may be efficiently brought in the 0..P-1
135 * range by a few additions or substractions. It must return 0 on success and
136 * non-zero on failure.
Manuel Pégourié-Gonnard39d2adb2012-10-31 09:26:55 +0100137 */
138typedef struct
139{
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200140 mbedtls_ecp_group_id id; /*!< internal group identifier */
141 mbedtls_mpi P; /*!< prime modulus of the base field */
142 mbedtls_mpi A; /*!< 1. A in the equation, or 2. (A + 2) / 4 */
143 mbedtls_mpi B; /*!< 1. B in the equation, or 2. unused */
144 mbedtls_ecp_point G; /*!< generator of the (sub)group used */
145 mbedtls_mpi N; /*!< 1. the order of G, or 2. unused */
Manuel Pégourié-Gonnardcd7458a2013-10-08 13:11:30 +0200146 size_t pbits; /*!< number of bits in P */
Manuel Pégourié-Gonnard7a949d32013-12-05 10:26:01 +0100147 size_t nbits; /*!< number of bits in 1. P, or 2. private keys */
Manuel Pégourié-Gonnard1f82b042013-12-06 12:51:50 +0100148 unsigned int h; /*!< internal: 1 if the constants are static */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200149 int (*modp)(mbedtls_mpi *); /*!< function for fast reduction mod P */
150 int (*t_pre)(mbedtls_ecp_point *, void *); /*!< unused */
151 int (*t_post)(mbedtls_ecp_point *, void *); /*!< unused */
Manuel Pégourié-Gonnard7a949d32013-12-05 10:26:01 +0100152 void *t_data; /*!< unused */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200153 mbedtls_ecp_point *T; /*!< pre-computed points for ecp_mul_comb() */
Manuel Pégourié-Gonnardcd7458a2013-10-08 13:11:30 +0200154 size_t T_size; /*!< number for pre-computed points */
Manuel Pégourié-Gonnard39d2adb2012-10-31 09:26:55 +0100155}
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200156mbedtls_ecp_group;
Manuel Pégourié-Gonnard39d2adb2012-10-31 09:26:55 +0100157
158/**
Manuel Pégourié-Gonnardb8c6e0e2013-07-01 13:40:52 +0200159 * \brief ECP key pair structure
160 *
161 * A generic key pair that could be used for ECDSA, fixed ECDH, etc.
Manuel Pégourié-Gonnard09162dd2013-08-14 18:16:50 +0200162 *
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200163 * \note Members purposefully in the same order as struc mbedtls_ecdsa_context.
Manuel Pégourié-Gonnardb8c6e0e2013-07-01 13:40:52 +0200164 */
165typedef struct
166{
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200167 mbedtls_ecp_group grp; /*!< Elliptic curve and base point */
168 mbedtls_mpi d; /*!< our secret value */
169 mbedtls_ecp_point Q; /*!< our public value */
Manuel Pégourié-Gonnardb8c6e0e2013-07-01 13:40:52 +0200170}
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200171mbedtls_ecp_keypair;
Manuel Pégourié-Gonnardb8c6e0e2013-07-01 13:40:52 +0200172
Paul Bakker088c5c52014-04-25 11:11:10 +0200173/**
174 * \name SECTION: Module settings
175 *
176 * The configuration options you can set for this module are in this section.
177 * Either change them in config.h or define them on the compiler command line.
178 * \{
179 */
180
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200181#if !defined(MBEDTLS_ECP_MAX_BITS)
Manuel Pégourié-Gonnardb8c6e0e2013-07-01 13:40:52 +0200182/**
Manuel Pégourié-Gonnardb694b482013-08-08 13:30:57 +0200183 * Maximum size of the groups (that is, of N and P)
Manuel Pégourié-Gonnardb63f9e92012-11-21 13:00:58 +0100184 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200185#define MBEDTLS_ECP_MAX_BITS 521 /**< Maximum bit size of groups */
Paul Bakkere1b665e2013-12-11 16:02:58 +0100186#endif
187
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200188#define MBEDTLS_ECP_MAX_BYTES ( ( MBEDTLS_ECP_MAX_BITS + 7 ) / 8 )
189#define MBEDTLS_ECP_MAX_PT_LEN ( 2 * MBEDTLS_ECP_MAX_BYTES + 1 )
Manuel Pégourié-Gonnardb63f9e92012-11-21 13:00:58 +0100190
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200191#if !defined(MBEDTLS_ECP_WINDOW_SIZE)
Manuel Pégourié-Gonnard85556072012-11-17 19:54:20 +0100192/*
Manuel Pégourié-Gonnardc30200e2013-11-20 18:39:55 +0100193 * Maximum "window" size used for point multiplication.
194 * Default: 6.
195 * Minimum value: 2. Maximum value: 7.
Manuel Pégourié-Gonnard85556072012-11-17 19:54:20 +0100196 *
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200197 * Result is an array of at most ( 1 << ( MBEDTLS_ECP_WINDOW_SIZE - 1 ) )
Manuel Pégourié-Gonnard9e4191c2013-12-30 18:41:16 +0100198 * points used for point multiplication. This value is directly tied to EC
199 * peak memory usage, so decreasing it by one should roughly cut memory usage
200 * by two (if large curves are in use).
Manuel Pégourié-Gonnard85556072012-11-17 19:54:20 +0100201 *
Manuel Pégourié-Gonnard9e4191c2013-12-30 18:41:16 +0100202 * Reduction in size may reduce speed, but larger curves are impacted first.
203 * Sample performances (in ECDHE handshakes/s, with FIXED_POINT_OPTIM = 1):
204 * w-size: 6 5 4 3 2
205 * 521 145 141 135 120 97
206 * 384 214 209 198 177 146
207 * 256 320 320 303 262 226
208 * 224 475 475 453 398 342
209 * 192 640 640 633 587 476
Manuel Pégourié-Gonnard85556072012-11-17 19:54:20 +0100210 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200211#define MBEDTLS_ECP_WINDOW_SIZE 6 /**< Maximum window size used */
212#endif /* MBEDTLS_ECP_WINDOW_SIZE */
Manuel Pégourié-Gonnard9e4191c2013-12-30 18:41:16 +0100213
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200214#if !defined(MBEDTLS_ECP_FIXED_POINT_OPTIM)
Manuel Pégourié-Gonnard9e4191c2013-12-30 18:41:16 +0100215/*
216 * Trade memory for speed on fixed-point multiplication.
217 *
218 * This speeds up repeated multiplication of the generator (that is, the
219 * multiplication in ECDSA signatures, and half of the multiplications in
220 * ECDSA verification and ECDHE) by a factor roughly 3 to 4.
221 *
222 * The cost is increasing EC peak memory usage by a factor roughly 2.
223 *
224 * Change this value to 0 to reduce peak memory usage.
225 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200226#define MBEDTLS_ECP_FIXED_POINT_OPTIM 1 /**< Enable fixed-point speed-up */
227#endif /* MBEDTLS_ECP_FIXED_POINT_OPTIM */
Manuel Pégourié-Gonnard85556072012-11-17 19:54:20 +0100228
Paul Bakker088c5c52014-04-25 11:11:10 +0200229/* \} name SECTION: Module settings */
230
Manuel Pégourié-Gonnard37d218a2012-11-24 15:19:55 +0100231/*
Manuel Pégourié-Gonnard00794052013-02-09 19:00:07 +0100232 * Point formats, from RFC 4492's enum ECPointFormat
Manuel Pégourié-Gonnard37d218a2012-11-24 15:19:55 +0100233 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200234#define MBEDTLS_ECP_PF_UNCOMPRESSED 0 /**< Uncompressed point format */
235#define MBEDTLS_ECP_PF_COMPRESSED 1 /**< Compressed point format */
Manuel Pégourié-Gonnard37d218a2012-11-24 15:19:55 +0100236
Manuel Pégourié-Gonnard1a967282013-02-09 17:03:58 +0100237/*
Manuel Pégourié-Gonnard00794052013-02-09 19:00:07 +0100238 * Some other constants from RFC 4492
Manuel Pégourié-Gonnard1a967282013-02-09 17:03:58 +0100239 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200240#define MBEDTLS_ECP_TLS_NAMED_CURVE 3 /**< ECCurveType's named_curve */
Manuel Pégourié-Gonnard1a967282013-02-09 17:03:58 +0100241
Manuel Pégourié-Gonnard39d2adb2012-10-31 09:26:55 +0100242/**
Manuel Pégourié-Gonnardac719412014-02-04 14:48:50 +0100243 * \brief Get the list of supported curves in order of preferrence
244 * (full information)
Manuel Pégourié-Gonnardda179e42013-09-18 15:31:24 +0200245 *
246 * \return A statically allocated array, the last entry is 0.
247 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200248const mbedtls_ecp_curve_info *mbedtls_ecp_curve_list( void );
Manuel Pégourié-Gonnardda179e42013-09-18 15:31:24 +0200249
250/**
Manuel Pégourié-Gonnardac719412014-02-04 14:48:50 +0100251 * \brief Get the list of supported curves in order of preferrence
252 * (grp_id only)
253 *
254 * \return A statically allocated array,
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200255 * terminated with MBEDTLS_ECP_DP_NONE.
Manuel Pégourié-Gonnardac719412014-02-04 14:48:50 +0100256 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200257const mbedtls_ecp_group_id *mbedtls_ecp_grp_id_list( void );
Manuel Pégourié-Gonnardac719412014-02-04 14:48:50 +0100258
259/**
Manuel Pégourié-Gonnardcae6f3e2013-10-23 20:19:57 +0200260 * \brief Get curve information from an internal group identifier
261 *
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200262 * \param grp_id A MBEDTLS_ECP_DP_XXX value
Manuel Pégourié-Gonnardcae6f3e2013-10-23 20:19:57 +0200263 *
264 * \return The associated curve information or NULL
265 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200266const mbedtls_ecp_curve_info *mbedtls_ecp_curve_info_from_grp_id( mbedtls_ecp_group_id grp_id );
Manuel Pégourié-Gonnardcae6f3e2013-10-23 20:19:57 +0200267
268/**
269 * \brief Get curve information from a TLS NamedCurve value
270 *
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200271 * \param tls_id A MBEDTLS_ECP_DP_XXX value
Manuel Pégourié-Gonnardcae6f3e2013-10-23 20:19:57 +0200272 *
273 * \return The associated curve information or NULL
274 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200275const mbedtls_ecp_curve_info *mbedtls_ecp_curve_info_from_tls_id( uint16_t tls_id );
Manuel Pégourié-Gonnardcae6f3e2013-10-23 20:19:57 +0200276
277/**
Manuel Pégourié-Gonnard0267e3d2013-11-30 15:10:14 +0100278 * \brief Get curve information from a human-readable name
279 *
280 * \param name The name
281 *
282 * \return The associated curve information or NULL
283 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200284const mbedtls_ecp_curve_info *mbedtls_ecp_curve_info_from_name( const char *name );
Manuel Pégourié-Gonnard0267e3d2013-11-30 15:10:14 +0100285
286/**
Manuel Pégourié-Gonnard847395a2012-11-05 13:13:44 +0100287 * \brief Initialize a point (as zero)
Manuel Pégourié-Gonnardae180d02012-11-02 18:14:40 +0100288 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200289void mbedtls_ecp_point_init( mbedtls_ecp_point *pt );
Manuel Pégourié-Gonnardae180d02012-11-02 18:14:40 +0100290
291/**
Manuel Pégourié-Gonnardb505c272012-11-05 17:27:54 +0100292 * \brief Initialize a group (to something meaningless)
293 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200294void mbedtls_ecp_group_init( mbedtls_ecp_group *grp );
Manuel Pégourié-Gonnardb505c272012-11-05 17:27:54 +0100295
296/**
Manuel Pégourié-Gonnardb8c6e0e2013-07-01 13:40:52 +0200297 * \brief Initialize a key pair (as an invalid one)
298 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200299void mbedtls_ecp_keypair_init( mbedtls_ecp_keypair *key );
Manuel Pégourié-Gonnardb8c6e0e2013-07-01 13:40:52 +0200300
301/**
Manuel Pégourié-Gonnard883f3132012-11-02 09:40:25 +0100302 * \brief Free the components of a point
303 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200304void mbedtls_ecp_point_free( mbedtls_ecp_point *pt );
Manuel Pégourié-Gonnard883f3132012-11-02 09:40:25 +0100305
306/**
307 * \brief Free the components of an ECP group
308 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200309void mbedtls_ecp_group_free( mbedtls_ecp_group *grp );
Manuel Pégourié-Gonnard883f3132012-11-02 09:40:25 +0100310
311/**
Manuel Pégourié-Gonnardb8c6e0e2013-07-01 13:40:52 +0200312 * \brief Free the components of a key pair
313 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200314void mbedtls_ecp_keypair_free( mbedtls_ecp_keypair *key );
Manuel Pégourié-Gonnardb8c6e0e2013-07-01 13:40:52 +0200315
316/**
Manuel Pégourié-Gonnard883f3132012-11-02 09:40:25 +0100317 * \brief Copy the contents of point Q into P
318 *
319 * \param P Destination point
320 * \param Q Source point
321 *
Manuel Pégourié-Gonnard7cfcea32012-11-05 10:06:12 +0100322 * \return 0 if successful,
Manuel Pégourié-Gonnard6a8ca332015-05-28 09:33:39 +0200323 * MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed
Manuel Pégourié-Gonnard883f3132012-11-02 09:40:25 +0100324 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200325int mbedtls_ecp_copy( mbedtls_ecp_point *P, const mbedtls_ecp_point *Q );
Manuel Pégourié-Gonnard883f3132012-11-02 09:40:25 +0100326
327/**
Manuel Pégourié-Gonnarde09631b2013-08-12 15:44:31 +0200328 * \brief Copy the contents of a group object
329 *
330 * \param dst Destination group
331 * \param src Source group
332 *
333 * \return 0 if successful,
Manuel Pégourié-Gonnard6a8ca332015-05-28 09:33:39 +0200334 * MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed
Manuel Pégourié-Gonnarde09631b2013-08-12 15:44:31 +0200335 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200336int mbedtls_ecp_group_copy( mbedtls_ecp_group *dst, const mbedtls_ecp_group *src );
Manuel Pégourié-Gonnarde09631b2013-08-12 15:44:31 +0200337
338/**
Manuel Pégourié-Gonnardcae6f3e2013-10-23 20:19:57 +0200339 * \brief Set a point to zero
340 *
341 * \param pt Destination point
342 *
343 * \return 0 if successful,
Manuel Pégourié-Gonnard6a8ca332015-05-28 09:33:39 +0200344 * MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed
Manuel Pégourié-Gonnardcae6f3e2013-10-23 20:19:57 +0200345 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200346int mbedtls_ecp_set_zero( mbedtls_ecp_point *pt );
Manuel Pégourié-Gonnardcae6f3e2013-10-23 20:19:57 +0200347
348/**
349 * \brief Tell if a point is zero
350 *
351 * \param pt Point to test
352 *
353 * \return 1 if point is zero, 0 otherwise
354 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200355int mbedtls_ecp_is_zero( mbedtls_ecp_point *pt );
Manuel Pégourié-Gonnardcae6f3e2013-10-23 20:19:57 +0200356
357/**
Manuel Pégourié-Gonnard6029a852015-08-11 15:44:41 +0200358 * \brief Compare two points
359 *
360 * \note This assumes the points are normalized. Otherwise,
361 * they may compare as "not equal" even if they are.
362 *
363 * \param P First point to compare
364 * \param Q Second point to compare
365 *
366 * \return 0 if the points are equal,
367 * MBEDTLS_ERR_ECP_BAD_INPUT_DATA otherwise
368 */
369int mbedtls_ecp_point_cmp( const mbedtls_ecp_point *P,
370 const mbedtls_ecp_point *Q );
371
372/**
Manuel Pégourié-Gonnard847395a2012-11-05 13:13:44 +0100373 * \brief Import a non-zero point from two ASCII strings
374 *
375 * \param P Destination point
376 * \param radix Input numeric base
377 * \param x First affine coordinate as a null-terminated string
378 * \param y Second affine coordinate as a null-terminated string
379 *
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200380 * \return 0 if successful, or a MBEDTLS_ERR_MPI_XXX error code
Manuel Pégourié-Gonnard847395a2012-11-05 13:13:44 +0100381 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200382int mbedtls_ecp_point_read_string( mbedtls_ecp_point *P, int radix,
Manuel Pégourié-Gonnard847395a2012-11-05 13:13:44 +0100383 const char *x, const char *y );
384
385/**
Manuel Pégourié-Gonnard37d218a2012-11-24 15:19:55 +0100386 * \brief Export a point into unsigned binary data
Manuel Pégourié-Gonnarde19feb52012-11-24 14:10:14 +0100387 *
Manuel Pégourié-Gonnard5e402d82012-11-24 16:19:42 +0100388 * \param grp Group to which the point should belong
Manuel Pégourié-Gonnarde19feb52012-11-24 14:10:14 +0100389 * \param P Point to export
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200390 * \param format Point format, should be a MBEDTLS_ECP_PF_XXX macro
Manuel Pégourié-Gonnard00794052013-02-09 19:00:07 +0100391 * \param olen Length of the actual output
Manuel Pégourié-Gonnarde19feb52012-11-24 14:10:14 +0100392 * \param buf Output buffer
393 * \param buflen Length of the output buffer
394 *
Manuel Pégourié-Gonnard00794052013-02-09 19:00:07 +0100395 * \return 0 if successful,
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200396 * or MBEDTLS_ERR_ECP_BAD_INPUT_DATA
397 * or MBEDTLS_ERR_ECP_BUFFER_TOO_SMALL
Manuel Pégourié-Gonnarde19feb52012-11-24 14:10:14 +0100398 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200399int mbedtls_ecp_point_write_binary( const mbedtls_ecp_group *grp, const mbedtls_ecp_point *P,
Manuel Pégourié-Gonnard420f1eb2013-02-10 12:22:46 +0100400 int format, size_t *olen,
Manuel Pégourié-Gonnard7e860252013-02-10 10:58:48 +0100401 unsigned char *buf, size_t buflen );
Manuel Pégourié-Gonnarde19feb52012-11-24 14:10:14 +0100402
403/**
Manuel Pégourié-Gonnard5e402d82012-11-24 16:19:42 +0100404 * \brief Import a point from unsigned binary data
405 *
406 * \param grp Group to which the point should belong
407 * \param P Point to import
Manuel Pégourié-Gonnard5e402d82012-11-24 16:19:42 +0100408 * \param buf Input buffer
409 * \param ilen Actual length of input
410 *
411 * \return 0 if successful,
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200412 * MBEDTLS_ERR_ECP_BAD_INPUT_DATA if input is invalid,
Manuel Pégourié-Gonnard6a8ca332015-05-28 09:33:39 +0200413 * MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed,
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200414 * MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE if the point format
Manuel Pégourié-Gonnard5246ee52014-03-19 16:18:38 +0100415 * is not implemented.
Manuel Pégourié-Gonnard5e402d82012-11-24 16:19:42 +0100416 *
417 * \note This function does NOT check that the point actually
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200418 * belongs to the given group, see mbedtls_ecp_check_pubkey() for
Manuel Pégourié-Gonnard5e402d82012-11-24 16:19:42 +0100419 * that.
420 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200421int mbedtls_ecp_point_read_binary( const mbedtls_ecp_group *grp, mbedtls_ecp_point *P,
Manuel Pégourié-Gonnard7e860252013-02-10 10:58:48 +0100422 const unsigned char *buf, size_t ilen );
Manuel Pégourié-Gonnard1a967282013-02-09 17:03:58 +0100423
Manuel Pégourié-Gonnard5e402d82012-11-24 16:19:42 +0100424/**
Manuel Pégourié-Gonnardcae6f3e2013-10-23 20:19:57 +0200425 * \brief Import a point from a TLS ECPoint record
426 *
427 * \param grp ECP group used
428 * \param pt Destination point
429 * \param buf $(Start of input buffer)
430 * \param len Buffer length
431 *
Manuel Pégourié-Gonnard150c4f62014-11-21 09:14:52 +0100432 * \note buf is updated to point right after the ECPoint on exit
433 *
Manuel Pégourié-Gonnardeecb43c2015-05-12 12:56:41 +0200434 * \return 0 if successful,
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200435 * MBEDTLS_ERR_MPI_XXX if initialization failed
436 * MBEDTLS_ERR_ECP_BAD_INPUT_DATA if input is invalid
Manuel Pégourié-Gonnardcae6f3e2013-10-23 20:19:57 +0200437 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200438int mbedtls_ecp_tls_read_point( const mbedtls_ecp_group *grp, mbedtls_ecp_point *pt,
Manuel Pégourié-Gonnardcae6f3e2013-10-23 20:19:57 +0200439 const unsigned char **buf, size_t len );
440
441/**
442 * \brief Export a point as a TLS ECPoint record
443 *
444 * \param grp ECP group used
445 * \param pt Point to export
446 * \param format Export format
447 * \param olen length of data written
448 * \param buf Buffer to write to
449 * \param blen Buffer length
450 *
451 * \return 0 if successful,
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200452 * or MBEDTLS_ERR_ECP_BAD_INPUT_DATA
453 * or MBEDTLS_ERR_ECP_BUFFER_TOO_SMALL
Manuel Pégourié-Gonnardcae6f3e2013-10-23 20:19:57 +0200454 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200455int mbedtls_ecp_tls_write_point( const mbedtls_ecp_group *grp, const mbedtls_ecp_point *pt,
Manuel Pégourié-Gonnardcae6f3e2013-10-23 20:19:57 +0200456 int format, size_t *olen,
457 unsigned char *buf, size_t blen );
458
459/**
Manuel Pégourié-Gonnarda5402fe2012-11-07 20:24:05 +0100460 * \brief Set a group using well-known domain parameters
461 *
462 * \param grp Destination group
463 * \param index Index in the list of well-known domain parameters
464 *
Manuel Pégourié-Gonnardeecb43c2015-05-12 12:56:41 +0200465 * \return 0 if successful,
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200466 * MBEDTLS_ERR_MPI_XXX if initialization failed
467 * MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE for unkownn groups
Manuel Pégourié-Gonnarda5402fe2012-11-07 20:24:05 +0100468 *
Manuel Pégourié-Gonnardaff37e52015-05-11 18:11:57 +0200469 * \note Index should be a value of RFC 4492's enum NamedCurve,
470 * usually in the form of a MBEDTLS_ECP_DP_XXX macro.
Manuel Pégourié-Gonnarda5402fe2012-11-07 20:24:05 +0100471 */
Manuel Pégourié-Gonnarde3a062b2015-05-11 18:46:47 +0200472int mbedtls_ecp_group_load( mbedtls_ecp_group *grp, mbedtls_ecp_group_id index );
Manuel Pégourié-Gonnard1a967282013-02-09 17:03:58 +0100473
474/**
Manuel Pégourié-Gonnard00794052013-02-09 19:00:07 +0100475 * \brief Set a group from a TLS ECParameters record
Manuel Pégourié-Gonnard1a967282013-02-09 17:03:58 +0100476 *
477 * \param grp Destination group
Manuel Pégourié-Gonnard7c145c62013-02-10 13:20:52 +0100478 * \param buf &(Start of input buffer)
Manuel Pégourié-Gonnard1a967282013-02-09 17:03:58 +0100479 * \param len Buffer length
480 *
Manuel Pégourié-Gonnard150c4f62014-11-21 09:14:52 +0100481 * \note buf is updated to point right after ECParameters on exit
482 *
Manuel Pégourié-Gonnardeecb43c2015-05-12 12:56:41 +0200483 * \return 0 if successful,
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200484 * MBEDTLS_ERR_MPI_XXX if initialization failed
485 * MBEDTLS_ERR_ECP_BAD_INPUT_DATA if input is invalid
Manuel Pégourié-Gonnard1a967282013-02-09 17:03:58 +0100486 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200487int mbedtls_ecp_tls_read_group( mbedtls_ecp_group *grp, const unsigned char **buf, size_t len );
Manuel Pégourié-Gonnarda5402fe2012-11-07 20:24:05 +0100488
489/**
Manuel Pégourié-Gonnardb3258872013-02-10 12:06:19 +0100490 * \brief Write the TLS ECParameters record for a group
491 *
492 * \param grp ECP group used
493 * \param olen Number of bytes actually written
494 * \param buf Buffer to write to
495 * \param blen Buffer length
496 *
497 * \return 0 if successful,
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200498 * or MBEDTLS_ERR_ECP_BUFFER_TOO_SMALL
Manuel Pégourié-Gonnardb3258872013-02-10 12:06:19 +0100499 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200500int mbedtls_ecp_tls_write_group( const mbedtls_ecp_group *grp, size_t *olen,
Manuel Pégourié-Gonnardb3258872013-02-10 12:06:19 +0100501 unsigned char *buf, size_t blen );
502
503/**
Manuel Pégourié-Gonnard39d2adb2012-10-31 09:26:55 +0100504 * \brief Multiplication by an integer: R = m * P
Paul Bakker6838bd12013-09-30 13:56:38 +0200505 * (Not thread-safe to use same group in multiple threads)
Manuel Pégourié-Gonnard39d2adb2012-10-31 09:26:55 +0100506 *
Manuel Pégourié-Gonnard56cc88a2015-05-11 18:40:45 +0200507 * \note In order to prevent timing attacks, this function
508 * executes the exact same sequence of (base field)
509 * operations for any valid m. It avoids any if-branch or
510 * array index depending on the value of m.
511 *
512 * \note If f_rng is not NULL, it is used to randomize intermediate
513 * results in order to prevent potential timing attacks
514 * targeting these results. It is recommended to always
515 * provide a non-NULL f_rng (the overhead is negligible).
516 *
Manuel Pégourié-Gonnard39d2adb2012-10-31 09:26:55 +0100517 * \param grp ECP group
518 * \param R Destination point
519 * \param m Integer by which to multiply
520 * \param P Point to multiply
Manuel Pégourié-Gonnarde09d2f82013-09-02 14:29:09 +0200521 * \param f_rng RNG function (see notes)
522 * \param p_rng RNG parameter
Manuel Pégourié-Gonnard39d2adb2012-10-31 09:26:55 +0100523 *
Manuel Pégourié-Gonnard7cfcea32012-11-05 10:06:12 +0100524 * \return 0 if successful,
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200525 * MBEDTLS_ERR_ECP_INVALID_KEY if m is not a valid privkey
Manuel Pégourié-Gonnardff27b7c2013-11-21 09:28:03 +0100526 * or P is not a valid pubkey,
Manuel Pégourié-Gonnard6a8ca332015-05-28 09:33:39 +0200527 * MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed
Manuel Pégourié-Gonnard39d2adb2012-10-31 09:26:55 +0100528 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200529int mbedtls_ecp_mul( mbedtls_ecp_group *grp, mbedtls_ecp_point *R,
530 const mbedtls_mpi *m, const mbedtls_ecp_point *P,
Manuel Pégourié-Gonnard09ceaf42013-11-20 23:06:14 +0100531 int (*f_rng)(void *, unsigned char *, size_t), void *p_rng );
Manuel Pégourié-Gonnard39d2adb2012-10-31 09:26:55 +0100532
533/**
Manuel Pégourié-Gonnard56cc88a2015-05-11 18:40:45 +0200534 * \brief Multiplication and addition of two points by integers:
535 * R = m * P + n * Q
536 * (Not thread-safe to use same group in multiple threads)
537 *
Manuel Pégourié-Gonnard151dc772015-05-14 13:55:51 +0200538 * \note In contrast to mbedtls_ecp_mul(), this function does not guarantee
Manuel Pégourié-Gonnard56cc88a2015-05-11 18:40:45 +0200539 * a constant execution flow and timing.
540 *
541 * \param grp ECP group
542 * \param R Destination point
543 * \param m Integer by which to multiply P
544 * \param P Point to multiply by m
545 * \param n Integer by which to multiply Q
546 * \param Q Point to be multiplied by n
547 *
548 * \return 0 if successful,
549 * MBEDTLS_ERR_ECP_INVALID_KEY if m or n is not a valid privkey
550 * or P or Q is not a valid pubkey,
Manuel Pégourié-Gonnard6a8ca332015-05-28 09:33:39 +0200551 * MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed
Manuel Pégourié-Gonnard56cc88a2015-05-11 18:40:45 +0200552 */
553int mbedtls_ecp_muladd( mbedtls_ecp_group *grp, mbedtls_ecp_point *R,
554 const mbedtls_mpi *m, const mbedtls_ecp_point *P,
555 const mbedtls_mpi *n, const mbedtls_ecp_point *Q );
556
557/**
Manuel Pégourié-Gonnardc8dc2952013-07-01 14:06:13 +0200558 * \brief Check that a point is a valid public key on this curve
559 *
560 * \param grp Curve/group the point should belong to
561 * \param pt Point to check
562 *
563 * \return 0 if point is a valid public key,
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200564 * MBEDTLS_ERR_ECP_INVALID_KEY otherwise.
Manuel Pégourié-Gonnardc8dc2952013-07-01 14:06:13 +0200565 *
566 * \note This function only checks the point is non-zero, has valid
567 * coordinates and lies on the curve, but not that it is
568 * indeed a multiple of G. This is additional check is more
569 * expensive, isn't required by standards, and shouldn't be
570 * necessary if the group used has a small cofactor. In
571 * particular, it is useless for the NIST groups which all
572 * have a cofactor of 1.
573 *
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200574 * \note Uses bare components rather than an mbedtls_ecp_keypair structure
Manuel Pégourié-Gonnardc8dc2952013-07-01 14:06:13 +0200575 * in order to ease use with other structures such as
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200576 * mbedtls_ecdh_context of mbedtls_ecdsa_context.
Manuel Pégourié-Gonnardc8dc2952013-07-01 14:06:13 +0200577 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200578int mbedtls_ecp_check_pubkey( const mbedtls_ecp_group *grp, const mbedtls_ecp_point *pt );
Manuel Pégourié-Gonnardc8dc2952013-07-01 14:06:13 +0200579
580/**
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200581 * \brief Check that an mbedtls_mpi is a valid private key for this curve
Manuel Pégourié-Gonnardc8dc2952013-07-01 14:06:13 +0200582 *
583 * \param grp Group used
584 * \param d Integer to check
585 *
586 * \return 0 if point is a valid private key,
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200587 * MBEDTLS_ERR_ECP_INVALID_KEY otherwise.
Manuel Pégourié-Gonnardc8dc2952013-07-01 14:06:13 +0200588 *
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200589 * \note Uses bare components rather than an mbedtls_ecp_keypair structure
Manuel Pégourié-Gonnardc8dc2952013-07-01 14:06:13 +0200590 * in order to ease use with other structures such as
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200591 * mbedtls_ecdh_context of mbedtls_ecdsa_context.
Manuel Pégourié-Gonnardc8dc2952013-07-01 14:06:13 +0200592 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200593int mbedtls_ecp_check_privkey( const mbedtls_ecp_group *grp, const mbedtls_mpi *d );
Manuel Pégourié-Gonnardc8dc2952013-07-01 14:06:13 +0200594
595/**
Manuel Pégourié-Gonnardd9a3f472015-08-11 14:31:03 +0200596 * \brief Generate a keypair with configurable base point
597 *
598 * \param grp ECP group
599 * \param G Chosen base point
600 * \param d Destination MPI (secret part)
601 * \param Q Destination point (public part)
602 * \param f_rng RNG function
603 * \param p_rng RNG parameter
604 *
605 * \return 0 if successful,
606 * or a MBEDTLS_ERR_ECP_XXX or MBEDTLS_MPI_XXX error code
607 *
608 * \note Uses bare components rather than an mbedtls_ecp_keypair structure
609 * in order to ease use with other structures such as
610 * mbedtls_ecdh_context of mbedtls_ecdsa_context.
611 */
612int mbedtls_ecp_gen_keypair_base( mbedtls_ecp_group *grp,
613 const mbedtls_ecp_point *G,
614 mbedtls_mpi *d, mbedtls_ecp_point *Q,
615 int (*f_rng)(void *, unsigned char *, size_t),
616 void *p_rng );
617
618/**
Manuel Pégourié-Gonnard45a035a2013-01-26 14:42:45 +0100619 * \brief Generate a keypair
620 *
621 * \param grp ECP group
622 * \param d Destination MPI (secret part)
623 * \param Q Destination point (public part)
624 * \param f_rng RNG function
625 * \param p_rng RNG parameter
626 *
627 * \return 0 if successful,
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200628 * or a MBEDTLS_ERR_ECP_XXX or MBEDTLS_MPI_XXX error code
Manuel Pégourié-Gonnardc8dc2952013-07-01 14:06:13 +0200629 *
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200630 * \note Uses bare components rather than an mbedtls_ecp_keypair structure
Manuel Pégourié-Gonnardc8dc2952013-07-01 14:06:13 +0200631 * in order to ease use with other structures such as
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200632 * mbedtls_ecdh_context of mbedtls_ecdsa_context.
Manuel Pégourié-Gonnard45a035a2013-01-26 14:42:45 +0100633 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200634int mbedtls_ecp_gen_keypair( mbedtls_ecp_group *grp, mbedtls_mpi *d, mbedtls_ecp_point *Q,
Manuel Pégourié-Gonnard45a035a2013-01-26 14:42:45 +0100635 int (*f_rng)(void *, unsigned char *, size_t),
636 void *p_rng );
637
638/**
Manuel Pégourié-Gonnard104ee1d2013-11-30 14:13:16 +0100639 * \brief Generate a keypair
640 *
641 * \param grp_id ECP group identifier
642 * \param key Destination keypair
643 * \param f_rng RNG function
644 * \param p_rng RNG parameter
645 *
646 * \return 0 if successful,
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200647 * or a MBEDTLS_ERR_ECP_XXX or MBEDTLS_MPI_XXX error code
Manuel Pégourié-Gonnard104ee1d2013-11-30 14:13:16 +0100648 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200649int mbedtls_ecp_gen_key( mbedtls_ecp_group_id grp_id, mbedtls_ecp_keypair *key,
Manuel Pégourié-Gonnard104ee1d2013-11-30 14:13:16 +0100650 int (*f_rng)(void *, unsigned char *, size_t), void *p_rng );
651
Manuel Pégourié-Gonnard30668d62014-11-06 15:25:32 +0100652/**
653 * \brief Check a public-private key pair
654 *
655 * \param pub Keypair structure holding a public key
656 * \param prv Keypair structure holding a private (plus public) key
657 *
Manuel Pégourié-Gonnard862d5032015-04-15 11:30:46 +0200658 * \return 0 if successful (keys are valid and match), or
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200659 * MBEDTLS_ERR_ECP_BAD_INPUT_DATA, or
660 * a MBEDTLS_ERR_ECP_XXX or MBEDTLS_ERR_MPI_XXX code.
Manuel Pégourié-Gonnard30668d62014-11-06 15:25:32 +0100661 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200662int mbedtls_ecp_check_pub_priv( const mbedtls_ecp_keypair *pub, const mbedtls_ecp_keypair *prv );
Manuel Pégourié-Gonnard30668d62014-11-06 15:25:32 +0100663
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200664#if defined(MBEDTLS_SELF_TEST)
Janos Follathb0697532016-08-18 12:38:46 +0100665
Manuel Pégourié-Gonnard104ee1d2013-11-30 14:13:16 +0100666/**
Manuel Pégourié-Gonnard39d2adb2012-10-31 09:26:55 +0100667 * \brief Checkup routine
668 *
Manuel Pégourié-Gonnard13a1ef82014-03-27 20:12:44 +0100669 * \return 0 if successful, or 1 if a test failed
Manuel Pégourié-Gonnard39d2adb2012-10-31 09:26:55 +0100670 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200671int mbedtls_ecp_self_test( int verbose );
Janos Follathb0697532016-08-18 12:38:46 +0100672
Janos Follath372697b2016-10-28 16:53:11 +0100673#endif /* MBEDTLS_SELF_TEST */
Manuel Pégourié-Gonnard39d2adb2012-10-31 09:26:55 +0100674
675#ifdef __cplusplus
676}
677#endif
678
Janos Follathb0697532016-08-18 12:38:46 +0100679#else /* MBEDTLS_ECP_ALT */
680#include "ecp_alt.h"
681#endif /* MBEDTLS_ECP_ALT */
682
Paul Bakker9af723c2014-05-01 13:03:14 +0200683#endif /* ecp.h */