2 * Copyright 2017 The OpenSSL Project Authors. All Rights Reserved.
3 * Copyright 2015-2016 Cryptography Research, Inc.
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
10 * Originally written by Mike Hamburg
13 #ifndef __DECAF_ED448_H__
14 #define __DECAF_ED448_H__ 1
16 #include "point_448.h"
22 /** Number of bytes in an EdDSA public key. */
23 #define DECAF_EDDSA_448_PUBLIC_BYTES 57
25 /** Number of bytes in an EdDSA private key. */
26 #define DECAF_EDDSA_448_PRIVATE_BYTES DECAF_EDDSA_448_PUBLIC_BYTES
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)
31 /** Does EdDSA support non-contextual signatures? */
32 #define DECAF_EDDSA_448_SUPPORTS_CONTEXTLESS_SIGS 0
34 /** EdDSA encoding ratio. */
35 #define DECAF_448_EDDSA_ENCODE_RATIO 4
37 /** EdDSA decoding ratio. */
38 #define DECAF_448_EDDSA_DECODE_RATIO (4 / 4)
41 * @brief EdDSA key generation. This function uses a different (non-Decaf)
44 * @param [out] pubkey The public key.
45 * @param [in] privkey The private key.
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]
53 * @brief EdDSA signing.
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.
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
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,
76 const uint8_t *context,
78 ) __attribute__((nonnull(1,2,3)));
81 * @brief EdDSA signing with prehash.
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.
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
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,
102 ) __attribute__((nonnull(1,2,3,4)));
105 * @brief EdDSA signature verification.
107 * Uses the standard (i.e. less-strict) verification formula.
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.
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
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,
128 const uint8_t *context,
130 ) __attribute__((nonnull(1,2)));
133 * @brief EdDSA signature verification.
135 * Uses the standard (i.e. less-strict) verification formula.
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.
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
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,
154 ) __attribute__((nonnull(1,2)));
157 * @brief EdDSA point encoding. Used internally, exposed externally.
158 * Multiplies by DECAF_448_EDDSA_ENCODE_RATIO first.
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.
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.
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
177 * @param [out] enc The encoded point.
178 * @param [in] p The point.
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
186 * @brief EdDSA point decoding. Multiplies by DECAF_448_EDDSA_DECODE_RATIO,
187 * and ignores cofactor information.
189 * See notes on curve448_point_mul_by_ratio_and_encode_like_eddsa
191 * @param [out] enc The encoded point.
192 * @param [in] p The point.
194 decaf_error_t curve448_point_decode_like_eddsa_and_mul_by_ratio (
196 const uint8_t enc[DECAF_EDDSA_448_PUBLIC_BYTES]
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.
204 * @warning This function does not check that the public key being converted
205 * is a valid EdDSA public key (FUTURE?)
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)
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]
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
220 * @param[out] x The ECDH private key as in RFC7748
221 * @param[in] ed The EdDSA private key
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]
232 #endif /* __DECAF_ED448_H__ */