ecp_internal.h

00001 /**
00002  * \file ecp_internal.h
00003  *
00004  * \brief Function declarations for alternative implementation of elliptic curve
00005  * point arithmetic.
00006  */
00007 /*
00008  *  Copyright (C) 2016, ARM Limited, All Rights Reserved
00009  *  SPDX-License-Identifier: Apache-2.0
00010  *
00011  *  Licensed under the Apache License, Version 2.0 (the "License"); you may
00012  *  not use this file except in compliance with the License.
00013  *  You may obtain a copy of the License at
00014  *
00015  *  http://www.apache.org/licenses/LICENSE-2.0
00016  *
00017  *  Unless required by applicable law or agreed to in writing, software
00018  *  distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
00019  *  WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00020  *  See the License for the specific language governing permissions and
00021  *  limitations under the License.
00022  *
00023  *  This file is part of mbed TLS (https://tls.mbed.org)
00024  */
00025 
00026 /*
00027  * References:
00028  *
00029  * [1] BERNSTEIN, Daniel J. Curve25519: new Diffie-Hellman speed records.
00030  *     <http://cr.yp.to/ecdh/curve25519-20060209.pdf>
00031  *
00032  * [2] CORON, Jean-S'ebastien. Resistance against differential power analysis
00033  *     for elliptic curve cryptosystems. In : Cryptographic Hardware and
00034  *     Embedded Systems. Springer Berlin Heidelberg, 1999. p. 292-302.
00035  *     <http://link.springer.com/chapter/10.1007/3-540-48059-5_25>
00036  *
00037  * [3] HEDABOU, Mustapha, PINEL, Pierre, et B'EN'ETEAU, Lucien. A comb method to
00038  *     render ECC resistant against Side Channel Attacks. IACR Cryptology
00039  *     ePrint Archive, 2004, vol. 2004, p. 342.
00040  *     <http://eprint.iacr.org/2004/342.pdf>
00041  *
00042  * [4] Certicom Research. SEC 2: Recommended Elliptic Curve Domain Parameters.
00043  *     <http://www.secg.org/sec2-v2.pdf>
00044  *
00045  * [5] HANKERSON, Darrel, MENEZES, Alfred J., VANSTONE, Scott. Guide to Elliptic
00046  *     Curve Cryptography.
00047  *
00048  * [6] Digital Signature Standard (DSS), FIPS 186-4.
00049  *     <http://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-4.pdf>
00050  *
00051  * [7] Elliptic Curve Cryptography (ECC) Cipher Suites for Transport Layer 
00052  *     Security (TLS), RFC 4492.
00053  *     <https://tools.ietf.org/search/rfc4492>
00054  *
00055  * [8] <http://www.hyperelliptic.org/EFD/g1p/auto-shortw-jacobian.html>
00056  *
00057  * [9] COHEN, Henri. A Course in Computational Algebraic Number Theory.
00058  *     Springer Science & Business Media, 1 Aug 2000
00059  */
00060 
00061 #ifndef MBEDTLS_ECP_INTERNAL_H
00062 #define MBEDTLS_ECP_INTERNAL_H
00063 
00064 #if defined(MBEDTLS_ECP_INTERNAL_ALT)
00065 
00066 /**
00067  * \brief           Indicate if the Elliptic Curve Point module extension can
00068  *                  handle the group.
00069  *
00070  * \param grp       The pointer to the elliptic curve group that will be the
00071  *                  basis of the cryptographic computations.
00072  *
00073  * \return          Non-zero if successful.
00074  */
00075 unsigned char mbedtls_internal_ecp_grp_capable( const mbedtls_ecp_group *grp );
00076 
00077 /**
00078  * \brief           Initialise the Elliptic Curve Point module extension.
00079  *
00080  *                  If mbedtls_internal_ecp_grp_capable returns true for a
00081  *                  group, this function has to be able to initialise the
00082  *                  module for it.
00083  *
00084  *                  This module can be a driver to a crypto hardware
00085  *                  accelerator, for which this could be an initialise function.
00086  *
00087  * \param grp       The pointer to the group the module needs to be
00088  *                  initialised for.
00089  *
00090  * \return          0 if successful.
00091  */
00092 int mbedtls_internal_ecp_init( const mbedtls_ecp_group *grp );
00093 
00094 /**
00095  * \brief           Frees and deallocates the Elliptic Curve Point module
00096  *                  extension.
00097  *
00098  * \param grp       The pointer to the group the module was initialised for.
00099  */
00100 void mbedtls_internal_ecp_free( const mbedtls_ecp_group *grp );
00101 
00102 #if defined(ECP_SHORTWEIERSTRASS)
00103 
00104 #if defined(MBEDTLS_ECP_RANDOMIZE_JAC_ALT)
00105 /**
00106  * \brief           Randomize jacobian coordinates:
00107  *                  (X, Y, Z) -> (l^2 X, l^3 Y, l Z) for random l.
00108  *
00109  * \param grp       Pointer to the group representing the curve.
00110  *
00111  * \param pt        The point on the curve to be randomised, given with Jacobian
00112  *                  coordinates.
00113  *
00114  * \param f_rng     A function pointer to the random number generator.
00115  *
00116  * \param p_rng     A pointer to the random number generator state.
00117  *
00118  * \return          0 if successful.
00119  */
00120 int mbedtls_internal_ecp_randomize_jac( const mbedtls_ecp_group *grp,
00121         mbedtls_ecp_point *pt, int (*f_rng)(void *, unsigned char *, size_t),
00122         void *p_rng );
00123 #endif
00124 
00125 #if defined(MBEDTLS_ECP_ADD_MIXED_ALT)
00126 /**
00127  * \brief           Addition: R = P + Q, mixed affine-Jacobian coordinates.
00128  *
00129  *                  The coordinates of Q must be normalized (= affine),
00130  *                  but those of P don't need to. R is not normalized.
00131  *
00132  *                  This function is used only as a subrutine of
00133  *                  ecp_mul_comb().
00134  *
00135  *                  Special cases: (1) P or Q is zero, (2) R is zero,
00136  *                      (3) P == Q.
00137  *                  None of these cases can happen as intermediate step in
00138  *                  ecp_mul_comb():
00139  *                      - at each step, P, Q and R are multiples of the base
00140  *                      point, the factor being less than its order, so none of
00141  *                      them is zero;
00142  *                      - Q is an odd multiple of the base point, P an even
00143  *                      multiple, due to the choice of precomputed points in the
00144  *                      modified comb method.
00145  *                  So branches for these cases do not leak secret information.
00146  *
00147  *                  We accept Q->Z being unset (saving memory in tables) as
00148  *                  meaning 1.
00149  *
00150  *                  Cost in field operations if done by [5] 3.22:
00151  *                      1A := 8M + 3S
00152  *
00153  * \param grp       Pointer to the group representing the curve.
00154  *
00155  * \param R         Pointer to a point structure to hold the result.
00156  *
00157  * \param P         Pointer to the first summand, given with Jacobian
00158  *                  coordinates
00159  *
00160  * \param Q         Pointer to the second summand, given with affine
00161  *                  coordinates.
00162  *
00163  * \return          0 if successful.
00164  */
00165 int mbedtls_internal_ecp_add_mixed( const mbedtls_ecp_group *grp,
00166         mbedtls_ecp_point *R, const mbedtls_ecp_point *P,
00167         const mbedtls_ecp_point *Q );
00168 #endif
00169 
00170 /**
00171  * \brief           Point doubling R = 2 P, Jacobian coordinates.
00172  *
00173  *                  Cost:   1D := 3M + 4S    (A ==  0)
00174  *                          4M + 4S          (A == -3)
00175  *                          3M + 6S + 1a     otherwise
00176  *                  when the implementation is based on the "dbl-1998-cmo-2"
00177  *                  doubling formulas in [8] and standard optimizations are
00178  *                  applied when curve parameter A is one of { 0, -3 }.
00179  *
00180  * \param grp       Pointer to the group representing the curve.
00181  *
00182  * \param R         Pointer to a point structure to hold the result.
00183  *
00184  * \param P         Pointer to the point that has to be doubled, given with
00185  *                  Jacobian coordinates.
00186  *
00187  * \return          0 if successful.
00188  */
00189 #if defined(MBEDTLS_ECP_DOUBLE_JAC_ALT)
00190 int mbedtls_internal_ecp_double_jac( const mbedtls_ecp_group *grp,
00191         mbedtls_ecp_point *R, const mbedtls_ecp_point *P );
00192 #endif
00193 
00194 /**
00195  * \brief           Normalize jacobian coordinates of an array of (pointers to)
00196  *                  points.
00197  *
00198  *                  Using Montgomery's trick to perform only one inversion mod P
00199  *                  the cost is:
00200  *                      1N(t) := 1I + (6t - 3)M + 1S
00201  *                  (See for example Algorithm 10.3.4. in [9])
00202  *
00203  *                  This function is used only as a subrutine of
00204  *                  ecp_mul_comb().
00205  *
00206  *                  Warning: fails (returning an error) if one of the points is
00207  *                  zero!
00208  *                  This should never happen, see choice of w in ecp_mul_comb().
00209  *
00210  * \param grp       Pointer to the group representing the curve.
00211  *
00212  * \param T         Array of pointers to the points to normalise.
00213  *
00214  * \param t_len     Number of elements in the array.
00215  *
00216  * \return          0 if successful,
00217  *                      an error if one of the points is zero.
00218  */
00219 #if defined(MBEDTLS_ECP_NORMALIZE_JAC_MANY_ALT)
00220 int mbedtls_internal_ecp_normalize_jac_many( const mbedtls_ecp_group *grp,
00221         mbedtls_ecp_point *T[], size_t t_len );
00222 #endif
00223 
00224 /**
00225  * \brief           Normalize jacobian coordinates so that Z == 0 || Z == 1.
00226  *
00227  *                  Cost in field operations if done by [5] 3.2.1:
00228  *                      1N := 1I + 3M + 1S
00229  *
00230  * \param grp       Pointer to the group representing the curve.
00231  *
00232  * \param pt        pointer to the point to be normalised. This is an
00233  *                  input/output parameter.
00234  *
00235  * \return          0 if successful.
00236  */
00237 #if defined(MBEDTLS_ECP_NORMALIZE_JAC_ALT)
00238 int mbedtls_internal_ecp_normalize_jac( const mbedtls_ecp_group *grp,
00239         mbedtls_ecp_point *pt );
00240 #endif
00241 
00242 #endif /* ECP_SHORTWEIERSTRASS */
00243 
00244 #if defined(ECP_MONTGOMERY)
00245 
00246 #if defined(MBEDTLS_ECP_DOUBLE_ADD_MXZ_ALT)
00247 int mbedtls_internal_ecp_double_add_mxz( const mbedtls_ecp_group *grp,
00248         mbedtls_ecp_point *R, mbedtls_ecp_point *S, const mbedtls_ecp_point *P,
00249         const mbedtls_ecp_point *Q, const mbedtls_mpi *d );
00250 #endif
00251 
00252 /**
00253  * \brief           Randomize projective x/z coordinates:
00254  *                      (X, Z) -> (l X, l Z) for random l
00255  *
00256  * \param grp       pointer to the group representing the curve
00257  *
00258  * \param P         the point on the curve to be randomised given with
00259  *                  projective coordinates. This is an input/output parameter.
00260  *
00261  * \param f_rng     a function pointer to the random number generator
00262  *
00263  * \param p_rng     a pointer to the random number generator state
00264  *
00265  * \return          0 if successful
00266  */
00267 #if defined(MBEDTLS_ECP_RANDOMIZE_MXZ_ALT)
00268 int mbedtls_internal_ecp_randomize_mxz( const mbedtls_ecp_group *grp,
00269         mbedtls_ecp_point *P, int (*f_rng)(void *, unsigned char *, size_t),
00270         void *p_rng );
00271 #endif
00272 
00273 /**
00274  * \brief           Normalize Montgomery x/z coordinates: X = X/Z, Z = 1.
00275  *
00276  * \param grp       pointer to the group representing the curve
00277  *
00278  * \param P         pointer to the point to be normalised. This is an
00279  *                  input/output parameter.
00280  *
00281  * \return          0 if successful
00282  */
00283 #if defined(MBEDTLS_ECP_NORMALIZE_MXZ_ALT)
00284 int mbedtls_internal_ecp_normalize_mxz( const mbedtls_ecp_group *grp,
00285         mbedtls_ecp_point *P );
00286 #endif
00287 
00288 #endif /* ECP_MONTGOMERY */
00289 
00290 #endif /* MBEDTLS_ECP_INTERNAL_ALT */
00291 
00292 #endif /* ecp_internal.h */
00293