Kenji Arai / mbed-os_TYBLE16

Dependents:   TYBLE16_simple_data_logger TYBLE16_MP3_Air

Embed: (wiki syntax)

« Back to documentation index

Show/hide line numbers ecp.h Source File

ecp.h

00001 /**
00002  * \file ecp.h
00003  *
00004  * \brief This file provides an API for Elliptic Curves over GF(P) (ECP).
00005  *
00006  * The use of ECP in cryptography and TLS is defined in
00007  * <em>Standards for Efficient Cryptography Group (SECG): SEC1
00008  * Elliptic Curve Cryptography</em> and
00009  * <em>RFC-4492: Elliptic Curve Cryptography (ECC) Cipher Suites
00010  * for Transport Layer Security (TLS)</em>.
00011  *
00012  * <em>RFC-2409: The Internet Key Exchange (IKE)</em> defines ECP
00013  * group types.
00014  *
00015  */
00016 
00017 /*
00018  *  Copyright (C) 2006-2018, Arm Limited (or its affiliates), All Rights Reserved
00019  *  SPDX-License-Identifier: Apache-2.0
00020  *
00021  *  Licensed under the Apache License, Version 2.0 (the "License"); you may
00022  *  not use this file except in compliance with the License.
00023  *  You may obtain a copy of the License at
00024  *
00025  *  http://www.apache.org/licenses/LICENSE-2.0
00026  *
00027  *  Unless required by applicable law or agreed to in writing, software
00028  *  distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
00029  *  WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00030  *  See the License for the specific language governing permissions and
00031  *  limitations under the License.
00032  *
00033  *  This file is part of Mbed TLS (https://tls.mbed.org)
00034  */
00035 
00036 #ifndef MBEDTLS_ECP_H
00037 #define MBEDTLS_ECP_H
00038 
00039 #if !defined(MBEDTLS_CONFIG_FILE)
00040 #include "mbedtls/config.h"
00041 #else
00042 #include MBEDTLS_CONFIG_FILE
00043 #endif
00044 
00045 #include "mbedtls/bignum.h"
00046 
00047 /*
00048  * ECP error codes
00049  */
00050 #define MBEDTLS_ERR_ECP_BAD_INPUT_DATA                    -0x4F80  /**< Bad input parameters to function. */
00051 #define MBEDTLS_ERR_ECP_BUFFER_TOO_SMALL                  -0x4F00  /**< The buffer is too small to write to. */
00052 #define MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE               -0x4E80  /**< The requested feature is not available, for example, the requested curve is not supported. */
00053 #define MBEDTLS_ERR_ECP_VERIFY_FAILED                     -0x4E00  /**< The signature is not valid. */
00054 #define MBEDTLS_ERR_ECP_ALLOC_FAILED                      -0x4D80  /**< Memory allocation failed. */
00055 #define MBEDTLS_ERR_ECP_RANDOM_FAILED                     -0x4D00  /**< Generation of random value, such as ephemeral key, failed. */
00056 #define MBEDTLS_ERR_ECP_INVALID_KEY                       -0x4C80  /**< Invalid private or public key. */
00057 #define MBEDTLS_ERR_ECP_SIG_LEN_MISMATCH                  -0x4C00  /**< The buffer contains a valid signature followed by more data. */
00058 
00059 /* MBEDTLS_ERR_ECP_HW_ACCEL_FAILED is deprecated and should not be used. */
00060 #define MBEDTLS_ERR_ECP_HW_ACCEL_FAILED                   -0x4B80  /**< The ECP hardware accelerator failed. */
00061 
00062 #define MBEDTLS_ERR_ECP_IN_PROGRESS                       -0x4B00  /**< Operation in progress, call again with the same parameters to continue. */
00063 
00064 #ifdef __cplusplus
00065 extern "C" {
00066 #endif
00067 
00068 /**
00069  * Domain-parameter identifiers: curve, subgroup, and generator.
00070  *
00071  * \note Only curves over prime fields are supported.
00072  *
00073  * \warning This library does not support validation of arbitrary domain
00074  * parameters. Therefore, only standardized domain parameters from trusted
00075  * sources should be used. See mbedtls_ecp_group_load().
00076  */
00077 typedef enum
00078 {
00079     MBEDTLS_ECP_DP_NONE = 0,       /*!< Curve not defined. */
00080     MBEDTLS_ECP_DP_SECP192R1,      /*!< Domain parameters for the 192-bit curve defined by FIPS 186-4 and SEC1. */
00081     MBEDTLS_ECP_DP_SECP224R1,      /*!< Domain parameters for the 224-bit curve defined by FIPS 186-4 and SEC1. */
00082     MBEDTLS_ECP_DP_SECP256R1,      /*!< Domain parameters for the 256-bit curve defined by FIPS 186-4 and SEC1. */
00083     MBEDTLS_ECP_DP_SECP384R1,      /*!< Domain parameters for the 384-bit curve defined by FIPS 186-4 and SEC1. */
00084     MBEDTLS_ECP_DP_SECP521R1,      /*!< Domain parameters for the 521-bit curve defined by FIPS 186-4 and SEC1. */
00085     MBEDTLS_ECP_DP_BP256R1,        /*!< Domain parameters for 256-bit Brainpool curve. */
00086     MBEDTLS_ECP_DP_BP384R1,        /*!< Domain parameters for 384-bit Brainpool curve. */
00087     MBEDTLS_ECP_DP_BP512R1,        /*!< Domain parameters for 512-bit Brainpool curve. */
00088     MBEDTLS_ECP_DP_CURVE25519,     /*!< Domain parameters for Curve25519. */
00089     MBEDTLS_ECP_DP_SECP192K1,      /*!< Domain parameters for 192-bit "Koblitz" curve. */
00090     MBEDTLS_ECP_DP_SECP224K1,      /*!< Domain parameters for 224-bit "Koblitz" curve. */
00091     MBEDTLS_ECP_DP_SECP256K1,      /*!< Domain parameters for 256-bit "Koblitz" curve. */
00092     MBEDTLS_ECP_DP_CURVE448,       /*!< Domain parameters for Curve448. */
00093 } mbedtls_ecp_group_id;
00094 
00095 /**
00096  * The number of supported curves, plus one for #MBEDTLS_ECP_DP_NONE.
00097  *
00098  * \note Montgomery curves are currently excluded.
00099  */
00100 #define MBEDTLS_ECP_DP_MAX     12
00101 
00102 /*
00103  * Curve types
00104  */
00105 typedef enum
00106 {
00107     MBEDTLS_ECP_TYPE_NONE = 0,
00108     MBEDTLS_ECP_TYPE_SHORT_WEIERSTRASS,    /* y^2 = x^3 + a x + b      */
00109     MBEDTLS_ECP_TYPE_MONTGOMERY,           /* y^2 = x^3 + a x^2 + x    */
00110 } mbedtls_ecp_curve_type;
00111 
00112 /**
00113  * Curve information, for use by other modules.
00114  */
00115 typedef struct mbedtls_ecp_curve_info
00116 {
00117     mbedtls_ecp_group_id grp_id ;    /*!< An internal identifier. */
00118     uint16_t tls_id ;                /*!< The TLS NamedCurve identifier. */
00119     uint16_t bit_size ;              /*!< The curve size in bits. */
00120     const char *name ;               /*!< A human-friendly name. */
00121 } mbedtls_ecp_curve_info;
00122 
00123 /**
00124  * \brief           The ECP point structure, in Jacobian coordinates.
00125  *
00126  * \note            All functions expect and return points satisfying
00127  *                  the following condition: <code>Z == 0</code> or
00128  *                  <code>Z == 1</code>. Other values of \p Z are
00129  *                  used only by internal functions.
00130  *                  The point is zero, or "at infinity", if <code>Z == 0</code>.
00131  *                  Otherwise, \p X and \p Y are its standard (affine)
00132  *                  coordinates.
00133  */
00134 typedef struct mbedtls_ecp_point
00135 {
00136     mbedtls_mpi X ;          /*!< The X coordinate of the ECP point. */
00137     mbedtls_mpi Y ;          /*!< The Y coordinate of the ECP point. */
00138     mbedtls_mpi Z ;          /*!< The Z coordinate of the ECP point. */
00139 }
00140 mbedtls_ecp_point;
00141 
00142 #if !defined(MBEDTLS_ECP_ALT)
00143 /*
00144  * default mbed TLS elliptic curve arithmetic implementation
00145  *
00146  * (in case MBEDTLS_ECP_ALT is defined then the developer has to provide an
00147  * alternative implementation for the whole module and it will replace this
00148  * one.)
00149  */
00150 
00151 /**
00152  * \brief           The ECP group structure.
00153  *
00154  * We consider two types of curve equations:
00155  * <ul><li>Short Weierstrass: <code>y^2 = x^3 + A x + B mod P</code>
00156  * (SEC1 + RFC-4492)</li>
00157  * <li>Montgomery: <code>y^2 = x^3 + A x^2 + x mod P</code> (Curve25519,
00158  * Curve448)</li></ul>
00159  * In both cases, the generator (\p G) for a prime-order subgroup is fixed.
00160  *
00161  * For Short Weierstrass, this subgroup is the whole curve, and its
00162  * cardinality is denoted by \p N. Our code requires that \p N is an
00163  * odd prime as mbedtls_ecp_mul() requires an odd number, and
00164  * mbedtls_ecdsa_sign() requires that it is prime for blinding purposes.
00165  *
00166  * For Montgomery curves, we do not store \p A, but <code>(A + 2) / 4</code>,
00167  * which is the quantity used in the formulas. Additionally, \p nbits is
00168  * not the size of \p N but the required size for private keys.
00169  *
00170  * If \p modp is NULL, reduction modulo \p P is done using a generic algorithm.
00171  * Otherwise, \p modp must point to a function that takes an \p mbedtls_mpi in the
00172  * range of <code>0..2^(2*pbits)-1</code>, and transforms it in-place to an integer
00173  * which is congruent mod \p P to the given MPI, and is close enough to \p pbits
00174  * in size, so that it may be efficiently brought in the 0..P-1 range by a few
00175  * additions or subtractions. Therefore, it is only an approximative modular
00176  * reduction. It must return 0 on success and non-zero on failure.
00177  *
00178  * \note        Alternative implementations must keep the group IDs distinct. If
00179  *              two group structures have the same ID, then they must be
00180  *              identical.
00181  *
00182  */
00183 typedef struct mbedtls_ecp_group
00184 {
00185     mbedtls_ecp_group_id id ;    /*!< An internal group identifier. */
00186     mbedtls_mpi P ;              /*!< The prime modulus of the base field. */
00187     mbedtls_mpi A ;              /*!< For Short Weierstrass: \p A in the equation. For
00188                                      Montgomery curves: <code>(A + 2) / 4</code>. */
00189     mbedtls_mpi B ;              /*!< For Short Weierstrass: \p B in the equation.
00190                                      For Montgomery curves: unused. */
00191     mbedtls_ecp_point G ;        /*!< The generator of the subgroup used. */
00192     mbedtls_mpi N ;              /*!< The order of \p G. */
00193     size_t pbits ;               /*!< The number of bits in \p P.*/
00194     size_t nbits ;               /*!< For Short Weierstrass: The number of bits in \p P.
00195                                      For Montgomery curves: the number of bits in the
00196                                      private keys. */
00197     unsigned int h;             /*!< \internal 1 if the constants are static. */
00198     int (*modp )(mbedtls_mpi *); /*!< The function for fast pseudo-reduction
00199                                      mod \p P (see above).*/
00200     int (*t_pre )(mbedtls_ecp_point *, void *);  /*!< Unused. */
00201     int (*t_post )(mbedtls_ecp_point *, void *); /*!< Unused. */
00202     void *t_data ;               /*!< Unused. */
00203     mbedtls_ecp_point *T ;       /*!< Pre-computed points for ecp_mul_comb(). */
00204     size_t T_size ;              /*!< The number of pre-computed points. */
00205 }
00206 mbedtls_ecp_group;
00207 
00208 /**
00209  * \name SECTION: Module settings
00210  *
00211  * The configuration options you can set for this module are in this section.
00212  * Either change them in config.h, or define them using the compiler command line.
00213  * \{
00214  */
00215 
00216 #if !defined(MBEDTLS_ECP_MAX_BITS)
00217 /**
00218  * The maximum size of the groups, that is, of \c N and \c P.
00219  */
00220 #define MBEDTLS_ECP_MAX_BITS     521   /**< The maximum size of groups, in bits. */
00221 #endif
00222 
00223 #define MBEDTLS_ECP_MAX_BYTES    ( ( MBEDTLS_ECP_MAX_BITS + 7 ) / 8 )
00224 #define MBEDTLS_ECP_MAX_PT_LEN   ( 2 * MBEDTLS_ECP_MAX_BYTES + 1 )
00225 
00226 #if !defined(MBEDTLS_ECP_WINDOW_SIZE)
00227 /*
00228  * Maximum "window" size used for point multiplication.
00229  * Default: 6.
00230  * Minimum value: 2. Maximum value: 7.
00231  *
00232  * Result is an array of at most ( 1 << ( MBEDTLS_ECP_WINDOW_SIZE - 1 ) )
00233  * points used for point multiplication. This value is directly tied to EC
00234  * peak memory usage, so decreasing it by one should roughly cut memory usage
00235  * by two (if large curves are in use).
00236  *
00237  * Reduction in size may reduce speed, but larger curves are impacted first.
00238  * Sample performances (in ECDHE handshakes/s, with FIXED_POINT_OPTIM = 1):
00239  *      w-size:     6       5       4       3       2
00240  *      521       145     141     135     120      97
00241  *      384       214     209     198     177     146
00242  *      256       320     320     303     262     226
00243  *      224       475     475     453     398     342
00244  *      192       640     640     633     587     476
00245  */
00246 #define MBEDTLS_ECP_WINDOW_SIZE    6   /**< The maximum window size used. */
00247 #endif /* MBEDTLS_ECP_WINDOW_SIZE */
00248 
00249 #if !defined(MBEDTLS_ECP_FIXED_POINT_OPTIM)
00250 /*
00251  * Trade memory for speed on fixed-point multiplication.
00252  *
00253  * This speeds up repeated multiplication of the generator (that is, the
00254  * multiplication in ECDSA signatures, and half of the multiplications in
00255  * ECDSA verification and ECDHE) by a factor roughly 3 to 4.
00256  *
00257  * The cost is increasing EC peak memory usage by a factor roughly 2.
00258  *
00259  * Change this value to 0 to reduce peak memory usage.
00260  */
00261 #define MBEDTLS_ECP_FIXED_POINT_OPTIM  1   /**< Enable fixed-point speed-up. */
00262 #endif /* MBEDTLS_ECP_FIXED_POINT_OPTIM */
00263 
00264 /* \} name SECTION: Module settings */
00265 
00266 #else  /* MBEDTLS_ECP_ALT */
00267 #include "ecp_alt.h"
00268 #endif /* MBEDTLS_ECP_ALT */
00269 
00270 #if defined(MBEDTLS_ECP_RESTARTABLE)
00271 
00272 /**
00273  * \brief           Internal restart context for multiplication
00274  *
00275  * \note            Opaque struct
00276  */
00277 typedef struct mbedtls_ecp_restart_mul mbedtls_ecp_restart_mul_ctx;
00278 
00279 /**
00280  * \brief           Internal restart context for ecp_muladd()
00281  *
00282  * \note            Opaque struct
00283  */
00284 typedef struct mbedtls_ecp_restart_muladd mbedtls_ecp_restart_muladd_ctx;
00285 
00286 /**
00287  * \brief           General context for resuming ECC operations
00288  */
00289 typedef struct
00290 {
00291     unsigned ops_done ;                  /*!<  current ops count             */
00292     unsigned depth ;                     /*!<  call depth (0 = top-level)    */
00293     mbedtls_ecp_restart_mul_ctx *rsm ;   /*!<  ecp_mul_comb() sub-context    */
00294     mbedtls_ecp_restart_muladd_ctx *ma ; /*!<  ecp_muladd() sub-context      */
00295 } mbedtls_ecp_restart_ctx;
00296 
00297 /*
00298  * Operation counts for restartable functions
00299  */
00300 #define MBEDTLS_ECP_OPS_CHK   3 /*!< basic ops count for ecp_check_pubkey()  */
00301 #define MBEDTLS_ECP_OPS_DBL   8 /*!< basic ops count for ecp_double_jac()    */
00302 #define MBEDTLS_ECP_OPS_ADD  11 /*!< basic ops count for see ecp_add_mixed() */
00303 #define MBEDTLS_ECP_OPS_INV 120 /*!< empirical equivalent for mpi_mod_inv()  */
00304 
00305 /**
00306  * \brief           Internal; for restartable functions in other modules.
00307  *                  Check and update basic ops budget.
00308  *
00309  * \param grp       Group structure
00310  * \param rs_ctx    Restart context
00311  * \param ops       Number of basic ops to do
00312  *
00313  * \return          \c 0 if doing \p ops basic ops is still allowed,
00314  * \return          #MBEDTLS_ERR_ECP_IN_PROGRESS otherwise.
00315  */
00316 int mbedtls_ecp_check_budget( const mbedtls_ecp_group *grp,
00317                               mbedtls_ecp_restart_ctx *rs_ctx,
00318                               unsigned ops );
00319 
00320 /* Utility macro for checking and updating ops budget */
00321 #define MBEDTLS_ECP_BUDGET( ops )   \
00322     MBEDTLS_MPI_CHK( mbedtls_ecp_check_budget( grp, rs_ctx, \
00323                                                (unsigned) (ops) ) );
00324 
00325 #else /* MBEDTLS_ECP_RESTARTABLE */
00326 
00327 #define MBEDTLS_ECP_BUDGET( ops )   /* no-op; for compatibility */
00328 
00329 /* We want to declare restartable versions of existing functions anyway */
00330 typedef void mbedtls_ecp_restart_ctx;
00331 
00332 #endif /* MBEDTLS_ECP_RESTARTABLE */
00333 
00334 /**
00335  * \brief    The ECP key-pair structure.
00336  *
00337  * A generic key-pair that may be used for ECDSA and fixed ECDH, for example.
00338  *
00339  * \note    Members are deliberately in the same order as in the
00340  *          ::mbedtls_ecdsa_context structure.
00341  */
00342 typedef struct mbedtls_ecp_keypair
00343 {
00344     mbedtls_ecp_group grp ;      /*!<  Elliptic curve and base point     */
00345     mbedtls_mpi d ;              /*!<  our secret value                  */
00346     mbedtls_ecp_point Q ;        /*!<  our public value                  */
00347 }
00348 mbedtls_ecp_keypair;
00349 
00350 /*
00351  * Point formats, from RFC 4492's enum ECPointFormat
00352  */
00353 #define MBEDTLS_ECP_PF_UNCOMPRESSED    0   /**< Uncompressed point format. */
00354 #define MBEDTLS_ECP_PF_COMPRESSED      1   /**< Compressed point format. */
00355 
00356 /*
00357  * Some other constants from RFC 4492
00358  */
00359 #define MBEDTLS_ECP_TLS_NAMED_CURVE    3   /**< The named_curve of ECCurveType. */
00360 
00361 #if defined(MBEDTLS_ECP_RESTARTABLE)
00362 /**
00363  * \brief           Set the maximum number of basic operations done in a row.
00364  *
00365  *                  If more operations are needed to complete a computation,
00366  *                  #MBEDTLS_ERR_ECP_IN_PROGRESS will be returned by the
00367  *                  function performing the computation. It is then the
00368  *                  caller's responsibility to either call again with the same
00369  *                  parameters until it returns 0 or an error code; or to free
00370  *                  the restart context if the operation is to be aborted.
00371  *
00372  *                  It is strictly required that all input parameters and the
00373  *                  restart context be the same on successive calls for the
00374  *                  same operation, but output parameters need not be the
00375  *                  same; they must not be used until the function finally
00376  *                  returns 0.
00377  *
00378  *                  This only applies to functions whose documentation mentions
00379  *                  they may return #MBEDTLS_ERR_ECP_IN_PROGRESS (or
00380  *                  `MBEDTLS_ERR_SSL_CRYPTO_IN_PROGRESS` for functions in the
00381  *                  Mbed TLS SSL module). For functions that accept a "restart
00382  *                  context" argument, passing NULL disables restart and makes
00383  *                  the function equivalent to the function with the same name
00384  *                  with \c _restartable removed. For functions in the ECDH
00385  *                  module, restart is disabled unless the function accepts an
00386  *                  "ECDH context" argument and mbedtls_ecdh_enable_restart()
00387  *                  was previously called on that context. For function in the
00388  *                  Mbed TLS SSL module, restart is only enabled for specific
00389  *                  sides and key exchanges (currently only for clients and
00390  *                  ECDHE-ECDSA).
00391  *
00392  * \param max_ops   Maximum number of basic operations done in a row.
00393  *                  Default: 0 (unlimited).
00394  *                  Lower (non-zero) values mean ECC functions will block for
00395  *                  a lesser maximum amount of time.
00396  *
00397  * \note            A "basic operation" is defined as a rough equivalent of a
00398  *                  multiplication in GF(p) for the NIST P-256 curve.
00399  *                  As an indication, with default settings, a scalar
00400  *                  multiplication (full run of \c mbedtls_ecp_mul()) is:
00401  *                  - about 3300 basic operations for P-256
00402  *                  - about 9400 basic operations for P-384
00403  *
00404  * \note            Very low values are not always respected: sometimes
00405  *                  functions need to block for a minimum number of
00406  *                  operations, and will do so even if max_ops is set to a
00407  *                  lower value.  That minimum depends on the curve size, and
00408  *                  can be made lower by decreasing the value of
00409  *                  \c MBEDTLS_ECP_WINDOW_SIZE.  As an indication, here is the
00410  *                  lowest effective value for various curves and values of
00411  *                  that parameter (w for short):
00412  *                          w=6     w=5     w=4     w=3     w=2
00413  *                  P-256   208     208     160     136     124
00414  *                  P-384   682     416     320     272     248
00415  *                  P-521  1364     832     640     544     496
00416  *
00417  * \note            This setting is currently ignored by Curve25519.
00418  */
00419 void mbedtls_ecp_set_max_ops( unsigned max_ops );
00420 
00421 /**
00422  * \brief           Check if restart is enabled (max_ops != 0)
00423  *
00424  * \return          \c 0 if \c max_ops == 0 (restart disabled)
00425  * \return          \c 1 otherwise (restart enabled)
00426  */
00427 int mbedtls_ecp_restart_is_enabled( void );
00428 #endif /* MBEDTLS_ECP_RESTARTABLE */
00429 
00430 /*
00431  * Get the type of a curve
00432  */
00433 mbedtls_ecp_curve_type mbedtls_ecp_get_type( const mbedtls_ecp_group *grp );
00434 
00435 /**
00436  * \brief           This function retrieves the information defined in
00437  *                  mbedtls_ecp_curve_info() for all supported curves in order
00438  *                  of preference.
00439  *
00440  * \note            This function returns information about all curves
00441  *                  supported by the library. Some curves may not be
00442  *                  supported for all algorithms. Call mbedtls_ecdh_can_do()
00443  *                  or mbedtls_ecdsa_can_do() to check if a curve is
00444  *                  supported for ECDH or ECDSA.
00445  *
00446  * \return          A statically allocated array. The last entry is 0.
00447  */
00448 const mbedtls_ecp_curve_info *mbedtls_ecp_curve_list( void );
00449 
00450 /**
00451  * \brief           This function retrieves the list of internal group
00452  *                  identifiers of all supported curves in the order of
00453  *                  preference.
00454  *
00455  * \note            This function returns information about all curves
00456  *                  supported by the library. Some curves may not be
00457  *                  supported for all algorithms. Call mbedtls_ecdh_can_do()
00458  *                  or mbedtls_ecdsa_can_do() to check if a curve is
00459  *                  supported for ECDH or ECDSA.
00460  *
00461  * \return          A statically allocated array,
00462  *                  terminated with MBEDTLS_ECP_DP_NONE.
00463  */
00464 const mbedtls_ecp_group_id *mbedtls_ecp_grp_id_list( void );
00465 
00466 /**
00467  * \brief           This function retrieves curve information from an internal
00468  *                  group identifier.
00469  *
00470  * \param grp_id    An \c MBEDTLS_ECP_DP_XXX value.
00471  *
00472  * \return          The associated curve information on success.
00473  * \return          NULL on failure.
00474  */
00475 const mbedtls_ecp_curve_info *mbedtls_ecp_curve_info_from_grp_id( mbedtls_ecp_group_id grp_id );
00476 
00477 /**
00478  * \brief           This function retrieves curve information from a TLS
00479  *                  NamedCurve value.
00480  *
00481  * \param tls_id    An \c MBEDTLS_ECP_DP_XXX value.
00482  *
00483  * \return          The associated curve information on success.
00484  * \return          NULL on failure.
00485  */
00486 const mbedtls_ecp_curve_info *mbedtls_ecp_curve_info_from_tls_id( uint16_t tls_id );
00487 
00488 /**
00489  * \brief           This function retrieves curve information from a
00490  *                  human-readable name.
00491  *
00492  * \param name      The human-readable name.
00493  *
00494  * \return          The associated curve information on success.
00495  * \return          NULL on failure.
00496  */
00497 const mbedtls_ecp_curve_info *mbedtls_ecp_curve_info_from_name( const char *name );
00498 
00499 /**
00500  * \brief           This function initializes a point as zero.
00501  *
00502  * \param pt        The point to initialize.
00503  */
00504 void mbedtls_ecp_point_init( mbedtls_ecp_point *pt );
00505 
00506 /**
00507  * \brief           This function initializes an ECP group context
00508  *                  without loading any domain parameters.
00509  *
00510  * \note            After this function is called, domain parameters
00511  *                  for various ECP groups can be loaded through the
00512  *                  mbedtls_ecp_group_load() or mbedtls_ecp_tls_read_group()
00513  *                  functions.
00514  */
00515 void mbedtls_ecp_group_init( mbedtls_ecp_group *grp );
00516 
00517 /**
00518  * \brief           This function initializes a key pair as an invalid one.
00519  *
00520  * \param key       The key pair to initialize.
00521  */
00522 void mbedtls_ecp_keypair_init( mbedtls_ecp_keypair *key );
00523 
00524 /**
00525  * \brief           This function frees the components of a point.
00526  *
00527  * \param pt        The point to free.
00528  */
00529 void mbedtls_ecp_point_free( mbedtls_ecp_point *pt );
00530 
00531 /**
00532  * \brief           This function frees the components of an ECP group.
00533  *
00534  * \param grp       The group to free. This may be \c NULL, in which
00535  *                  case this function returns immediately. If it is not
00536  *                  \c NULL, it must point to an initialized ECP group.
00537  */
00538 void mbedtls_ecp_group_free( mbedtls_ecp_group *grp );
00539 
00540 /**
00541  * \brief           This function frees the components of a key pair.
00542  *
00543  * \param key       The key pair to free. This may be \c NULL, in which
00544  *                  case this function returns immediately. If it is not
00545  *                  \c NULL, it must point to an initialized ECP key pair.
00546  */
00547 void mbedtls_ecp_keypair_free( mbedtls_ecp_keypair *key );
00548 
00549 #if defined(MBEDTLS_ECP_RESTARTABLE)
00550 /**
00551  * \brief           Initialize a restart context.
00552  *
00553  * \param ctx       The restart context to initialize. This must
00554  *                  not be \c NULL.
00555  */
00556 void mbedtls_ecp_restart_init( mbedtls_ecp_restart_ctx *ctx );
00557 
00558 /**
00559  * \brief           Free the components of a restart context.
00560  *
00561  * \param ctx       The restart context to free. This may be \c NULL, in which
00562  *                  case this function returns immediately. If it is not
00563  *                  \c NULL, it must point to an initialized restart context.
00564  */
00565 void mbedtls_ecp_restart_free( mbedtls_ecp_restart_ctx *ctx );
00566 #endif /* MBEDTLS_ECP_RESTARTABLE */
00567 
00568 /**
00569  * \brief           This function copies the contents of point \p Q into
00570  *                  point \p P.
00571  *
00572  * \param P         The destination point. This must be initialized.
00573  * \param Q         The source point. This must be initialized.
00574  *
00575  * \return          \c 0 on success.
00576  * \return          #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory-allocation failure.
00577  * \return          Another negative error code for other kinds of failure.
00578  */
00579 int mbedtls_ecp_copy( mbedtls_ecp_point *P, const mbedtls_ecp_point *Q );
00580 
00581 /**
00582  * \brief           This function copies the contents of group \p src into
00583  *                  group \p dst.
00584  *
00585  * \param dst       The destination group. This must be initialized.
00586  * \param src       The source group. This must be initialized.
00587  *
00588  * \return          \c 0 on success.
00589  * \return          #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory-allocation failure.
00590  * \return          Another negative error code on other kinds of failure.
00591  */
00592 int mbedtls_ecp_group_copy( mbedtls_ecp_group *dst,
00593                             const mbedtls_ecp_group *src );
00594 
00595 /**
00596  * \brief           This function sets a point to the point at infinity.
00597  *
00598  * \param pt        The point to set. This must be initialized.
00599  *
00600  * \return          \c 0 on success.
00601  * \return          #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory-allocation failure.
00602  * \return          Another negative error code on other kinds of failure.
00603  */
00604 int mbedtls_ecp_set_zero( mbedtls_ecp_point *pt );
00605 
00606 /**
00607  * \brief           This function checks if a point is the point at infinity.
00608  *
00609  * \param pt        The point to test. This must be initialized.
00610  *
00611  * \return          \c 1 if the point is zero.
00612  * \return          \c 0 if the point is non-zero.
00613  * \return          A negative error code on failure.
00614  */
00615 int mbedtls_ecp_is_zero( mbedtls_ecp_point *pt );
00616 
00617 /**
00618  * \brief           This function compares two points.
00619  *
00620  * \note            This assumes that the points are normalized. Otherwise,
00621  *                  they may compare as "not equal" even if they are.
00622  *
00623  * \param P         The first point to compare. This must be initialized.
00624  * \param Q         The second point to compare. This must be initialized.
00625  *
00626  * \return          \c 0 if the points are equal.
00627  * \return          #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if the points are not equal.
00628  */
00629 int mbedtls_ecp_point_cmp( const mbedtls_ecp_point *P,
00630                            const mbedtls_ecp_point *Q );
00631 
00632 /**
00633  * \brief           This function imports a non-zero point from two ASCII
00634  *                  strings.
00635  *
00636  * \param P         The destination point. This must be initialized.
00637  * \param radix     The numeric base of the input.
00638  * \param x         The first affine coordinate, as a null-terminated string.
00639  * \param y         The second affine coordinate, as a null-terminated string.
00640  *
00641  * \return          \c 0 on success.
00642  * \return          An \c MBEDTLS_ERR_MPI_XXX error code on failure.
00643  */
00644 int mbedtls_ecp_point_read_string( mbedtls_ecp_point *P, int radix,
00645                            const char *x, const char *y );
00646 
00647 /**
00648  * \brief           This function exports a point into unsigned binary data.
00649  *
00650  * \param grp       The group to which the point should belong.
00651  *                  This must be initialized and have group parameters
00652  *                  set, for example through mbedtls_ecp_group_load().
00653  * \param P         The point to export. This must be initialized.
00654  * \param format    The point format. This must be either
00655  *                  #MBEDTLS_ECP_PF_COMPRESSED or #MBEDTLS_ECP_PF_UNCOMPRESSED.
00656  *                  (For groups without these formats, this parameter is
00657  *                  ignored. But it still has to be either of the above
00658  *                  values.)
00659  * \param olen      The address at which to store the length of
00660  *                  the output in Bytes. This must not be \c NULL.
00661  * \param buf       The output buffer. This must be a writable buffer
00662  *                  of length \p buflen Bytes.
00663  * \param buflen    The length of the output buffer \p buf in Bytes.
00664  *
00665  * \return          \c 0 on success.
00666  * \return          #MBEDTLS_ERR_ECP_BUFFER_TOO_SMALL if the output buffer
00667  *                  is too small to hold the point.
00668  * \return          #MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE if the point format
00669  *                  or the export for the given group is not implemented.
00670  * \return          Another negative error code on other kinds of failure.
00671  */
00672 int mbedtls_ecp_point_write_binary( const mbedtls_ecp_group *grp,
00673                                     const mbedtls_ecp_point *P,
00674                                     int format, size_t *olen,
00675                                     unsigned char *buf, size_t buflen );
00676 
00677 /**
00678  * \brief           This function imports a point from unsigned binary data.
00679  *
00680  * \note            This function does not check that the point actually
00681  *                  belongs to the given group, see mbedtls_ecp_check_pubkey()
00682  *                  for that.
00683  *
00684  * \param grp       The group to which the point should belong.
00685  *                  This must be initialized and have group parameters
00686  *                  set, for example through mbedtls_ecp_group_load().
00687  * \param P         The destination context to import the point to.
00688  *                  This must be initialized.
00689  * \param buf       The input buffer. This must be a readable buffer
00690  *                  of length \p ilen Bytes.
00691  * \param ilen      The length of the input buffer \p buf in Bytes.
00692  *
00693  * \return          \c 0 on success.
00694  * \return          #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if the input is invalid.
00695  * \return          #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory-allocation failure.
00696  * \return          #MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE if the import for the
00697  *                  given group is not implemented.
00698  */
00699 int mbedtls_ecp_point_read_binary( const mbedtls_ecp_group *grp,
00700                                    mbedtls_ecp_point *P,
00701                                    const unsigned char *buf, size_t ilen );
00702 
00703 /**
00704  * \brief           This function imports a point from a TLS ECPoint record.
00705  *
00706  * \note            On function return, \p *buf is updated to point immediately
00707  *                  after the ECPoint record.
00708  *
00709  * \param grp       The ECP group to use.
00710  *                  This must be initialized and have group parameters
00711  *                  set, for example through mbedtls_ecp_group_load().
00712  * \param pt        The destination point.
00713  * \param buf       The address of the pointer to the start of the input buffer.
00714  * \param len       The length of the buffer.
00715  *
00716  * \return          \c 0 on success.
00717  * \return          An \c MBEDTLS_ERR_MPI_XXX error code on initialization
00718  *                  failure.
00719  * \return          #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if input is invalid.
00720  */
00721 int mbedtls_ecp_tls_read_point( const mbedtls_ecp_group *grp,
00722                                 mbedtls_ecp_point *pt,
00723                                 const unsigned char **buf, size_t len );
00724 
00725 /**
00726  * \brief           This function exports a point as a TLS ECPoint record
00727  *                  defined in RFC 4492, Section 5.4.
00728  *
00729  * \param grp       The ECP group to use.
00730  *                  This must be initialized and have group parameters
00731  *                  set, for example through mbedtls_ecp_group_load().
00732  * \param pt        The point to be exported. This must be initialized.
00733  * \param format    The point format to use. This must be either
00734  *                  #MBEDTLS_ECP_PF_COMPRESSED or #MBEDTLS_ECP_PF_UNCOMPRESSED.
00735  * \param olen      The address at which to store the length in Bytes
00736  *                  of the data written.
00737  * \param buf       The target buffer. This must be a writable buffer of
00738  *                  length \p blen Bytes.
00739  * \param blen      The length of the target buffer \p buf in Bytes.
00740  *
00741  * \return          \c 0 on success.
00742  * \return          #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if the input is invalid.
00743  * \return          #MBEDTLS_ERR_ECP_BUFFER_TOO_SMALL if the target buffer
00744  *                  is too small to hold the exported point.
00745  * \return          Another negative error code on other kinds of failure.
00746  */
00747 int mbedtls_ecp_tls_write_point( const mbedtls_ecp_group *grp,
00748                                  const mbedtls_ecp_point *pt,
00749                                  int format, size_t *olen,
00750                                  unsigned char *buf, size_t blen );
00751 
00752 /**
00753  * \brief           This function sets up an ECP group context
00754  *                  from a standardized set of domain parameters.
00755  *
00756  * \note            The index should be a value of the NamedCurve enum,
00757  *                  as defined in <em>RFC-4492: Elliptic Curve Cryptography
00758  *                  (ECC) Cipher Suites for Transport Layer Security (TLS)</em>,
00759  *                  usually in the form of an \c MBEDTLS_ECP_DP_XXX macro.
00760  *
00761  * \param grp       The group context to setup. This must be initialized.
00762  * \param id        The identifier of the domain parameter set to load.
00763  *
00764  * \return          \c 0 on success.
00765  * \return          #MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE if \p id doesn't
00766  *                  correspond to a known group.
00767  * \return          Another negative error code on other kinds of failure.
00768  */
00769 int mbedtls_ecp_group_load( mbedtls_ecp_group *grp, mbedtls_ecp_group_id id );
00770 
00771 /**
00772  * \brief           This function sets up an ECP group context from a TLS
00773  *                  ECParameters record as defined in RFC 4492, Section 5.4.
00774  *
00775  * \note            The read pointer \p buf is updated to point right after
00776  *                  the ECParameters record on exit.
00777  *
00778  * \param grp       The group context to setup. This must be initialized.
00779  * \param buf       The address of the pointer to the start of the input buffer.
00780  * \param len       The length of the input buffer \c *buf in Bytes.
00781  *
00782  * \return          \c 0 on success.
00783  * \return          #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if input is invalid.
00784  * \return          #MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE if the group is not
00785  *                  recognized.
00786  * \return          Another negative error code on other kinds of failure.
00787  */
00788 int mbedtls_ecp_tls_read_group( mbedtls_ecp_group *grp,
00789                                 const unsigned char **buf, size_t len );
00790 
00791 /**
00792  * \brief           This function extracts an elliptic curve group ID from a
00793  *                  TLS ECParameters record as defined in RFC 4492, Section 5.4.
00794  *
00795  * \note            The read pointer \p buf is updated to point right after
00796  *                  the ECParameters record on exit.
00797  *
00798  * \param grp       The address at which to store the group id.
00799  *                  This must not be \c NULL.
00800  * \param buf       The address of the pointer to the start of the input buffer.
00801  * \param len       The length of the input buffer \c *buf in Bytes.
00802  *
00803  * \return          \c 0 on success.
00804  * \return          #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if input is invalid.
00805  * \return          #MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE if the group is not
00806  *                  recognized.
00807  * \return          Another negative error code on other kinds of failure.
00808  */
00809 int mbedtls_ecp_tls_read_group_id( mbedtls_ecp_group_id *grp,
00810                                    const unsigned char **buf,
00811                                    size_t len );
00812 /**
00813  * \brief           This function exports an elliptic curve as a TLS
00814  *                  ECParameters record as defined in RFC 4492, Section 5.4.
00815  *
00816  * \param grp       The ECP group to be exported.
00817  *                  This must be initialized and have group parameters
00818  *                  set, for example through mbedtls_ecp_group_load().
00819  * \param olen      The address at which to store the number of Bytes written.
00820  *                  This must not be \c NULL.
00821  * \param buf       The buffer to write to. This must be a writable buffer
00822  *                  of length \p blen Bytes.
00823  * \param blen      The length of the output buffer \p buf in Bytes.
00824  *
00825  * \return          \c 0 on success.
00826  * \return          #MBEDTLS_ERR_ECP_BUFFER_TOO_SMALL if the output
00827  *                  buffer is too small to hold the exported group.
00828  * \return          Another negative error code on other kinds of failure.
00829  */
00830 int mbedtls_ecp_tls_write_group( const mbedtls_ecp_group *grp,
00831                                  size_t *olen,
00832                                  unsigned char *buf, size_t blen );
00833 
00834 /**
00835  * \brief           This function performs a scalar multiplication of a point
00836  *                  by an integer: \p R = \p m * \p P.
00837  *
00838  *                  It is not thread-safe to use same group in multiple threads.
00839  *
00840  * \note            To prevent timing attacks, this function
00841  *                  executes the exact same sequence of base-field
00842  *                  operations for any valid \p m. It avoids any if-branch or
00843  *                  array index depending on the value of \p m.
00844  *
00845  * \note            If \p f_rng is not NULL, it is used to randomize
00846  *                  intermediate results to prevent potential timing attacks
00847  *                  targeting these results. We recommend always providing
00848  *                  a non-NULL \p f_rng. The overhead is negligible.
00849  *
00850  * \param grp       The ECP group to use.
00851  *                  This must be initialized and have group parameters
00852  *                  set, for example through mbedtls_ecp_group_load().
00853  * \param R         The point in which to store the result of the calculation.
00854  *                  This must be initialized.
00855  * \param m         The integer by which to multiply. This must be initialized.
00856  * \param P         The point to multiply. This must be initialized.
00857  * \param f_rng     The RNG function. This may be \c NULL if randomization
00858  *                  of intermediate results isn't desired (discouraged).
00859  * \param p_rng     The RNG context to be passed to \p p_rng.
00860  *
00861  * \return          \c 0 on success.
00862  * \return          #MBEDTLS_ERR_ECP_INVALID_KEY if \p m is not a valid private
00863  *                  key, or \p P is not a valid public key.
00864  * \return          #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory-allocation failure.
00865  * \return          Another negative error code on other kinds of failure.
00866  */
00867 int mbedtls_ecp_mul( mbedtls_ecp_group *grp, mbedtls_ecp_point *R,
00868              const mbedtls_mpi *m, const mbedtls_ecp_point *P,
00869              int (*f_rng)(void *, unsigned char *, size_t), void *p_rng );
00870 
00871 /**
00872  * \brief           This function performs multiplication of a point by
00873  *                  an integer: \p R = \p m * \p P in a restartable way.
00874  *
00875  * \see             mbedtls_ecp_mul()
00876  *
00877  * \note            This function does the same as \c mbedtls_ecp_mul(), but
00878  *                  it can return early and restart according to the limit set
00879  *                  with \c mbedtls_ecp_set_max_ops() to reduce blocking.
00880  *
00881  * \param grp       The ECP group to use.
00882  *                  This must be initialized and have group parameters
00883  *                  set, for example through mbedtls_ecp_group_load().
00884  * \param R         The point in which to store the result of the calculation.
00885  *                  This must be initialized.
00886  * \param m         The integer by which to multiply. This must be initialized.
00887  * \param P         The point to multiply. This must be initialized.
00888  * \param f_rng     The RNG function. This may be \c NULL if randomization
00889  *                  of intermediate results isn't desired (discouraged).
00890  * \param p_rng     The RNG context to be passed to \p p_rng.
00891  * \param rs_ctx    The restart context (NULL disables restart).
00892  *
00893  * \return          \c 0 on success.
00894  * \return          #MBEDTLS_ERR_ECP_INVALID_KEY if \p m is not a valid private
00895  *                  key, or \p P is not a valid public key.
00896  * \return          #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory-allocation failure.
00897  * \return          #MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of
00898  *                  operations was reached: see \c mbedtls_ecp_set_max_ops().
00899  * \return          Another negative error code on other kinds of failure.
00900  */
00901 int mbedtls_ecp_mul_restartable( mbedtls_ecp_group *grp, mbedtls_ecp_point *R,
00902              const mbedtls_mpi *m, const mbedtls_ecp_point *P,
00903              int (*f_rng)(void *, unsigned char *, size_t), void *p_rng,
00904              mbedtls_ecp_restart_ctx *rs_ctx );
00905 
00906 /**
00907  * \brief           This function performs multiplication and addition of two
00908  *                  points by integers: \p R = \p m * \p P + \p n * \p Q
00909  *
00910  *                  It is not thread-safe to use same group in multiple threads.
00911  *
00912  * \note            In contrast to mbedtls_ecp_mul(), this function does not
00913  *                  guarantee a constant execution flow and timing.
00914  *
00915  * \param grp       The ECP group to use.
00916  *                  This must be initialized and have group parameters
00917  *                  set, for example through mbedtls_ecp_group_load().
00918  * \param R         The point in which to store the result of the calculation.
00919  *                  This must be initialized.
00920  * \param m         The integer by which to multiply \p P.
00921  *                  This must be initialized.
00922  * \param P         The point to multiply by \p m. This must be initialized.
00923  * \param n         The integer by which to multiply \p Q.
00924  *                  This must be initialized.
00925  * \param Q         The point to be multiplied by \p n.
00926  *                  This must be initialized.
00927  *
00928  * \return          \c 0 on success.
00929  * \return          #MBEDTLS_ERR_ECP_INVALID_KEY if \p m or \p n are not
00930  *                  valid private keys, or \p P or \p Q are not valid public
00931  *                  keys.
00932  * \return          #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory-allocation failure.
00933  * \return          Another negative error code on other kinds of failure.
00934  */
00935 int mbedtls_ecp_muladd( mbedtls_ecp_group *grp, mbedtls_ecp_point *R,
00936              const mbedtls_mpi *m, const mbedtls_ecp_point *P,
00937              const mbedtls_mpi *n, const mbedtls_ecp_point *Q );
00938 
00939 /**
00940  * \brief           This function performs multiplication and addition of two
00941  *                  points by integers: \p R = \p m * \p P + \p n * \p Q in a
00942  *                  restartable way.
00943  *
00944  * \see             \c mbedtls_ecp_muladd()
00945  *
00946  * \note            This function works the same as \c mbedtls_ecp_muladd(),
00947  *                  but it can return early and restart according to the limit
00948  *                  set with \c mbedtls_ecp_set_max_ops() to reduce blocking.
00949  *
00950  * \param grp       The ECP group to use.
00951  *                  This must be initialized and have group parameters
00952  *                  set, for example through mbedtls_ecp_group_load().
00953  * \param R         The point in which to store the result of the calculation.
00954  *                  This must be initialized.
00955  * \param m         The integer by which to multiply \p P.
00956  *                  This must be initialized.
00957  * \param P         The point to multiply by \p m. This must be initialized.
00958  * \param n         The integer by which to multiply \p Q.
00959  *                  This must be initialized.
00960  * \param Q         The point to be multiplied by \p n.
00961  *                  This must be initialized.
00962  * \param rs_ctx    The restart context (NULL disables restart).
00963  *
00964  * \return          \c 0 on success.
00965  * \return          #MBEDTLS_ERR_ECP_INVALID_KEY if \p m or \p n are not
00966  *                  valid private keys, or \p P or \p Q are not valid public
00967  *                  keys.
00968  * \return          #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory-allocation failure.
00969  * \return          #MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of
00970  *                  operations was reached: see \c mbedtls_ecp_set_max_ops().
00971  * \return          Another negative error code on other kinds of failure.
00972  */
00973 int mbedtls_ecp_muladd_restartable(
00974              mbedtls_ecp_group *grp, mbedtls_ecp_point *R,
00975              const mbedtls_mpi *m, const mbedtls_ecp_point *P,
00976              const mbedtls_mpi *n, const mbedtls_ecp_point *Q,
00977              mbedtls_ecp_restart_ctx *rs_ctx );
00978 
00979 /**
00980  * \brief           This function checks that a point is a valid public key
00981  *                  on this curve.
00982  *
00983  *                  It only checks that the point is non-zero, has
00984  *                  valid coordinates and lies on the curve. It does not verify
00985  *                  that it is indeed a multiple of \p G. This additional
00986  *                  check is computationally more expensive, is not required
00987  *                  by standards, and should not be necessary if the group
00988  *                  used has a small cofactor. In particular, it is useless for
00989  *                  the NIST groups which all have a cofactor of 1.
00990  *
00991  * \note            This function uses bare components rather than an
00992  *                  ::mbedtls_ecp_keypair structure, to ease use with other
00993  *                  structures, such as ::mbedtls_ecdh_context or
00994  *                  ::mbedtls_ecdsa_context.
00995  *
00996  * \param grp       The ECP group the point should belong to.
00997  *                  This must be initialized and have group parameters
00998  *                  set, for example through mbedtls_ecp_group_load().
00999  * \param pt        The point to check. This must be initialized.
01000  *
01001  * \return          \c 0 if the point is a valid public key.
01002  * \return          #MBEDTLS_ERR_ECP_INVALID_KEY if the point is not
01003  *                  a valid public key for the given curve.
01004  * \return          Another negative error code on other kinds of failure.
01005  */
01006 int mbedtls_ecp_check_pubkey( const mbedtls_ecp_group *grp,
01007                               const mbedtls_ecp_point *pt );
01008 
01009 /**
01010  * \brief           This function checks that an \p mbedtls_mpi is a
01011  *                  valid private key for this curve.
01012  *
01013  * \note            This function uses bare components rather than an
01014  *                  ::mbedtls_ecp_keypair structure to ease use with other
01015  *                  structures, such as ::mbedtls_ecdh_context or
01016  *                  ::mbedtls_ecdsa_context.
01017  *
01018  * \param grp       The ECP group the private key should belong to.
01019  *                  This must be initialized and have group parameters
01020  *                  set, for example through mbedtls_ecp_group_load().
01021  * \param d         The integer to check. This must be initialized.
01022  *
01023  * \return          \c 0 if the point is a valid private key.
01024  * \return          #MBEDTLS_ERR_ECP_INVALID_KEY if the point is not a valid
01025  *                  private key for the given curve.
01026  * \return          Another negative error code on other kinds of failure.
01027  */
01028 int mbedtls_ecp_check_privkey( const mbedtls_ecp_group *grp,
01029                                const mbedtls_mpi *d );
01030 
01031 /**
01032  * \brief           This function generates a private key.
01033  *
01034  * \param grp       The ECP group to generate a private key for.
01035  *                  This must be initialized and have group parameters
01036  *                  set, for example through mbedtls_ecp_group_load().
01037  * \param d         The destination MPI (secret part). This must be initialized.
01038  * \param f_rng     The RNG function. This must not be \c NULL.
01039  * \param p_rng     The RNG parameter to be passed to \p f_rng. This may be
01040  *                  \c NULL if \p f_rng doesn't need a context argument.
01041  *
01042  * \return          \c 0 on success.
01043  * \return          An \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_MPI_XXX error code
01044  *                  on failure.
01045  */
01046 int mbedtls_ecp_gen_privkey( const mbedtls_ecp_group *grp,
01047                      mbedtls_mpi *d,
01048                      int (*f_rng)(void *, unsigned char *, size_t),
01049                      void *p_rng );
01050 
01051 /**
01052  * \brief           This function generates a keypair with a configurable base
01053  *                  point.
01054  *
01055  * \note            This function uses bare components rather than an
01056  *                  ::mbedtls_ecp_keypair structure to ease use with other
01057  *                  structures, such as ::mbedtls_ecdh_context or
01058  *                  ::mbedtls_ecdsa_context.
01059  *
01060  * \param grp       The ECP group to generate a key pair for.
01061  *                  This must be initialized and have group parameters
01062  *                  set, for example through mbedtls_ecp_group_load().
01063  * \param G         The base point to use. This must be initialized
01064  *                  and belong to \p grp. It replaces the default base
01065  *                  point \c grp->G used by mbedtls_ecp_gen_keypair().
01066  * \param d         The destination MPI (secret part).
01067  *                  This must be initialized.
01068  * \param Q         The destination point (public part).
01069  *                  This must be initialized.
01070  * \param f_rng     The RNG function. This must not be \c NULL.
01071  * \param p_rng     The RNG context to be passed to \p f_rng. This may
01072  *                  be \c NULL if \p f_rng doesn't need a context argument.
01073  *
01074  * \return          \c 0 on success.
01075  * \return          An \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_MPI_XXX error code
01076  *                  on failure.
01077  */
01078 int mbedtls_ecp_gen_keypair_base( mbedtls_ecp_group *grp,
01079                                   const mbedtls_ecp_point *G,
01080                                   mbedtls_mpi *d, mbedtls_ecp_point *Q,
01081                                   int (*f_rng)(void *, unsigned char *, size_t),
01082                                   void *p_rng );
01083 
01084 /**
01085  * \brief           This function generates an ECP keypair.
01086  *
01087  * \note            This function uses bare components rather than an
01088  *                  ::mbedtls_ecp_keypair structure to ease use with other
01089  *                  structures, such as ::mbedtls_ecdh_context or
01090  *                  ::mbedtls_ecdsa_context.
01091  *
01092  * \param grp       The ECP group to generate a key pair for.
01093  *                  This must be initialized and have group parameters
01094  *                  set, for example through mbedtls_ecp_group_load().
01095  * \param d         The destination MPI (secret part).
01096  *                  This must be initialized.
01097  * \param Q         The destination point (public part).
01098  *                  This must be initialized.
01099  * \param f_rng     The RNG function. This must not be \c NULL.
01100  * \param p_rng     The RNG context to be passed to \p f_rng. This may
01101  *                  be \c NULL if \p f_rng doesn't need a context argument.
01102  *
01103  * \return          \c 0 on success.
01104  * \return          An \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_MPI_XXX error code
01105  *                  on failure.
01106  */
01107 int mbedtls_ecp_gen_keypair( mbedtls_ecp_group *grp, mbedtls_mpi *d,
01108                              mbedtls_ecp_point *Q,
01109                              int (*f_rng)(void *, unsigned char *, size_t),
01110                              void *p_rng );
01111 
01112 /**
01113  * \brief           This function generates an ECP key.
01114  *
01115  * \param grp_id    The ECP group identifier.
01116  * \param key       The destination key. This must be initialized.
01117  * \param f_rng     The RNG function to use. This must not be \c NULL.
01118  * \param p_rng     The RNG context to be passed to \p f_rng. This may
01119  *                  be \c NULL if \p f_rng doesn't need a context argument.
01120  *
01121  * \return          \c 0 on success.
01122  * \return          An \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_MPI_XXX error code
01123  *                  on failure.
01124  */
01125 int mbedtls_ecp_gen_key( mbedtls_ecp_group_id grp_id, mbedtls_ecp_keypair *key,
01126                          int (*f_rng)(void *, unsigned char *, size_t),
01127                          void *p_rng );
01128 
01129 /**
01130  * \brief           This function reads an elliptic curve private key.
01131  *
01132  * \param grp_id    The ECP group identifier.
01133  * \param key       The destination key.
01134  * \param buf       The the buffer containing the binary representation of the
01135  *                  key. (Big endian integer for Weierstrass curves, byte
01136  *                  string for Montgomery curves.)
01137  * \param buflen    The length of the buffer in bytes.
01138  *
01139  * \return          \c 0 on success.
01140  * \return          #MBEDTLS_ERR_ECP_INVALID_KEY error if the key is
01141  *                  invalid.
01142  * \return          #MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed.
01143  * \return          #MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE if the operation for
01144  *                  the group is not implemented.
01145  * \return          Another negative error code on different kinds of failure.
01146  */
01147 int mbedtls_ecp_read_key( mbedtls_ecp_group_id grp_id, mbedtls_ecp_keypair *key,
01148                           const unsigned char *buf, size_t buflen );
01149 /**
01150  * \brief           This function checks that the keypair objects
01151  *                  \p pub and \p prv have the same group and the
01152  *                  same public point, and that the private key in
01153  *                  \p prv is consistent with the public key.
01154  *
01155  * \param pub       The keypair structure holding the public key. This
01156  *                  must be initialized. If it contains a private key, that
01157  *                  part is ignored.
01158  * \param prv       The keypair structure holding the full keypair.
01159  *                  This must be initialized.
01160  *
01161  * \return          \c 0 on success, meaning that the keys are valid and match.
01162  * \return          #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if the keys are invalid or do not match.
01163  * \return          An \c MBEDTLS_ERR_ECP_XXX or an \c MBEDTLS_ERR_MPI_XXX
01164  *                  error code on calculation failure.
01165  */
01166 int mbedtls_ecp_check_pub_priv( const mbedtls_ecp_keypair *pub,
01167                                 const mbedtls_ecp_keypair *prv );
01168 
01169 #if defined(MBEDTLS_SELF_TEST)
01170 
01171 /**
01172  * \brief          The ECP checkup routine.
01173  *
01174  * \return         \c 0 on success.
01175  * \return         \c 1 on failure.
01176  */
01177 int mbedtls_ecp_self_test( int verbose );
01178 
01179 #endif /* MBEDTLS_SELF_TEST */
01180 
01181 #ifdef __cplusplus
01182 }
01183 #endif
01184 
01185 #endif /* ecp.h */