4 * \brief Function declarations for alternative implementation of elliptic curve
8 * Copyright (C) 2016, ARM Limited, All Rights Reserved
9 * SPDX-License-Identifier: GPL-2.0
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.
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.
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.
25 * This file is part of mbed TLS (https://tls.mbed.org)
31 * [1] BERNSTEIN, Daniel J. Curve25519: new Diffie-Hellman speed records.
32 * <http://cr.yp.to/ecdh/curve25519-20060209.pdf>
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>
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>
44 * [4] Certicom Research. SEC 2: Recommended Elliptic Curve Domain Parameters.
45 * <http://www.secg.org/sec2-v2.pdf>
47 * [5] HANKERSON, Darrel, MENEZES, Alfred J., VANSTONE, Scott. Guide to Elliptic
50 * [6] Digital Signature Standard (DSS), FIPS 186-4.
51 * <http://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-4.pdf>
53 * [7] Elliptic Curve Cryptography (ECC) Cipher Suites for Transport Layer
54 * Security (TLS), RFC 4492.
55 * <https://tools.ietf.org/search/rfc4492>
57 * [8] <http://www.hyperelliptic.org/EFD/g1p/auto-shortw-jacobian.html>
59 * [9] COHEN, Henri. A Course in Computational Algebraic Number Theory.
60 * Springer Science & Business Media, 1 Aug 2000
63 #ifndef MBEDTLS_ECP_INTERNAL_H
64 #define MBEDTLS_ECP_INTERNAL_H
66 #if !defined(MBEDTLS_CONFIG_FILE)
69 #include MBEDTLS_CONFIG_FILE
72 #if defined(MBEDTLS_ECP_INTERNAL_ALT)
75 * \brief Indicate if the Elliptic Curve Point module extension can
78 * \param grp The pointer to the elliptic curve group that will be the
79 * basis of the cryptographic computations.
81 * \return Non-zero if successful.
83 unsigned char mbedtls_internal_ecp_grp_capable( const mbedtls_ecp_group
*grp
);
86 * \brief Initialise the Elliptic Curve Point module extension.
88 * If mbedtls_internal_ecp_grp_capable returns true for a
89 * group, this function has to be able to initialise the
92 * This module can be a driver to a crypto hardware
93 * accelerator, for which this could be an initialise function.
95 * \param grp The pointer to the group the module needs to be
98 * \return 0 if successful.
100 int mbedtls_internal_ecp_init( const mbedtls_ecp_group
*grp
);
103 * \brief Frees and deallocates the Elliptic Curve Point module
106 * \param grp The pointer to the group the module was initialised for.
108 void mbedtls_internal_ecp_free( const mbedtls_ecp_group
*grp
);
110 #if defined(ECP_SHORTWEIERSTRASS)
112 #if defined(MBEDTLS_ECP_RANDOMIZE_JAC_ALT)
114 * \brief Randomize jacobian coordinates:
115 * (X, Y, Z) -> (l^2 X, l^3 Y, l Z) for random l.
117 * \param grp Pointer to the group representing the curve.
119 * \param pt The point on the curve to be randomised, given with Jacobian
122 * \param f_rng A function pointer to the random number generator.
124 * \param p_rng A pointer to the random number generator state.
126 * \return 0 if successful.
128 int mbedtls_internal_ecp_randomize_jac( const mbedtls_ecp_group
*grp
,
129 mbedtls_ecp_point
*pt
, int (*f_rng
)(void *, unsigned char *, size_t),
133 #if defined(MBEDTLS_ECP_ADD_MIXED_ALT)
135 * \brief Addition: R = P + Q, mixed affine-Jacobian coordinates.
137 * The coordinates of Q must be normalized (= affine),
138 * but those of P don't need to. R is not normalized.
140 * This function is used only as a subrutine of
143 * Special cases: (1) P or Q is zero, (2) R is zero,
145 * None of these cases can happen as intermediate step in
147 * - at each step, P, Q and R are multiples of the base
148 * point, the factor being less than its order, so none of
150 * - Q is an odd multiple of the base point, P an even
151 * multiple, due to the choice of precomputed points in the
152 * modified comb method.
153 * So branches for these cases do not leak secret information.
155 * We accept Q->Z being unset (saving memory in tables) as
158 * Cost in field operations if done by [5] 3.22:
161 * \param grp Pointer to the group representing the curve.
163 * \param R Pointer to a point structure to hold the result.
165 * \param P Pointer to the first summand, given with Jacobian
168 * \param Q Pointer to the second summand, given with affine
171 * \return 0 if successful.
173 int mbedtls_internal_ecp_add_mixed( const mbedtls_ecp_group
*grp
,
174 mbedtls_ecp_point
*R
, const mbedtls_ecp_point
*P
,
175 const mbedtls_ecp_point
*Q
);
179 * \brief Point doubling R = 2 P, Jacobian coordinates.
181 * Cost: 1D := 3M + 4S (A == 0)
183 * 3M + 6S + 1a otherwise
184 * when the implementation is based on the "dbl-1998-cmo-2"
185 * doubling formulas in [8] and standard optimizations are
186 * applied when curve parameter A is one of { 0, -3 }.
188 * \param grp Pointer to the group representing the curve.
190 * \param R Pointer to a point structure to hold the result.
192 * \param P Pointer to the point that has to be doubled, given with
193 * Jacobian coordinates.
195 * \return 0 if successful.
197 #if defined(MBEDTLS_ECP_DOUBLE_JAC_ALT)
198 int mbedtls_internal_ecp_double_jac( const mbedtls_ecp_group
*grp
,
199 mbedtls_ecp_point
*R
, const mbedtls_ecp_point
*P
);
203 * \brief Normalize jacobian coordinates of an array of (pointers to)
206 * Using Montgomery's trick to perform only one inversion mod P
208 * 1N(t) := 1I + (6t - 3)M + 1S
209 * (See for example Algorithm 10.3.4. in [9])
211 * This function is used only as a subrutine of
214 * Warning: fails (returning an error) if one of the points is
216 * This should never happen, see choice of w in ecp_mul_comb().
218 * \param grp Pointer to the group representing the curve.
220 * \param T Array of pointers to the points to normalise.
222 * \param t_len Number of elements in the array.
224 * \return 0 if successful,
225 * an error if one of the points is zero.
227 #if defined(MBEDTLS_ECP_NORMALIZE_JAC_MANY_ALT)
228 int mbedtls_internal_ecp_normalize_jac_many( const mbedtls_ecp_group
*grp
,
229 mbedtls_ecp_point
*T
[], size_t t_len
);
233 * \brief Normalize jacobian coordinates so that Z == 0 || Z == 1.
235 * Cost in field operations if done by [5] 3.2.1:
238 * \param grp Pointer to the group representing the curve.
240 * \param pt pointer to the point to be normalised. This is an
241 * input/output parameter.
243 * \return 0 if successful.
245 #if defined(MBEDTLS_ECP_NORMALIZE_JAC_ALT)
246 int mbedtls_internal_ecp_normalize_jac( const mbedtls_ecp_group
*grp
,
247 mbedtls_ecp_point
*pt
);
250 #endif /* ECP_SHORTWEIERSTRASS */
252 #if defined(ECP_MONTGOMERY)
254 #if defined(MBEDTLS_ECP_DOUBLE_ADD_MXZ_ALT)
255 int mbedtls_internal_ecp_double_add_mxz( const mbedtls_ecp_group
*grp
,
256 mbedtls_ecp_point
*R
, mbedtls_ecp_point
*S
, const mbedtls_ecp_point
*P
,
257 const mbedtls_ecp_point
*Q
, const mbedtls_mpi
*d
);
261 * \brief Randomize projective x/z coordinates:
262 * (X, Z) -> (l X, l Z) for random l
264 * \param grp pointer to the group representing the curve
266 * \param P the point on the curve to be randomised given with
267 * projective coordinates. This is an input/output parameter.
269 * \param f_rng a function pointer to the random number generator
271 * \param p_rng a pointer to the random number generator state
273 * \return 0 if successful
275 #if defined(MBEDTLS_ECP_RANDOMIZE_MXZ_ALT)
276 int mbedtls_internal_ecp_randomize_mxz( const mbedtls_ecp_group
*grp
,
277 mbedtls_ecp_point
*P
, int (*f_rng
)(void *, unsigned char *, size_t),
282 * \brief Normalize Montgomery x/z coordinates: X = X/Z, Z = 1.
284 * \param grp pointer to the group representing the curve
286 * \param P pointer to the point to be normalised. This is an
287 * input/output parameter.
289 * \return 0 if successful
291 #if defined(MBEDTLS_ECP_NORMALIZE_MXZ_ALT)
292 int mbedtls_internal_ecp_normalize_mxz( const mbedtls_ecp_group
*grp
,
293 mbedtls_ecp_point
*P
);
296 #endif /* ECP_MONTGOMERY */
298 #endif /* MBEDTLS_ECP_INTERNAL_ALT */
300 #endif /* ecp_internal.h */