ecp.h 25 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686
  1. /**
  2. * \file ecp.h
  3. *
  4. * \brief Elliptic curves over GF(p)
  5. */
  6. /*
  7. * Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  8. * SPDX-License-Identifier: Apache-2.0
  9. *
  10. * Licensed under the Apache License, Version 2.0 (the "License"); you may
  11. * not use this file except in compliance with the License.
  12. * You may obtain a copy of the License at
  13. *
  14. * http://www.apache.org/licenses/LICENSE-2.0
  15. *
  16. * Unless required by applicable law or agreed to in writing, software
  17. * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
  18. * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  19. * See the License for the specific language governing permissions and
  20. * limitations under the License.
  21. *
  22. * This file is part of mbed TLS (https://tls.mbed.org)
  23. */
  24. #ifndef MBEDTLS_ECP_H
  25. #define MBEDTLS_ECP_H
  26. #include "bignum.h"
  27. /*
  28. * ECP error codes
  29. */
  30. #define MBEDTLS_ERR_ECP_BAD_INPUT_DATA -0x4F80 /**< Bad input parameters to function. */
  31. #define MBEDTLS_ERR_ECP_BUFFER_TOO_SMALL -0x4F00 /**< The buffer is too small to write to. */
  32. #define MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE -0x4E80 /**< Requested curve not available. */
  33. #define MBEDTLS_ERR_ECP_VERIFY_FAILED -0x4E00 /**< The signature is not valid. */
  34. #define MBEDTLS_ERR_ECP_ALLOC_FAILED -0x4D80 /**< Memory allocation failed. */
  35. #define MBEDTLS_ERR_ECP_RANDOM_FAILED -0x4D00 /**< Generation of random value, such as (ephemeral) key, failed. */
  36. #define MBEDTLS_ERR_ECP_INVALID_KEY -0x4C80 /**< Invalid private or public key. */
  37. #define MBEDTLS_ERR_ECP_SIG_LEN_MISMATCH -0x4C00 /**< Signature is valid but shorter than the user-supplied length. */
  38. #define MBEDTLS_ERR_ECP_HW_ACCEL_FAILED -0x4B80 /**< ECP hardware accelerator failed. */
  39. #if !defined(MBEDTLS_ECP_ALT)
  40. /*
  41. * default mbed TLS elliptic curve arithmetic implementation
  42. *
  43. * (in case MBEDTLS_ECP_ALT is defined then the developer has to provide an
  44. * alternative implementation for the whole module and it will replace this
  45. * one.)
  46. */
  47. #ifdef __cplusplus
  48. extern "C" {
  49. #endif
  50. /**
  51. * Domain parameters (curve, subgroup and generator) identifiers.
  52. *
  53. * Only curves over prime fields are supported.
  54. *
  55. * \warning This library does not support validation of arbitrary domain
  56. * parameters. Therefore, only well-known domain parameters from trusted
  57. * sources should be used. See mbedtls_ecp_group_load().
  58. */
  59. typedef enum
  60. {
  61. MBEDTLS_ECP_DP_NONE = 0,
  62. MBEDTLS_ECP_DP_SECP192R1, /*!< 192-bits NIST curve */
  63. MBEDTLS_ECP_DP_SECP224R1, /*!< 224-bits NIST curve */
  64. MBEDTLS_ECP_DP_SECP256R1, /*!< 256-bits NIST curve */
  65. MBEDTLS_ECP_DP_SECP384R1, /*!< 384-bits NIST curve */
  66. MBEDTLS_ECP_DP_SECP521R1, /*!< 521-bits NIST curve */
  67. MBEDTLS_ECP_DP_BP256R1, /*!< 256-bits Brainpool curve */
  68. MBEDTLS_ECP_DP_BP384R1, /*!< 384-bits Brainpool curve */
  69. MBEDTLS_ECP_DP_BP512R1, /*!< 512-bits Brainpool curve */
  70. MBEDTLS_ECP_DP_CURVE25519, /*!< Curve25519 */
  71. MBEDTLS_ECP_DP_SECP192K1, /*!< 192-bits "Koblitz" curve */
  72. MBEDTLS_ECP_DP_SECP224K1, /*!< 224-bits "Koblitz" curve */
  73. MBEDTLS_ECP_DP_SECP256K1, /*!< 256-bits "Koblitz" curve */
  74. } mbedtls_ecp_group_id;
  75. /**
  76. * Number of supported curves (plus one for NONE).
  77. *
  78. * (Montgomery curves excluded for now.)
  79. */
  80. #define MBEDTLS_ECP_DP_MAX 12
  81. /**
  82. * Curve information for use by other modules
  83. */
  84. typedef struct
  85. {
  86. mbedtls_ecp_group_id grp_id; /*!< Internal identifier */
  87. uint16_t tls_id; /*!< TLS NamedCurve identifier */
  88. uint16_t bit_size; /*!< Curve size in bits */
  89. const char *name; /*!< Human-friendly name */
  90. } mbedtls_ecp_curve_info;
  91. /**
  92. * \brief ECP point structure (jacobian coordinates)
  93. *
  94. * \note All functions expect and return points satisfying
  95. * the following condition: Z == 0 or Z == 1. (Other
  96. * values of Z are used by internal functions only.)
  97. * The point is zero, or "at infinity", if Z == 0.
  98. * Otherwise, X and Y are its standard (affine) coordinates.
  99. */
  100. typedef struct
  101. {
  102. mbedtls_mpi X; /*!< the point's X coordinate */
  103. mbedtls_mpi Y; /*!< the point's Y coordinate */
  104. mbedtls_mpi Z; /*!< the point's Z coordinate */
  105. }
  106. mbedtls_ecp_point;
  107. /**
  108. * \brief ECP group structure
  109. *
  110. * We consider two types of curves equations:
  111. * 1. Short Weierstrass y^2 = x^3 + A x + B mod P (SEC1 + RFC 4492)
  112. * 2. Montgomery, y^2 = x^3 + A x^2 + x mod P (Curve25519 + draft)
  113. * In both cases, a generator G for a prime-order subgroup is fixed. In the
  114. * short weierstrass, this subgroup is actually the whole curve, and its
  115. * cardinal is denoted by N.
  116. *
  117. * In the case of Short Weierstrass curves, our code requires that N is an odd
  118. * prime. (Use odd in mbedtls_ecp_mul() and prime in mbedtls_ecdsa_sign() for blinding.)
  119. *
  120. * In the case of Montgomery curves, we don't store A but (A + 2) / 4 which is
  121. * the quantity actually used in the formulas. Also, nbits is not the size of N
  122. * but the required size for private keys.
  123. *
  124. * If modp is NULL, reduction modulo P is done using a generic algorithm.
  125. * Otherwise, it must point to a function that takes an mbedtls_mpi in the range
  126. * 0..2^(2*pbits)-1 and transforms it in-place in an integer of little more
  127. * than pbits, so that the integer may be efficiently brought in the 0..P-1
  128. * range by a few additions or substractions. It must return 0 on success and
  129. * non-zero on failure.
  130. */
  131. typedef struct
  132. {
  133. mbedtls_ecp_group_id id; /*!< internal group identifier */
  134. mbedtls_mpi P; /*!< prime modulus of the base field */
  135. mbedtls_mpi A; /*!< 1. A in the equation, or 2. (A + 2) / 4 */
  136. mbedtls_mpi B; /*!< 1. B in the equation, or 2. unused */
  137. mbedtls_ecp_point G; /*!< generator of the (sub)group used */
  138. mbedtls_mpi N; /*!< 1. the order of G, or 2. unused */
  139. size_t pbits; /*!< number of bits in P */
  140. size_t nbits; /*!< number of bits in 1. P, or 2. private keys */
  141. unsigned int h; /*!< internal: 1 if the constants are static */
  142. int (*modp)(mbedtls_mpi *); /*!< function for fast reduction mod P */
  143. int (*t_pre)(mbedtls_ecp_point *, void *); /*!< unused */
  144. int (*t_post)(mbedtls_ecp_point *, void *); /*!< unused */
  145. void *t_data; /*!< unused */
  146. mbedtls_ecp_point *T; /*!< pre-computed points for ecp_mul_comb() */
  147. size_t T_size; /*!< number for pre-computed points */
  148. }
  149. mbedtls_ecp_group;
  150. /**
  151. * \brief ECP key pair structure
  152. *
  153. * A generic key pair that could be used for ECDSA, fixed ECDH, etc.
  154. *
  155. * \note Members purposefully in the same order as struc mbedtls_ecdsa_context.
  156. */
  157. typedef struct
  158. {
  159. mbedtls_ecp_group grp; /*!< Elliptic curve and base point */
  160. mbedtls_mpi d; /*!< our secret value */
  161. mbedtls_ecp_point Q; /*!< our public value */
  162. }
  163. mbedtls_ecp_keypair;
  164. /**
  165. * \name SECTION: Module settings
  166. *
  167. * The configuration options you can set for this module are in this section.
  168. * Either change them in config.h or define them on the compiler command line.
  169. * \{
  170. */
  171. #if !defined(MBEDTLS_ECP_MAX_BITS)
  172. /**
  173. * Maximum size of the groups (that is, of N and P)
  174. */
  175. #define MBEDTLS_ECP_MAX_BITS 521 /**< Maximum bit size of groups */
  176. #endif
  177. #define MBEDTLS_ECP_MAX_BYTES ( ( MBEDTLS_ECP_MAX_BITS + 7 ) / 8 )
  178. #define MBEDTLS_ECP_MAX_PT_LEN ( 2 * MBEDTLS_ECP_MAX_BYTES + 1 )
  179. #if !defined(MBEDTLS_ECP_WINDOW_SIZE)
  180. /*
  181. * Maximum "window" size used for point multiplication.
  182. * Default: 6.
  183. * Minimum value: 2. Maximum value: 7.
  184. *
  185. * Result is an array of at most ( 1 << ( MBEDTLS_ECP_WINDOW_SIZE - 1 ) )
  186. * points used for point multiplication. This value is directly tied to EC
  187. * peak memory usage, so decreasing it by one should roughly cut memory usage
  188. * by two (if large curves are in use).
  189. *
  190. * Reduction in size may reduce speed, but larger curves are impacted first.
  191. * Sample performances (in ECDHE handshakes/s, with FIXED_POINT_OPTIM = 1):
  192. * w-size: 6 5 4 3 2
  193. * 521 145 141 135 120 97
  194. * 384 214 209 198 177 146
  195. * 256 320 320 303 262 226
  196. * 224 475 475 453 398 342
  197. * 192 640 640 633 587 476
  198. */
  199. #define MBEDTLS_ECP_WINDOW_SIZE 6 /**< Maximum window size used */
  200. #endif /* MBEDTLS_ECP_WINDOW_SIZE */
  201. #if !defined(MBEDTLS_ECP_FIXED_POINT_OPTIM)
  202. /*
  203. * Trade memory for speed on fixed-point multiplication.
  204. *
  205. * This speeds up repeated multiplication of the generator (that is, the
  206. * multiplication in ECDSA signatures, and half of the multiplications in
  207. * ECDSA verification and ECDHE) by a factor roughly 3 to 4.
  208. *
  209. * The cost is increasing EC peak memory usage by a factor roughly 2.
  210. *
  211. * Change this value to 0 to reduce peak memory usage.
  212. */
  213. #define MBEDTLS_ECP_FIXED_POINT_OPTIM 1 /**< Enable fixed-point speed-up */
  214. #endif /* MBEDTLS_ECP_FIXED_POINT_OPTIM */
  215. /* \} name SECTION: Module settings */
  216. /*
  217. * Point formats, from RFC 4492's enum ECPointFormat
  218. */
  219. #define MBEDTLS_ECP_PF_UNCOMPRESSED 0 /**< Uncompressed point format */
  220. #define MBEDTLS_ECP_PF_COMPRESSED 1 /**< Compressed point format */
  221. /*
  222. * Some other constants from RFC 4492
  223. */
  224. #define MBEDTLS_ECP_TLS_NAMED_CURVE 3 /**< ECCurveType's named_curve */
  225. /**
  226. * \brief Get the list of supported curves in order of preferrence
  227. * (full information)
  228. *
  229. * \return A statically allocated array, the last entry is 0.
  230. */
  231. const mbedtls_ecp_curve_info *mbedtls_ecp_curve_list( void );
  232. /**
  233. * \brief Get the list of supported curves in order of preferrence
  234. * (grp_id only)
  235. *
  236. * \return A statically allocated array,
  237. * terminated with MBEDTLS_ECP_DP_NONE.
  238. */
  239. const mbedtls_ecp_group_id *mbedtls_ecp_grp_id_list( void );
  240. /**
  241. * \brief Get curve information from an internal group identifier
  242. *
  243. * \param grp_id A MBEDTLS_ECP_DP_XXX value
  244. *
  245. * \return The associated curve information or NULL
  246. */
  247. const mbedtls_ecp_curve_info *mbedtls_ecp_curve_info_from_grp_id( mbedtls_ecp_group_id grp_id );
  248. /**
  249. * \brief Get curve information from a TLS NamedCurve value
  250. *
  251. * \param tls_id A MBEDTLS_ECP_DP_XXX value
  252. *
  253. * \return The associated curve information or NULL
  254. */
  255. const mbedtls_ecp_curve_info *mbedtls_ecp_curve_info_from_tls_id( uint16_t tls_id );
  256. /**
  257. * \brief Get curve information from a human-readable name
  258. *
  259. * \param name The name
  260. *
  261. * \return The associated curve information or NULL
  262. */
  263. const mbedtls_ecp_curve_info *mbedtls_ecp_curve_info_from_name( const char *name );
  264. /**
  265. * \brief Initialize a point (as zero)
  266. */
  267. void mbedtls_ecp_point_init( mbedtls_ecp_point *pt );
  268. /**
  269. * \brief Initialize a group (to something meaningless)
  270. */
  271. void mbedtls_ecp_group_init( mbedtls_ecp_group *grp );
  272. /**
  273. * \brief Initialize a key pair (as an invalid one)
  274. */
  275. void mbedtls_ecp_keypair_init( mbedtls_ecp_keypair *key );
  276. /**
  277. * \brief Free the components of a point
  278. */
  279. void mbedtls_ecp_point_free( mbedtls_ecp_point *pt );
  280. /**
  281. * \brief Free the components of an ECP group
  282. */
  283. void mbedtls_ecp_group_free( mbedtls_ecp_group *grp );
  284. /**
  285. * \brief Free the components of a key pair
  286. */
  287. void mbedtls_ecp_keypair_free( mbedtls_ecp_keypair *key );
  288. /**
  289. * \brief Copy the contents of point Q into P
  290. *
  291. * \param P Destination point
  292. * \param Q Source point
  293. *
  294. * \return 0 if successful,
  295. * MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed
  296. */
  297. int mbedtls_ecp_copy( mbedtls_ecp_point *P, const mbedtls_ecp_point *Q );
  298. /**
  299. * \brief Copy the contents of a group object
  300. *
  301. * \param dst Destination group
  302. * \param src Source group
  303. *
  304. * \return 0 if successful,
  305. * MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed
  306. */
  307. int mbedtls_ecp_group_copy( mbedtls_ecp_group *dst, const mbedtls_ecp_group *src );
  308. /**
  309. * \brief Set a point to zero
  310. *
  311. * \param pt Destination point
  312. *
  313. * \return 0 if successful,
  314. * MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed
  315. */
  316. int mbedtls_ecp_set_zero( mbedtls_ecp_point *pt );
  317. /**
  318. * \brief Tell if a point is zero
  319. *
  320. * \param pt Point to test
  321. *
  322. * \return 1 if point is zero, 0 otherwise
  323. */
  324. int mbedtls_ecp_is_zero( mbedtls_ecp_point *pt );
  325. /**
  326. * \brief Compare two points
  327. *
  328. * \note This assumes the points are normalized. Otherwise,
  329. * they may compare as "not equal" even if they are.
  330. *
  331. * \param P First point to compare
  332. * \param Q Second point to compare
  333. *
  334. * \return 0 if the points are equal,
  335. * MBEDTLS_ERR_ECP_BAD_INPUT_DATA otherwise
  336. */
  337. int mbedtls_ecp_point_cmp( const mbedtls_ecp_point *P,
  338. const mbedtls_ecp_point *Q );
  339. /**
  340. * \brief Import a non-zero point from two ASCII strings
  341. *
  342. * \param P Destination point
  343. * \param radix Input numeric base
  344. * \param x First affine coordinate as a null-terminated string
  345. * \param y Second affine coordinate as a null-terminated string
  346. *
  347. * \return 0 if successful, or a MBEDTLS_ERR_MPI_XXX error code
  348. */
  349. int mbedtls_ecp_point_read_string( mbedtls_ecp_point *P, int radix,
  350. const char *x, const char *y );
  351. /**
  352. * \brief Export a point into unsigned binary data
  353. *
  354. * \param grp Group to which the point should belong
  355. * \param P Point to export
  356. * \param format Point format, should be a MBEDTLS_ECP_PF_XXX macro
  357. * \param olen Length of the actual output
  358. * \param buf Output buffer
  359. * \param buflen Length of the output buffer
  360. *
  361. * \return 0 if successful,
  362. * or MBEDTLS_ERR_ECP_BAD_INPUT_DATA
  363. * or MBEDTLS_ERR_ECP_BUFFER_TOO_SMALL
  364. */
  365. int mbedtls_ecp_point_write_binary( const mbedtls_ecp_group *grp, const mbedtls_ecp_point *P,
  366. int format, size_t *olen,
  367. unsigned char *buf, size_t buflen );
  368. /**
  369. * \brief Import a point from unsigned binary data
  370. *
  371. * \param grp Group to which the point should belong
  372. * \param P Point to import
  373. * \param buf Input buffer
  374. * \param ilen Actual length of input
  375. *
  376. * \return 0 if successful,
  377. * MBEDTLS_ERR_ECP_BAD_INPUT_DATA if input is invalid,
  378. * MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed,
  379. * MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE if the point format
  380. * is not implemented.
  381. *
  382. * \note This function does NOT check that the point actually
  383. * belongs to the given group, see mbedtls_ecp_check_pubkey() for
  384. * that.
  385. */
  386. int mbedtls_ecp_point_read_binary( const mbedtls_ecp_group *grp, mbedtls_ecp_point *P,
  387. const unsigned char *buf, size_t ilen );
  388. /**
  389. * \brief Import a point from a TLS ECPoint record
  390. *
  391. * \param grp ECP group used
  392. * \param pt Destination point
  393. * \param buf $(Start of input buffer)
  394. * \param len Buffer length
  395. *
  396. * \note buf is updated to point right after the ECPoint on exit
  397. *
  398. * \return 0 if successful,
  399. * MBEDTLS_ERR_MPI_XXX if initialization failed
  400. * MBEDTLS_ERR_ECP_BAD_INPUT_DATA if input is invalid
  401. */
  402. int mbedtls_ecp_tls_read_point( const mbedtls_ecp_group *grp, mbedtls_ecp_point *pt,
  403. const unsigned char **buf, size_t len );
  404. /**
  405. * \brief Export a point as a TLS ECPoint record
  406. *
  407. * \param grp ECP group used
  408. * \param pt Point to export
  409. * \param format Export format
  410. * \param olen length of data written
  411. * \param buf Buffer to write to
  412. * \param blen Buffer length
  413. *
  414. * \return 0 if successful,
  415. * or MBEDTLS_ERR_ECP_BAD_INPUT_DATA
  416. * or MBEDTLS_ERR_ECP_BUFFER_TOO_SMALL
  417. */
  418. int mbedtls_ecp_tls_write_point( const mbedtls_ecp_group *grp, const mbedtls_ecp_point *pt,
  419. int format, size_t *olen,
  420. unsigned char *buf, size_t blen );
  421. /**
  422. * \brief Set a group using well-known domain parameters
  423. *
  424. * \param grp Destination group
  425. * \param id Index in the list of well-known domain parameters
  426. *
  427. * \return 0 if successful,
  428. * MBEDTLS_ERR_MPI_XXX if initialization failed
  429. * MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE for unkownn groups
  430. *
  431. * \note Index should be a value of RFC 4492's enum NamedCurve,
  432. * usually in the form of a MBEDTLS_ECP_DP_XXX macro.
  433. */
  434. int mbedtls_ecp_group_load( mbedtls_ecp_group *grp, mbedtls_ecp_group_id id );
  435. /**
  436. * \brief Set a group from a TLS ECParameters record
  437. *
  438. * \param grp Destination group
  439. * \param buf &(Start of input buffer)
  440. * \param len Buffer length
  441. *
  442. * \note buf is updated to point right after ECParameters on exit
  443. *
  444. * \return 0 if successful,
  445. * MBEDTLS_ERR_MPI_XXX if initialization failed
  446. * MBEDTLS_ERR_ECP_BAD_INPUT_DATA if input is invalid
  447. */
  448. int mbedtls_ecp_tls_read_group( mbedtls_ecp_group *grp, const unsigned char **buf, size_t len );
  449. /**
  450. * \brief Write the TLS ECParameters record for a group
  451. *
  452. * \param grp ECP group used
  453. * \param olen Number of bytes actually written
  454. * \param buf Buffer to write to
  455. * \param blen Buffer length
  456. *
  457. * \return 0 if successful,
  458. * or MBEDTLS_ERR_ECP_BUFFER_TOO_SMALL
  459. */
  460. int mbedtls_ecp_tls_write_group( const mbedtls_ecp_group *grp, size_t *olen,
  461. unsigned char *buf, size_t blen );
  462. /**
  463. * \brief Multiplication by an integer: R = m * P
  464. * (Not thread-safe to use same group in multiple threads)
  465. *
  466. * \note In order to prevent timing attacks, this function
  467. * executes the exact same sequence of (base field)
  468. * operations for any valid m. It avoids any if-branch or
  469. * array index depending on the value of m.
  470. *
  471. * \note If f_rng is not NULL, it is used to randomize intermediate
  472. * results in order to prevent potential timing attacks
  473. * targeting these results. It is recommended to always
  474. * provide a non-NULL f_rng (the overhead is negligible).
  475. *
  476. * \param grp ECP group
  477. * \param R Destination point
  478. * \param m Integer by which to multiply
  479. * \param P Point to multiply
  480. * \param f_rng RNG function (see notes)
  481. * \param p_rng RNG parameter
  482. *
  483. * \return 0 if successful,
  484. * MBEDTLS_ERR_ECP_INVALID_KEY if m is not a valid privkey
  485. * or P is not a valid pubkey,
  486. * MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed
  487. */
  488. int mbedtls_ecp_mul( mbedtls_ecp_group *grp, mbedtls_ecp_point *R,
  489. const mbedtls_mpi *m, const mbedtls_ecp_point *P,
  490. int (*f_rng)(void *, unsigned char *, size_t), void *p_rng );
  491. /**
  492. * \brief Multiplication and addition of two points by integers:
  493. * R = m * P + n * Q
  494. * (Not thread-safe to use same group in multiple threads)
  495. *
  496. * \note In contrast to mbedtls_ecp_mul(), this function does not guarantee
  497. * a constant execution flow and timing.
  498. *
  499. * \param grp ECP group
  500. * \param R Destination point
  501. * \param m Integer by which to multiply P
  502. * \param P Point to multiply by m
  503. * \param n Integer by which to multiply Q
  504. * \param Q Point to be multiplied by n
  505. *
  506. * \return 0 if successful,
  507. * MBEDTLS_ERR_ECP_INVALID_KEY if m or n is not a valid privkey
  508. * or P or Q is not a valid pubkey,
  509. * MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed
  510. */
  511. int mbedtls_ecp_muladd( mbedtls_ecp_group *grp, mbedtls_ecp_point *R,
  512. const mbedtls_mpi *m, const mbedtls_ecp_point *P,
  513. const mbedtls_mpi *n, const mbedtls_ecp_point *Q );
  514. /**
  515. * \brief Check that a point is a valid public key on this curve
  516. *
  517. * \param grp Curve/group the point should belong to
  518. * \param pt Point to check
  519. *
  520. * \return 0 if point is a valid public key,
  521. * MBEDTLS_ERR_ECP_INVALID_KEY otherwise.
  522. *
  523. * \note This function only checks the point is non-zero, has valid
  524. * coordinates and lies on the curve, but not that it is
  525. * indeed a multiple of G. This is additional check is more
  526. * expensive, isn't required by standards, and shouldn't be
  527. * necessary if the group used has a small cofactor. In
  528. * particular, it is useless for the NIST groups which all
  529. * have a cofactor of 1.
  530. *
  531. * \note Uses bare components rather than an mbedtls_ecp_keypair structure
  532. * in order to ease use with other structures such as
  533. * mbedtls_ecdh_context of mbedtls_ecdsa_context.
  534. */
  535. int mbedtls_ecp_check_pubkey( const mbedtls_ecp_group *grp, const mbedtls_ecp_point *pt );
  536. /**
  537. * \brief Check that an mbedtls_mpi is a valid private key for this curve
  538. *
  539. * \param grp Group used
  540. * \param d Integer to check
  541. *
  542. * \return 0 if point is a valid private key,
  543. * MBEDTLS_ERR_ECP_INVALID_KEY otherwise.
  544. *
  545. * \note Uses bare components rather than an mbedtls_ecp_keypair structure
  546. * in order to ease use with other structures such as
  547. * mbedtls_ecdh_context of mbedtls_ecdsa_context.
  548. */
  549. int mbedtls_ecp_check_privkey( const mbedtls_ecp_group *grp, const mbedtls_mpi *d );
  550. /**
  551. * \brief Generate a keypair with configurable base point
  552. *
  553. * \param grp ECP group
  554. * \param G Chosen base point
  555. * \param d Destination MPI (secret part)
  556. * \param Q Destination point (public part)
  557. * \param f_rng RNG function
  558. * \param p_rng RNG parameter
  559. *
  560. * \return 0 if successful,
  561. * or a MBEDTLS_ERR_ECP_XXX or MBEDTLS_MPI_XXX error code
  562. *
  563. * \note Uses bare components rather than an mbedtls_ecp_keypair structure
  564. * in order to ease use with other structures such as
  565. * mbedtls_ecdh_context of mbedtls_ecdsa_context.
  566. */
  567. int mbedtls_ecp_gen_keypair_base( mbedtls_ecp_group *grp,
  568. const mbedtls_ecp_point *G,
  569. mbedtls_mpi *d, mbedtls_ecp_point *Q,
  570. int (*f_rng)(void *, unsigned char *, size_t),
  571. void *p_rng );
  572. /**
  573. * \brief Generate a keypair
  574. *
  575. * \param grp ECP group
  576. * \param d Destination MPI (secret part)
  577. * \param Q Destination point (public part)
  578. * \param f_rng RNG function
  579. * \param p_rng RNG parameter
  580. *
  581. * \return 0 if successful,
  582. * or a MBEDTLS_ERR_ECP_XXX or MBEDTLS_MPI_XXX error code
  583. *
  584. * \note Uses bare components rather than an mbedtls_ecp_keypair structure
  585. * in order to ease use with other structures such as
  586. * mbedtls_ecdh_context of mbedtls_ecdsa_context.
  587. */
  588. int mbedtls_ecp_gen_keypair( mbedtls_ecp_group *grp, mbedtls_mpi *d, mbedtls_ecp_point *Q,
  589. int (*f_rng)(void *, unsigned char *, size_t),
  590. void *p_rng );
  591. /**
  592. * \brief Generate a keypair
  593. *
  594. * \param grp_id ECP group identifier
  595. * \param key Destination keypair
  596. * \param f_rng RNG function
  597. * \param p_rng RNG parameter
  598. *
  599. * \return 0 if successful,
  600. * or a MBEDTLS_ERR_ECP_XXX or MBEDTLS_MPI_XXX error code
  601. */
  602. int mbedtls_ecp_gen_key( mbedtls_ecp_group_id grp_id, mbedtls_ecp_keypair *key,
  603. int (*f_rng)(void *, unsigned char *, size_t), void *p_rng );
  604. /**
  605. * \brief Check a public-private key pair
  606. *
  607. * \param pub Keypair structure holding a public key
  608. * \param prv Keypair structure holding a private (plus public) key
  609. *
  610. * \return 0 if successful (keys are valid and match), or
  611. * MBEDTLS_ERR_ECP_BAD_INPUT_DATA, or
  612. * a MBEDTLS_ERR_ECP_XXX or MBEDTLS_ERR_MPI_XXX code.
  613. */
  614. int mbedtls_ecp_check_pub_priv( const mbedtls_ecp_keypair *pub, const mbedtls_ecp_keypair *prv );
  615. #if defined(MBEDTLS_SELF_TEST)
  616. /**
  617. * \brief Checkup routine
  618. *
  619. * \return 0 if successful, or 1 if a test failed
  620. */
  621. int mbedtls_ecp_self_test( int verbose );
  622. #endif /* MBEDTLS_SELF_TEST */
  623. #ifdef __cplusplus
  624. }
  625. #endif
  626. #else /* MBEDTLS_ECP_ALT */
  627. #include "ecp_alt.h"
  628. #endif /* MBEDTLS_ECP_ALT */
  629. #endif /* ecp.h */