mbed TLS library
Dependents: HTTPClient-SSL WS_SERVER
include/polarssl/ecp.h@0:137634ff4186, 2015-06-11 (annotated)
- Committer:
- ansond
- Date:
- Thu Jun 11 03:27:03 2015 +0000
- Revision:
- 0:137634ff4186
initial commit
Who changed what in which revision?
User | Revision | Line number | New contents of line |
---|---|---|---|
ansond | 0:137634ff4186 | 1 | /** |
ansond | 0:137634ff4186 | 2 | * \file ecp.h |
ansond | 0:137634ff4186 | 3 | * |
ansond | 0:137634ff4186 | 4 | * \brief Elliptic curves over GF(p) |
ansond | 0:137634ff4186 | 5 | * |
ansond | 0:137634ff4186 | 6 | * Copyright (C) 2006-2013, ARM Limited, All Rights Reserved |
ansond | 0:137634ff4186 | 7 | * |
ansond | 0:137634ff4186 | 8 | * This file is part of mbed TLS (https://tls.mbed.org) |
ansond | 0:137634ff4186 | 9 | * |
ansond | 0:137634ff4186 | 10 | * This program is free software; you can redistribute it and/or modify |
ansond | 0:137634ff4186 | 11 | * it under the terms of the GNU General Public License as published by |
ansond | 0:137634ff4186 | 12 | * the Free Software Foundation; either version 2 of the License, or |
ansond | 0:137634ff4186 | 13 | * (at your option) any later version. |
ansond | 0:137634ff4186 | 14 | * |
ansond | 0:137634ff4186 | 15 | * This program is distributed in the hope that it will be useful, |
ansond | 0:137634ff4186 | 16 | * but WITHOUT ANY WARRANTY; without even the implied warranty of |
ansond | 0:137634ff4186 | 17 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
ansond | 0:137634ff4186 | 18 | * GNU General Public License for more details. |
ansond | 0:137634ff4186 | 19 | * |
ansond | 0:137634ff4186 | 20 | * You should have received a copy of the GNU General Public License along |
ansond | 0:137634ff4186 | 21 | * with this program; if not, write to the Free Software Foundation, Inc., |
ansond | 0:137634ff4186 | 22 | * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. |
ansond | 0:137634ff4186 | 23 | */ |
ansond | 0:137634ff4186 | 24 | #ifndef POLARSSL_ECP_H |
ansond | 0:137634ff4186 | 25 | #define POLARSSL_ECP_H |
ansond | 0:137634ff4186 | 26 | |
ansond | 0:137634ff4186 | 27 | #include "bignum.h" |
ansond | 0:137634ff4186 | 28 | |
ansond | 0:137634ff4186 | 29 | /* |
ansond | 0:137634ff4186 | 30 | * ECP error codes |
ansond | 0:137634ff4186 | 31 | */ |
ansond | 0:137634ff4186 | 32 | #define POLARSSL_ERR_ECP_BAD_INPUT_DATA -0x4F80 /**< Bad input parameters to function. */ |
ansond | 0:137634ff4186 | 33 | #define POLARSSL_ERR_ECP_BUFFER_TOO_SMALL -0x4F00 /**< The buffer is too small to write to. */ |
ansond | 0:137634ff4186 | 34 | #define POLARSSL_ERR_ECP_FEATURE_UNAVAILABLE -0x4E80 /**< Requested curve not available. */ |
ansond | 0:137634ff4186 | 35 | #define POLARSSL_ERR_ECP_VERIFY_FAILED -0x4E00 /**< The signature is not valid. */ |
ansond | 0:137634ff4186 | 36 | #define POLARSSL_ERR_ECP_MALLOC_FAILED -0x4D80 /**< Memory allocation failed. */ |
ansond | 0:137634ff4186 | 37 | #define POLARSSL_ERR_ECP_RANDOM_FAILED -0x4D00 /**< Generation of random value, such as (ephemeral) key, failed. */ |
ansond | 0:137634ff4186 | 38 | #define POLARSSL_ERR_ECP_INVALID_KEY -0x4C80 /**< Invalid private or public key. */ |
ansond | 0:137634ff4186 | 39 | #define POLARSSL_ERR_ECP_SIG_LEN_MISMATCH -0x4C00 /**< Signature is valid but shorter than the user-supplied length. */ |
ansond | 0:137634ff4186 | 40 | |
ansond | 0:137634ff4186 | 41 | #ifdef __cplusplus |
ansond | 0:137634ff4186 | 42 | extern "C" { |
ansond | 0:137634ff4186 | 43 | #endif |
ansond | 0:137634ff4186 | 44 | |
ansond | 0:137634ff4186 | 45 | /** |
ansond | 0:137634ff4186 | 46 | * Domain parameters (curve, subgroup and generator) identifiers. |
ansond | 0:137634ff4186 | 47 | * |
ansond | 0:137634ff4186 | 48 | * Only curves over prime fields are supported. |
ansond | 0:137634ff4186 | 49 | * |
ansond | 0:137634ff4186 | 50 | * \warning This library does not support validation of arbitrary domain |
ansond | 0:137634ff4186 | 51 | * parameters. Therefore, only well-known domain parameters from trusted |
ansond | 0:137634ff4186 | 52 | * sources should be used. See ecp_use_known_dp(). |
ansond | 0:137634ff4186 | 53 | */ |
ansond | 0:137634ff4186 | 54 | typedef enum |
ansond | 0:137634ff4186 | 55 | { |
ansond | 0:137634ff4186 | 56 | POLARSSL_ECP_DP_NONE = 0, |
ansond | 0:137634ff4186 | 57 | POLARSSL_ECP_DP_SECP192R1, /*!< 192-bits NIST curve */ |
ansond | 0:137634ff4186 | 58 | POLARSSL_ECP_DP_SECP224R1, /*!< 224-bits NIST curve */ |
ansond | 0:137634ff4186 | 59 | POLARSSL_ECP_DP_SECP256R1, /*!< 256-bits NIST curve */ |
ansond | 0:137634ff4186 | 60 | POLARSSL_ECP_DP_SECP384R1, /*!< 384-bits NIST curve */ |
ansond | 0:137634ff4186 | 61 | POLARSSL_ECP_DP_SECP521R1, /*!< 521-bits NIST curve */ |
ansond | 0:137634ff4186 | 62 | POLARSSL_ECP_DP_BP256R1, /*!< 256-bits Brainpool curve */ |
ansond | 0:137634ff4186 | 63 | POLARSSL_ECP_DP_BP384R1, /*!< 384-bits Brainpool curve */ |
ansond | 0:137634ff4186 | 64 | POLARSSL_ECP_DP_BP512R1, /*!< 512-bits Brainpool curve */ |
ansond | 0:137634ff4186 | 65 | POLARSSL_ECP_DP_M221, /*!< (not implemented yet) */ |
ansond | 0:137634ff4186 | 66 | POLARSSL_ECP_DP_M255, /*!< Curve25519 */ |
ansond | 0:137634ff4186 | 67 | POLARSSL_ECP_DP_M383, /*!< (not implemented yet) */ |
ansond | 0:137634ff4186 | 68 | POLARSSL_ECP_DP_M511, /*!< (not implemented yet) */ |
ansond | 0:137634ff4186 | 69 | POLARSSL_ECP_DP_SECP192K1, /*!< 192-bits "Koblitz" curve */ |
ansond | 0:137634ff4186 | 70 | POLARSSL_ECP_DP_SECP224K1, /*!< 224-bits "Koblitz" curve */ |
ansond | 0:137634ff4186 | 71 | POLARSSL_ECP_DP_SECP256K1, /*!< 256-bits "Koblitz" curve */ |
ansond | 0:137634ff4186 | 72 | } ecp_group_id; |
ansond | 0:137634ff4186 | 73 | |
ansond | 0:137634ff4186 | 74 | /** |
ansond | 0:137634ff4186 | 75 | * Number of supported curves (plus one for NONE). |
ansond | 0:137634ff4186 | 76 | * |
ansond | 0:137634ff4186 | 77 | * (Montgomery curves excluded for now.) |
ansond | 0:137634ff4186 | 78 | */ |
ansond | 0:137634ff4186 | 79 | #define POLARSSL_ECP_DP_MAX 12 |
ansond | 0:137634ff4186 | 80 | |
ansond | 0:137634ff4186 | 81 | /** |
ansond | 0:137634ff4186 | 82 | * Curve information for use by other modules |
ansond | 0:137634ff4186 | 83 | */ |
ansond | 0:137634ff4186 | 84 | typedef struct |
ansond | 0:137634ff4186 | 85 | { |
ansond | 0:137634ff4186 | 86 | ecp_group_id grp_id; /*!< Internal identifier */ |
ansond | 0:137634ff4186 | 87 | uint16_t tls_id; /*!< TLS NamedCurve identifier */ |
ansond | 0:137634ff4186 | 88 | uint16_t size; /*!< Curve size in bits */ |
ansond | 0:137634ff4186 | 89 | const char *name; /*!< Human-friendly name */ |
ansond | 0:137634ff4186 | 90 | } ecp_curve_info; |
ansond | 0:137634ff4186 | 91 | |
ansond | 0:137634ff4186 | 92 | /** |
ansond | 0:137634ff4186 | 93 | * \brief ECP point structure (jacobian coordinates) |
ansond | 0:137634ff4186 | 94 | * |
ansond | 0:137634ff4186 | 95 | * \note All functions expect and return points satisfying |
ansond | 0:137634ff4186 | 96 | * the following condition: Z == 0 or Z == 1. (Other |
ansond | 0:137634ff4186 | 97 | * values of Z are used by internal functions only.) |
ansond | 0:137634ff4186 | 98 | * The point is zero, or "at infinity", if Z == 0. |
ansond | 0:137634ff4186 | 99 | * Otherwise, X and Y are its standard (affine) coordinates. |
ansond | 0:137634ff4186 | 100 | */ |
ansond | 0:137634ff4186 | 101 | typedef struct |
ansond | 0:137634ff4186 | 102 | { |
ansond | 0:137634ff4186 | 103 | mpi X; /*!< the point's X coordinate */ |
ansond | 0:137634ff4186 | 104 | mpi Y; /*!< the point's Y coordinate */ |
ansond | 0:137634ff4186 | 105 | mpi Z; /*!< the point's Z coordinate */ |
ansond | 0:137634ff4186 | 106 | } |
ansond | 0:137634ff4186 | 107 | ecp_point; |
ansond | 0:137634ff4186 | 108 | |
ansond | 0:137634ff4186 | 109 | /** |
ansond | 0:137634ff4186 | 110 | * \brief ECP group structure |
ansond | 0:137634ff4186 | 111 | * |
ansond | 0:137634ff4186 | 112 | * We consider two types of curves equations: |
ansond | 0:137634ff4186 | 113 | * 1. Short Weierstrass y^2 = x^3 + A x + B mod P (SEC1 + RFC 4492) |
ansond | 0:137634ff4186 | 114 | * 2. Montgomery, y^2 = x^3 + A x^2 + x mod P (M255 + draft) |
ansond | 0:137634ff4186 | 115 | * In both cases, a generator G for a prime-order subgroup is fixed. In the |
ansond | 0:137634ff4186 | 116 | * short weierstrass, this subgroup is actually the whole curve, and its |
ansond | 0:137634ff4186 | 117 | * cardinal is denoted by N. |
ansond | 0:137634ff4186 | 118 | * |
ansond | 0:137634ff4186 | 119 | * In the case of Short Weierstrass curves, our code requires that N is an odd |
ansond | 0:137634ff4186 | 120 | * prime. (Use odd in ecp_mul() and prime in ecdsa_sign() for blinding.) |
ansond | 0:137634ff4186 | 121 | * |
ansond | 0:137634ff4186 | 122 | * In the case of Montgomery curves, we don't store A but (A + 2) / 4 which is |
ansond | 0:137634ff4186 | 123 | * the quantity actually used in the formulas. Also, nbits is not the size of N |
ansond | 0:137634ff4186 | 124 | * but the required size for private keys. |
ansond | 0:137634ff4186 | 125 | * |
ansond | 0:137634ff4186 | 126 | * If modp is NULL, reduction modulo P is done using a generic algorithm. |
ansond | 0:137634ff4186 | 127 | * Otherwise, it must point to a function that takes an mpi in the range |
ansond | 0:137634ff4186 | 128 | * 0..2^(2*pbits)-1 and transforms it in-place in an integer of little more |
ansond | 0:137634ff4186 | 129 | * than pbits, so that the integer may be efficiently brought in the 0..P-1 |
ansond | 0:137634ff4186 | 130 | * range by a few additions or substractions. It must return 0 on success and |
ansond | 0:137634ff4186 | 131 | * non-zero on failure. |
ansond | 0:137634ff4186 | 132 | */ |
ansond | 0:137634ff4186 | 133 | typedef struct |
ansond | 0:137634ff4186 | 134 | { |
ansond | 0:137634ff4186 | 135 | ecp_group_id id; /*!< internal group identifier */ |
ansond | 0:137634ff4186 | 136 | mpi P; /*!< prime modulus of the base field */ |
ansond | 0:137634ff4186 | 137 | mpi A; /*!< 1. A in the equation, or 2. (A + 2) / 4 */ |
ansond | 0:137634ff4186 | 138 | mpi B; /*!< 1. B in the equation, or 2. unused */ |
ansond | 0:137634ff4186 | 139 | ecp_point G; /*!< generator of the (sub)group used */ |
ansond | 0:137634ff4186 | 140 | mpi N; /*!< 1. the order of G, or 2. unused */ |
ansond | 0:137634ff4186 | 141 | size_t pbits; /*!< number of bits in P */ |
ansond | 0:137634ff4186 | 142 | size_t nbits; /*!< number of bits in 1. P, or 2. private keys */ |
ansond | 0:137634ff4186 | 143 | unsigned int h; /*!< internal: 1 if the constants are static */ |
ansond | 0:137634ff4186 | 144 | int (*modp)(mpi *); /*!< function for fast reduction mod P */ |
ansond | 0:137634ff4186 | 145 | int (*t_pre)(ecp_point *, void *); /*!< unused */ |
ansond | 0:137634ff4186 | 146 | int (*t_post)(ecp_point *, void *); /*!< unused */ |
ansond | 0:137634ff4186 | 147 | void *t_data; /*!< unused */ |
ansond | 0:137634ff4186 | 148 | ecp_point *T; /*!< pre-computed points for ecp_mul_comb() */ |
ansond | 0:137634ff4186 | 149 | size_t T_size; /*!< number for pre-computed points */ |
ansond | 0:137634ff4186 | 150 | } |
ansond | 0:137634ff4186 | 151 | ecp_group; |
ansond | 0:137634ff4186 | 152 | |
ansond | 0:137634ff4186 | 153 | /** |
ansond | 0:137634ff4186 | 154 | * \brief ECP key pair structure |
ansond | 0:137634ff4186 | 155 | * |
ansond | 0:137634ff4186 | 156 | * A generic key pair that could be used for ECDSA, fixed ECDH, etc. |
ansond | 0:137634ff4186 | 157 | * |
ansond | 0:137634ff4186 | 158 | * \note Members purposefully in the same order as struc ecdsa_context. |
ansond | 0:137634ff4186 | 159 | */ |
ansond | 0:137634ff4186 | 160 | typedef struct |
ansond | 0:137634ff4186 | 161 | { |
ansond | 0:137634ff4186 | 162 | ecp_group grp; /*!< Elliptic curve and base point */ |
ansond | 0:137634ff4186 | 163 | mpi d; /*!< our secret value */ |
ansond | 0:137634ff4186 | 164 | ecp_point Q; /*!< our public value */ |
ansond | 0:137634ff4186 | 165 | } |
ansond | 0:137634ff4186 | 166 | ecp_keypair; |
ansond | 0:137634ff4186 | 167 | |
ansond | 0:137634ff4186 | 168 | /** |
ansond | 0:137634ff4186 | 169 | * \name SECTION: Module settings |
ansond | 0:137634ff4186 | 170 | * |
ansond | 0:137634ff4186 | 171 | * The configuration options you can set for this module are in this section. |
ansond | 0:137634ff4186 | 172 | * Either change them in config.h or define them on the compiler command line. |
ansond | 0:137634ff4186 | 173 | * \{ |
ansond | 0:137634ff4186 | 174 | */ |
ansond | 0:137634ff4186 | 175 | |
ansond | 0:137634ff4186 | 176 | #if !defined(POLARSSL_ECP_MAX_BITS) |
ansond | 0:137634ff4186 | 177 | /** |
ansond | 0:137634ff4186 | 178 | * Maximum size of the groups (that is, of N and P) |
ansond | 0:137634ff4186 | 179 | */ |
ansond | 0:137634ff4186 | 180 | #define POLARSSL_ECP_MAX_BITS 521 /**< Maximum bit size of groups */ |
ansond | 0:137634ff4186 | 181 | #endif |
ansond | 0:137634ff4186 | 182 | |
ansond | 0:137634ff4186 | 183 | #define POLARSSL_ECP_MAX_BYTES ( ( POLARSSL_ECP_MAX_BITS + 7 ) / 8 ) |
ansond | 0:137634ff4186 | 184 | #define POLARSSL_ECP_MAX_PT_LEN ( 2 * POLARSSL_ECP_MAX_BYTES + 1 ) |
ansond | 0:137634ff4186 | 185 | |
ansond | 0:137634ff4186 | 186 | #if !defined(POLARSSL_ECP_WINDOW_SIZE) |
ansond | 0:137634ff4186 | 187 | /* |
ansond | 0:137634ff4186 | 188 | * Maximum "window" size used for point multiplication. |
ansond | 0:137634ff4186 | 189 | * Default: 6. |
ansond | 0:137634ff4186 | 190 | * Minimum value: 2. Maximum value: 7. |
ansond | 0:137634ff4186 | 191 | * |
ansond | 0:137634ff4186 | 192 | * Result is an array of at most ( 1 << ( POLARSSL_ECP_WINDOW_SIZE - 1 ) ) |
ansond | 0:137634ff4186 | 193 | * points used for point multiplication. This value is directly tied to EC |
ansond | 0:137634ff4186 | 194 | * peak memory usage, so decreasing it by one should roughly cut memory usage |
ansond | 0:137634ff4186 | 195 | * by two (if large curves are in use). |
ansond | 0:137634ff4186 | 196 | * |
ansond | 0:137634ff4186 | 197 | * Reduction in size may reduce speed, but larger curves are impacted first. |
ansond | 0:137634ff4186 | 198 | * Sample performances (in ECDHE handshakes/s, with FIXED_POINT_OPTIM = 1): |
ansond | 0:137634ff4186 | 199 | * w-size: 6 5 4 3 2 |
ansond | 0:137634ff4186 | 200 | * 521 145 141 135 120 97 |
ansond | 0:137634ff4186 | 201 | * 384 214 209 198 177 146 |
ansond | 0:137634ff4186 | 202 | * 256 320 320 303 262 226 |
ansond | 0:137634ff4186 | 203 | |
ansond | 0:137634ff4186 | 204 | * 224 475 475 453 398 342 |
ansond | 0:137634ff4186 | 205 | * 192 640 640 633 587 476 |
ansond | 0:137634ff4186 | 206 | */ |
ansond | 0:137634ff4186 | 207 | #define POLARSSL_ECP_WINDOW_SIZE 6 /**< Maximum window size used */ |
ansond | 0:137634ff4186 | 208 | #endif /* POLARSSL_ECP_WINDOW_SIZE */ |
ansond | 0:137634ff4186 | 209 | |
ansond | 0:137634ff4186 | 210 | #if !defined(POLARSSL_ECP_FIXED_POINT_OPTIM) |
ansond | 0:137634ff4186 | 211 | /* |
ansond | 0:137634ff4186 | 212 | * Trade memory for speed on fixed-point multiplication. |
ansond | 0:137634ff4186 | 213 | * |
ansond | 0:137634ff4186 | 214 | * This speeds up repeated multiplication of the generator (that is, the |
ansond | 0:137634ff4186 | 215 | * multiplication in ECDSA signatures, and half of the multiplications in |
ansond | 0:137634ff4186 | 216 | * ECDSA verification and ECDHE) by a factor roughly 3 to 4. |
ansond | 0:137634ff4186 | 217 | * |
ansond | 0:137634ff4186 | 218 | * The cost is increasing EC peak memory usage by a factor roughly 2. |
ansond | 0:137634ff4186 | 219 | * |
ansond | 0:137634ff4186 | 220 | * Change this value to 0 to reduce peak memory usage. |
ansond | 0:137634ff4186 | 221 | */ |
ansond | 0:137634ff4186 | 222 | #define POLARSSL_ECP_FIXED_POINT_OPTIM 1 /**< Enable fixed-point speed-up */ |
ansond | 0:137634ff4186 | 223 | #endif /* POLARSSL_ECP_FIXED_POINT_OPTIM */ |
ansond | 0:137634ff4186 | 224 | |
ansond | 0:137634ff4186 | 225 | /* \} name SECTION: Module settings */ |
ansond | 0:137634ff4186 | 226 | |
ansond | 0:137634ff4186 | 227 | /* |
ansond | 0:137634ff4186 | 228 | * Point formats, from RFC 4492's enum ECPointFormat |
ansond | 0:137634ff4186 | 229 | */ |
ansond | 0:137634ff4186 | 230 | #define POLARSSL_ECP_PF_UNCOMPRESSED 0 /**< Uncompressed point format */ |
ansond | 0:137634ff4186 | 231 | #define POLARSSL_ECP_PF_COMPRESSED 1 /**< Compressed point format */ |
ansond | 0:137634ff4186 | 232 | |
ansond | 0:137634ff4186 | 233 | /* |
ansond | 0:137634ff4186 | 234 | * Some other constants from RFC 4492 |
ansond | 0:137634ff4186 | 235 | */ |
ansond | 0:137634ff4186 | 236 | #define POLARSSL_ECP_TLS_NAMED_CURVE 3 /**< ECCurveType's named_curve */ |
ansond | 0:137634ff4186 | 237 | |
ansond | 0:137634ff4186 | 238 | /** |
ansond | 0:137634ff4186 | 239 | * \brief Get the list of supported curves in order of preferrence |
ansond | 0:137634ff4186 | 240 | * (full information) |
ansond | 0:137634ff4186 | 241 | * |
ansond | 0:137634ff4186 | 242 | * \return A statically allocated array, the last entry is 0. |
ansond | 0:137634ff4186 | 243 | */ |
ansond | 0:137634ff4186 | 244 | const ecp_curve_info *ecp_curve_list( void ); |
ansond | 0:137634ff4186 | 245 | |
ansond | 0:137634ff4186 | 246 | /** |
ansond | 0:137634ff4186 | 247 | * \brief Get the list of supported curves in order of preferrence |
ansond | 0:137634ff4186 | 248 | * (grp_id only) |
ansond | 0:137634ff4186 | 249 | * |
ansond | 0:137634ff4186 | 250 | * \return A statically allocated array, |
ansond | 0:137634ff4186 | 251 | * terminated with POLARSSL_ECP_DP_NONE. |
ansond | 0:137634ff4186 | 252 | */ |
ansond | 0:137634ff4186 | 253 | const ecp_group_id *ecp_grp_id_list( void ); |
ansond | 0:137634ff4186 | 254 | |
ansond | 0:137634ff4186 | 255 | /** |
ansond | 0:137634ff4186 | 256 | * \brief Get curve information from an internal group identifier |
ansond | 0:137634ff4186 | 257 | * |
ansond | 0:137634ff4186 | 258 | * \param grp_id A POLARSSL_ECP_DP_XXX value |
ansond | 0:137634ff4186 | 259 | * |
ansond | 0:137634ff4186 | 260 | * \return The associated curve information or NULL |
ansond | 0:137634ff4186 | 261 | */ |
ansond | 0:137634ff4186 | 262 | const ecp_curve_info *ecp_curve_info_from_grp_id( ecp_group_id grp_id ); |
ansond | 0:137634ff4186 | 263 | |
ansond | 0:137634ff4186 | 264 | /** |
ansond | 0:137634ff4186 | 265 | * \brief Get curve information from a TLS NamedCurve value |
ansond | 0:137634ff4186 | 266 | * |
ansond | 0:137634ff4186 | 267 | * \param tls_id A POLARSSL_ECP_DP_XXX value |
ansond | 0:137634ff4186 | 268 | * |
ansond | 0:137634ff4186 | 269 | * \return The associated curve information or NULL |
ansond | 0:137634ff4186 | 270 | */ |
ansond | 0:137634ff4186 | 271 | const ecp_curve_info *ecp_curve_info_from_tls_id( uint16_t tls_id ); |
ansond | 0:137634ff4186 | 272 | |
ansond | 0:137634ff4186 | 273 | /** |
ansond | 0:137634ff4186 | 274 | * \brief Get curve information from a human-readable name |
ansond | 0:137634ff4186 | 275 | * |
ansond | 0:137634ff4186 | 276 | * \param name The name |
ansond | 0:137634ff4186 | 277 | * |
ansond | 0:137634ff4186 | 278 | * \return The associated curve information or NULL |
ansond | 0:137634ff4186 | 279 | */ |
ansond | 0:137634ff4186 | 280 | const ecp_curve_info *ecp_curve_info_from_name( const char *name ); |
ansond | 0:137634ff4186 | 281 | |
ansond | 0:137634ff4186 | 282 | /** |
ansond | 0:137634ff4186 | 283 | * \brief Initialize a point (as zero) |
ansond | 0:137634ff4186 | 284 | */ |
ansond | 0:137634ff4186 | 285 | void ecp_point_init( ecp_point *pt ); |
ansond | 0:137634ff4186 | 286 | |
ansond | 0:137634ff4186 | 287 | /** |
ansond | 0:137634ff4186 | 288 | * \brief Initialize a group (to something meaningless) |
ansond | 0:137634ff4186 | 289 | */ |
ansond | 0:137634ff4186 | 290 | void ecp_group_init( ecp_group *grp ); |
ansond | 0:137634ff4186 | 291 | |
ansond | 0:137634ff4186 | 292 | /** |
ansond | 0:137634ff4186 | 293 | * \brief Initialize a key pair (as an invalid one) |
ansond | 0:137634ff4186 | 294 | */ |
ansond | 0:137634ff4186 | 295 | void ecp_keypair_init( ecp_keypair *key ); |
ansond | 0:137634ff4186 | 296 | |
ansond | 0:137634ff4186 | 297 | /** |
ansond | 0:137634ff4186 | 298 | * \brief Free the components of a point |
ansond | 0:137634ff4186 | 299 | */ |
ansond | 0:137634ff4186 | 300 | void ecp_point_free( ecp_point *pt ); |
ansond | 0:137634ff4186 | 301 | |
ansond | 0:137634ff4186 | 302 | /** |
ansond | 0:137634ff4186 | 303 | * \brief Free the components of an ECP group |
ansond | 0:137634ff4186 | 304 | */ |
ansond | 0:137634ff4186 | 305 | void ecp_group_free( ecp_group *grp ); |
ansond | 0:137634ff4186 | 306 | |
ansond | 0:137634ff4186 | 307 | /** |
ansond | 0:137634ff4186 | 308 | * \brief Free the components of a key pair |
ansond | 0:137634ff4186 | 309 | */ |
ansond | 0:137634ff4186 | 310 | void ecp_keypair_free( ecp_keypair *key ); |
ansond | 0:137634ff4186 | 311 | |
ansond | 0:137634ff4186 | 312 | /** |
ansond | 0:137634ff4186 | 313 | * \brief Copy the contents of point Q into P |
ansond | 0:137634ff4186 | 314 | * |
ansond | 0:137634ff4186 | 315 | * \param P Destination point |
ansond | 0:137634ff4186 | 316 | * \param Q Source point |
ansond | 0:137634ff4186 | 317 | * |
ansond | 0:137634ff4186 | 318 | * \return 0 if successful, |
ansond | 0:137634ff4186 | 319 | * POLARSSL_ERR_MPI_MALLOC_FAILED if memory allocation failed |
ansond | 0:137634ff4186 | 320 | */ |
ansond | 0:137634ff4186 | 321 | int ecp_copy( ecp_point *P, const ecp_point *Q ); |
ansond | 0:137634ff4186 | 322 | |
ansond | 0:137634ff4186 | 323 | /** |
ansond | 0:137634ff4186 | 324 | * \brief Copy the contents of a group object |
ansond | 0:137634ff4186 | 325 | * |
ansond | 0:137634ff4186 | 326 | * \param dst Destination group |
ansond | 0:137634ff4186 | 327 | * \param src Source group |
ansond | 0:137634ff4186 | 328 | * |
ansond | 0:137634ff4186 | 329 | * \return 0 if successful, |
ansond | 0:137634ff4186 | 330 | * POLARSSL_ERR_MPI_MALLOC_FAILED if memory allocation failed |
ansond | 0:137634ff4186 | 331 | */ |
ansond | 0:137634ff4186 | 332 | int ecp_group_copy( ecp_group *dst, const ecp_group *src ); |
ansond | 0:137634ff4186 | 333 | |
ansond | 0:137634ff4186 | 334 | /** |
ansond | 0:137634ff4186 | 335 | * \brief Set a point to zero |
ansond | 0:137634ff4186 | 336 | * |
ansond | 0:137634ff4186 | 337 | * \param pt Destination point |
ansond | 0:137634ff4186 | 338 | * |
ansond | 0:137634ff4186 | 339 | * \return 0 if successful, |
ansond | 0:137634ff4186 | 340 | * POLARSSL_ERR_MPI_MALLOC_FAILED if memory allocation failed |
ansond | 0:137634ff4186 | 341 | */ |
ansond | 0:137634ff4186 | 342 | int ecp_set_zero( ecp_point *pt ); |
ansond | 0:137634ff4186 | 343 | |
ansond | 0:137634ff4186 | 344 | /** |
ansond | 0:137634ff4186 | 345 | * \brief Tell if a point is zero |
ansond | 0:137634ff4186 | 346 | * |
ansond | 0:137634ff4186 | 347 | * \param pt Point to test |
ansond | 0:137634ff4186 | 348 | * |
ansond | 0:137634ff4186 | 349 | * \return 1 if point is zero, 0 otherwise |
ansond | 0:137634ff4186 | 350 | */ |
ansond | 0:137634ff4186 | 351 | int ecp_is_zero( ecp_point *pt ); |
ansond | 0:137634ff4186 | 352 | |
ansond | 0:137634ff4186 | 353 | /** |
ansond | 0:137634ff4186 | 354 | * \brief Import a non-zero point from two ASCII strings |
ansond | 0:137634ff4186 | 355 | * |
ansond | 0:137634ff4186 | 356 | * \param P Destination point |
ansond | 0:137634ff4186 | 357 | * \param radix Input numeric base |
ansond | 0:137634ff4186 | 358 | * \param x First affine coordinate as a null-terminated string |
ansond | 0:137634ff4186 | 359 | * \param y Second affine coordinate as a null-terminated string |
ansond | 0:137634ff4186 | 360 | * |
ansond | 0:137634ff4186 | 361 | * \return 0 if successful, or a POLARSSL_ERR_MPI_XXX error code |
ansond | 0:137634ff4186 | 362 | */ |
ansond | 0:137634ff4186 | 363 | int ecp_point_read_string( ecp_point *P, int radix, |
ansond | 0:137634ff4186 | 364 | const char *x, const char *y ); |
ansond | 0:137634ff4186 | 365 | |
ansond | 0:137634ff4186 | 366 | /** |
ansond | 0:137634ff4186 | 367 | * \brief Export a point into unsigned binary data |
ansond | 0:137634ff4186 | 368 | * |
ansond | 0:137634ff4186 | 369 | * \param grp Group to which the point should belong |
ansond | 0:137634ff4186 | 370 | * \param P Point to export |
ansond | 0:137634ff4186 | 371 | * \param format Point format, should be a POLARSSL_ECP_PF_XXX macro |
ansond | 0:137634ff4186 | 372 | * \param olen Length of the actual output |
ansond | 0:137634ff4186 | 373 | * \param buf Output buffer |
ansond | 0:137634ff4186 | 374 | * \param buflen Length of the output buffer |
ansond | 0:137634ff4186 | 375 | * |
ansond | 0:137634ff4186 | 376 | * \return 0 if successful, |
ansond | 0:137634ff4186 | 377 | * or POLARSSL_ERR_ECP_BAD_INPUT_DATA |
ansond | 0:137634ff4186 | 378 | * or POLARSSL_ERR_ECP_BUFFER_TOO_SMALL |
ansond | 0:137634ff4186 | 379 | */ |
ansond | 0:137634ff4186 | 380 | int ecp_point_write_binary( const ecp_group *grp, const ecp_point *P, |
ansond | 0:137634ff4186 | 381 | int format, size_t *olen, |
ansond | 0:137634ff4186 | 382 | unsigned char *buf, size_t buflen ); |
ansond | 0:137634ff4186 | 383 | |
ansond | 0:137634ff4186 | 384 | /** |
ansond | 0:137634ff4186 | 385 | * \brief Import a point from unsigned binary data |
ansond | 0:137634ff4186 | 386 | * |
ansond | 0:137634ff4186 | 387 | * \param grp Group to which the point should belong |
ansond | 0:137634ff4186 | 388 | * \param P Point to import |
ansond | 0:137634ff4186 | 389 | * \param buf Input buffer |
ansond | 0:137634ff4186 | 390 | * \param ilen Actual length of input |
ansond | 0:137634ff4186 | 391 | * |
ansond | 0:137634ff4186 | 392 | * \return 0 if successful, |
ansond | 0:137634ff4186 | 393 | * POLARSSL_ERR_ECP_BAD_INPUT_DATA if input is invalid, |
ansond | 0:137634ff4186 | 394 | * POLARSSL_ERR_MPI_MALLOC_FAILED if memory allocation failed, |
ansond | 0:137634ff4186 | 395 | * POLARSSL_ERR_ECP_FEATURE_UNAVAILABLE if the point format |
ansond | 0:137634ff4186 | 396 | * is not implemented. |
ansond | 0:137634ff4186 | 397 | * |
ansond | 0:137634ff4186 | 398 | * \note This function does NOT check that the point actually |
ansond | 0:137634ff4186 | 399 | * belongs to the given group, see ecp_check_pubkey() for |
ansond | 0:137634ff4186 | 400 | * that. |
ansond | 0:137634ff4186 | 401 | */ |
ansond | 0:137634ff4186 | 402 | int ecp_point_read_binary( const ecp_group *grp, ecp_point *P, |
ansond | 0:137634ff4186 | 403 | const unsigned char *buf, size_t ilen ); |
ansond | 0:137634ff4186 | 404 | |
ansond | 0:137634ff4186 | 405 | /** |
ansond | 0:137634ff4186 | 406 | * \brief Import a point from a TLS ECPoint record |
ansond | 0:137634ff4186 | 407 | * |
ansond | 0:137634ff4186 | 408 | * \param grp ECP group used |
ansond | 0:137634ff4186 | 409 | * \param pt Destination point |
ansond | 0:137634ff4186 | 410 | * \param buf $(Start of input buffer) |
ansond | 0:137634ff4186 | 411 | * \param len Buffer length |
ansond | 0:137634ff4186 | 412 | * |
ansond | 0:137634ff4186 | 413 | * \note buf is updated to point right after the ECPoint on exit |
ansond | 0:137634ff4186 | 414 | * |
ansond | 0:137634ff4186 | 415 | * \return 0 if successful, |
ansond | 0:137634ff4186 | 416 | * POLARSSL_ERR_MPI_XXX if initialization failed |
ansond | 0:137634ff4186 | 417 | * POLARSSL_ERR_ECP_BAD_INPUT_DATA if input is invalid |
ansond | 0:137634ff4186 | 418 | */ |
ansond | 0:137634ff4186 | 419 | int ecp_tls_read_point( const ecp_group *grp, ecp_point *pt, |
ansond | 0:137634ff4186 | 420 | const unsigned char **buf, size_t len ); |
ansond | 0:137634ff4186 | 421 | |
ansond | 0:137634ff4186 | 422 | /** |
ansond | 0:137634ff4186 | 423 | * \brief Export a point as a TLS ECPoint record |
ansond | 0:137634ff4186 | 424 | * |
ansond | 0:137634ff4186 | 425 | * \param grp ECP group used |
ansond | 0:137634ff4186 | 426 | * \param pt Point to export |
ansond | 0:137634ff4186 | 427 | * \param format Export format |
ansond | 0:137634ff4186 | 428 | * \param olen length of data written |
ansond | 0:137634ff4186 | 429 | * \param buf Buffer to write to |
ansond | 0:137634ff4186 | 430 | * \param blen Buffer length |
ansond | 0:137634ff4186 | 431 | * |
ansond | 0:137634ff4186 | 432 | * \return 0 if successful, |
ansond | 0:137634ff4186 | 433 | * or POLARSSL_ERR_ECP_BAD_INPUT_DATA |
ansond | 0:137634ff4186 | 434 | * or POLARSSL_ERR_ECP_BUFFER_TOO_SMALL |
ansond | 0:137634ff4186 | 435 | */ |
ansond | 0:137634ff4186 | 436 | int ecp_tls_write_point( const ecp_group *grp, const ecp_point *pt, |
ansond | 0:137634ff4186 | 437 | int format, size_t *olen, |
ansond | 0:137634ff4186 | 438 | unsigned char *buf, size_t blen ); |
ansond | 0:137634ff4186 | 439 | |
ansond | 0:137634ff4186 | 440 | /** |
ansond | 0:137634ff4186 | 441 | * \brief Import an ECP group from null-terminated ASCII strings |
ansond | 0:137634ff4186 | 442 | * |
ansond | 0:137634ff4186 | 443 | * \param grp Destination group |
ansond | 0:137634ff4186 | 444 | * \param radix Input numeric base |
ansond | 0:137634ff4186 | 445 | * \param p Prime modulus of the base field |
ansond | 0:137634ff4186 | 446 | * \param b Constant term in the equation |
ansond | 0:137634ff4186 | 447 | * \param gx The generator's X coordinate |
ansond | 0:137634ff4186 | 448 | * \param gy The generator's Y coordinate |
ansond | 0:137634ff4186 | 449 | * \param n The generator's order |
ansond | 0:137634ff4186 | 450 | * |
ansond | 0:137634ff4186 | 451 | * \return 0 if successful, or a POLARSSL_ERR_MPI_XXX error code |
ansond | 0:137634ff4186 | 452 | * |
ansond | 0:137634ff4186 | 453 | * \note Sets all fields except modp. |
ansond | 0:137634ff4186 | 454 | */ |
ansond | 0:137634ff4186 | 455 | int ecp_group_read_string( ecp_group *grp, int radix, |
ansond | 0:137634ff4186 | 456 | const char *p, const char *b, |
ansond | 0:137634ff4186 | 457 | const char *gx, const char *gy, const char *n); |
ansond | 0:137634ff4186 | 458 | |
ansond | 0:137634ff4186 | 459 | /** |
ansond | 0:137634ff4186 | 460 | * \brief Set a group using well-known domain parameters |
ansond | 0:137634ff4186 | 461 | * |
ansond | 0:137634ff4186 | 462 | * \param grp Destination group |
ansond | 0:137634ff4186 | 463 | * \param index Index in the list of well-known domain parameters |
ansond | 0:137634ff4186 | 464 | * |
ansond | 0:137634ff4186 | 465 | * \return 0 if successful, |
ansond | 0:137634ff4186 | 466 | * POLARSSL_ERR_MPI_XXX if initialization failed |
ansond | 0:137634ff4186 | 467 | * POLARSSL_ERR_ECP_FEATURE_UNAVAILABLE for unkownn groups |
ansond | 0:137634ff4186 | 468 | * |
ansond | 0:137634ff4186 | 469 | * \note Index should be a value of RFC 4492's enum NamdeCurve, |
ansond | 0:137634ff4186 | 470 | * possibly in the form of a POLARSSL_ECP_DP_XXX macro. |
ansond | 0:137634ff4186 | 471 | */ |
ansond | 0:137634ff4186 | 472 | int ecp_use_known_dp( ecp_group *grp, ecp_group_id index ); |
ansond | 0:137634ff4186 | 473 | |
ansond | 0:137634ff4186 | 474 | /** |
ansond | 0:137634ff4186 | 475 | * \brief Set a group from a TLS ECParameters record |
ansond | 0:137634ff4186 | 476 | * |
ansond | 0:137634ff4186 | 477 | * \param grp Destination group |
ansond | 0:137634ff4186 | 478 | * \param buf &(Start of input buffer) |
ansond | 0:137634ff4186 | 479 | * \param len Buffer length |
ansond | 0:137634ff4186 | 480 | * |
ansond | 0:137634ff4186 | 481 | * \note buf is updated to point right after ECParameters on exit |
ansond | 0:137634ff4186 | 482 | * |
ansond | 0:137634ff4186 | 483 | * \return 0 if successful, |
ansond | 0:137634ff4186 | 484 | * POLARSSL_ERR_MPI_XXX if initialization failed |
ansond | 0:137634ff4186 | 485 | * POLARSSL_ERR_ECP_BAD_INPUT_DATA if input is invalid |
ansond | 0:137634ff4186 | 486 | */ |
ansond | 0:137634ff4186 | 487 | int ecp_tls_read_group( ecp_group *grp, const unsigned char **buf, size_t len ); |
ansond | 0:137634ff4186 | 488 | |
ansond | 0:137634ff4186 | 489 | /** |
ansond | 0:137634ff4186 | 490 | * \brief Write the TLS ECParameters record for a group |
ansond | 0:137634ff4186 | 491 | * |
ansond | 0:137634ff4186 | 492 | * \param grp ECP group used |
ansond | 0:137634ff4186 | 493 | * \param olen Number of bytes actually written |
ansond | 0:137634ff4186 | 494 | * \param buf Buffer to write to |
ansond | 0:137634ff4186 | 495 | * \param blen Buffer length |
ansond | 0:137634ff4186 | 496 | * |
ansond | 0:137634ff4186 | 497 | * \return 0 if successful, |
ansond | 0:137634ff4186 | 498 | * or POLARSSL_ERR_ECP_BUFFER_TOO_SMALL |
ansond | 0:137634ff4186 | 499 | */ |
ansond | 0:137634ff4186 | 500 | int ecp_tls_write_group( const ecp_group *grp, size_t *olen, |
ansond | 0:137634ff4186 | 501 | unsigned char *buf, size_t blen ); |
ansond | 0:137634ff4186 | 502 | |
ansond | 0:137634ff4186 | 503 | /** |
ansond | 0:137634ff4186 | 504 | * \brief Addition: R = P + Q |
ansond | 0:137634ff4186 | 505 | * |
ansond | 0:137634ff4186 | 506 | * \param grp ECP group |
ansond | 0:137634ff4186 | 507 | * \param R Destination point |
ansond | 0:137634ff4186 | 508 | * \param P Left-hand point |
ansond | 0:137634ff4186 | 509 | * \param Q Right-hand point |
ansond | 0:137634ff4186 | 510 | * |
ansond | 0:137634ff4186 | 511 | * \return 0 if successful, |
ansond | 0:137634ff4186 | 512 | * POLARSSL_ERR_MPI_MALLOC_FAILED if memory allocation failed |
ansond | 0:137634ff4186 | 513 | * |
ansond | 0:137634ff4186 | 514 | * \note This function does not support Montgomery curves, such as |
ansond | 0:137634ff4186 | 515 | * Curve25519. |
ansond | 0:137634ff4186 | 516 | */ |
ansond | 0:137634ff4186 | 517 | int ecp_add( const ecp_group *grp, ecp_point *R, |
ansond | 0:137634ff4186 | 518 | const ecp_point *P, const ecp_point *Q ); |
ansond | 0:137634ff4186 | 519 | |
ansond | 0:137634ff4186 | 520 | /** |
ansond | 0:137634ff4186 | 521 | * \brief Subtraction: R = P - Q |
ansond | 0:137634ff4186 | 522 | * |
ansond | 0:137634ff4186 | 523 | * \param grp ECP group |
ansond | 0:137634ff4186 | 524 | * \param R Destination point |
ansond | 0:137634ff4186 | 525 | * \param P Left-hand point |
ansond | 0:137634ff4186 | 526 | * \param Q Right-hand point |
ansond | 0:137634ff4186 | 527 | * |
ansond | 0:137634ff4186 | 528 | * \return 0 if successful, |
ansond | 0:137634ff4186 | 529 | * POLARSSL_ERR_MPI_MALLOC_FAILED if memory allocation failed |
ansond | 0:137634ff4186 | 530 | * |
ansond | 0:137634ff4186 | 531 | * \note This function does not support Montgomery curves, such as |
ansond | 0:137634ff4186 | 532 | * Curve25519. |
ansond | 0:137634ff4186 | 533 | */ |
ansond | 0:137634ff4186 | 534 | int ecp_sub( const ecp_group *grp, ecp_point *R, |
ansond | 0:137634ff4186 | 535 | const ecp_point *P, const ecp_point *Q ); |
ansond | 0:137634ff4186 | 536 | |
ansond | 0:137634ff4186 | 537 | /** |
ansond | 0:137634ff4186 | 538 | * \brief Multiplication by an integer: R = m * P |
ansond | 0:137634ff4186 | 539 | * (Not thread-safe to use same group in multiple threads) |
ansond | 0:137634ff4186 | 540 | * |
ansond | 0:137634ff4186 | 541 | * \param grp ECP group |
ansond | 0:137634ff4186 | 542 | * \param R Destination point |
ansond | 0:137634ff4186 | 543 | * \param m Integer by which to multiply |
ansond | 0:137634ff4186 | 544 | * \param P Point to multiply |
ansond | 0:137634ff4186 | 545 | * \param f_rng RNG function (see notes) |
ansond | 0:137634ff4186 | 546 | * \param p_rng RNG parameter |
ansond | 0:137634ff4186 | 547 | * |
ansond | 0:137634ff4186 | 548 | * \return 0 if successful, |
ansond | 0:137634ff4186 | 549 | * POLARSSL_ERR_ECP_INVALID_KEY if m is not a valid privkey |
ansond | 0:137634ff4186 | 550 | * or P is not a valid pubkey, |
ansond | 0:137634ff4186 | 551 | * POLARSSL_ERR_MPI_MALLOC_FAILED if memory allocation failed |
ansond | 0:137634ff4186 | 552 | * |
ansond | 0:137634ff4186 | 553 | * \note In order to prevent timing attacks, this function |
ansond | 0:137634ff4186 | 554 | * executes the exact same sequence of (base field) |
ansond | 0:137634ff4186 | 555 | * operations for any valid m. It avoids any if-branch or |
ansond | 0:137634ff4186 | 556 | * array index depending on the value of m. |
ansond | 0:137634ff4186 | 557 | * |
ansond | 0:137634ff4186 | 558 | * \note If f_rng is not NULL, it is used to randomize intermediate |
ansond | 0:137634ff4186 | 559 | * results in order to prevent potential timing attacks |
ansond | 0:137634ff4186 | 560 | * targeting these results. It is recommended to always |
ansond | 0:137634ff4186 | 561 | * provide a non-NULL f_rng (the overhead is negligible). |
ansond | 0:137634ff4186 | 562 | */ |
ansond | 0:137634ff4186 | 563 | int ecp_mul( ecp_group *grp, ecp_point *R, |
ansond | 0:137634ff4186 | 564 | const mpi *m, const ecp_point *P, |
ansond | 0:137634ff4186 | 565 | int (*f_rng)(void *, unsigned char *, size_t), void *p_rng ); |
ansond | 0:137634ff4186 | 566 | |
ansond | 0:137634ff4186 | 567 | /** |
ansond | 0:137634ff4186 | 568 | * \brief Check that a point is a valid public key on this curve |
ansond | 0:137634ff4186 | 569 | * |
ansond | 0:137634ff4186 | 570 | * \param grp Curve/group the point should belong to |
ansond | 0:137634ff4186 | 571 | * \param pt Point to check |
ansond | 0:137634ff4186 | 572 | * |
ansond | 0:137634ff4186 | 573 | * \return 0 if point is a valid public key, |
ansond | 0:137634ff4186 | 574 | * POLARSSL_ERR_ECP_INVALID_KEY otherwise. |
ansond | 0:137634ff4186 | 575 | * |
ansond | 0:137634ff4186 | 576 | * \note This function only checks the point is non-zero, has valid |
ansond | 0:137634ff4186 | 577 | * coordinates and lies on the curve, but not that it is |
ansond | 0:137634ff4186 | 578 | * indeed a multiple of G. This is additional check is more |
ansond | 0:137634ff4186 | 579 | * expensive, isn't required by standards, and shouldn't be |
ansond | 0:137634ff4186 | 580 | * necessary if the group used has a small cofactor. In |
ansond | 0:137634ff4186 | 581 | * particular, it is useless for the NIST groups which all |
ansond | 0:137634ff4186 | 582 | * have a cofactor of 1. |
ansond | 0:137634ff4186 | 583 | * |
ansond | 0:137634ff4186 | 584 | * \note Uses bare components rather than an ecp_keypair structure |
ansond | 0:137634ff4186 | 585 | * in order to ease use with other structures such as |
ansond | 0:137634ff4186 | 586 | * ecdh_context of ecdsa_context. |
ansond | 0:137634ff4186 | 587 | */ |
ansond | 0:137634ff4186 | 588 | int ecp_check_pubkey( const ecp_group *grp, const ecp_point *pt ); |
ansond | 0:137634ff4186 | 589 | |
ansond | 0:137634ff4186 | 590 | /** |
ansond | 0:137634ff4186 | 591 | * \brief Check that an mpi is a valid private key for this curve |
ansond | 0:137634ff4186 | 592 | * |
ansond | 0:137634ff4186 | 593 | * \param grp Group used |
ansond | 0:137634ff4186 | 594 | * \param d Integer to check |
ansond | 0:137634ff4186 | 595 | * |
ansond | 0:137634ff4186 | 596 | * \return 0 if point is a valid private key, |
ansond | 0:137634ff4186 | 597 | * POLARSSL_ERR_ECP_INVALID_KEY otherwise. |
ansond | 0:137634ff4186 | 598 | * |
ansond | 0:137634ff4186 | 599 | * \note Uses bare components rather than an ecp_keypair structure |
ansond | 0:137634ff4186 | 600 | * in order to ease use with other structures such as |
ansond | 0:137634ff4186 | 601 | * ecdh_context of ecdsa_context. |
ansond | 0:137634ff4186 | 602 | */ |
ansond | 0:137634ff4186 | 603 | int ecp_check_privkey( const ecp_group *grp, const mpi *d ); |
ansond | 0:137634ff4186 | 604 | |
ansond | 0:137634ff4186 | 605 | /** |
ansond | 0:137634ff4186 | 606 | * \brief Generate a keypair |
ansond | 0:137634ff4186 | 607 | * |
ansond | 0:137634ff4186 | 608 | * \param grp ECP group |
ansond | 0:137634ff4186 | 609 | * \param d Destination MPI (secret part) |
ansond | 0:137634ff4186 | 610 | * \param Q Destination point (public part) |
ansond | 0:137634ff4186 | 611 | * \param f_rng RNG function |
ansond | 0:137634ff4186 | 612 | * \param p_rng RNG parameter |
ansond | 0:137634ff4186 | 613 | * |
ansond | 0:137634ff4186 | 614 | * \return 0 if successful, |
ansond | 0:137634ff4186 | 615 | * or a POLARSSL_ERR_ECP_XXX or POLARSSL_MPI_XXX error code |
ansond | 0:137634ff4186 | 616 | * |
ansond | 0:137634ff4186 | 617 | * \note Uses bare components rather than an ecp_keypair structure |
ansond | 0:137634ff4186 | 618 | * in order to ease use with other structures such as |
ansond | 0:137634ff4186 | 619 | * ecdh_context of ecdsa_context. |
ansond | 0:137634ff4186 | 620 | */ |
ansond | 0:137634ff4186 | 621 | int ecp_gen_keypair( ecp_group *grp, mpi *d, ecp_point *Q, |
ansond | 0:137634ff4186 | 622 | int (*f_rng)(void *, unsigned char *, size_t), |
ansond | 0:137634ff4186 | 623 | void *p_rng ); |
ansond | 0:137634ff4186 | 624 | |
ansond | 0:137634ff4186 | 625 | /** |
ansond | 0:137634ff4186 | 626 | * \brief Generate a keypair |
ansond | 0:137634ff4186 | 627 | * |
ansond | 0:137634ff4186 | 628 | * \param grp_id ECP group identifier |
ansond | 0:137634ff4186 | 629 | * \param key Destination keypair |
ansond | 0:137634ff4186 | 630 | * \param f_rng RNG function |
ansond | 0:137634ff4186 | 631 | * \param p_rng RNG parameter |
ansond | 0:137634ff4186 | 632 | * |
ansond | 0:137634ff4186 | 633 | * \return 0 if successful, |
ansond | 0:137634ff4186 | 634 | * or a POLARSSL_ERR_ECP_XXX or POLARSSL_MPI_XXX error code |
ansond | 0:137634ff4186 | 635 | */ |
ansond | 0:137634ff4186 | 636 | int ecp_gen_key( ecp_group_id grp_id, ecp_keypair *key, |
ansond | 0:137634ff4186 | 637 | int (*f_rng)(void *, unsigned char *, size_t), void *p_rng ); |
ansond | 0:137634ff4186 | 638 | |
ansond | 0:137634ff4186 | 639 | /** |
ansond | 0:137634ff4186 | 640 | * \brief Check a public-private key pair |
ansond | 0:137634ff4186 | 641 | * |
ansond | 0:137634ff4186 | 642 | * \param pub Keypair structure holding a public key |
ansond | 0:137634ff4186 | 643 | * \param prv Keypair structure holding a private (plus public) key |
ansond | 0:137634ff4186 | 644 | * |
ansond | 0:137634ff4186 | 645 | * \return 0 if successful (keys are valid and match), or |
ansond | 0:137634ff4186 | 646 | * POLARSSL_ERR_ECP_BAD_INPUT_DATA, or |
ansond | 0:137634ff4186 | 647 | * a POLARSSL_ERR_ECP_XXX or POLARSSL_ERR_MPI_XXX code. |
ansond | 0:137634ff4186 | 648 | */ |
ansond | 0:137634ff4186 | 649 | int ecp_check_pub_priv( const ecp_keypair *pub, const ecp_keypair *prv ); |
ansond | 0:137634ff4186 | 650 | |
ansond | 0:137634ff4186 | 651 | #if defined(POLARSSL_SELF_TEST) |
ansond | 0:137634ff4186 | 652 | /** |
ansond | 0:137634ff4186 | 653 | * \brief Checkup routine |
ansond | 0:137634ff4186 | 654 | * |
ansond | 0:137634ff4186 | 655 | * \return 0 if successful, or 1 if a test failed |
ansond | 0:137634ff4186 | 656 | */ |
ansond | 0:137634ff4186 | 657 | int ecp_self_test( int verbose ); |
ansond | 0:137634ff4186 | 658 | #endif |
ansond | 0:137634ff4186 | 659 | |
ansond | 0:137634ff4186 | 660 | #ifdef __cplusplus |
ansond | 0:137634ff4186 | 661 | } |
ansond | 0:137634ff4186 | 662 | #endif |
ansond | 0:137634ff4186 | 663 | |
ansond | 0:137634ff4186 | 664 | #endif /* ecp.h */ |
ansond | 0:137634ff4186 | 665 |