Run util/openssl-format-source on the Curve448 code
[openssl.git] / crypto / ec / curve448 / ed448.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_ED448_H__
14 # define __DECAF_ED448_H__ 1
15
16 # include "point_448.h"
17
18 #ifdef __cplusplus
19 extern "C" {
20 #endif
21
22 /** Number of bytes in an EdDSA public key. */
23 # define DECAF_EDDSA_448_PUBLIC_BYTES 57
24
25 /** Number of bytes in an EdDSA private key. */
26 # define DECAF_EDDSA_448_PRIVATE_BYTES DECAF_EDDSA_448_PUBLIC_BYTES
27
28 /** Number of bytes in an EdDSA private key. */
29 # define DECAF_EDDSA_448_SIGNATURE_BYTES (DECAF_EDDSA_448_PUBLIC_BYTES + DECAF_EDDSA_448_PRIVATE_BYTES)
30
31 /** Does EdDSA support non-contextual signatures? */
32 # define DECAF_EDDSA_448_SUPPORTS_CONTEXTLESS_SIGS 0
33
34 /** EdDSA encoding ratio. */
35 # define DECAF_448_EDDSA_ENCODE_RATIO 4
36
37 /** EdDSA decoding ratio. */
38 # define DECAF_448_EDDSA_DECODE_RATIO (4 / 4)
39
40 /**
41  * @brief EdDSA key generation.  This function uses a different (non-Decaf)
42  * encoding.
43  *
44  * @param [out] pubkey The public key.
45  * @param [in] privkey The private key.
46  */
47 decaf_error_t decaf_ed448_derive_public_key(uint8_t
48                                             pubkey
49                                             [DECAF_EDDSA_448_PUBLIC_BYTES],
50                                             const uint8_t
51                                             privkey
52                                             [DECAF_EDDSA_448_PRIVATE_BYTES]
53     );
54
55 /**
56  * @brief EdDSA signing.
57  *
58  * @param [out] signature The signature.
59  * @param [in] privkey The private key.
60  * @param [in] pubkey The public key.
61  * @param [in] message The message to sign.
62  * @param [in] message_len The length of the message.
63  * @param [in] prehashed Nonzero if the message is actually the hash of something you want to sign.
64  * @param [in] context A "context" for this signature of up to 255 bytes.
65  * @param [in] context_len Length of the context.
66  *
67  * @warning For Ed25519, it is unsafe to use the same key for both prehashed and non-prehashed
68  * messages, at least without some very careful protocol-level disambiguation.  For Ed448 it is
69  * safe.  The C++ wrapper is designed to make it harder to screw this up, but this C code gives
70  * you no seat belt.
71  */
72 decaf_error_t decaf_ed448_sign(uint8_t
73                                signature[DECAF_EDDSA_448_SIGNATURE_BYTES],
74                                const uint8_t
75                                privkey[DECAF_EDDSA_448_PRIVATE_BYTES],
76                                const uint8_t
77                                pubkey[DECAF_EDDSA_448_PUBLIC_BYTES],
78                                const uint8_t *message, size_t message_len,
79                                uint8_t prehashed, const uint8_t *context,
80                                size_t context_len)
81     __attribute__ ((nonnull(1, 2, 3)));
82
83 /**
84  * @brief EdDSA signing with prehash.
85  *
86  * @param [out] signature The signature.
87  * @param [in] privkey The private key.
88  * @param [in] pubkey The public key.
89  * @param [in] hash The hash of the message.  This object will not be modified by the call.
90  * @param [in] context A "context" for this signature of up to 255 bytes.  Must be the same as what was used for the prehash.
91  * @param [in] context_len Length of the context.
92  *
93  * @warning For Ed25519, it is unsafe to use the same key for both prehashed and non-prehashed
94  * messages, at least without some very careful protocol-level disambiguation.  For Ed448 it is
95  * safe.  The C++ wrapper is designed to make it harder to screw this up, but this C code gives
96  * you no seat belt.
97  */
98 decaf_error_t decaf_ed448_sign_prehash(uint8_t
99                                        signature
100                                        [DECAF_EDDSA_448_SIGNATURE_BYTES],
101                                        const uint8_t
102                                        privkey[DECAF_EDDSA_448_PRIVATE_BYTES],
103                                        const uint8_t
104                                        pubkey[DECAF_EDDSA_448_PUBLIC_BYTES],
105                                        const uint8_t hash[64],
106                                        const uint8_t *context,
107                                        size_t context_len)
108     __attribute__ ((nonnull(1, 2, 3, 4)));
109
110 /**
111  * @brief EdDSA signature verification.
112  *
113  * Uses the standard (i.e. less-strict) verification formula.
114  *
115  * @param [in] signature The signature.
116  * @param [in] pubkey The public key.
117  * @param [in] message The message to verify.
118  * @param [in] message_len The length of the message.
119  * @param [in] prehashed Nonzero if the message is actually the hash of something you want to verify.
120  * @param [in] context A "context" for this signature of up to 255 bytes.
121  * @param [in] context_len Length of the context.
122  *
123  * @warning For Ed25519, it is unsafe to use the same key for both prehashed and non-prehashed
124  * messages, at least without some very careful protocol-level disambiguation.  For Ed448 it is
125  * safe.  The C++ wrapper is designed to make it harder to screw this up, but this C code gives
126  * you no seat belt.
127  */
128 decaf_error_t decaf_ed448_verify(const uint8_t
129                                  signature[DECAF_EDDSA_448_SIGNATURE_BYTES],
130                                  const uint8_t
131                                  pubkey[DECAF_EDDSA_448_PUBLIC_BYTES],
132                                  const uint8_t *message, size_t message_len,
133                                  uint8_t prehashed, const uint8_t *context,
134                                  uint8_t context_len)
135     __attribute__ ((nonnull(1, 2)));
136
137 /**
138  * @brief EdDSA signature verification.
139  *
140  * Uses the standard (i.e. less-strict) verification formula.
141  *
142  * @param [in] signature The signature.
143  * @param [in] pubkey The public key.
144  * @param [in] hash The hash of the message.  This object will not be modified by the call.
145  * @param [in] context A "context" for this signature of up to 255 bytes.  Must be the same as what was used for the prehash.
146  * @param [in] context_len Length of the context.
147  *
148  * @warning For Ed25519, it is unsafe to use the same key for both prehashed and non-prehashed
149  * messages, at least without some very careful protocol-level disambiguation.  For Ed448 it is
150  * safe.  The C++ wrapper is designed to make it harder to screw this up, but this C code gives
151  * you no seat belt.
152  */
153 decaf_error_t decaf_ed448_verify_prehash(const uint8_t
154                                          signature
155                                          [DECAF_EDDSA_448_SIGNATURE_BYTES],
156                                          const uint8_t
157                                          pubkey[DECAF_EDDSA_448_PUBLIC_BYTES],
158                                          const uint8_t hash[64],
159                                          const uint8_t *context,
160                                          uint8_t context_len)
161     __attribute__ ((nonnull(1, 2)));
162
163 /**
164  * @brief EdDSA point encoding.  Used internally, exposed externally.
165  * Multiplies by DECAF_448_EDDSA_ENCODE_RATIO first.
166  *
167  * The multiplication is required because the EdDSA encoding represents
168  * the cofactor information, but the Decaf encoding ignores it (which
169  * is the whole point).  So if you decode from EdDSA and re-encode to
170  * EdDSA, the cofactor info must get cleared, because the intermediate
171  * representation doesn't track it.
172  *
173  * The way libdecaf handles this is to multiply by
174  * DECAF_448_EDDSA_DECODE_RATIO when decoding, and by
175  * DECAF_448_EDDSA_ENCODE_RATIO when encoding.  The product of these
176  * ratios is always exactly the cofactor 4, so the cofactor
177  * ends up cleared one way or another.  But exactly how that shakes
178  * out depends on the base points specified in RFC 8032.
179  *
180  * The upshot is that if you pass the Decaf/Ristretto base point to
181  * this function, you will get DECAF_448_EDDSA_ENCODE_RATIO times the
182  * EdDSA base point.
183  *
184  * @param [out] enc The encoded point.
185  * @param [in] p The point.
186  */
187 void curve448_point_mul_by_ratio_and_encode_like_eddsa(uint8_t
188                                                        enc
189                                                        [DECAF_EDDSA_448_PUBLIC_BYTES],
190                                                        const curve448_point_t
191                                                        p);
192
193 /**
194  * @brief EdDSA point decoding.  Multiplies by DECAF_448_EDDSA_DECODE_RATIO,
195  * and ignores cofactor information.
196  *
197  * See notes on curve448_point_mul_by_ratio_and_encode_like_eddsa
198  *
199  * @param [out] enc The encoded point.
200  * @param [in] p The point.
201  */
202 decaf_error_t curve448_point_decode_like_eddsa_and_mul_by_ratio(curve448_point_t
203                                                                 p,
204                                                                 const uint8_t
205                                                                 enc
206                                                                 [DECAF_EDDSA_448_PUBLIC_BYTES]
207     );
208
209 /**
210  * @brief EdDSA to ECDH public key conversion
211  * Deserialize the point to get y on Edwards curve,
212  * Convert it to u coordinate on Montgomery curve.
213  *
214  * @warning This function does not check that the public key being converted
215  * is a valid EdDSA public key (FUTURE?)
216  *
217  * @param[out] x The ECDH public key as in RFC7748(point on Montgomery curve)
218  * @param[in] ed The EdDSA public key(point on Edwards curve)
219  */
220 void decaf_ed448_convert_public_key_to_x448(uint8_t x[DECAF_X448_PUBLIC_BYTES],
221                                             const uint8_t
222                                             ed[DECAF_EDDSA_448_PUBLIC_BYTES]
223     );
224
225 /**
226  * @brief EdDSA to ECDH private key conversion
227  * Using the appropriate hash function, hash the EdDSA private key
228  * and keep only the lower bytes to get the ECDH private key
229  *
230  * @param[out] x The ECDH private key as in RFC7748
231  * @param[in] ed The EdDSA private key
232  */
233 decaf_error_t decaf_ed448_convert_private_key_to_x448(uint8_t
234                                                       x
235                                                       [DECAF_X448_PRIVATE_BYTES],
236                                                       const uint8_t
237                                                       ed
238                                                       [DECAF_EDDSA_448_PRIVATE_BYTES]
239     );
240
241 #ifdef __cplusplus
242 } /* extern "C" */
243 #endif
244
245 #endif                          /* __DECAF_ED448_H__ */