ecp_internal.h 10 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297
  1. /**
  2. * \file ecp_internal.h
  3. *
  4. * \brief Function declarations for alternative implementation of elliptic curve
  5. * point arithmetic.
  6. */
  7. /*
  8. * Copyright The Mbed TLS Contributors
  9. * SPDX-License-Identifier: Apache-2.0
  10. *
  11. * Licensed under the Apache License, Version 2.0 (the "License"); you may
  12. * not use this file except in compliance with the License.
  13. * You may obtain a copy of the License at
  14. *
  15. * http://www.apache.org/licenses/LICENSE-2.0
  16. *
  17. * Unless required by applicable law or agreed to in writing, software
  18. * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
  19. * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  20. * See the License for the specific language governing permissions and
  21. * limitations under the License.
  22. */
  23. /*
  24. * References:
  25. *
  26. * [1] BERNSTEIN, Daniel J. Curve25519: new Diffie-Hellman speed records.
  27. * <http://cr.yp.to/ecdh/curve25519-20060209.pdf>
  28. *
  29. * [2] CORON, Jean-S'ebastien. Resistance against differential power analysis
  30. * for elliptic curve cryptosystems. In : Cryptographic Hardware and
  31. * Embedded Systems. Springer Berlin Heidelberg, 1999. p. 292-302.
  32. * <http://link.springer.com/chapter/10.1007/3-540-48059-5_25>
  33. *
  34. * [3] HEDABOU, Mustapha, PINEL, Pierre, et B'EN'ETEAU, Lucien. A comb method to
  35. * render ECC resistant against Side Channel Attacks. IACR Cryptology
  36. * ePrint Archive, 2004, vol. 2004, p. 342.
  37. * <http://eprint.iacr.org/2004/342.pdf>
  38. *
  39. * [4] Certicom Research. SEC 2: Recommended Elliptic Curve Domain Parameters.
  40. * <http://www.secg.org/sec2-v2.pdf>
  41. *
  42. * [5] HANKERSON, Darrel, MENEZES, Alfred J., VANSTONE, Scott. Guide to Elliptic
  43. * Curve Cryptography.
  44. *
  45. * [6] Digital Signature Standard (DSS), FIPS 186-4.
  46. * <http://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-4.pdf>
  47. *
  48. * [7] Elliptic Curve Cryptography (ECC) Cipher Suites for Transport Layer
  49. * Security (TLS), RFC 4492.
  50. * <https://tools.ietf.org/search/rfc4492>
  51. *
  52. * [8] <http://www.hyperelliptic.org/EFD/g1p/auto-shortw-jacobian.html>
  53. *
  54. * [9] COHEN, Henri. A Course in Computational Algebraic Number Theory.
  55. * Springer Science & Business Media, 1 Aug 2000
  56. */
  57. #ifndef MBEDTLS_ECP_INTERNAL_H
  58. #define MBEDTLS_ECP_INTERNAL_H
  59. #if !defined(MBEDTLS_CONFIG_FILE)
  60. #include "mbedtls/config.h"
  61. #else
  62. #include MBEDTLS_CONFIG_FILE
  63. #endif
  64. #if defined(MBEDTLS_ECP_INTERNAL_ALT)
  65. /**
  66. * \brief Indicate if the Elliptic Curve Point module extension can
  67. * handle the group.
  68. *
  69. * \param grp The pointer to the elliptic curve group that will be the
  70. * basis of the cryptographic computations.
  71. *
  72. * \return Non-zero if successful.
  73. */
  74. unsigned char mbedtls_internal_ecp_grp_capable( const mbedtls_ecp_group *grp );
  75. /**
  76. * \brief Initialise the Elliptic Curve Point module extension.
  77. *
  78. * If mbedtls_internal_ecp_grp_capable returns true for a
  79. * group, this function has to be able to initialise the
  80. * module for it.
  81. *
  82. * This module can be a driver to a crypto hardware
  83. * accelerator, for which this could be an initialise function.
  84. *
  85. * \param grp The pointer to the group the module needs to be
  86. * initialised for.
  87. *
  88. * \return 0 if successful.
  89. */
  90. int mbedtls_internal_ecp_init( const mbedtls_ecp_group *grp );
  91. /**
  92. * \brief Frees and deallocates the Elliptic Curve Point module
  93. * extension.
  94. *
  95. * \param grp The pointer to the group the module was initialised for.
  96. */
  97. void mbedtls_internal_ecp_free( const mbedtls_ecp_group *grp );
  98. #if defined(MBEDTLS_ECP_SHORT_WEIERSTRASS_ENABLED)
  99. #if defined(MBEDTLS_ECP_RANDOMIZE_JAC_ALT)
  100. /**
  101. * \brief Randomize jacobian coordinates:
  102. * (X, Y, Z) -> (l^2 X, l^3 Y, l Z) for random l.
  103. *
  104. * \param grp Pointer to the group representing the curve.
  105. *
  106. * \param pt The point on the curve to be randomised, given with Jacobian
  107. * coordinates.
  108. *
  109. * \param f_rng A function pointer to the random number generator.
  110. *
  111. * \param p_rng A pointer to the random number generator state.
  112. *
  113. * \return 0 if successful.
  114. */
  115. int mbedtls_internal_ecp_randomize_jac( const mbedtls_ecp_group *grp,
  116. mbedtls_ecp_point *pt, int (*f_rng)(void *, unsigned char *, size_t),
  117. void *p_rng );
  118. #endif
  119. #if defined(MBEDTLS_ECP_ADD_MIXED_ALT)
  120. /**
  121. * \brief Addition: R = P + Q, mixed affine-Jacobian coordinates.
  122. *
  123. * The coordinates of Q must be normalized (= affine),
  124. * but those of P don't need to. R is not normalized.
  125. *
  126. * This function is used only as a subrutine of
  127. * ecp_mul_comb().
  128. *
  129. * Special cases: (1) P or Q is zero, (2) R is zero,
  130. * (3) P == Q.
  131. * None of these cases can happen as intermediate step in
  132. * ecp_mul_comb():
  133. * - at each step, P, Q and R are multiples of the base
  134. * point, the factor being less than its order, so none of
  135. * them is zero;
  136. * - Q is an odd multiple of the base point, P an even
  137. * multiple, due to the choice of precomputed points in the
  138. * modified comb method.
  139. * So branches for these cases do not leak secret information.
  140. *
  141. * We accept Q->Z being unset (saving memory in tables) as
  142. * meaning 1.
  143. *
  144. * Cost in field operations if done by [5] 3.22:
  145. * 1A := 8M + 3S
  146. *
  147. * \param grp Pointer to the group representing the curve.
  148. *
  149. * \param R Pointer to a point structure to hold the result.
  150. *
  151. * \param P Pointer to the first summand, given with Jacobian
  152. * coordinates
  153. *
  154. * \param Q Pointer to the second summand, given with affine
  155. * coordinates.
  156. *
  157. * \return 0 if successful.
  158. */
  159. int mbedtls_internal_ecp_add_mixed( const mbedtls_ecp_group *grp,
  160. mbedtls_ecp_point *R, const mbedtls_ecp_point *P,
  161. const mbedtls_ecp_point *Q );
  162. #endif
  163. /**
  164. * \brief Point doubling R = 2 P, Jacobian coordinates.
  165. *
  166. * Cost: 1D := 3M + 4S (A == 0)
  167. * 4M + 4S (A == -3)
  168. * 3M + 6S + 1a otherwise
  169. * when the implementation is based on the "dbl-1998-cmo-2"
  170. * doubling formulas in [8] and standard optimizations are
  171. * applied when curve parameter A is one of { 0, -3 }.
  172. *
  173. * \param grp Pointer to the group representing the curve.
  174. *
  175. * \param R Pointer to a point structure to hold the result.
  176. *
  177. * \param P Pointer to the point that has to be doubled, given with
  178. * Jacobian coordinates.
  179. *
  180. * \return 0 if successful.
  181. */
  182. #if defined(MBEDTLS_ECP_DOUBLE_JAC_ALT)
  183. int mbedtls_internal_ecp_double_jac( const mbedtls_ecp_group *grp,
  184. mbedtls_ecp_point *R, const mbedtls_ecp_point *P );
  185. #endif
  186. /**
  187. * \brief Normalize jacobian coordinates of an array of (pointers to)
  188. * points.
  189. *
  190. * Using Montgomery's trick to perform only one inversion mod P
  191. * the cost is:
  192. * 1N(t) := 1I + (6t - 3)M + 1S
  193. * (See for example Algorithm 10.3.4. in [9])
  194. *
  195. * This function is used only as a subrutine of
  196. * ecp_mul_comb().
  197. *
  198. * Warning: fails (returning an error) if one of the points is
  199. * zero!
  200. * This should never happen, see choice of w in ecp_mul_comb().
  201. *
  202. * \param grp Pointer to the group representing the curve.
  203. *
  204. * \param T Array of pointers to the points to normalise.
  205. *
  206. * \param t_len Number of elements in the array.
  207. *
  208. * \return 0 if successful,
  209. * an error if one of the points is zero.
  210. */
  211. #if defined(MBEDTLS_ECP_NORMALIZE_JAC_MANY_ALT)
  212. int mbedtls_internal_ecp_normalize_jac_many( const mbedtls_ecp_group *grp,
  213. mbedtls_ecp_point *T[], size_t t_len );
  214. #endif
  215. /**
  216. * \brief Normalize jacobian coordinates so that Z == 0 || Z == 1.
  217. *
  218. * Cost in field operations if done by [5] 3.2.1:
  219. * 1N := 1I + 3M + 1S
  220. *
  221. * \param grp Pointer to the group representing the curve.
  222. *
  223. * \param pt pointer to the point to be normalised. This is an
  224. * input/output parameter.
  225. *
  226. * \return 0 if successful.
  227. */
  228. #if defined(MBEDTLS_ECP_NORMALIZE_JAC_ALT)
  229. int mbedtls_internal_ecp_normalize_jac( const mbedtls_ecp_group *grp,
  230. mbedtls_ecp_point *pt );
  231. #endif
  232. #endif /* MBEDTLS_ECP_SHORT_WEIERSTRASS_ENABLED */
  233. #if defined(MBEDTLS_ECP_MONTGOMERY_ENABLED)
  234. #if defined(MBEDTLS_ECP_DOUBLE_ADD_MXZ_ALT)
  235. int mbedtls_internal_ecp_double_add_mxz( const mbedtls_ecp_group *grp,
  236. mbedtls_ecp_point *R, mbedtls_ecp_point *S, const mbedtls_ecp_point *P,
  237. const mbedtls_ecp_point *Q, const mbedtls_mpi *d );
  238. #endif
  239. /**
  240. * \brief Randomize projective x/z coordinates:
  241. * (X, Z) -> (l X, l Z) for random l
  242. *
  243. * \param grp pointer to the group representing the curve
  244. *
  245. * \param P the point on the curve to be randomised given with
  246. * projective coordinates. This is an input/output parameter.
  247. *
  248. * \param f_rng a function pointer to the random number generator
  249. *
  250. * \param p_rng a pointer to the random number generator state
  251. *
  252. * \return 0 if successful
  253. */
  254. #if defined(MBEDTLS_ECP_RANDOMIZE_MXZ_ALT)
  255. int mbedtls_internal_ecp_randomize_mxz( const mbedtls_ecp_group *grp,
  256. mbedtls_ecp_point *P, int (*f_rng)(void *, unsigned char *, size_t),
  257. void *p_rng );
  258. #endif
  259. /**
  260. * \brief Normalize Montgomery x/z coordinates: X = X/Z, Z = 1.
  261. *
  262. * \param grp pointer to the group representing the curve
  263. *
  264. * \param P pointer to the point to be normalised. This is an
  265. * input/output parameter.
  266. *
  267. * \return 0 if successful
  268. */
  269. #if defined(MBEDTLS_ECP_NORMALIZE_MXZ_ALT)
  270. int mbedtls_internal_ecp_normalize_mxz( const mbedtls_ecp_group *grp,
  271. mbedtls_ecp_point *P );
  272. #endif
  273. #endif /* MBEDTLS_ECP_MONTGOMERY_ENABLED */
  274. #endif /* MBEDTLS_ECP_INTERNAL_ALT */
  275. #endif /* ecp_internal.h */