]>
Commit | Line | Data |
---|---|---|
1308e022 | 1 | /* |
f53c7764 | 2 | * Copyright 2017-2018 The OpenSSL Project Authors. All Rights Reserved. |
1308e022 | 3 | * Copyright 2015-2016 Cryptography Research, Inc. |
7324473f | 4 | * |
1308e022 MC |
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 | |
7324473f | 9 | * |
1308e022 | 10 | * Originally written by Mike Hamburg |
7324473f MC |
11 | */ |
12 | ||
68b20c00 MC |
13 | #ifndef HEADER_POINT_448_H |
14 | # define HEADER_POINT_448_H | |
7324473f | 15 | |
205fd638 MC |
16 | # include "curve448utils.h" |
17 | # include "field.h" | |
7324473f | 18 | |
7324473f | 19 | |
db90b274 | 20 | # define C448_SCALAR_LIMBS ((446-1)/C448_WORD_BITS+1) |
7324473f | 21 | |
8d55f844 | 22 | /* The number of bits in a scalar */ |
db90b274 | 23 | # define C448_SCALAR_BITS 446 |
7324473f | 24 | |
8d55f844 | 25 | /* Number of bytes in a serialized scalar. */ |
db90b274 | 26 | # define C448_SCALAR_BYTES 56 |
7324473f | 27 | |
8d55f844 | 28 | /* X448 encoding ratio. */ |
db90b274 | 29 | # define X448_ENCODE_RATIO 2 |
7324473f | 30 | |
8d55f844 | 31 | /* Number of bytes in an x448 public key */ |
db90b274 | 32 | # define X448_PUBLIC_BYTES 56 |
7324473f | 33 | |
8d55f844 | 34 | /* Number of bytes in an x448 private key */ |
db90b274 | 35 | # define X448_PRIVATE_BYTES 56 |
7324473f | 36 | |
8d55f844 | 37 | /* Twisted Edwards extended homogeneous coordinates */ |
e7772577 | 38 | typedef struct curve448_point_s { |
35b7c85a | 39 | gf x, y, z, t; |
e7772577 | 40 | } curve448_point_t[1]; |
7324473f | 41 | |
8d55f844 | 42 | /* Precomputed table based on a point. Can be trivial implementation. */ |
e7772577 | 43 | struct curve448_precomputed_s; |
7324473f | 44 | |
8d55f844 | 45 | /* Precomputed table based on a point. Can be trivial implementation. */ |
205fd638 | 46 | typedef struct curve448_precomputed_s curve448_precomputed_s; |
7324473f | 47 | |
8d55f844 | 48 | /* Scalar is stored packed, because we don't need the speed. */ |
e7772577 | 49 | typedef struct curve448_scalar_s { |
db90b274 | 50 | c448_word_t limb[C448_SCALAR_LIMBS]; |
e7772577 | 51 | } curve448_scalar_t[1]; |
7324473f | 52 | |
8d55f844 | 53 | /* A scalar equal to 1. */ |
09ffbc94 | 54 | extern const curve448_scalar_t curve448_scalar_one; |
7324473f | 55 | |
8d55f844 | 56 | /* A scalar equal to 0. */ |
09ffbc94 | 57 | extern const curve448_scalar_t curve448_scalar_zero; |
7324473f | 58 | |
8d55f844 | 59 | /* The identity point on the curve. */ |
09ffbc94 | 60 | extern const curve448_point_t curve448_point_identity; |
7324473f | 61 | |
8d55f844 | 62 | /* Precomputed table for the base point on the curve. */ |
09ffbc94 | 63 | extern const struct curve448_precomputed_s *curve448_precomputed_base; |
7324473f | 64 | |
8d55f844 MC |
65 | /* |
66 | * Read a scalar from wire format or from bytes. | |
7324473f | 67 | * |
8d55f844 MC |
68 | * ser (in): Serialized form of a scalar. |
69 | * out (out): Deserialized form. | |
7324473f | 70 | * |
8d55f844 | 71 | * Returns: |
aeeef83c MC |
72 | * C448_SUCCESS: The scalar was correctly encoded. |
73 | * C448_FAILURE: The scalar was greater than the modulus, and has been reduced | |
8d55f844 | 74 | * modulo that modulus. |
7324473f | 75 | */ |
aeeef83c | 76 | __owur c448_error_t curve448_scalar_decode( |
8d55f844 | 77 | curve448_scalar_t out, |
db90b274 | 78 | const unsigned char ser[C448_SCALAR_BYTES]); |
8d55f844 MC |
79 | |
80 | /* | |
81 | * Read a scalar from wire format or from bytes. Reduces mod scalar prime. | |
7324473f | 82 | * |
8d55f844 MC |
83 | * ser (in): Serialized form of a scalar. |
84 | * ser_len (in): Length of serialized form. | |
85 | * out (out): Deserialized form. | |
7324473f | 86 | */ |
205fd638 MC |
87 | void curve448_scalar_decode_long(curve448_scalar_t out, |
88 | const unsigned char *ser, size_t ser_len); | |
89 | ||
8d55f844 MC |
90 | /* |
91 | * Serialize a scalar to wire format. | |
7324473f | 92 | * |
8d55f844 MC |
93 | * ser (out): Serialized form of a scalar. |
94 | * s (in): Deserialized scalar. | |
7324473f | 95 | */ |
db90b274 | 96 | void curve448_scalar_encode(unsigned char ser[C448_SCALAR_BYTES], |
205fd638 MC |
97 | const curve448_scalar_t s); |
98 | ||
8d55f844 MC |
99 | /* |
100 | * Add two scalars. The scalars may use the same memory. | |
101 | * | |
102 | * a (in): One scalar. | |
103 | * b (in): Another scalar. | |
104 | * out (out): a+b. | |
7324473f | 105 | */ |
205fd638 MC |
106 | void curve448_scalar_add(curve448_scalar_t out, |
107 | const curve448_scalar_t a, const curve448_scalar_t b); | |
7324473f | 108 | |
8d55f844 MC |
109 | /* |
110 | * Subtract two scalars. The scalars may use the same memory. | |
111 | * a (in): One scalar. | |
112 | * b (in): Another scalar. | |
113 | * out (out): a-b. | |
205fd638 MC |
114 | */ |
115 | void curve448_scalar_sub(curve448_scalar_t out, | |
116 | const curve448_scalar_t a, const curve448_scalar_t b); | |
7324473f | 117 | |
8d55f844 MC |
118 | /* |
119 | * Multiply two scalars. The scalars may use the same memory. | |
120 | * | |
121 | * a (in): One scalar. | |
122 | * b (in): Another scalar. | |
123 | * out (out): a*b. | |
205fd638 MC |
124 | */ |
125 | void curve448_scalar_mul(curve448_scalar_t out, | |
126 | const curve448_scalar_t a, const curve448_scalar_t b); | |
127 | ||
8d55f844 MC |
128 | /* |
129 | * Halve a scalar. The scalars may use the same memory. | |
130 | * | |
131 | * a (in): A scalar. | |
132 | * out (out): a/2. | |
7324473f | 133 | */ |
205fd638 | 134 | void curve448_scalar_halve(curve448_scalar_t out, const curve448_scalar_t a); |
7324473f | 135 | |
8d55f844 MC |
136 | /* |
137 | * Copy a scalar. The scalars may use the same memory, in which case this | |
138 | * function does nothing. | |
139 | * | |
140 | * a (in): A scalar. | |
141 | * out (out): Will become a copy of a. | |
7324473f | 142 | */ |
205fd638 MC |
143 | static ossl_inline void curve448_scalar_copy(curve448_scalar_t out, |
144 | const curve448_scalar_t a) | |
145 | { | |
7324473f MC |
146 | *out = *a; |
147 | } | |
148 | ||
8d55f844 MC |
149 | /* |
150 | * Copy a point. The input and output may alias, in which case this function | |
151 | * does nothing. | |
7324473f | 152 | * |
8d55f844 MC |
153 | * a (out): A copy of the point. |
154 | * b (in): Any point. | |
7324473f | 155 | */ |
205fd638 MC |
156 | static ossl_inline void curve448_point_copy(curve448_point_t a, |
157 | const curve448_point_t b) | |
158 | { | |
159 | *a = *b; | |
7324473f MC |
160 | } |
161 | ||
8d55f844 | 162 | /* |
aeeef83c MC |
163 | * Test whether two points are equal. If yes, return C448_TRUE, else return |
164 | * C448_FALSE. | |
7324473f | 165 | * |
8d55f844 MC |
166 | * a (in): A point. |
167 | * b (in): Another point. | |
168 | * | |
169 | * Returns: | |
aeeef83c MC |
170 | * C448_TRUE: The points are equal. |
171 | * C448_FALSE: The points are not equal. | |
7324473f | 172 | */ |
aeeef83c MC |
173 | __owur c448_bool_t curve448_point_eq(const curve448_point_t a, |
174 | const curve448_point_t b); | |
7324473f | 175 | |
8d55f844 MC |
176 | /* |
177 | * Double a point. Equivalent to curve448_point_add(two_a,a,a), but potentially | |
178 | * faster. | |
7324473f | 179 | * |
8d55f844 MC |
180 | * two_a (out): The sum a+a. |
181 | * a (in): A point. | |
7324473f | 182 | */ |
205fd638 | 183 | void curve448_point_double(curve448_point_t two_a, const curve448_point_t a); |
7324473f | 184 | |
8d55f844 MC |
185 | /* |
186 | * RFC 7748 Diffie-Hellman scalarmul. This function uses a different | |
7324473f MC |
187 | * (non-Decaf) encoding. |
188 | * | |
8d55f844 MC |
189 | * out (out): The scaled point base*scalar |
190 | * base (in): The point to be scaled. | |
191 | * scalar (in): The scalar to multiply by. | |
7324473f | 192 | * |
8d55f844 | 193 | * Returns: |
aeeef83c MC |
194 | * C448_SUCCESS: The scalarmul succeeded. |
195 | * C448_FAILURE: The scalarmul didn't succeed, because the base point is in a | |
8d55f844 | 196 | * small subgroup. |
7324473f | 197 | */ |
db90b274 MC |
198 | __owur c448_error_t x448_int(uint8_t out[X448_PUBLIC_BYTES], |
199 | const uint8_t base[X448_PUBLIC_BYTES], | |
200 | const uint8_t scalar[X448_PRIVATE_BYTES]); | |
7324473f | 201 | |
8d55f844 | 202 | /* |
db90b274 | 203 | * Multiply a point by X448_ENCODE_RATIO, then encode it like RFC 7748. |
7324473f MC |
204 | * |
205 | * This function is mainly used internally, but is exported in case | |
206 | * it will be useful. | |
207 | * | |
208 | * The ratio is necessary because the internal representation doesn't | |
209 | * track the cofactor information, so on output we must clear the cofactor. | |
aeeef83c MC |
210 | * This would multiply by the cofactor, but in fact internally points are always |
211 | * even, so it multiplies by half the cofactor instead. | |
7324473f MC |
212 | * |
213 | * As it happens, this aligns with the base point definitions; that is, | |
214 | * if you pass the Decaf/Ristretto base point to this function, the result | |
db90b274 | 215 | * will be X448_ENCODE_RATIO times the X448 |
7324473f MC |
216 | * base point. |
217 | * | |
8d55f844 MC |
218 | * out (out): The scaled and encoded point. |
219 | * p (in): The point to be scaled and encoded. | |
7324473f | 220 | */ |
8d55f844 | 221 | void curve448_point_mul_by_ratio_and_encode_like_x448( |
db90b274 | 222 | uint8_t out[X448_PUBLIC_BYTES], |
8d55f844 | 223 | const curve448_point_t p); |
7324473f | 224 | |
8d55f844 MC |
225 | /* |
226 | * RFC 7748 Diffie-Hellman base point scalarmul. This function uses a different | |
227 | * (non-Decaf) encoding. | |
228 | * | |
229 | * out (out): The scaled point base*scalar | |
230 | * scalar (in): The scalar to multiply by. | |
7324473f | 231 | */ |
db90b274 MC |
232 | void x448_derive_public_key(uint8_t out[X448_PUBLIC_BYTES], |
233 | const uint8_t scalar[X448_PRIVATE_BYTES]); | |
8d55f844 MC |
234 | |
235 | /* | |
236 | * Multiply a precomputed base point by a scalar: out = scalar*base. | |
7324473f | 237 | * |
8d55f844 MC |
238 | * scaled (out): The scaled point base*scalar |
239 | * base (in): The point to be scaled. | |
240 | * scalar (in): The scalar to multiply by. | |
7324473f | 241 | */ |
205fd638 MC |
242 | void curve448_precomputed_scalarmul(curve448_point_t scaled, |
243 | const curve448_precomputed_s * base, | |
244 | const curve448_scalar_t scalar); | |
7324473f | 245 | |
8d55f844 MC |
246 | /* |
247 | * Multiply two base points by two scalars: | |
248 | * combo = scalar1*curve448_point_base + scalar2*base2. | |
7324473f | 249 | * |
e7772577 | 250 | * Otherwise equivalent to curve448_point_double_scalarmul, but may be |
7324473f MC |
251 | * faster at the expense of being variable time. |
252 | * | |
8d55f844 MC |
253 | * combo (out): The linear combination scalar1*base + scalar2*base2. |
254 | * scalar1 (in): A first scalar to multiply by. | |
255 | * base2 (in): A second point to be scaled. | |
256 | * scalar2 (in) A second scalar to multiply by. | |
7324473f | 257 | * |
8d55f844 MC |
258 | * Warning: This function takes variable time, and may leak the scalars used. |
259 | * It is designed for signature verification. | |
7324473f | 260 | */ |
205fd638 MC |
261 | void curve448_base_double_scalarmul_non_secret(curve448_point_t combo, |
262 | const curve448_scalar_t scalar1, | |
263 | const curve448_point_t base2, | |
264 | const curve448_scalar_t scalar2); | |
7324473f | 265 | |
8d55f844 MC |
266 | /* |
267 | * Test that a point is valid, for debugging purposes. | |
7324473f | 268 | * |
8d55f844 MC |
269 | * to_test (in): The point to test. |
270 | * | |
271 | * Returns: | |
aeeef83c MC |
272 | * C448_TRUE The point is valid. |
273 | * C448_FALSE The point is invalid. | |
7324473f | 274 | */ |
aeeef83c | 275 | __owur c448_bool_t curve448_point_valid(const curve448_point_t to_test); |
7324473f | 276 | |
8d55f844 | 277 | /* Overwrite scalar with zeros. */ |
205fd638 | 278 | void curve448_scalar_destroy(curve448_scalar_t scalar); |
7324473f | 279 | |
8d55f844 | 280 | /* Overwrite point with zeros. */ |
205fd638 | 281 | void curve448_point_destroy(curve448_point_t point); |
7324473f | 282 | |
68b20c00 | 283 | #endif /* HEADER_POINT_448_H */ |