git.sur5r.net Git - freertos/blob - FreeRTOS-Labs/Source/mbedtls/include/mbedtls/ecp.h

   1 /**\r
   2  * \file ecp.h\r
   3  *\r
   4  * \brief This file provides an API for Elliptic Curves over GF(P) (ECP).\r
   5  *\r
   6  * The use of ECP in cryptography and TLS is defined in\r
   7  * <em>Standards for Efficient Cryptography Group (SECG): SEC1\r
   8  * Elliptic Curve Cryptography</em> and\r
   9  * <em>RFC-4492: Elliptic Curve Cryptography (ECC) Cipher Suites\r
  10  * for Transport Layer Security (TLS)</em>.\r
  11  *\r
  12  * <em>RFC-2409: The Internet Key Exchange (IKE)</em> defines ECP\r
  13  * group types.\r
  14  *\r
  15  */\r
  16 \r
  17 /*\r
  18  *  Copyright (C) 2006-2018, Arm Limited (or its affiliates), All Rights Reserved\r
  19  *  SPDX-License-Identifier: Apache-2.0\r
  20  *\r
  21  *  Licensed under the Apache License, Version 2.0 (the "License"); you may\r
  22  *  not use this file except in compliance with the License.\r
  23  *  You may obtain a copy of the License at\r
  24  *\r
  25  *  http://www.apache.org/licenses/LICENSE-2.0\r
  26  *\r
  27  *  Unless required by applicable law or agreed to in writing, software\r
  28  *  distributed under the License is distributed on an "AS IS" BASIS, WITHOUT\r
  29  *  WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\r
  30  *  See the License for the specific language governing permissions and\r
  31  *  limitations under the License.\r
  32  *\r
  33  *  This file is part of Mbed TLS (https://tls.mbed.org)\r
  34  */\r
  35 \r
  36 #ifndef MBEDTLS_ECP_H\r
  37 #define MBEDTLS_ECP_H\r
  38 \r
  39 #if !defined(MBEDTLS_CONFIG_FILE)\r
  40 #include "config.h"\r
  41 #else\r
  42 #include MBEDTLS_CONFIG_FILE\r
  43 #endif\r
  44 \r
  45 #include "bignum.h"\r
  46 \r
  47 /*\r
  48  * ECP error codes\r
  49  */\r
  50 #define MBEDTLS_ERR_ECP_BAD_INPUT_DATA                    -0x4F80  /**< Bad input parameters to function. */\r
  51 #define MBEDTLS_ERR_ECP_BUFFER_TOO_SMALL                  -0x4F00  /**< The buffer is too small to write to. */\r
  52 #define MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE               -0x4E80  /**< The requested feature is not available, for example, the requested curve is not supported. */\r
  53 #define MBEDTLS_ERR_ECP_VERIFY_FAILED                     -0x4E00  /**< The signature is not valid. */\r
  54 #define MBEDTLS_ERR_ECP_ALLOC_FAILED                      -0x4D80  /**< Memory allocation failed. */\r
  55 #define MBEDTLS_ERR_ECP_RANDOM_FAILED                     -0x4D00  /**< Generation of random value, such as ephemeral key, failed. */\r
  56 #define MBEDTLS_ERR_ECP_INVALID_KEY                       -0x4C80  /**< Invalid private or public key. */\r
  57 #define MBEDTLS_ERR_ECP_SIG_LEN_MISMATCH                  -0x4C00  /**< The buffer contains a valid signature followed by more data. */\r
  58 \r
  59 /* MBEDTLS_ERR_ECP_HW_ACCEL_FAILED is deprecated and should not be used. */\r
  60 #define MBEDTLS_ERR_ECP_HW_ACCEL_FAILED                   -0x4B80  /**< The ECP hardware accelerator failed. */\r
  61 \r
  62 #define MBEDTLS_ERR_ECP_IN_PROGRESS                       -0x4B00  /**< Operation in progress, call again with the same parameters to continue. */\r
  63 \r
  64 #ifdef __cplusplus\r
  65 extern "C" {\r
  66 #endif\r
  67 \r
  68 /**\r
  69  * Domain-parameter identifiers: curve, subgroup, and generator.\r
  70  *\r
  71  * \note Only curves over prime fields are supported.\r
  72  *\r
  73  * \warning This library does not support validation of arbitrary domain\r
  74  * parameters. Therefore, only standardized domain parameters from trusted\r
  75  * sources should be used. See mbedtls_ecp_group_load().\r
  76  */\r
  77 typedef enum\r
  78 {\r
  79     MBEDTLS_ECP_DP_NONE = 0,       /*!< Curve not defined. */\r
  80     MBEDTLS_ECP_DP_SECP192R1,      /*!< Domain parameters for the 192-bit curve defined by FIPS 186-4 and SEC1. */\r
  81     MBEDTLS_ECP_DP_SECP224R1,      /*!< Domain parameters for the 224-bit curve defined by FIPS 186-4 and SEC1. */\r
  82     MBEDTLS_ECP_DP_SECP256R1,      /*!< Domain parameters for the 256-bit curve defined by FIPS 186-4 and SEC1. */\r
  83     MBEDTLS_ECP_DP_SECP384R1,      /*!< Domain parameters for the 384-bit curve defined by FIPS 186-4 and SEC1. */\r
  84     MBEDTLS_ECP_DP_SECP521R1,      /*!< Domain parameters for the 521-bit curve defined by FIPS 186-4 and SEC1. */\r
  85     MBEDTLS_ECP_DP_BP256R1,        /*!< Domain parameters for 256-bit Brainpool curve. */\r
  86     MBEDTLS_ECP_DP_BP384R1,        /*!< Domain parameters for 384-bit Brainpool curve. */\r
  87     MBEDTLS_ECP_DP_BP512R1,        /*!< Domain parameters for 512-bit Brainpool curve. */\r
  88     MBEDTLS_ECP_DP_CURVE25519,     /*!< Domain parameters for Curve25519. */\r
  89     MBEDTLS_ECP_DP_SECP192K1,      /*!< Domain parameters for 192-bit "Koblitz" curve. */\r
  90     MBEDTLS_ECP_DP_SECP224K1,      /*!< Domain parameters for 224-bit "Koblitz" curve. */\r
  91     MBEDTLS_ECP_DP_SECP256K1,      /*!< Domain parameters for 256-bit "Koblitz" curve. */\r
  92     MBEDTLS_ECP_DP_CURVE448,       /*!< Domain parameters for Curve448. */\r
  93 } mbedtls_ecp_group_id;\r
  94 \r
  95 /**\r
  96  * The number of supported curves, plus one for #MBEDTLS_ECP_DP_NONE.\r
  97  *\r
  98  * \note Montgomery curves are currently excluded.\r
  99  */\r
 100 #define MBEDTLS_ECP_DP_MAX     12\r
 101 \r
 102 /*\r
 103  * Curve types\r
 104  */\r
 105 typedef enum\r
 106 {\r
 107     MBEDTLS_ECP_TYPE_NONE = 0,\r
 108     MBEDTLS_ECP_TYPE_SHORT_WEIERSTRASS,    /* y^2 = x^3 + a x + b      */\r
 109     MBEDTLS_ECP_TYPE_MONTGOMERY,           /* y^2 = x^3 + a x^2 + x    */\r
 110 } mbedtls_ecp_curve_type;\r
 111 \r
 112 /**\r
 113  * Curve information, for use by other modules.\r
 114  */\r
 115 typedef struct mbedtls_ecp_curve_info\r
 116 {\r
 117     mbedtls_ecp_group_id grp_id;    /*!< An internal identifier. */\r
 118     uint16_t tls_id;                /*!< The TLS NamedCurve identifier. */\r
 119     uint16_t bit_size;              /*!< The curve size in bits. */\r
 120     const char *name;               /*!< A human-friendly name. */\r
 121 } mbedtls_ecp_curve_info;\r
 122 \r
 123 /**\r
 124  * \brief           The ECP point structure, in Jacobian coordinates.\r
 125  *\r
 126  * \note            All functions expect and return points satisfying\r
 127  *                  the following condition: <code>Z == 0</code> or\r
 128  *                  <code>Z == 1</code>. Other values of \p Z are\r
 129  *                  used only by internal functions.\r
 130  *                  The point is zero, or "at infinity", if <code>Z == 0</code>.\r
 131  *                  Otherwise, \p X and \p Y are its standard (affine)\r
 132  *                  coordinates.\r
 133  */\r
 134 typedef struct mbedtls_ecp_point\r
 135 {\r
 136     mbedtls_mpi X;          /*!< The X coordinate of the ECP point. */\r
 137     mbedtls_mpi Y;          /*!< The Y coordinate of the ECP point. */\r
 138     mbedtls_mpi Z;          /*!< The Z coordinate of the ECP point. */\r
 139 }\r
 140 mbedtls_ecp_point;\r
 141 \r
 142 #if !defined(MBEDTLS_ECP_ALT)\r
 143 /*\r
 144  * default mbed TLS elliptic curve arithmetic implementation\r
 145  *\r
 146  * (in case MBEDTLS_ECP_ALT is defined then the developer has to provide an\r
 147  * alternative implementation for the whole module and it will replace this\r
 148  * one.)\r
 149  */\r
 150 \r
 151 /**\r
 152  * \brief           The ECP group structure.\r
 153  *\r
 154  * We consider two types of curve equations:\r
 155  * <ul><li>Short Weierstrass: <code>y^2 = x^3 + A x + B mod P</code>\r
 156  * (SEC1 + RFC-4492)</li>\r
 157  * <li>Montgomery: <code>y^2 = x^3 + A x^2 + x mod P</code> (Curve25519,\r
 158  * Curve448)</li></ul>\r
 159  * In both cases, the generator (\p G) for a prime-order subgroup is fixed.\r
 160  *\r
 161  * For Short Weierstrass, this subgroup is the whole curve, and its\r
 162  * cardinality is denoted by \p N. Our code requires that \p N is an\r
 163  * odd prime as mbedtls_ecp_mul() requires an odd number, and\r
 164  * mbedtls_ecdsa_sign() requires that it is prime for blinding purposes.\r
 165  *\r
 166  * For Montgomery curves, we do not store \p A, but <code>(A + 2) / 4</code>,\r
 167  * which is the quantity used in the formulas. Additionally, \p nbits is\r
 168  * not the size of \p N but the required size for private keys.\r
 169  *\r
 170  * If \p modp is NULL, reduction modulo \p P is done using a generic algorithm.\r
 171  * Otherwise, \p modp must point to a function that takes an \p mbedtls_mpi in the\r
 172  * range of <code>0..2^(2*pbits)-1</code>, and transforms it in-place to an integer\r
 173  * which is congruent mod \p P to the given MPI, and is close enough to \p pbits\r
 174  * in size, so that it may be efficiently brought in the 0..P-1 range by a few\r
 175  * additions or subtractions. Therefore, it is only an approximative modular\r
 176  * reduction. It must return 0 on success and non-zero on failure.\r
 177  *\r
 178  * \note        Alternative implementations must keep the group IDs distinct. If\r
 179  *              two group structures have the same ID, then they must be\r
 180  *              identical.\r
 181  *\r
 182  */\r
 183 typedef struct mbedtls_ecp_group\r
 184 {\r
 185     mbedtls_ecp_group_id id;    /*!< An internal group identifier. */\r
 186     mbedtls_mpi P;              /*!< The prime modulus of the base field. */\r
 187     mbedtls_mpi A;              /*!< For Short Weierstrass: \p A in the equation. For\r
 188                                      Montgomery curves: <code>(A + 2) / 4</code>. */\r
 189     mbedtls_mpi B;              /*!< For Short Weierstrass: \p B in the equation.\r
 190                                      For Montgomery curves: unused. */\r
 191     mbedtls_ecp_point G;        /*!< The generator of the subgroup used. */\r
 192     mbedtls_mpi N;              /*!< The order of \p G. */\r
 193     size_t pbits;               /*!< The number of bits in \p P.*/\r
 194     size_t nbits;               /*!< For Short Weierstrass: The number of bits in \p P.\r
 195                                      For Montgomery curves: the number of bits in the\r
 196                                      private keys. */\r
 197     unsigned int h;             /*!< \internal 1 if the constants are static. */\r
 198     int (*modp)(mbedtls_mpi *); /*!< The function for fast pseudo-reduction\r
 199                                      mod \p P (see above).*/\r
 200     int (*t_pre)(mbedtls_ecp_point *, void *);  /*!< Unused. */\r
 201     int (*t_post)(mbedtls_ecp_point *, void *); /*!< Unused. */\r
 202     void *t_data;               /*!< Unused. */\r
 203     mbedtls_ecp_point *T;       /*!< Pre-computed points for ecp_mul_comb(). */\r
 204     size_t T_size;              /*!< The number of pre-computed points. */\r
 205 }\r
 206 mbedtls_ecp_group;\r
 207 \r
 208 /**\r
 209  * \name SECTION: Module settings\r
 210  *\r
 211  * The configuration options you can set for this module are in this section.\r
 212  * Either change them in config.h, or define them using the compiler command line.\r
 213  * \{\r
 214  */\r
 215 \r
 216 #if !defined(MBEDTLS_ECP_MAX_BITS)\r
 217 /**\r
 218  * The maximum size of the groups, that is, of \c N and \c P.\r
 219  */\r
 220 #define MBEDTLS_ECP_MAX_BITS     521   /**< The maximum size of groups, in bits. */\r
 221 #endif\r
 222 \r
 223 #define MBEDTLS_ECP_MAX_BYTES    ( ( MBEDTLS_ECP_MAX_BITS + 7 ) / 8 )\r
 224 #define MBEDTLS_ECP_MAX_PT_LEN   ( 2 * MBEDTLS_ECP_MAX_BYTES + 1 )\r
 225 \r
 226 #if !defined(MBEDTLS_ECP_WINDOW_SIZE)\r
 227 /*\r
 228  * Maximum "window" size used for point multiplication.\r
 229  * Default: 6.\r
 230  * Minimum value: 2. Maximum value: 7.\r
 231  *\r
 232  * Result is an array of at most ( 1 << ( MBEDTLS_ECP_WINDOW_SIZE - 1 ) )\r
 233  * points used for point multiplication. This value is directly tied to EC\r
 234  * peak memory usage, so decreasing it by one should roughly cut memory usage\r
 235  * by two (if large curves are in use).\r
 236  *\r
 237  * Reduction in size may reduce speed, but larger curves are impacted first.\r
 238  * Sample performances (in ECDHE handshakes/s, with FIXED_POINT_OPTIM = 1):\r
 239  *      w-size:     6       5       4       3       2\r
 240  *      521       145     141     135     120      97\r
 241  *      384       214     209     198     177     146\r
 242  *      256       320     320     303     262     226\r
 243  *      224       475     475     453     398     342\r
 244  *      192       640     640     633     587     476\r
 245  */\r
 246 #define MBEDTLS_ECP_WINDOW_SIZE    6   /**< The maximum window size used. */\r
 247 #endif /* MBEDTLS_ECP_WINDOW_SIZE */\r
 248 \r
 249 #if !defined(MBEDTLS_ECP_FIXED_POINT_OPTIM)\r
 250 /*\r
 251  * Trade memory for speed on fixed-point multiplication.\r
 252  *\r
 253  * This speeds up repeated multiplication of the generator (that is, the\r
 254  * multiplication in ECDSA signatures, and half of the multiplications in\r
 255  * ECDSA verification and ECDHE) by a factor roughly 3 to 4.\r
 256  *\r
 257  * The cost is increasing EC peak memory usage by a factor roughly 2.\r
 258  *\r
 259  * Change this value to 0 to reduce peak memory usage.\r
 260  */\r
 261 #define MBEDTLS_ECP_FIXED_POINT_OPTIM  1   /**< Enable fixed-point speed-up. */\r
 262 #endif /* MBEDTLS_ECP_FIXED_POINT_OPTIM */\r
 263 \r
 264 /* \} name SECTION: Module settings */\r
 265 \r
 266 #else  /* MBEDTLS_ECP_ALT */\r
 267 #include "ecp_alt.h"\r
 268 #endif /* MBEDTLS_ECP_ALT */\r
 269 \r
 270 #if defined(MBEDTLS_ECP_RESTARTABLE)\r
 271 \r
 272 /**\r
 273  * \brief           Internal restart context for multiplication\r
 274  *\r
 275  * \note            Opaque struct\r
 276  */\r
 277 typedef struct mbedtls_ecp_restart_mul mbedtls_ecp_restart_mul_ctx;\r
 278 \r
 279 /**\r
 280  * \brief           Internal restart context for ecp_muladd()\r
 281  *\r
 282  * \note            Opaque struct\r
 283  */\r
 284 typedef struct mbedtls_ecp_restart_muladd mbedtls_ecp_restart_muladd_ctx;\r
 285 \r
 286 /**\r
 287  * \brief           General context for resuming ECC operations\r
 288  */\r
 289 typedef struct\r
 290 {\r
 291     unsigned ops_done;                  /*!<  current ops count             */\r
 292     unsigned depth;                     /*!<  call depth (0 = top-level)    */\r
 293     mbedtls_ecp_restart_mul_ctx *rsm;   /*!<  ecp_mul_comb() sub-context    */\r
 294     mbedtls_ecp_restart_muladd_ctx *ma; /*!<  ecp_muladd() sub-context      */\r
 295 } mbedtls_ecp_restart_ctx;\r
 296 \r
 297 /*\r
 298  * Operation counts for restartable functions\r
 299  */\r
 300 #define MBEDTLS_ECP_OPS_CHK   3 /*!< basic ops count for ecp_check_pubkey()  */\r
 301 #define MBEDTLS_ECP_OPS_DBL   8 /*!< basic ops count for ecp_double_jac()    */\r
 302 #define MBEDTLS_ECP_OPS_ADD  11 /*!< basic ops count for see ecp_add_mixed() */\r
 303 #define MBEDTLS_ECP_OPS_INV 120 /*!< empirical equivalent for mpi_mod_inv()  */\r
 304 \r
 305 /**\r
 306  * \brief           Internal; for restartable functions in other modules.\r
 307  *                  Check and update basic ops budget.\r
 308  *\r
 309  * \param grp       Group structure\r
 310  * \param rs_ctx    Restart context\r
 311  * \param ops       Number of basic ops to do\r
 312  *\r
 313  * \return          \c 0 if doing \p ops basic ops is still allowed,\r
 314  * \return          #MBEDTLS_ERR_ECP_IN_PROGRESS otherwise.\r
 315  */\r
 316 int mbedtls_ecp_check_budget( const mbedtls_ecp_group *grp,\r
 317                               mbedtls_ecp_restart_ctx *rs_ctx,\r
 318                               unsigned ops );\r
 319 \r
 320 /* Utility macro for checking and updating ops budget */\r
 321 #define MBEDTLS_ECP_BUDGET( ops )   \\r
 322     MBEDTLS_MPI_CHK( mbedtls_ecp_check_budget( grp, rs_ctx, \\r
 323                                                (unsigned) (ops) ) );\r
 324 \r
 325 #else /* MBEDTLS_ECP_RESTARTABLE */\r
 326 \r
 327 #define MBEDTLS_ECP_BUDGET( ops )   /* no-op; for compatibility */\r
 328 \r
 329 /* We want to declare restartable versions of existing functions anyway */\r
 330 typedef void mbedtls_ecp_restart_ctx;\r
 331 \r
 332 #endif /* MBEDTLS_ECP_RESTARTABLE */\r
 333 \r
 334 /**\r
 335  * \brief    The ECP key-pair structure.\r
 336  *\r
 337  * A generic key-pair that may be used for ECDSA and fixed ECDH, for example.\r
 338  *\r
 339  * \note    Members are deliberately in the same order as in the\r
 340  *          ::mbedtls_ecdsa_context structure.\r
 341  */\r
 342 typedef struct mbedtls_ecp_keypair\r
 343 {\r
 344     mbedtls_ecp_group grp;      /*!<  Elliptic curve and base point     */\r
 345     mbedtls_mpi d;              /*!<  our secret value                  */\r
 346     mbedtls_ecp_point Q;        /*!<  our public value                  */\r
 347 }\r
 348 mbedtls_ecp_keypair;\r
 349 \r
 350 /*\r
 351  * Point formats, from RFC 4492's enum ECPointFormat\r
 352  */\r
 353 #define MBEDTLS_ECP_PF_UNCOMPRESSED    0   /**< Uncompressed point format. */\r
 354 #define MBEDTLS_ECP_PF_COMPRESSED      1   /**< Compressed point format. */\r
 355 \r
 356 /*\r
 357  * Some other constants from RFC 4492\r
 358  */\r
 359 #define MBEDTLS_ECP_TLS_NAMED_CURVE    3   /**< The named_curve of ECCurveType. */\r
 360 \r
 361 #if defined(MBEDTLS_ECP_RESTARTABLE)\r
 362 /**\r
 363  * \brief           Set the maximum number of basic operations done in a row.\r
 364  *\r
 365  *                  If more operations are needed to complete a computation,\r
 366  *                  #MBEDTLS_ERR_ECP_IN_PROGRESS will be returned by the\r
 367  *                  function performing the computation. It is then the\r
 368  *                  caller's responsibility to either call again with the same\r
 369  *                  parameters until it returns 0 or an error code; or to free\r
 370  *                  the restart context if the operation is to be aborted.\r
 371  *\r
 372  *                  It is strictly required that all input parameters and the\r
 373  *                  restart context be the same on successive calls for the\r
 374  *                  same operation, but output parameters need not be the\r
 375  *                  same; they must not be used until the function finally\r
 376  *                  returns 0.\r
 377  *\r
 378  *                  This only applies to functions whose documentation\r
 379  *                  mentions they may return #MBEDTLS_ERR_ECP_IN_PROGRESS (or\r
 380  *                  #MBEDTLS_ERR_SSL_CRYPTO_IN_PROGRESS for functions in the\r
 381  *                  SSL module). For functions that accept a "restart context"\r
 382  *                  argument, passing NULL disables restart and makes the\r
 383  *                  function equivalent to the function with the same name\r
 384  *                  with \c _restartable removed. For functions in the ECDH\r
 385  *                  module, restart is disabled unless the function accepts\r
 386  *                  an "ECDH context" argument and\r
 387  *                  mbedtls_ecdh_enable_restart() was previously called on\r
 388  *                  that context. For function in the SSL module, restart is\r
 389  *                  only enabled for specific sides and key exchanges\r
 390  *                  (currently only for clients and ECDHE-ECDSA).\r
 391  *\r
 392  * \param max_ops   Maximum number of basic operations done in a row.\r
 393  *                  Default: 0 (unlimited).\r
 394  *                  Lower (non-zero) values mean ECC functions will block for\r
 395  *                  a lesser maximum amount of time.\r
 396  *\r
 397  * \note            A "basic operation" is defined as a rough equivalent of a\r
 398  *                  multiplication in GF(p) for the NIST P-256 curve.\r
 399  *                  As an indication, with default settings, a scalar\r
 400  *                  multiplication (full run of \c mbedtls_ecp_mul()) is:\r
 401  *                  - about 3300 basic operations for P-256\r
 402  *                  - about 9400 basic operations for P-384\r
 403  *\r
 404  * \note            Very low values are not always respected: sometimes\r
 405  *                  functions need to block for a minimum number of\r
 406  *                  operations, and will do so even if max_ops is set to a\r
 407  *                  lower value.  That minimum depends on the curve size, and\r
 408  *                  can be made lower by decreasing the value of\r
 409  *                  \c MBEDTLS_ECP_WINDOW_SIZE.  As an indication, here is the\r
 410  *                  lowest effective value for various curves and values of\r
 411  *                  that parameter (w for short):\r
 412  *                          w=6     w=5     w=4     w=3     w=2\r
 413  *                  P-256   208     208     160     136     124\r
 414  *                  P-384   682     416     320     272     248\r
 415  *                  P-521  1364     832     640     544     496\r
 416  *\r
 417  * \note            This setting is currently ignored by Curve25519.\r
 418  */\r
 419 void mbedtls_ecp_set_max_ops( unsigned max_ops );\r
 420 \r
 421 /**\r
 422  * \brief           Check if restart is enabled (max_ops != 0)\r
 423  *\r
 424  * \return          \c 0 if \c max_ops == 0 (restart disabled)\r
 425  * \return          \c 1 otherwise (restart enabled)\r
 426  */\r
 427 int mbedtls_ecp_restart_is_enabled( void );\r
 428 #endif /* MBEDTLS_ECP_RESTARTABLE */\r
 429 \r
 430 /*\r
 431  * Get the type of a curve\r
 432  */\r
 433 mbedtls_ecp_curve_type mbedtls_ecp_get_type( const mbedtls_ecp_group *grp );\r
 434 \r
 435 /**\r
 436  * \brief           This function retrieves the information defined in\r
 437  *                  mbedtls_ecp_curve_info() for all supported curves in order\r
 438  *                  of preference.\r
 439  *\r
 440  * \return          A statically allocated array. The last entry is 0.\r
 441  */\r
 442 const mbedtls_ecp_curve_info *mbedtls_ecp_curve_list( void );\r
 443 \r
 444 /**\r
 445  * \brief           This function retrieves the list of internal group\r
 446  *                  identifiers of all supported curves in the order of\r
 447  *                  preference.\r
 448  *\r
 449  * \return          A statically allocated array,\r
 450  *                  terminated with MBEDTLS_ECP_DP_NONE.\r
 451  */\r
 452 const mbedtls_ecp_group_id *mbedtls_ecp_grp_id_list( void );\r
 453 \r
 454 /**\r
 455  * \brief           This function retrieves curve information from an internal\r
 456  *                  group identifier.\r
 457  *\r
 458  * \param grp_id    An \c MBEDTLS_ECP_DP_XXX value.\r
 459  *\r
 460  * \return          The associated curve information on success.\r
 461  * \return          NULL on failure.\r
 462  */\r
 463 const mbedtls_ecp_curve_info *mbedtls_ecp_curve_info_from_grp_id( mbedtls_ecp_group_id grp_id );\r
 464 \r
 465 /**\r
 466  * \brief           This function retrieves curve information from a TLS\r
 467  *                  NamedCurve value.\r
 468  *\r
 469  * \param tls_id    An \c MBEDTLS_ECP_DP_XXX value.\r
 470  *\r
 471  * \return          The associated curve information on success.\r
 472  * \return          NULL on failure.\r
 473  */\r
 474 const mbedtls_ecp_curve_info *mbedtls_ecp_curve_info_from_tls_id( uint16_t tls_id );\r
 475 \r
 476 /**\r
 477  * \brief           This function retrieves curve information from a\r
 478  *                  human-readable name.\r
 479  *\r
 480  * \param name      The human-readable name.\r
 481  *\r
 482  * \return          The associated curve information on success.\r
 483  * \return          NULL on failure.\r
 484  */\r
 485 const mbedtls_ecp_curve_info *mbedtls_ecp_curve_info_from_name( const char *name );\r
 486 \r
 487 /**\r
 488  * \brief           This function initializes a point as zero.\r
 489  *\r
 490  * \param pt        The point to initialize.\r
 491  */\r
 492 void mbedtls_ecp_point_init( mbedtls_ecp_point *pt );\r
 493 \r
 494 /**\r
 495  * \brief           This function initializes an ECP group context\r
 496  *                  without loading any domain parameters.\r
 497  *\r
 498  * \note            After this function is called, domain parameters\r
 499  *                  for various ECP groups can be loaded through the\r
 500  *                  mbedtls_ecp_group_load() or mbedtls_ecp_tls_read_group()\r
 501  *                  functions.\r
 502  */\r
 503 void mbedtls_ecp_group_init( mbedtls_ecp_group *grp );\r
 504 \r
 505 /**\r
 506  * \brief           This function initializes a key pair as an invalid one.\r
 507  *\r
 508  * \param key       The key pair to initialize.\r
 509  */\r
 510 void mbedtls_ecp_keypair_init( mbedtls_ecp_keypair *key );\r
 511 \r
 512 /**\r
 513  * \brief           This function frees the components of a point.\r
 514  *\r
 515  * \param pt        The point to free.\r
 516  */\r
 517 void mbedtls_ecp_point_free( mbedtls_ecp_point *pt );\r
 518 \r
 519 /**\r
 520  * \brief           This function frees the components of an ECP group.\r
 521  *\r
 522  * \param grp       The group to free. This may be \c NULL, in which\r
 523  *                  case this function returns immediately. If it is not\r
 524  *                  \c NULL, it must point to an initialized ECP group.\r
 525  */\r
 526 void mbedtls_ecp_group_free( mbedtls_ecp_group *grp );\r
 527 \r
 528 /**\r
 529  * \brief           This function frees the components of a key pair.\r
 530  *\r
 531  * \param key       The key pair to free. This may be \c NULL, in which\r
 532  *                  case this function returns immediately. If it is not\r
 533  *                  \c NULL, it must point to an initialized ECP key pair.\r
 534  */\r
 535 void mbedtls_ecp_keypair_free( mbedtls_ecp_keypair *key );\r
 536 \r
 537 #if defined(MBEDTLS_ECP_RESTARTABLE)\r
 538 /**\r
 539  * \brief           Initialize a restart context.\r
 540  *\r
 541  * \param ctx       The restart context to initialize. This must\r
 542  *                  not be \c NULL.\r
 543  */\r
 544 void mbedtls_ecp_restart_init( mbedtls_ecp_restart_ctx *ctx );\r
 545 \r
 546 /**\r
 547  * \brief           Free the components of a restart context.\r
 548  *\r
 549  * \param ctx       The restart context to free. This may be \c NULL, in which\r
 550  *                  case this function returns immediately. If it is not\r
 551  *                  \c NULL, it must point to an initialized restart context.\r
 552  */\r
 553 void mbedtls_ecp_restart_free( mbedtls_ecp_restart_ctx *ctx );\r
 554 #endif /* MBEDTLS_ECP_RESTARTABLE */\r
 555 \r
 556 /**\r
 557  * \brief           This function copies the contents of point \p Q into\r
 558  *                  point \p P.\r
 559  *\r
 560  * \param P         The destination point. This must be initialized.\r
 561  * \param Q         The source point. This must be initialized.\r
 562  *\r
 563  * \return          \c 0 on success.\r
 564  * \return          #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory-allocation failure.\r
 565  * \return          Another negative error code for other kinds of failure.\r
 566  */\r
 567 int mbedtls_ecp_copy( mbedtls_ecp_point *P, const mbedtls_ecp_point *Q );\r
 568 \r
 569 /**\r
 570  * \brief           This function copies the contents of group \p src into\r
 571  *                  group \p dst.\r
 572  *\r
 573  * \param dst       The destination group. This must be initialized.\r
 574  * \param src       The source group. This must be initialized.\r
 575  *\r
 576  * \return          \c 0 on success.\r
 577  * \return          #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory-allocation failure.\r
 578  * \return          Another negative error code on other kinds of failure.\r
 579  */\r
 580 int mbedtls_ecp_group_copy( mbedtls_ecp_group *dst,\r
 581                             const mbedtls_ecp_group *src );\r
 582 \r
 583 /**\r
 584  * \brief           This function sets a point to the point at infinity.\r
 585  *\r
 586  * \param pt        The point to set. This must be initialized.\r
 587  *\r
 588  * \return          \c 0 on success.\r
 589  * \return          #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory-allocation failure.\r
 590  * \return          Another negative error code on other kinds of failure.\r
 591  */\r
 592 int mbedtls_ecp_set_zero( mbedtls_ecp_point *pt );\r
 593 \r
 594 /**\r
 595  * \brief           This function checks if a point is the point at infinity.\r
 596  *\r
 597  * \param pt        The point to test. This must be initialized.\r
 598  *\r
 599  * \return          \c 1 if the point is zero.\r
 600  * \return          \c 0 if the point is non-zero.\r
 601  * \return          A negative error code on failure.\r
 602  */\r
 603 int mbedtls_ecp_is_zero( mbedtls_ecp_point *pt );\r
 604 \r
 605 /**\r
 606  * \brief           This function compares two points.\r
 607  *\r
 608  * \note            This assumes that the points are normalized. Otherwise,\r
 609  *                  they may compare as "not equal" even if they are.\r
 610  *\r
 611  * \param P         The first point to compare. This must be initialized.\r
 612  * \param Q         The second point to compare. This must be initialized.\r
 613  *\r
 614  * \return          \c 0 if the points are equal.\r
 615  * \return          #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if the points are not equal.\r
 616  */\r
 617 int mbedtls_ecp_point_cmp( const mbedtls_ecp_point *P,\r
 618                            const mbedtls_ecp_point *Q );\r
 619 \r
 620 /**\r
 621  * \brief           This function imports a non-zero point from two ASCII\r
 622  *                  strings.\r
 623  *\r
 624  * \param P         The destination point. This must be initialized.\r
 625  * \param radix     The numeric base of the input.\r
 626  * \param x         The first affine coordinate, as a null-terminated string.\r
 627  * \param y         The second affine coordinate, as a null-terminated string.\r
 628  *\r
 629  * \return          \c 0 on success.\r
 630  * \return          An \c MBEDTLS_ERR_MPI_XXX error code on failure.\r
 631  */\r
 632 int mbedtls_ecp_point_read_string( mbedtls_ecp_point *P, int radix,\r
 633                            const char *x, const char *y );\r
 634 \r
 635 /**\r
 636  * \brief           This function exports a point into unsigned binary data.\r
 637  *\r
 638  * \param grp       The group to which the point should belong.\r
 639  *                  This must be initialized and have group parameters\r
 640  *                  set, for example through mbedtls_ecp_group_load().\r
 641  * \param P         The point to export. This must be initialized.\r
 642  * \param format    The point format. This must be either\r
 643  *                  #MBEDTLS_ECP_PF_COMPRESSED or #MBEDTLS_ECP_PF_UNCOMPRESSED.\r
 644  *                  (For groups without these formats, this parameter is\r
 645  *                  ignored. But it still has to be either of the above\r
 646  *                  values.)\r
 647  * \param olen      The address at which to store the length of\r
 648  *                  the output in Bytes. This must not be \c NULL.\r
 649  * \param buf       The output buffer. This must be a writable buffer\r
 650  *                  of length \p buflen Bytes.\r
 651  * \param buflen    The length of the output buffer \p buf in Bytes.\r
 652  *\r
 653  * \return          \c 0 on success.\r
 654  * \return          #MBEDTLS_ERR_ECP_BUFFER_TOO_SMALL if the output buffer\r
 655  *                  is too small to hold the point.\r
 656  * \return          #MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE if the point format\r
 657  *                  or the export for the given group is not implemented.\r
 658  * \return          Another negative error code on other kinds of failure.\r
 659  */\r
 660 int mbedtls_ecp_point_write_binary( const mbedtls_ecp_group *grp,\r
 661                                     const mbedtls_ecp_point *P,\r
 662                                     int format, size_t *olen,\r
 663                                     unsigned char *buf, size_t buflen );\r
 664 \r
 665 /**\r
 666  * \brief           This function imports a point from unsigned binary data.\r
 667  *\r
 668  * \note            This function does not check that the point actually\r
 669  *                  belongs to the given group, see mbedtls_ecp_check_pubkey()\r
 670  *                  for that.\r
 671  *\r
 672  * \param grp       The group to which the point should belong.\r
 673  *                  This must be initialized and have group parameters\r
 674  *                  set, for example through mbedtls_ecp_group_load().\r
 675  * \param P         The destination context to import the point to.\r
 676  *                  This must be initialized.\r
 677  * \param buf       The input buffer. This must be a readable buffer\r
 678  *                  of length \p ilen Bytes.\r
 679  * \param ilen      The length of the input buffer \p buf in Bytes.\r
 680  *\r
 681  * \return          \c 0 on success.\r
 682  * \return          #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if the input is invalid.\r
 683  * \return          #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory-allocation failure.\r
 684  * \return          #MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE if the import for the\r
 685  *                  given group is not implemented.\r
 686  */\r
 687 int mbedtls_ecp_point_read_binary( const mbedtls_ecp_group *grp,\r
 688                                    mbedtls_ecp_point *P,\r
 689                                    const unsigned char *buf, size_t ilen );\r
 690 \r
 691 /**\r
 692  * \brief           This function imports a point from a TLS ECPoint record.\r
 693  *\r
 694  * \note            On function return, \p *buf is updated to point immediately\r
 695  *                  after the ECPoint record.\r
 696  *\r
 697  * \param grp       The ECP group to use.\r
 698  *                  This must be initialized and have group parameters\r
 699  *                  set, for example through mbedtls_ecp_group_load().\r
 700  * \param pt        The destination point.\r
 701  * \param buf       The address of the pointer to the start of the input buffer.\r
 702  * \param len       The length of the buffer.\r
 703  *\r
 704  * \return          \c 0 on success.\r
 705  * \return          An \c MBEDTLS_ERR_MPI_XXX error code on initialization\r
 706  *                  failure.\r
 707  * \return          #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if input is invalid.\r
 708  */\r
 709 int mbedtls_ecp_tls_read_point( const mbedtls_ecp_group *grp,\r
 710                                 mbedtls_ecp_point *pt,\r
 711                                 const unsigned char **buf, size_t len );\r
 712 \r
 713 /**\r
 714  * \brief           This function exports a point as a TLS ECPoint record\r
 715  *                  defined in RFC 4492, Section 5.4.\r
 716  *\r
 717  * \param grp       The ECP group to use.\r
 718  *                  This must be initialized and have group parameters\r
 719  *                  set, for example through mbedtls_ecp_group_load().\r
 720  * \param pt        The point to be exported. This must be initialized.\r
 721  * \param format    The point format to use. This must be either\r
 722  *                  #MBEDTLS_ECP_PF_COMPRESSED or #MBEDTLS_ECP_PF_UNCOMPRESSED.\r
 723  * \param olen      The address at which to store the length in Bytes\r
 724  *                  of the data written.\r
 725  * \param buf       The target buffer. This must be a writable buffer of\r
 726  *                  length \p blen Bytes.\r
 727  * \param blen      The length of the target buffer \p buf in Bytes.\r
 728  *\r
 729  * \return          \c 0 on success.\r
 730  * \return          #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if the input is invalid.\r
 731  * \return          #MBEDTLS_ERR_ECP_BUFFER_TOO_SMALL if the target buffer\r
 732  *                  is too small to hold the exported point.\r
 733  * \return          Another negative error code on other kinds of failure.\r
 734  */\r
 735 int mbedtls_ecp_tls_write_point( const mbedtls_ecp_group *grp,\r
 736                                  const mbedtls_ecp_point *pt,\r
 737                                  int format, size_t *olen,\r
 738                                  unsigned char *buf, size_t blen );\r
 739 \r
 740 /**\r
 741  * \brief           This function sets up an ECP group context\r
 742  *                  from a standardized set of domain parameters.\r
 743  *\r
 744  * \note            The index should be a value of the NamedCurve enum,\r
 745  *                  as defined in <em>RFC-4492: Elliptic Curve Cryptography\r
 746  *                  (ECC) Cipher Suites for Transport Layer Security (TLS)</em>,\r
 747  *                  usually in the form of an \c MBEDTLS_ECP_DP_XXX macro.\r
 748  *\r
 749  * \param grp       The group context to setup. This must be initialized.\r
 750  * \param id        The identifier of the domain parameter set to load.\r
 751  *\r
 752  * \return          \c 0 on success.\r
 753  * \return          #MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE if \p id doesn't\r
 754  *                  correspond to a known group.\r
 755  * \return          Another negative error code on other kinds of failure.\r
 756  */\r
 757 int mbedtls_ecp_group_load( mbedtls_ecp_group *grp, mbedtls_ecp_group_id id );\r
 758 \r
 759 /**\r
 760  * \brief           This function sets up an ECP group context from a TLS\r
 761  *                  ECParameters record as defined in RFC 4492, Section 5.4.\r
 762  *\r
 763  * \note            The read pointer \p buf is updated to point right after\r
 764  *                  the ECParameters record on exit.\r
 765  *\r
 766  * \param grp       The group context to setup. This must be initialized.\r
 767  * \param buf       The address of the pointer to the start of the input buffer.\r
 768  * \param len       The length of the input buffer \c *buf in Bytes.\r
 769  *\r
 770  * \return          \c 0 on success.\r
 771  * \return          #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if input is invalid.\r
 772  * \return          #MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE if the group is not\r
 773  *                  recognized.\r
 774  * \return          Another negative error code on other kinds of failure.\r
 775  */\r
 776 int mbedtls_ecp_tls_read_group( mbedtls_ecp_group *grp,\r
 777                                 const unsigned char **buf, size_t len );\r
 778 \r
 779 /**\r
 780  * \brief           This function extracts an elliptic curve group ID from a\r
 781  *                  TLS ECParameters record as defined in RFC 4492, Section 5.4.\r
 782  *\r
 783  * \note            The read pointer \p buf is updated to point right after\r
 784  *                  the ECParameters record on exit.\r
 785  *\r
 786  * \param grp       The address at which to store the group id.\r
 787  *                  This must not be \c NULL.\r
 788  * \param buf       The address of the pointer to the start of the input buffer.\r
 789  * \param len       The length of the input buffer \c *buf in Bytes.\r
 790  *\r
 791  * \return          \c 0 on success.\r
 792  * \return          #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if input is invalid.\r
 793  * \return          #MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE if the group is not\r
 794  *                  recognized.\r
 795  * \return          Another negative error code on other kinds of failure.\r
 796  */\r
 797 int mbedtls_ecp_tls_read_group_id( mbedtls_ecp_group_id *grp,\r
 798                                    const unsigned char **buf,\r
 799                                    size_t len );\r
 800 /**\r
 801  * \brief           This function exports an elliptic curve as a TLS\r
 802  *                  ECParameters record as defined in RFC 4492, Section 5.4.\r
 803  *\r
 804  * \param grp       The ECP group to be exported.\r
 805  *                  This must be initialized and have group parameters\r
 806  *                  set, for example through mbedtls_ecp_group_load().\r
 807  * \param olen      The address at which to store the number of Bytes written.\r
 808  *                  This must not be \c NULL.\r
 809  * \param buf       The buffer to write to. This must be a writable buffer\r
 810  *                  of length \p blen Bytes.\r
 811  * \param blen      The length of the output buffer \p buf in Bytes.\r
 812  *\r
 813  * \return          \c 0 on success.\r
 814  * \return          #MBEDTLS_ERR_ECP_BUFFER_TOO_SMALL if the output\r
 815  *                  buffer is too small to hold the exported group.\r
 816  * \return          Another negative error code on other kinds of failure.\r
 817  */\r
 818 int mbedtls_ecp_tls_write_group( const mbedtls_ecp_group *grp,\r
 819                                  size_t *olen,\r
 820                                  unsigned char *buf, size_t blen );\r
 821 \r
 822 /**\r
 823  * \brief           This function performs a scalar multiplication of a point\r
 824  *                  by an integer: \p R = \p m * \p P.\r
 825  *\r
 826  *                  It is not thread-safe to use same group in multiple threads.\r
 827  *\r
 828  * \note            To prevent timing attacks, this function\r
 829  *                  executes the exact same sequence of base-field\r
 830  *                  operations for any valid \p m. It avoids any if-branch or\r
 831  *                  array index depending on the value of \p m.\r
 832  *\r
 833  * \note            If \p f_rng is not NULL, it is used to randomize\r
 834  *                  intermediate results to prevent potential timing attacks\r
 835  *                  targeting these results. We recommend always providing\r
 836  *                  a non-NULL \p f_rng. The overhead is negligible.\r
 837  *\r
 838  * \param grp       The ECP group to use.\r
 839  *                  This must be initialized and have group parameters\r
 840  *                  set, for example through mbedtls_ecp_group_load().\r
 841  * \param R         The point in which to store the result of the calculation.\r
 842  *                  This must be initialized.\r
 843  * \param m         The integer by which to multiply. This must be initialized.\r
 844  * \param P         The point to multiply. This must be initialized.\r
 845  * \param f_rng     The RNG function. This may be \c NULL if randomization\r
 846  *                  of intermediate results isn't desired (discouraged).\r
 847  * \param p_rng     The RNG context to be passed to \p p_rng.\r
 848  *\r
 849  * \return          \c 0 on success.\r
 850  * \return          #MBEDTLS_ERR_ECP_INVALID_KEY if \p m is not a valid private\r
 851  *                  key, or \p P is not a valid public key.\r
 852  * \return          #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory-allocation failure.\r
 853  * \return          Another negative error code on other kinds of failure.\r
 854  */\r
 855 int mbedtls_ecp_mul( mbedtls_ecp_group *grp, mbedtls_ecp_point *R,\r
 856              const mbedtls_mpi *m, const mbedtls_ecp_point *P,\r
 857              int (*f_rng)(void *, unsigned char *, size_t), void *p_rng );\r
 858 \r
 859 /**\r
 860  * \brief           This function performs multiplication of a point by\r
 861  *                  an integer: \p R = \p m * \p P in a restartable way.\r
 862  *\r
 863  * \see             mbedtls_ecp_mul()\r
 864  *\r
 865  * \note            This function does the same as \c mbedtls_ecp_mul(), but\r
 866  *                  it can return early and restart according to the limit set\r
 867  *                  with \c mbedtls_ecp_set_max_ops() to reduce blocking.\r
 868  *\r
 869  * \param grp       The ECP group to use.\r
 870  *                  This must be initialized and have group parameters\r
 871  *                  set, for example through mbedtls_ecp_group_load().\r
 872  * \param R         The point in which to store the result of the calculation.\r
 873  *                  This must be initialized.\r
 874  * \param m         The integer by which to multiply. This must be initialized.\r
 875  * \param P         The point to multiply. This must be initialized.\r
 876  * \param f_rng     The RNG function. This may be \c NULL if randomization\r
 877  *                  of intermediate results isn't desired (discouraged).\r
 878  * \param p_rng     The RNG context to be passed to \p p_rng.\r
 879  * \param rs_ctx    The restart context (NULL disables restart).\r
 880  *\r
 881  * \return          \c 0 on success.\r
 882  * \return          #MBEDTLS_ERR_ECP_INVALID_KEY if \p m is not a valid private\r
 883  *                  key, or \p P is not a valid public key.\r
 884  * \return          #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory-allocation failure.\r
 885  * \return          #MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of\r
 886  *                  operations was reached: see \c mbedtls_ecp_set_max_ops().\r
 887  * \return          Another negative error code on other kinds of failure.\r
 888  */\r
 889 int mbedtls_ecp_mul_restartable( mbedtls_ecp_group *grp, mbedtls_ecp_point *R,\r
 890              const mbedtls_mpi *m, const mbedtls_ecp_point *P,\r
 891              int (*f_rng)(void *, unsigned char *, size_t), void *p_rng,\r
 892              mbedtls_ecp_restart_ctx *rs_ctx );\r
 893 \r
 894 /**\r
 895  * \brief           This function performs multiplication and addition of two\r
 896  *                  points by integers: \p R = \p m * \p P + \p n * \p Q\r
 897  *\r
 898  *                  It is not thread-safe to use same group in multiple threads.\r
 899  *\r
 900  * \note            In contrast to mbedtls_ecp_mul(), this function does not\r
 901  *                  guarantee a constant execution flow and timing.\r
 902  *\r
 903  * \param grp       The ECP group to use.\r
 904  *                  This must be initialized and have group parameters\r
 905  *                  set, for example through mbedtls_ecp_group_load().\r
 906  * \param R         The point in which to store the result of the calculation.\r
 907  *                  This must be initialized.\r
 908  * \param m         The integer by which to multiply \p P.\r
 909  *                  This must be initialized.\r
 910  * \param P         The point to multiply by \p m. This must be initialized.\r
 911  * \param n         The integer by which to multiply \p Q.\r
 912  *                  This must be initialized.\r
 913  * \param Q         The point to be multiplied by \p n.\r
 914  *                  This must be initialized.\r
 915  *\r
 916  * \return          \c 0 on success.\r
 917  * \return          #MBEDTLS_ERR_ECP_INVALID_KEY if \p m or \p n are not\r
 918  *                  valid private keys, or \p P or \p Q are not valid public\r
 919  *                  keys.\r
 920  * \return          #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory-allocation failure.\r
 921  * \return          Another negative error code on other kinds of failure.\r
 922  */\r
 923 int mbedtls_ecp_muladd( mbedtls_ecp_group *grp, mbedtls_ecp_point *R,\r
 924              const mbedtls_mpi *m, const mbedtls_ecp_point *P,\r
 925              const mbedtls_mpi *n, const mbedtls_ecp_point *Q );\r
 926 \r
 927 /**\r
 928  * \brief           This function performs multiplication and addition of two\r
 929  *                  points by integers: \p R = \p m * \p P + \p n * \p Q in a\r
 930  *                  restartable way.\r
 931  *\r
 932  * \see             \c mbedtls_ecp_muladd()\r
 933  *\r
 934  * \note            This function works the same as \c mbedtls_ecp_muladd(),\r
 935  *                  but it can return early and restart according to the limit\r
 936  *                  set with \c mbedtls_ecp_set_max_ops() to reduce blocking.\r
 937  *\r
 938  * \param grp       The ECP group to use.\r
 939  *                  This must be initialized and have group parameters\r
 940  *                  set, for example through mbedtls_ecp_group_load().\r
 941  * \param R         The point in which to store the result of the calculation.\r
 942  *                  This must be initialized.\r
 943  * \param m         The integer by which to multiply \p P.\r
 944  *                  This must be initialized.\r
 945  * \param P         The point to multiply by \p m. This must be initialized.\r
 946  * \param n         The integer by which to multiply \p Q.\r
 947  *                  This must be initialized.\r
 948  * \param Q         The point to be multiplied by \p n.\r
 949  *                  This must be initialized.\r
 950  * \param rs_ctx    The restart context (NULL disables restart).\r
 951  *\r
 952  * \return          \c 0 on success.\r
 953  * \return          #MBEDTLS_ERR_ECP_INVALID_KEY if \p m or \p n are not\r
 954  *                  valid private keys, or \p P or \p Q are not valid public\r
 955  *                  keys.\r
 956  * \return          #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory-allocation failure.\r
 957  * \return          #MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of\r
 958  *                  operations was reached: see \c mbedtls_ecp_set_max_ops().\r
 959  * \return          Another negative error code on other kinds of failure.\r
 960  */\r
 961 int mbedtls_ecp_muladd_restartable(\r
 962              mbedtls_ecp_group *grp, mbedtls_ecp_point *R,\r
 963              const mbedtls_mpi *m, const mbedtls_ecp_point *P,\r
 964              const mbedtls_mpi *n, const mbedtls_ecp_point *Q,\r
 965              mbedtls_ecp_restart_ctx *rs_ctx );\r
 966 \r
 967 /**\r
 968  * \brief           This function checks that a point is a valid public key\r
 969  *                  on this curve.\r
 970  *\r
 971  *                  It only checks that the point is non-zero, has\r
 972  *                  valid coordinates and lies on the curve. It does not verify\r
 973  *                  that it is indeed a multiple of \p G. This additional\r
 974  *                  check is computationally more expensive, is not required\r
 975  *                  by standards, and should not be necessary if the group\r
 976  *                  used has a small cofactor. In particular, it is useless for\r
 977  *                  the NIST groups which all have a cofactor of 1.\r
 978  *\r
 979  * \note            This function uses bare components rather than an\r
 980  *                  ::mbedtls_ecp_keypair structure, to ease use with other\r
 981  *                  structures, such as ::mbedtls_ecdh_context or\r
 982  *                  ::mbedtls_ecdsa_context.\r
 983  *\r
 984  * \param grp       The ECP group the point should belong to.\r
 985  *                  This must be initialized and have group parameters\r
 986  *                  set, for example through mbedtls_ecp_group_load().\r
 987  * \param pt        The point to check. This must be initialized.\r
 988  *\r
 989  * \return          \c 0 if the point is a valid public key.\r
 990  * \return          #MBEDTLS_ERR_ECP_INVALID_KEY if the point is not\r
 991  *                  a valid public key for the given curve.\r
 992  * \return          Another negative error code on other kinds of failure.\r
 993  */\r
 994 int mbedtls_ecp_check_pubkey( const mbedtls_ecp_group *grp,\r
 995                               const mbedtls_ecp_point *pt );\r
 996 \r
 997 /**\r
 998  * \brief           This function checks that an \p mbedtls_mpi is a\r
 999  *                  valid private key for this curve.\r
1000  *\r
1001  * \note            This function uses bare components rather than an\r
1002  *                  ::mbedtls_ecp_keypair structure to ease use with other\r
1003  *                  structures, such as ::mbedtls_ecdh_context or\r
1004  *                  ::mbedtls_ecdsa_context.\r
1005  *\r
1006  * \param grp       The ECP group the private key should belong to.\r
1007  *                  This must be initialized and have group parameters\r
1008  *                  set, for example through mbedtls_ecp_group_load().\r
1009  * \param d         The integer to check. This must be initialized.\r
1010  *\r
1011  * \return          \c 0 if the point is a valid private key.\r
1012  * \return          #MBEDTLS_ERR_ECP_INVALID_KEY if the point is not a valid\r
1013  *                  private key for the given curve.\r
1014  * \return          Another negative error code on other kinds of failure.\r
1015  */\r
1016 int mbedtls_ecp_check_privkey( const mbedtls_ecp_group *grp,\r
1017                                const mbedtls_mpi *d );\r
1018 \r
1019 /**\r
1020  * \brief           This function generates a private key.\r
1021  *\r
1022  * \param grp       The ECP group to generate a private key for.\r
1023  *                  This must be initialized and have group parameters\r
1024  *                  set, for example through mbedtls_ecp_group_load().\r
1025  * \param d         The destination MPI (secret part). This must be initialized.\r
1026  * \param f_rng     The RNG function. This must not be \c NULL.\r
1027  * \param p_rng     The RNG parameter to be passed to \p f_rng. This may be\r
1028  *                  \c NULL if \p f_rng doesn't need a context argument.\r
1029  *\r
1030  * \return          \c 0 on success.\r
1031  * \return          An \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_MPI_XXX error code\r
1032  *                  on failure.\r
1033  */\r
1034 int mbedtls_ecp_gen_privkey( const mbedtls_ecp_group *grp,\r
1035                      mbedtls_mpi *d,\r
1036                      int (*f_rng)(void *, unsigned char *, size_t),\r
1037                      void *p_rng );\r
1038 \r
1039 /**\r
1040  * \brief           This function generates a keypair with a configurable base\r
1041  *                  point.\r
1042  *\r
1043  * \note            This function uses bare components rather than an\r
1044  *                  ::mbedtls_ecp_keypair structure to ease use with other\r
1045  *                  structures, such as ::mbedtls_ecdh_context or\r
1046  *                  ::mbedtls_ecdsa_context.\r
1047  *\r
1048  * \param grp       The ECP group to generate a key pair for.\r
1049  *                  This must be initialized and have group parameters\r
1050  *                  set, for example through mbedtls_ecp_group_load().\r
1051  * \param G         The base point to use. This must be initialized\r
1052  *                  and belong to \p grp. It replaces the default base\r
1053  *                  point \c grp->G used by mbedtls_ecp_gen_keypair().\r
1054  * \param d         The destination MPI (secret part).\r
1055  *                  This must be initialized.\r
1056  * \param Q         The destination point (public part).\r
1057  *                  This must be initialized.\r
1058  * \param f_rng     The RNG function. This must not be \c NULL.\r
1059  * \param p_rng     The RNG context to be passed to \p f_rng. This may\r
1060  *                  be \c NULL if \p f_rng doesn't need a context argument.\r
1061  *\r
1062  * \return          \c 0 on success.\r
1063  * \return          An \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_MPI_XXX error code\r
1064  *                  on failure.\r
1065  */\r
1066 int mbedtls_ecp_gen_keypair_base( mbedtls_ecp_group *grp,\r
1067                                   const mbedtls_ecp_point *G,\r
1068                                   mbedtls_mpi *d, mbedtls_ecp_point *Q,\r
1069                                   int (*f_rng)(void *, unsigned char *, size_t),\r
1070                                   void *p_rng );\r
1071 \r
1072 /**\r
1073  * \brief           This function generates an ECP keypair.\r
1074  *\r
1075  * \note            This function uses bare components rather than an\r
1076  *                  ::mbedtls_ecp_keypair structure to ease use with other\r
1077  *                  structures, such as ::mbedtls_ecdh_context or\r
1078  *                  ::mbedtls_ecdsa_context.\r
1079  *\r
1080  * \param grp       The ECP group to generate a key pair for.\r
1081  *                  This must be initialized and have group parameters\r
1082  *                  set, for example through mbedtls_ecp_group_load().\r
1083  * \param d         The destination MPI (secret part).\r
1084  *                  This must be initialized.\r
1085  * \param Q         The destination point (public part).\r
1086  *                  This must be initialized.\r
1087  * \param f_rng     The RNG function. This must not be \c NULL.\r
1088  * \param p_rng     The RNG context to be passed to \p f_rng. This may\r
1089  *                  be \c NULL if \p f_rng doesn't need a context argument.\r
1090  *\r
1091  * \return          \c 0 on success.\r
1092  * \return          An \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_MPI_XXX error code\r
1093  *                  on failure.\r
1094  */\r
1095 int mbedtls_ecp_gen_keypair( mbedtls_ecp_group *grp, mbedtls_mpi *d,\r
1096                              mbedtls_ecp_point *Q,\r
1097                              int (*f_rng)(void *, unsigned char *, size_t),\r
1098                              void *p_rng );\r
1099 \r
1100 /**\r
1101  * \brief           This function generates an ECP key.\r
1102  *\r
1103  * \param grp_id    The ECP group identifier.\r
1104  * \param key       The destination key. This must be initialized.\r
1105  * \param f_rng     The RNG function to use. This must not be \c NULL.\r
1106  * \param p_rng     The RNG context to be passed to \p f_rng. This may\r
1107  *                  be \c NULL if \p f_rng doesn't need a context argument.\r
1108  *\r
1109  * \return          \c 0 on success.\r
1110  * \return          An \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_MPI_XXX error code\r
1111  *                  on failure.\r
1112  */\r
1113 int mbedtls_ecp_gen_key( mbedtls_ecp_group_id grp_id, mbedtls_ecp_keypair *key,\r
1114                          int (*f_rng)(void *, unsigned char *, size_t),\r
1115                          void *p_rng );\r
1116 \r
1117 /**\r
1118  * \brief           This function reads an elliptic curve private key.\r
1119  *\r
1120  * \param grp_id    The ECP group identifier.\r
1121  * \param key       The destination key.\r
1122  * \param buf       The the buffer containing the binary representation of the\r
1123  *                  key. (Big endian integer for Weierstrass curves, byte\r
1124  *                  string for Montgomery curves.)\r
1125  * \param buflen    The length of the buffer in bytes.\r
1126  *\r
1127  * \return          \c 0 on success.\r
1128  * \return          #MBEDTLS_ERR_ECP_INVALID_KEY error if the key is\r
1129  *                  invalid.\r
1130  * \return          #MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed.\r
1131  * \return          #MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE if the operation for\r
1132  *                  the group is not implemented.\r
1133  * \return          Another negative error code on different kinds of failure.\r
1134  */\r
1135 int mbedtls_ecp_read_key( mbedtls_ecp_group_id grp_id, mbedtls_ecp_keypair *key,\r
1136                           const unsigned char *buf, size_t buflen );\r
1137 /**\r
1138  * \brief           This function checks that the keypair objects\r
1139  *                  \p pub and \p prv have the same group and the\r
1140  *                  same public point, and that the private key in\r
1141  *                  \p prv is consistent with the public key.\r
1142  *\r
1143  * \param pub       The keypair structure holding the public key. This\r
1144  *                  must be initialized. If it contains a private key, that\r
1145  *                  part is ignored.\r
1146  * \param prv       The keypair structure holding the full keypair.\r
1147  *                  This must be initialized.\r
1148  *\r
1149  * \return          \c 0 on success, meaning that the keys are valid and match.\r
1150  * \return          #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if the keys are invalid or do not match.\r
1151  * \return          An \c MBEDTLS_ERR_ECP_XXX or an \c MBEDTLS_ERR_MPI_XXX\r
1152  *                  error code on calculation failure.\r
1153  */\r
1154 int mbedtls_ecp_check_pub_priv( const mbedtls_ecp_keypair *pub,\r
1155                                 const mbedtls_ecp_keypair *prv );\r
1156 \r
1157 #if defined(MBEDTLS_SELF_TEST)\r
1158 \r
1159 /**\r
1160  * \brief          The ECP checkup routine.\r
1161  *\r
1162  * \return         \c 0 on success.\r
1163  * \return         \c 1 on failure.\r
1164  */\r
1165 int mbedtls_ecp_self_test( int verbose );\r
1166 \r
1167 #endif /* MBEDTLS_SELF_TEST */\r
1168 \r
1169 #ifdef __cplusplus\r
1170 }\r
1171 #endif\r
1172 \r
1173 #endif /* ecp.h */\r