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