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 #include "bignum.h"
00040 
00041 /*
00042  * ECP error codes
00043  */
00044 #define MBEDTLS_ERR_ECP_BAD_INPUT_DATA                    -0x4F80  /**< Bad input parameters to function. */
00045 #define MBEDTLS_ERR_ECP_BUFFER_TOO_SMALL                  -0x4F00  /**< The buffer is too small to write to. */
00046 #define MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE               -0x4E80  /**< The requested feature is not available, for example, the requested curve is not supported. */
00047 #define MBEDTLS_ERR_ECP_VERIFY_FAILED                     -0x4E00  /**< The signature is not valid. */
00048 #define MBEDTLS_ERR_ECP_ALLOC_FAILED                      -0x4D80  /**< Memory allocation failed. */
00049 #define MBEDTLS_ERR_ECP_RANDOM_FAILED                     -0x4D00  /**< Generation of random value, such as ephemeral key, failed. */
00050 #define MBEDTLS_ERR_ECP_INVALID_KEY                       -0x4C80  /**< Invalid private or public key. */
00051 #define MBEDTLS_ERR_ECP_SIG_LEN_MISMATCH                  -0x4C00  /**< The buffer contains a valid signature followed by more data. */
00052 #define MBEDTLS_ERR_ECP_HW_ACCEL_FAILED                   -0x4B80  /**< The ECP hardware accelerator failed. */
00053 
00054 #ifdef __cplusplus
00055 extern "C" {
00056 #endif
00057 
00058 /**
00059  * Domain-parameter identifiers: curve, subgroup, and generator.
00060  *
00061  * \note Only curves over prime fields are supported.
00062  *
00063  * \warning This library does not support validation of arbitrary domain
00064  * parameters. Therefore, only standardized domain parameters from trusted
00065  * sources should be used. See mbedtls_ecp_group_load().
00066  */
00067 typedef enum
00068 {
00069     MBEDTLS_ECP_DP_NONE = 0,       /*!< Curve not defined. */
00070     MBEDTLS_ECP_DP_SECP192R1,      /*!< Domain parameters for the 192-bit curve defined by FIPS 186-4 and SEC1. */
00071     MBEDTLS_ECP_DP_SECP224R1,      /*!< Domain parameters for the 224-bit curve defined by FIPS 186-4 and SEC1. */
00072     MBEDTLS_ECP_DP_SECP256R1,      /*!< Domain parameters for the 256-bit curve defined by FIPS 186-4 and SEC1. */
00073     MBEDTLS_ECP_DP_SECP384R1,      /*!< Domain parameters for the 384-bit curve defined by FIPS 186-4 and SEC1. */
00074     MBEDTLS_ECP_DP_SECP521R1,      /*!< Domain parameters for the 521-bit curve defined by FIPS 186-4 and SEC1. */
00075     MBEDTLS_ECP_DP_BP256R1,        /*!< Domain parameters for 256-bit Brainpool curve. */
00076     MBEDTLS_ECP_DP_BP384R1,        /*!< Domain parameters for 384-bit Brainpool curve. */
00077     MBEDTLS_ECP_DP_BP512R1,        /*!< Domain parameters for 512-bit Brainpool curve. */
00078     MBEDTLS_ECP_DP_CURVE25519,     /*!< Domain parameters for Curve25519. */
00079     MBEDTLS_ECP_DP_SECP192K1,      /*!< Domain parameters for 192-bit "Koblitz" curve. */
00080     MBEDTLS_ECP_DP_SECP224K1,      /*!< Domain parameters for 224-bit "Koblitz" curve. */
00081     MBEDTLS_ECP_DP_SECP256K1,      /*!< Domain parameters for 256-bit "Koblitz" curve. */
00082     MBEDTLS_ECP_DP_CURVE448,       /*!< Domain parameters for Curve448. */
00083 } mbedtls_ecp_group_id;
00084 
00085 /**
00086  * The number of supported curves, plus one for #MBEDTLS_ECP_DP_NONE.
00087  *
00088  * \note Montgomery curves are currently excluded.
00089  */
00090 #define MBEDTLS_ECP_DP_MAX     12
00091 
00092 /**
00093  * Curve information, for use by other modules.
00094  */
00095 typedef struct
00096 {
00097     mbedtls_ecp_group_id grp_id ;    /*!< An internal identifier. */
00098     uint16_t tls_id ;                /*!< The TLS NamedCurve identifier. */
00099     uint16_t bit_size ;              /*!< The curve size in bits. */
00100     const char *name ;               /*!< A human-friendly name. */
00101 } mbedtls_ecp_curve_info;
00102 
00103 /**
00104  * \brief           The ECP point structure, in Jacobian coordinates.
00105  *
00106  * \note            All functions expect and return points satisfying
00107  *                  the following condition: <code>Z == 0</code> or
00108  *                  <code>Z == 1</code>. Other values of \p Z are
00109  *                  used only by internal functions.
00110  *                  The point is zero, or "at infinity", if <code>Z == 0</code>.
00111  *                  Otherwise, \p X and \p Y are its standard (affine)
00112  *                  coordinates.
00113  */
00114 typedef struct
00115 {
00116     mbedtls_mpi X ;          /*!< The X coordinate of the ECP point. */
00117     mbedtls_mpi Y ;          /*!< The Y coordinate of the ECP point. */
00118     mbedtls_mpi Z ;          /*!< The Z coordinate of the ECP point. */
00119 }
00120 mbedtls_ecp_point;
00121 
00122 #if !defined(MBEDTLS_ECP_ALT)
00123 /*
00124  * default mbed TLS elliptic curve arithmetic implementation
00125  *
00126  * (in case MBEDTLS_ECP_ALT is defined then the developer has to provide an
00127  * alternative implementation for the whole module and it will replace this
00128  * one.)
00129  */
00130 
00131 /**
00132  * \brief           The ECP group structure.
00133  *
00134  * We consider two types of curve equations:
00135  * <ul><li>Short Weierstrass: <code>y^2 = x^3 + A x + B mod P</code>
00136  * (SEC1 + RFC-4492)</li>
00137  * <li>Montgomery: <code>y^2 = x^3 + A x^2 + x mod P</code> (Curve25519,
00138  * Curve448)</li></ul>
00139  * In both cases, the generator (\p G) for a prime-order subgroup is fixed.
00140  *
00141  * For Short Weierstrass, this subgroup is the whole curve, and its
00142  * cardinality is denoted by \p N. Our code requires that \p N is an
00143  * odd prime as mbedtls_ecp_mul() requires an odd number, and
00144  * mbedtls_ecdsa_sign() requires that it is prime for blinding purposes.
00145  *
00146  * For Montgomery curves, we do not store \p A, but <code>(A + 2) / 4</code>,
00147  * which is the quantity used in the formulas. Additionally, \p nbits is
00148  * not the size of \p N but the required size for private keys.
00149  *
00150  * If \p modp is NULL, reduction modulo \p P is done using a generic algorithm.
00151  * Otherwise, \p modp must point to a function that takes an \p mbedtls_mpi in the
00152  * range of <code>0..2^(2*pbits)-1</code>, and transforms it in-place to an integer
00153  * which is congruent mod \p P to the given MPI, and is close enough to \p pbits
00154  * in size, so that it may be efficiently brought in the 0..P-1 range by a few
00155  * additions or subtractions. Therefore, it is only an approximative modular
00156  * reduction. It must return 0 on success and non-zero on failure.
00157  *
00158  */
00159 typedef struct
00160 {
00161     mbedtls_ecp_group_id id ;    /*!< An internal group identifier. */
00162     mbedtls_mpi P ;              /*!< The prime modulus of the base field. */
00163     mbedtls_mpi A;              /*!< For Short Weierstrass: \p A in the equation. For
00164                                      Montgomery curves: <code>(A + 2) / 4</code>. */
00165     mbedtls_mpi B;              /*!< For Short Weierstrass: \p B in the equation.
00166                                      For Montgomery curves: unused. */
00167     mbedtls_ecp_point G ;        /*!< The generator of the subgroup used. */
00168     mbedtls_mpi N ;              /*!< The order of \p G. */
00169     size_t pbits ;               /*!< The number of bits in \p P.*/
00170     size_t nbits;               /*!< For Short Weierstrass: The number of bits in \p P.
00171                                      For Montgomery curves: the number of bits in the
00172                                      private keys. */
00173     unsigned int h;             /*!< \internal 1 if the constants are static. */
00174     int (*modp)(mbedtls_mpi *); /*!< The function for fast pseudo-reduction
00175                                      mod \p P (see above).*/
00176     int (*t_pre)(mbedtls_ecp_point *, void *);  /*!< Unused. */
00177     int (*t_post)(mbedtls_ecp_point *, void *); /*!< Unused. */
00178     void *t_data ;               /*!< Unused. */
00179     mbedtls_ecp_point *T ;       /*!< Pre-computed points for ecp_mul_comb(). */
00180     size_t T_size ;              /*!< The number of pre-computed points. */
00181 }
00182 mbedtls_ecp_group;
00183 
00184 /**
00185  * \name SECTION: Module settings
00186  *
00187  * The configuration options you can set for this module are in this section.
00188  * Either change them in config.h, or define them using the compiler command line.
00189  * \{
00190  */
00191 
00192 #if !defined(MBEDTLS_ECP_MAX_BITS)
00193 /**
00194  * The maximum size of the groups, that is, of \c N and \c P.
00195  */
00196 #define MBEDTLS_ECP_MAX_BITS     521   /**< The maximum size of groups, in bits. */
00197 #endif
00198 
00199 #define MBEDTLS_ECP_MAX_BYTES    ( ( MBEDTLS_ECP_MAX_BITS + 7 ) / 8 )
00200 #define MBEDTLS_ECP_MAX_PT_LEN   ( 2 * MBEDTLS_ECP_MAX_BYTES + 1 )
00201 
00202 #if !defined(MBEDTLS_ECP_WINDOW_SIZE)
00203 /*
00204  * Maximum "window" size used for point multiplication.
00205  * Default: 6.
00206  * Minimum value: 2. Maximum value: 7.
00207  *
00208  * Result is an array of at most ( 1 << ( MBEDTLS_ECP_WINDOW_SIZE - 1 ) )
00209  * points used for point multiplication. This value is directly tied to EC
00210  * peak memory usage, so decreasing it by one should roughly cut memory usage
00211  * by two (if large curves are in use).
00212  *
00213  * Reduction in size may reduce speed, but larger curves are impacted first.
00214  * Sample performances (in ECDHE handshakes/s, with FIXED_POINT_OPTIM = 1):
00215  *      w-size:     6       5       4       3       2
00216  *      521       145     141     135     120      97
00217  *      384       214     209     198     177     146
00218  *      256       320     320     303     262     226
00219  *      224       475     475     453     398     342
00220  *      192       640     640     633     587     476
00221  */
00222 #define MBEDTLS_ECP_WINDOW_SIZE    6   /**< The maximum window size used. */
00223 #endif /* MBEDTLS_ECP_WINDOW_SIZE */
00224 
00225 #if !defined(MBEDTLS_ECP_FIXED_POINT_OPTIM)
00226 /*
00227  * Trade memory for speed on fixed-point multiplication.
00228  *
00229  * This speeds up repeated multiplication of the generator (that is, the
00230  * multiplication in ECDSA signatures, and half of the multiplications in
00231  * ECDSA verification and ECDHE) by a factor roughly 3 to 4.
00232  *
00233  * The cost is increasing EC peak memory usage by a factor roughly 2.
00234  *
00235  * Change this value to 0 to reduce peak memory usage.
00236  */
00237 #define MBEDTLS_ECP_FIXED_POINT_OPTIM  1   /**< Enable fixed-point speed-up. */
00238 #endif /* MBEDTLS_ECP_FIXED_POINT_OPTIM */
00239 
00240 /* \} name SECTION: Module settings */
00241 
00242 #else  /* MBEDTLS_ECP_ALT */
00243 #include "ecp_alt.h"
00244 #endif /* MBEDTLS_ECP_ALT */
00245 
00246 /**
00247  * \brief    The ECP key-pair structure.
00248  *
00249  * A generic key-pair that may be used for ECDSA and fixed ECDH, for example.
00250  *
00251  * \note    Members are deliberately in the same order as in the
00252  *          ::mbedtls_ecdsa_context structure.
00253  */
00254 typedef struct
00255 {
00256     mbedtls_ecp_group grp ;      /*!<  Elliptic curve and base point     */
00257     mbedtls_mpi d ;              /*!<  our secret value                  */
00258     mbedtls_ecp_point Q ;        /*!<  our public value                  */
00259 }
00260 mbedtls_ecp_keypair;
00261 
00262 /*
00263  * Point formats, from RFC 4492's enum ECPointFormat
00264  */
00265 #define MBEDTLS_ECP_PF_UNCOMPRESSED    0   /**< Uncompressed point format. */
00266 #define MBEDTLS_ECP_PF_COMPRESSED      1   /**< Compressed point format. */
00267 
00268 /*
00269  * Some other constants from RFC 4492
00270  */
00271 #define MBEDTLS_ECP_TLS_NAMED_CURVE    3   /**< The named_curve of ECCurveType. */
00272 
00273 /**
00274  * \brief           This function retrieves the information defined in
00275  *                  mbedtls_ecp_curve_info() for all supported curves in order
00276  *                  of preference.
00277  *
00278  * \return          A statically allocated array. The last entry is 0.
00279  */
00280 const mbedtls_ecp_curve_info *mbedtls_ecp_curve_list( void );
00281 
00282 /**
00283  * \brief           This function retrieves the list of internal group
00284  *                  identifiers of all supported curves in the order of
00285  *                  preference.
00286  *
00287  * \return          A statically allocated array,
00288  *                  terminated with MBEDTLS_ECP_DP_NONE.
00289  */
00290 const mbedtls_ecp_group_id *mbedtls_ecp_grp_id_list( void );
00291 
00292 /**
00293  * \brief           This function retrieves curve information from an internal
00294  *                  group identifier.
00295  *
00296  * \param grp_id    An \c MBEDTLS_ECP_DP_XXX value.
00297  *
00298  * \return          The associated curve information on success.
00299  * \return          NULL on failure.
00300  */
00301 const mbedtls_ecp_curve_info *mbedtls_ecp_curve_info_from_grp_id( mbedtls_ecp_group_id grp_id );
00302 
00303 /**
00304  * \brief           This function retrieves curve information from a TLS
00305  *                  NamedCurve value.
00306  *
00307  * \param tls_id    An \c MBEDTLS_ECP_DP_XXX value.
00308  *
00309  * \return          The associated curve information on success.
00310  * \return          NULL on failure.
00311  */
00312 const mbedtls_ecp_curve_info *mbedtls_ecp_curve_info_from_tls_id( uint16_t tls_id );
00313 
00314 /**
00315  * \brief           This function retrieves curve information from a
00316  *                  human-readable name.
00317  *
00318  * \param name      The human-readable name.
00319  *
00320  * \return          The associated curve information on success.
00321  * \return          NULL on failure.
00322  */
00323 const mbedtls_ecp_curve_info *mbedtls_ecp_curve_info_from_name( const char *name );
00324 
00325 /**
00326  * \brief           This function initializes a point as zero.
00327  *
00328  * \param pt        The point to initialize.
00329  */
00330 void mbedtls_ecp_point_init( mbedtls_ecp_point *pt );
00331 
00332 /**
00333  * \brief           This function initializes an ECP group context
00334  *                  without loading any domain parameters.
00335  *
00336  * \note            After this function is called, domain parameters
00337  *                  for various ECP groups can be loaded through the
00338  *                  mbedtls_ecp_load() or mbedtls_ecp_tls_read_group()
00339  *                  functions.
00340  */
00341 void mbedtls_ecp_group_init( mbedtls_ecp_group *grp );
00342 
00343 /**
00344  * \brief           This function initializes a key pair as an invalid one.
00345  *
00346  * \param key       The key pair to initialize.
00347  */
00348 void mbedtls_ecp_keypair_init( mbedtls_ecp_keypair *key );
00349 
00350 /**
00351  * \brief           This function frees the components of a point.
00352  *
00353  * \param pt        The point to free.
00354  */
00355 void mbedtls_ecp_point_free( mbedtls_ecp_point *pt );
00356 
00357 /**
00358  * \brief           This function frees the components of an ECP group.
00359  * \param grp       The group to free.
00360  */
00361 void mbedtls_ecp_group_free( mbedtls_ecp_group *grp );
00362 
00363 /**
00364  * \brief           This function frees the components of a key pair.
00365  * \param key       The key pair to free.
00366  */
00367 void mbedtls_ecp_keypair_free( mbedtls_ecp_keypair *key );
00368 
00369 /**
00370  * \brief           This function copies the contents of point \p Q into
00371  *                  point \p P.
00372  *
00373  * \param P         The destination point.
00374  * \param Q         The source point.
00375  *
00376  * \return          \c 0 on success.
00377  * \return          #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory-allocation failure.
00378  */
00379 int mbedtls_ecp_copy( mbedtls_ecp_point *P, const mbedtls_ecp_point *Q );
00380 
00381 /**
00382  * \brief           This function copies the contents of group \p src into
00383  *                  group \p dst.
00384  *
00385  * \param dst       The destination group.
00386  * \param src       The source group.
00387  *
00388  * \return          \c 0 on success.
00389  * \return          #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory-allocation failure.
00390  */
00391 int mbedtls_ecp_group_copy( mbedtls_ecp_group *dst, const mbedtls_ecp_group *src );
00392 
00393 /**
00394  * \brief           This function sets a point to zero.
00395  *
00396  * \param pt        The point to set.
00397  *
00398  * \return          \c 0 on success.
00399  * \return          #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory-allocation failure.
00400  */
00401 int mbedtls_ecp_set_zero( mbedtls_ecp_point *pt );
00402 
00403 /**
00404  * \brief           This function checks if a point is zero.
00405  *
00406  * \param pt        The point to test.
00407  *
00408  * \return          \c 1 if the point is zero.
00409  * \return          \c 0 if the point is non-zero.
00410  */
00411 int mbedtls_ecp_is_zero( mbedtls_ecp_point *pt );
00412 
00413 /**
00414  * \brief           This function compares two points.
00415  *
00416  * \note            This assumes that the points are normalized. Otherwise,
00417  *                  they may compare as "not equal" even if they are.
00418  *
00419  * \param P         The first point to compare.
00420  * \param Q         The second point to compare.
00421  *
00422  * \return          \c 0 if the points are equal.
00423  * \return          #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if the points are not equal.
00424  */
00425 int mbedtls_ecp_point_cmp( const mbedtls_ecp_point *P,
00426                            const mbedtls_ecp_point *Q );
00427 
00428 /**
00429  * \brief           This function imports a non-zero point from two ASCII
00430  *                  strings.
00431  *
00432  * \param P         The destination point.
00433  * \param radix     The numeric base of the input.
00434  * \param x         The first affine coordinate, as a null-terminated string.
00435  * \param y         The second affine coordinate, as a null-terminated string.
00436  *
00437  * \return          \c 0 on success.
00438  * \return          An \c MBEDTLS_ERR_MPI_XXX error code on failure.
00439  */
00440 int mbedtls_ecp_point_read_string( mbedtls_ecp_point *P, int radix,
00441                            const char *x, const char *y );
00442 
00443 /**
00444  * \brief           This function exports a point into unsigned binary data.
00445  *
00446  * \param grp       The group to which the point should belong.
00447  * \param P         The point to export.
00448  * \param format    The point format. Should be an \c MBEDTLS_ECP_PF_XXX macro.
00449  * \param olen      The length of the output.
00450  * \param buf       The output buffer.
00451  * \param buflen    The length of the output buffer.
00452  *
00453  * \return          \c 0 on success.
00454  * \return          #MBEDTLS_ERR_ECP_BAD_INPUT_DATA
00455  *                  or #MBEDTLS_ERR_ECP_BUFFER_TOO_SMALL on failure.
00456  */
00457 int mbedtls_ecp_point_write_binary( const mbedtls_ecp_group *grp, const mbedtls_ecp_point *P,
00458                             int format, size_t *olen,
00459                             unsigned char *buf, size_t buflen );
00460 
00461 /**
00462  * \brief           This function imports a point from unsigned binary data.
00463  *
00464  * \note            This function does not check that the point actually
00465  *                  belongs to the given group, see mbedtls_ecp_check_pubkey()
00466  *                  for that.
00467  *
00468  * \param grp       The group to which the point should belong.
00469  * \param P         The point to import.
00470  * \param buf       The input buffer.
00471  * \param ilen      The length of the input.
00472  *
00473  * \return          \c 0 on success.
00474  * \return          #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if input is invalid.
00475  * \return          #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory-allocation failure.
00476  * \return          #MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE if the point format
00477  *                  is not implemented.
00478  *
00479  */
00480 int mbedtls_ecp_point_read_binary( const mbedtls_ecp_group *grp, mbedtls_ecp_point *P,
00481                            const unsigned char *buf, size_t ilen );
00482 
00483 /**
00484  * \brief           This function imports a point from a TLS ECPoint record.
00485  *
00486  * \note            On function return, \p buf is updated to point to immediately
00487  *                  after the ECPoint record.
00488  *
00489  * \param grp       The ECP group used.
00490  * \param pt        The destination point.
00491  * \param buf       The address of the pointer to the start of the input buffer.
00492  * \param len       The length of the buffer.
00493  *
00494  * \return          \c 0 on success.
00495  * \return          An \c MBEDTLS_ERR_MPI_XXX error code on initialization failure.
00496  * \return          #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if input is invalid.
00497  */
00498 int mbedtls_ecp_tls_read_point( const mbedtls_ecp_group *grp, mbedtls_ecp_point *pt,
00499                         const unsigned char **buf, size_t len );
00500 
00501 /**
00502  * \brief           This function exports a point as a TLS ECPoint record.
00503  *
00504  * \param grp       The ECP group used.
00505  * \param pt        The point format to export to. The point format is an
00506  *                  \c MBEDTLS_ECP_PF_XXX constant.
00507  * \param format    The export format.
00508  * \param olen      The length of the data written.
00509  * \param buf       The buffer to write to.
00510  * \param blen      The length of the buffer.
00511  *
00512  * \return          \c 0 on success.
00513  * \return          #MBEDTLS_ERR_ECP_BAD_INPUT_DATA or
00514  *                  #MBEDTLS_ERR_ECP_BUFFER_TOO_SMALL on failure.
00515  */
00516 int mbedtls_ecp_tls_write_point( const mbedtls_ecp_group *grp, const mbedtls_ecp_point *pt,
00517                          int format, size_t *olen,
00518                          unsigned char *buf, size_t blen );
00519 
00520 /**
00521  * \brief           This function sets a group using standardized domain parameters.
00522  *
00523  * \note            The index should be a value of the NamedCurve enum,
00524  *                  as defined in <em>RFC-4492: Elliptic Curve Cryptography
00525  *                  (ECC) Cipher Suites for Transport Layer Security (TLS)</em>,
00526  *                  usually in the form of an \c MBEDTLS_ECP_DP_XXX macro.
00527  *
00528  * \param grp       The destination group.
00529  * \param id        The identifier of the domain parameter set to load.
00530  *
00531  * \return          \c 0 on success,
00532  * \return          An \c MBEDTLS_ERR_MPI_XXX error code on initialization failure.
00533  * \return          #MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE for unkownn groups.
00534 
00535  */
00536 int mbedtls_ecp_group_load( mbedtls_ecp_group *grp, mbedtls_ecp_group_id id );
00537 
00538 /**
00539  * \brief           This function sets a group from a TLS ECParameters record.
00540  *
00541  * \note            \p buf is updated to point right after the ECParameters record
00542  *                  on exit.
00543  *
00544  * \param grp       The destination group.
00545  * \param buf       The address of the pointer to the start of the input buffer.
00546  * \param len       The length of the buffer.
00547  *
00548  * \return          \c 0 on success.
00549  * \return          An \c MBEDTLS_ERR_MPI_XXX error code on initialization failure.
00550  * \return          #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if input is invalid.
00551  */
00552 int mbedtls_ecp_tls_read_group( mbedtls_ecp_group *grp, const unsigned char **buf, size_t len );
00553 
00554 /**
00555  * \brief           This function writes the TLS ECParameters record for a group.
00556  *
00557  * \param grp       The ECP group used.
00558  * \param olen      The number of Bytes written.
00559  * \param buf       The buffer to write to.
00560  * \param blen      The length of the buffer.
00561  *
00562  * \return          \c 0 on success.
00563  * \return          #MBEDTLS_ERR_ECP_BUFFER_TOO_SMALL on failure.
00564  */
00565 int mbedtls_ecp_tls_write_group( const mbedtls_ecp_group *grp, size_t *olen,
00566                          unsigned char *buf, size_t blen );
00567 
00568 /**
00569  * \brief           This function performs multiplication of a point by
00570  *                  an integer: \p R = \p m * \p P.
00571  *
00572  *                  It is not thread-safe to use same group in multiple threads.
00573  *
00574  * \note            To prevent timing attacks, this function
00575  *                  executes the exact same sequence of base-field
00576  *                  operations for any valid \p m. It avoids any if-branch or
00577  *                  array index depending on the value of \p m.
00578  *
00579  * \note            If \p f_rng is not NULL, it is used to randomize
00580  *                  intermediate results to prevent potential timing attacks
00581  *                  targeting these results. We recommend always providing
00582  *                  a non-NULL \p f_rng. The overhead is negligible.
00583  *
00584  * \param grp       The ECP group.
00585  * \param R         The destination point.
00586  * \param m         The integer by which to multiply.
00587  * \param P         The point to multiply.
00588  * \param f_rng     The RNG function.
00589  * \param p_rng     The RNG context.
00590  *
00591  * \return          \c 0 on success.
00592  * \return          #MBEDTLS_ERR_ECP_INVALID_KEY if \p m is not a valid private
00593  *                  key, or \p P is not a valid public key.
00594  * \return          #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory-allocation failure.
00595  */
00596 int mbedtls_ecp_mul( mbedtls_ecp_group *grp, mbedtls_ecp_point *R,
00597              const mbedtls_mpi *m, const mbedtls_ecp_point *P,
00598              int (*f_rng)(void *, unsigned char *, size_t), void *p_rng );
00599 
00600 /**
00601  * \brief           This function performs multiplication and addition of two
00602  *                  points by integers: \p R = \p m * \p P + \p n * \p Q
00603  *
00604  *                  It is not thread-safe to use same group in multiple threads.
00605  *
00606  * \note            In contrast to mbedtls_ecp_mul(), this function does not
00607  *                  guarantee a constant execution flow and timing.
00608  *
00609  * \param grp       The ECP group.
00610  * \param R         The destination point.
00611  * \param m         The integer by which to multiply \p P.
00612  * \param P         The point to multiply by \p m.
00613  * \param n         The integer by which to multiply \p Q.
00614  * \param Q         The point to be multiplied by \p n.
00615  *
00616  * \return          \c 0 on success.
00617  * \return          #MBEDTLS_ERR_ECP_INVALID_KEY if \p m or \p n are not
00618  *                  valid private keys, or \p P or \p Q are not valid public
00619  *                  keys.
00620  * \return          #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory-allocation failure.
00621  */
00622 int mbedtls_ecp_muladd( mbedtls_ecp_group *grp, mbedtls_ecp_point *R,
00623              const mbedtls_mpi *m, const mbedtls_ecp_point *P,
00624              const mbedtls_mpi *n, const mbedtls_ecp_point *Q );
00625 
00626 /**
00627  * \brief           This function checks that a point is a valid public key
00628  *                  on this curve.
00629  *
00630  *                  It only checks that the point is non-zero, has
00631  *                  valid coordinates and lies on the curve. It does not verify
00632  *                  that it is indeed a multiple of \p G. This additional
00633  *                  check is computationally more expensive, is not required
00634  *                  by standards, and should not be necessary if the group
00635  *                  used has a small cofactor. In particular, it is useless for
00636  *                  the NIST groups which all have a cofactor of 1.
00637  *
00638  * \note            This function uses bare components rather than an
00639  *                  ::mbedtls_ecp_keypair structure, to ease use with other
00640  *                  structures, such as ::mbedtls_ecdh_context or
00641  *                  ::mbedtls_ecdsa_context.
00642  *
00643  * \param grp       The curve the point should lie on.
00644  * \param pt        The point to check.
00645  *
00646  * \return          \c 0 if the point is a valid public key.
00647  * \return          #MBEDTLS_ERR_ECP_INVALID_KEY on failure.
00648  */
00649 int mbedtls_ecp_check_pubkey( const mbedtls_ecp_group *grp, const mbedtls_ecp_point *pt );
00650 
00651 /**
00652  * \brief           This function checks that an \p mbedtls_mpi is a valid private
00653  *                  key for this curve.
00654  *
00655  * \note            This function uses bare components rather than an
00656  *                  ::mbedtls_ecp_keypair structure to ease use with other
00657  *                  structures, such as ::mbedtls_ecdh_context or
00658  *                  ::mbedtls_ecdsa_context.
00659  *
00660  * \param grp       The group used.
00661  * \param d         The integer to check.
00662  *
00663  * \return          \c 0 if the point is a valid private key.
00664  * \return          #MBEDTLS_ERR_ECP_INVALID_KEY on failure.
00665  */
00666 int mbedtls_ecp_check_privkey( const mbedtls_ecp_group *grp, const mbedtls_mpi *d );
00667 
00668 /**
00669  * \brief           This function generates a keypair with a configurable base
00670  *                  point.
00671  *
00672  * \note            This function uses bare components rather than an
00673  *                  ::mbedtls_ecp_keypair structure to ease use with other
00674  *                  structures, such as ::mbedtls_ecdh_context or
00675  *                  ::mbedtls_ecdsa_context.
00676  *
00677  * \param grp       The ECP group.
00678  * \param G         The chosen base point.
00679  * \param d         The destination MPI (secret part).
00680  * \param Q         The destination point (public part).
00681  * \param f_rng     The RNG function.
00682  * \param p_rng     The RNG context.
00683  *
00684  * \return          \c 0 on success.
00685  * \return          An \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_MPI_XXX error code
00686  *                  on failure.
00687  */
00688 int mbedtls_ecp_gen_keypair_base( mbedtls_ecp_group *grp,
00689                      const mbedtls_ecp_point *G,
00690                      mbedtls_mpi *d, mbedtls_ecp_point *Q,
00691                      int (*f_rng)(void *, unsigned char *, size_t),
00692                      void *p_rng );
00693 
00694 /**
00695  * \brief           This function generates an ECP keypair.
00696  *
00697  * \note            This function uses bare components rather than an
00698  *                  ::mbedtls_ecp_keypair structure to ease use with other
00699  *                  structures, such as ::mbedtls_ecdh_context or
00700  *                  ::mbedtls_ecdsa_context.
00701  *
00702  * \param grp       The ECP group.
00703  * \param d         The destination MPI (secret part).
00704  * \param Q         The destination point (public part).
00705  * \param f_rng     The RNG function.
00706  * \param p_rng     The RNG context.
00707  *
00708  * \return          \c 0 on success.
00709  * \return          An \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_MPI_XXX error code
00710  *                  on failure.
00711  */
00712 int mbedtls_ecp_gen_keypair( mbedtls_ecp_group *grp, mbedtls_mpi *d, mbedtls_ecp_point *Q,
00713                      int (*f_rng)(void *, unsigned char *, size_t),
00714                      void *p_rng );
00715 
00716 /**
00717  * \brief           This function generates an ECP key.
00718  *
00719  * \param grp_id    The ECP group identifier.
00720  * \param key       The destination key.
00721  * \param f_rng     The RNG function.
00722  * \param p_rng     The RNG context.
00723  *
00724  * \return          \c 0 on success.
00725  * \return          An \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_MPI_XXX error code
00726  *                  on failure.
00727  */
00728 int mbedtls_ecp_gen_key( mbedtls_ecp_group_id grp_id, mbedtls_ecp_keypair *key,
00729                 int (*f_rng)(void *, unsigned char *, size_t), void *p_rng );
00730 
00731 /**
00732  * \brief           This function checks that the keypair objects
00733  *                  \p pub and \p prv have the same group and the
00734  *                  same public point, and that the private key in
00735  *                  \p prv is consistent with the public key.
00736  *
00737  * \param pub       The keypair structure holding the public key.
00738  *                  If it contains a private key, that part is ignored.
00739  * \param prv       The keypair structure holding the full keypair.
00740  *
00741  * \return          \c 0 on success, meaning that the keys are valid and match.
00742  * \return          #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if the keys are invalid or do not match.
00743  * \return          An \c MBEDTLS_ERR_ECP_XXX or an \c MBEDTLS_ERR_MPI_XXX
00744  *                  error code on calculation failure.
00745  */
00746 int mbedtls_ecp_check_pub_priv( const mbedtls_ecp_keypair *pub, const mbedtls_ecp_keypair *prv );
00747 
00748 #if defined(MBEDTLS_SELF_TEST)
00749 
00750 /**
00751  * \brief          The ECP checkup routine.
00752  *
00753  * \return         \c 0 on success.
00754  * \return         \c 1 on failure.
00755  */
00756 int mbedtls_ecp_self_test( int verbose );
00757 
00758 #endif /* MBEDTLS_SELF_TEST */
00759 
00760 #ifdef __cplusplus
00761 }
00762 #endif
00763 
00764 #endif /* ecp.h */