[proxmark3-svn] / common / mbedtls / ecp_internal.h

/**
 * \file ecp_internal.h
 *
 * \brief Function declarations for alternative implementation of elliptic curve
 * point arithmetic.
 */
/*
 *  Copyright (C) 2016, ARM Limited, All Rights Reserved
 *  SPDX-License-Identifier: GPL-2.0
 *
 *  This program is free software; you can redistribute it and/or modify
 *  it under the terms of the GNU General Public License as published by
 *  the Free Software Foundation; either version 2 of the License, or
 *  (at your option) any later version.
 *
 *  This program is distributed in the hope that it will be useful,
 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 *  GNU General Public License for more details.
 *
 *  You should have received a copy of the GNU General Public License along
 *  with this program; if not, write to the Free Software Foundation, Inc.,
 *  51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
 *
 *  This file is part of mbed TLS (https://tls.mbed.org)
 */

/*
 * References:
 *
 * [1] BERNSTEIN, Daniel J. Curve25519: new Diffie-Hellman speed records.
 *     <http://cr.yp.to/ecdh/curve25519-20060209.pdf>
 *
 * [2] CORON, Jean-S'ebastien. Resistance against differential power analysis
 *     for elliptic curve cryptosystems. In : Cryptographic Hardware and
 *     Embedded Systems. Springer Berlin Heidelberg, 1999. p. 292-302.
 *     <http://link.springer.com/chapter/10.1007/3-540-48059-5_25>
 *
 * [3] HEDABOU, Mustapha, PINEL, Pierre, et B'EN'ETEAU, Lucien. A comb method to
 *     render ECC resistant against Side Channel Attacks. IACR Cryptology
 *     ePrint Archive, 2004, vol. 2004, p. 342.
 *     <http://eprint.iacr.org/2004/342.pdf>
 *
 * [4] Certicom Research. SEC 2: Recommended Elliptic Curve Domain Parameters.
 *     <http://www.secg.org/sec2-v2.pdf>
 *
 * [5] HANKERSON, Darrel, MENEZES, Alfred J., VANSTONE, Scott. Guide to Elliptic
 *     Curve Cryptography.
 *
 * [6] Digital Signature Standard (DSS), FIPS 186-4.
 *     <http://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-4.pdf>
 *
 * [7] Elliptic Curve Cryptography (ECC) Cipher Suites for Transport Layer
 *     Security (TLS), RFC 4492.
 *     <https://tools.ietf.org/search/rfc4492>
 *
 * [8] <http://www.hyperelliptic.org/EFD/g1p/auto-shortw-jacobian.html>
 *
 * [9] COHEN, Henri. A Course in Computational Algebraic Number Theory.
 *     Springer Science & Business Media, 1 Aug 2000
 */

#ifndef MBEDTLS_ECP_INTERNAL_H
#define MBEDTLS_ECP_INTERNAL_H

#if defined(MBEDTLS_ECP_INTERNAL_ALT)

/**
 * \brief           Indicate if the Elliptic Curve Point module extension can
 *                  handle the group.
 *
 * \param grp       The pointer to the elliptic curve group that will be the
 *                  basis of the cryptographic computations.
 *
 * \return          Non-zero if successful.
 */
unsigned char mbedtls_internal_ecp_grp_capable( const mbedtls_ecp_group *grp );

/**
 * \brief           Initialise the Elliptic Curve Point module extension.
 *
 *                  If mbedtls_internal_ecp_grp_capable returns true for a
 *                  group, this function has to be able to initialise the
 *                  module for it.
 *
 *                  This module can be a driver to a crypto hardware
 *                  accelerator, for which this could be an initialise function.
 *
 * \param grp       The pointer to the group the module needs to be
 *                  initialised for.
 *
 * \return          0 if successful.
 */
int mbedtls_internal_ecp_init( const mbedtls_ecp_group *grp );

/**
 * \brief           Frees and deallocates the Elliptic Curve Point module
 *                  extension.
 *
 * \param grp       The pointer to the group the module was initialised for.
 */
void mbedtls_internal_ecp_free( const mbedtls_ecp_group *grp );

#if defined(ECP_SHORTWEIERSTRASS)

#if defined(MBEDTLS_ECP_RANDOMIZE_JAC_ALT)
/**
 * \brief           Randomize jacobian coordinates:
 *                  (X, Y, Z) -> (l^2 X, l^3 Y, l Z) for random l.
 *
 * \param grp       Pointer to the group representing the curve.
 *
 * \param pt        The point on the curve to be randomised, given with Jacobian
 *                  coordinates.
 *
 * \param f_rng     A function pointer to the random number generator.
 *
 * \param p_rng     A pointer to the random number generator state.
 *
 * \return          0 if successful.
 */
int mbedtls_internal_ecp_randomize_jac( const mbedtls_ecp_group *grp,
        mbedtls_ecp_point *pt, int (*f_rng)(void *, unsigned char *, size_t),
        void *p_rng );
#endif

