Run util/openssl-format-source on the Curve448 code
[openssl.git] / crypto / ec / curve448 / point_448.h
1 /*
2  * Copyright 2017 The OpenSSL Project Authors. All Rights Reserved.
3  * Copyright 2015-2016 Cryptography Research, Inc.
4  *
5  * Licensed under the OpenSSL license (the "License").  You may not use
6  * this file except in compliance with the License.  You can obtain a copy
7  * in the file LICENSE in the source distribution or at
8  * https://www.openssl.org/source/license.html
9  *
10  * Originally written by Mike Hamburg
11  */
12
13 #ifndef __DECAF_POINT_448_H__
14 # define __DECAF_POINT_448_H__ 1
15
16 # include "curve448utils.h"
17 # include "field.h"
18
19 #ifdef __cplusplus
20 extern "C" {
21 #endif
22
23 /** @cond internal */
24 # define DECAF_448_SCALAR_LIMBS ((446-1)/DECAF_WORD_BITS+1)
25 /** @endcond */
26
27 /** The number of bits in a scalar */
28 # define DECAF_448_SCALAR_BITS 446
29
30 /** Number of bytes in a serialized point. */
31 # define DECAF_448_SER_BYTES 56
32
33 /** Number of bytes in an elligated point.  For now set the same as SER_BYTES
34  * but could be different for other curves.
35  */
36 # define DECAF_448_HASH_BYTES 56
37
38 /** Number of bytes in a serialized scalar. */
39 # define DECAF_448_SCALAR_BYTES 56
40
41 /** Number of bits in the "which" field of an elligator inverse */
42 # define DECAF_448_INVERT_ELLIGATOR_WHICH_BITS 3
43
44 /** The cofactor the curve would have, if we hadn't removed it */
45 # define DECAF_448_REMOVED_COFACTOR 4
46
47 /** X448 encoding ratio. */
48 # define DECAF_X448_ENCODE_RATIO 2
49
50 /** Number of bytes in an x448 public key */
51 # define DECAF_X448_PUBLIC_BYTES 56
52
53 /** Number of bytes in an x448 private key */
54 # define DECAF_X448_PRIVATE_BYTES 56
55
56 /** Twisted Edwards extended homogeneous coordinates */
57 typedef struct curve448_point_s {
58     /** @cond internal */
59     gf_448_t x, y, z, t;
60     /** @endcond */
61 } curve448_point_t[1];
62
63 /** Precomputed table based on a point.  Can be trivial implementation. */
64 struct curve448_precomputed_s;
65
66 /** Precomputed table based on a point.  Can be trivial implementation. */
67 typedef struct curve448_precomputed_s curve448_precomputed_s;
68
69 /** Scalar is stored packed, because we don't need the speed. */
70 typedef struct curve448_scalar_s {
71     /** @cond internal */
72     decaf_word_t limb[DECAF_448_SCALAR_LIMBS];
73     /** @endcond */
74 } curve448_scalar_t[1];
75
76 /** A scalar equal to 1. */
77 extern const curve448_scalar_t curve448_scalar_one;
78
79 /** A scalar equal to 0. */
80 extern const curve448_scalar_t curve448_scalar_zero;
81
82 /** The identity point on the curve. */
83 extern const curve448_point_t curve448_point_identity;
84
85 /** An arbitrarily chosen base point on the curve. */
86 extern const curve448_point_t curve448_point_base;
87
88 /** Precomputed table for the base point on the curve. */
89 extern const struct curve448_precomputed_s *curve448_precomputed_base;
90
91 /**
92  * @brief Read a scalar from wire format or from bytes.
93  *
94  * @param [in] ser Serialized form of a scalar.
95  * @param [out] out Deserialized form.
96  *
97  * @retval DECAF_SUCCESS The scalar was correctly encoded.
98  * @retval DECAF_FAILURE The scalar was greater than the modulus,
99  * and has been reduced modulo that modulus.
100  */
101 __owur decaf_error_t curve448_scalar_decode(curve448_scalar_t out,
102                                             const unsigned char
103                                             ser[DECAF_448_SCALAR_BYTES]
104     );
105
106 /**
107  * @brief Read a scalar from wire format or from bytes.  Reduces mod
108  * scalar prime.
109  *
110  * @param [in] ser Serialized form of a scalar.
111  * @param [in] ser_len Length of serialized form.
112  * @param [out] out Deserialized form.
113  */
114 void curve448_scalar_decode_long(curve448_scalar_t out,
115                                  const unsigned char *ser, size_t ser_len);
116
117 /**
118  * @brief Serialize a scalar to wire format.
119  *
120  * @param [out] ser Serialized form of a scalar.
121  * @param [in] s Deserialized scalar.
122  */
123 void curve448_scalar_encode(unsigned char ser[DECAF_448_SCALAR_BYTES],
124                             const curve448_scalar_t s);
125
126 /**
127  * @brief Add two scalars.  The scalars may use the same memory.
128  * @param [in] a One scalar.
129  * @param [in] b Another scalar.
130  * @param [out] out a+b.
131  */
132 void curve448_scalar_add(curve448_scalar_t out,
133                          const curve448_scalar_t a, const curve448_scalar_t b);
134
135 /**
136  * @brief Subtract two scalars.  The scalars may use the same memory.
137  * @param [in] a One scalar.
138  * @param [in] b Another scalar.
139  * @param [out] out a-b.
140  */
141 void curve448_scalar_sub(curve448_scalar_t out,
142                          const curve448_scalar_t a, const curve448_scalar_t b);
143
144 /**
145  * @brief Multiply two scalars.  The scalars may use the same memory.
146  * @param [in] a One scalar.
147  * @param [in] b Another scalar.
148  * @param [out] out a*b.
149  */
150 void curve448_scalar_mul(curve448_scalar_t out,
151                          const curve448_scalar_t a, const curve448_scalar_t b);
152
153 /**
154 * @brief Halve a scalar.  The scalars may use the same memory.
155 * @param [in] a A scalar.
156 * @param [out] out a/2.
157 */
158 void curve448_scalar_halve(curve448_scalar_t out, const curve448_scalar_t a);
159
160 /**
161  * @brief Copy a scalar.  The scalars may use the same memory, in which
162  * case this function does nothing.
163  * @param [in] a A scalar.
164  * @param [out] out Will become a copy of a.
165  */
166 static ossl_inline void curve448_scalar_copy(curve448_scalar_t out,
167                                              const curve448_scalar_t a)
168 {
169     *out = *a;
170 }
171
172 /**
173  * @brief Copy a point.  The input and output may alias,
174  * in which case this function does nothing.
175  *
176  * @param [out] a A copy of the point.
177  * @param [in] b Any point.
178  */
179 static ossl_inline void curve448_point_copy(curve448_point_t a,
180                                             const curve448_point_t b)
181 {
182     *a = *b;
183 }
184
185 /**
186  * @brief Test whether two points are equal.  If yes, return
187  * DECAF_TRUE, else return DECAF_FALSE.
188  *
189  * @param [in] a A point.
190  * @param [in] b Another point.
191  * @retval DECAF_TRUE The points are equal.
192  * @retval DECAF_FALSE The points are not equal.
193  */
194 __owur decaf_bool_t curve448_point_eq(const curve448_point_t a,
195                                       const curve448_point_t b);
196
197 /**
198  * @brief Double a point.  Equivalent to
199  * curve448_point_add(two_a,a,a), but potentially faster.
200  *
201  * @param [out] two_a The sum a+a.
202  * @param [in] a A point.
203  */
204 void curve448_point_double(curve448_point_t two_a, const curve448_point_t a);
205
206 /**
207  * @brief RFC 7748 Diffie-Hellman scalarmul.  This function uses a different
208  * (non-Decaf) encoding.
209  *
210  * @param [out] scaled The scaled point base*scalar
211  * @param [in] base The point to be scaled.
212  * @param [in] scalar The scalar to multiply by.
213  *
214  * @retval DECAF_SUCCESS The scalarmul succeeded.
215  * @retval DECAF_FAILURE The scalarmul didn't succeed, because the base
216  * point is in a small subgroup.
217  */
218 __owur decaf_error_t decaf_x448(uint8_t out[DECAF_X448_PUBLIC_BYTES],
219                                 const uint8_t base[DECAF_X448_PUBLIC_BYTES],
220                                 const uint8_t scalar[DECAF_X448_PRIVATE_BYTES]
221     );
222
223 /**
224  * @brief Multiply a point by DECAF_X448_ENCODE_RATIO,
225  * then encode it like RFC 7748.
226  *
227  * This function is mainly used internally, but is exported in case
228  * it will be useful.
229  *
230  * The ratio is necessary because the internal representation doesn't
231  * track the cofactor information, so on output we must clear the cofactor.
232  * This would multiply by the cofactor, but in fact internally libdecaf's
233  * points are always even, so it multiplies by half the cofactor instead.
234  *
235  * As it happens, this aligns with the base point definitions; that is,
236  * if you pass the Decaf/Ristretto base point to this function, the result
237  * will be DECAF_X448_ENCODE_RATIO times the X448
238  * base point.
239  *
240  * @param [out] out The scaled and encoded point.
241  * @param [in] p The point to be scaled and encoded.
242  */
243 void curve448_point_mul_by_ratio_and_encode_like_x448(uint8_t
244                                                       out
245                                                       [DECAF_X448_PUBLIC_BYTES],
246                                                       const curve448_point_t p);
247
248 /** The base point for X448 Diffie-Hellman */
249 extern const uint8_t decaf_x448_base_point[DECAF_X448_PUBLIC_BYTES];
250
251 /**
252  * @brief RFC 7748 Diffie-Hellman base point scalarmul.  This function uses
253  * a different (non-Decaf) encoding.
254  *
255  * Does exactly the same thing as decaf_x448_generate_key,
256  * but has a better name.
257  *
258  * @param [out] scaled The scaled point base*scalar
259  * @param [in] scalar The scalar to multiply by.
260  */
261 void decaf_x448_derive_public_key(uint8_t out[DECAF_X448_PUBLIC_BYTES],
262                                   const uint8_t scalar[DECAF_X448_PRIVATE_BYTES]
263     );
264
265 /**
266  * @brief Multiply a precomputed base point by a scalar:
267  * scaled = scalar*base.
268  * Some implementations do not include precomputed points; for
269  * those implementations, this function is the same as
270  * curve448_point_scalarmul
271  *
272  * @param [out] scaled The scaled point base*scalar
273  * @param [in] base The point to be scaled.
274  * @param [in] scalar The scalar to multiply by.
275  */
276 void curve448_precomputed_scalarmul(curve448_point_t scaled,
277                                     const curve448_precomputed_s * base,
278                                     const curve448_scalar_t scalar);
279
280 /**
281  * @brief Multiply two base points by two scalars:
282  * scaled = scalar1*curve448_point_base + scalar2*base2.
283  *
284  * Otherwise equivalent to curve448_point_double_scalarmul, but may be
285  * faster at the expense of being variable time.
286  *
287  * @param [out] combo The linear combination scalar1*base + scalar2*base2.
288  * @param [in] scalar1 A first scalar to multiply by.
289  * @param [in] base2 A second point to be scaled.
290  * @param [in] scalar2 A second scalar to multiply by.
291  *
292  * @warning: This function takes variable time, and may leak the scalars
293  * used.  It is designed for signature verification.
294  */
295 void curve448_base_double_scalarmul_non_secret(curve448_point_t combo,
296                                                const curve448_scalar_t scalar1,
297                                                const curve448_point_t base2,
298                                                const curve448_scalar_t scalar2);
299
300 /**
301  * @brief Test that a point is valid, for debugging purposes.
302  *
303  * @param [in] to_test The point to test.
304  * @retval DECAF_TRUE The point is valid.
305  * @retval DECAF_FALSE The point is invalid.
306  */
307 __owur decaf_bool_t curve448_point_valid(const curve448_point_t to_test);
308
309 /**
310  * @brief Overwrite scalar with zeros.
311  */
312 void curve448_scalar_destroy(curve448_scalar_t scalar);
313
314 /**
315  * @brief Overwrite point with zeros.
316  */
317 void curve448_point_destroy(curve448_point_t point);
318
319 #ifdef __cplusplus
320 } /* extern "C" */
321 #endif
322
323 #endif                          /* __DECAF_POINT_448_H__ */