git.sur5r.net Git - freertos/blob - FreeRTOS-Labs/Source/mbedtls/include/mbedtls/ecp_internal.h

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