ecp.h 25 KB

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