#if defined(MBEDTLS_ECP_ADD_MIXED_ALT)
/**
 * \brief           Addition: R = P + Q, mixed affine-Jacobian coordinates.
 *
 *                  The coordinates of Q must be normalized (= affine),
 *                  but those of P don't need to. R is not normalized.
 *
 *                  This function is used only as a subrutine of
 *                  ecp_mul_comb().
 *
 *                  Special cases: (1) P or Q is zero, (2) R is zero,
 *                      (3) P == Q.
 *                  None of these cases can happen as intermediate step in
 *                  ecp_mul_comb():
 *                      - at each step, P, Q and R are multiples of the base
 *                      point, the factor being less than its order, so none of
 *                      them is zero;
 *                      - Q is an odd multiple of the base point, P an even
 *                      multiple, due to the choice of precomputed points in the
 *                      modified comb method.
 *                  So branches for these cases do not leak secret information.
 *
 *                  We accept Q->Z being unset (saving memory in tables) as
 *                  meaning 1.
 *
 *                  Cost in field operations if done by [5] 3.22:
 *                      1A := 8M + 3S
 *
 * \param grp       Pointer to the group representing the curve.
 *
 * \param R         Pointer to a point structure to hold the result.
 *
 * \param P         Pointer to the first summand, given with Jacobian
 *                  coordinates
 *
 * \param Q         Pointer to the second summand, given with affine
 *                  coordinates.
 *
 * \return          0 if successful.
 */
int mbedtls_internal_ecp_add_mixed( const mbedtls_ecp_group *grp,
        mbedtls_ecp_point *R, const mbedtls_ecp_point *P,
        const mbedtls_ecp_point *Q );
#endif

/**
 * \brief           Point doubling R = 2 P, Jacobian coordinates.
 *
 *                  Cost:   1D := 3M + 4S    (A ==  0)
 *                          4M + 4S          (A == -3)
 *                          3M + 6S + 1a     otherwise
 *                  when the implementation is based on the "dbl-1998-cmo-2"
 *                  doubling formulas in [8] and standard optimizations are
 *                  applied when curve parameter A is one of { 0, -3 }.
 *
 * \param grp       Pointer to the group representing the curve.
 *
 * \param R         Pointer to a point structure to hold the result.
 *
 * \param P         Pointer to the point that has to be doubled, given with
 *                  Jacobian coordinates.
 *
 * \return          0 if successful.
 */
#if defined(MBEDTLS_ECP_DOUBLE_JAC_ALT)
int mbedtls_internal_ecp_double_jac( const mbedtls_ecp_group *grp,
        mbedtls_ecp_point *R, const mbedtls_ecp_point *P );
#endif

/**
 * \brief           Normalize jacobian coordinates of an array of (pointers to)
 *                  points.
 *
 *                  Using Montgomery's trick to perform only one inversion mod P
 *                  the cost is:
 *                      1N(t) := 1I + (6t - 3)M + 1S
 *                  (See for example Algorithm 10.3.4. in [9])
 *
 *                  This function is used only as a subrutine of
 *                  ecp_mul_comb().
 *
 *                  Warning: fails (returning an error) if one of the points is
 *                  zero!
 *                  This should never happen, see choice of w in ecp_mul_comb().
 *
 * \param grp       Pointer to the group representing the curve.
 *
 * \param T         Array of pointers to the points to normalise.
 *
 * \param t_len     Number of elements in the array.
 *
 * \return          0 if successful,
 *                      an error if one of the points is zero.
 */
#if defined(MBEDTLS_ECP_NORMALIZE_JAC_MANY_ALT)
int mbedtls_internal_ecp_normalize_jac_many( const mbedtls_ecp_group *grp,
        mbedtls_ecp_point *T[], size_t t_len );
#endif

/**
 * \brief           Normalize jacobian coordinates so that Z == 0 || Z == 1.
 *
 *                  Cost in field operations if done by [5] 3.2.1:
 *                      1N := 1I + 3M + 1S
 *
 * \param grp       Pointer to the group representing the curve.
 *
 * \param pt        pointer to the point to be normalised. This is an
 *                  input/output parameter.
 *
 * \return          0 if successful.
 */
#if defined(MBEDTLS_ECP_NORMALIZE_JAC_ALT)
int mbedtls_internal_ecp_normalize_jac( const mbedtls_ecp_group *grp,
        mbedtls_ecp_point *pt );
#endif

#endif /* ECP_SHORTWEIERSTRASS */

#if defined(ECP_MONTGOMERY)

#if defined(MBEDTLS_ECP_DOUBLE_ADD_MXZ_ALT)
int mbedtls_internal_ecp_double_add_mxz( const mbedtls_ecp_group *grp,
        mbedtls_ecp_point *R, mbedtls_ecp_point *S, const mbedtls_ecp_point *P,
        const mbedtls_ecp_point *Q, const mbedtls_mpi *d );
#endif

/**
 * \brief           Randomize projective x/z coordinates:
 *                      (X, Z) -> (l X, l Z) for random l
 *
 * \param grp       pointer to the group representing the curve
 *
 * \param P         the point on the curve to be randomised given with
 *                  projective coordinates. This is an input/output parameter.
 *
 * \param f_rng     a function pointer to the random number generator
 *
 * \param p_rng     a pointer to the random number generator state
 *
 * \return          0 if successful
 */
#if defined(MBEDTLS_ECP_RANDOMIZE_MXZ_ALT)
int mbedtls_internal_ecp_randomize_mxz( const mbedtls_ecp_group *grp,
        mbedtls_ecp_point *P, int (*f_rng)(void *, unsigned char *, size_t),
        void *p_rng );
#endif

/**
 * \brief           Normalize Montgomery x/z coordinates: X = X/Z, Z = 1.
 *
 * \param grp       pointer to the group representing the curve
 *
 * \param P         pointer to the point to be normalised. This is an
 *                  input/output parameter.
 *
 * \return          0 if successful
 */
#if defined(MBEDTLS_ECP_NORMALIZE_MXZ_ALT)
int mbedtls_internal_ecp_normalize_mxz( const mbedtls_ecp_group *grp,
        mbedtls_ecp_point *P );
#endif

#endif /* ECP_MONTGOMERY */

#endif /* MBEDTLS_ECP_INTERNAL_ALT */

#endif /* ecp_internal.h */
Commit	Line	Data
700d8687 OM	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