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