git.zerfleddert.de Git - proxmark3-svn/blob - common/mbedtls/ecp_internal.h

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