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