1 /* 2 * Copyright 2017-2021 The OpenSSL Project Authors. All Rights Reserved. 3 * Copyright 2015-2016 Cryptography Research, Inc. 4 * 5 * Licensed under the Apache License 2.0 (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 OSSL_CRYPTO_EC_CURVE448_ED448_H 14 # define OSSL_CRYPTO_EC_CURVE448_ED448_H 15 16 # include "point_448.h" 17 18 /* Number of bytes in an EdDSA public key. */ 19 # define EDDSA_448_PUBLIC_BYTES 57 20 21 /* Number of bytes in an EdDSA private key. */ 22 # define EDDSA_448_PRIVATE_BYTES EDDSA_448_PUBLIC_BYTES 23 24 /* Number of bytes in an EdDSA private key. */ 25 # define EDDSA_448_SIGNATURE_BYTES (EDDSA_448_PUBLIC_BYTES + \ 26 EDDSA_448_PRIVATE_BYTES) 27 28 /* EdDSA encoding ratio. */ 29 # define C448_EDDSA_ENCODE_RATIO 4 30 31 /* EdDSA decoding ratio. */ 32 # define C448_EDDSA_DECODE_RATIO (4 / 4) 33 34 /* 35 * EdDSA key generation. This function uses a different (non-Decaf) encoding. 36 * 37 * pubkey (out): The public key. 38 * privkey (in): The private key. 39 */ 40 c448_error_t 41 ossl_c448_ed448_derive_public_key( 42 OSSL_LIB_CTX *ctx, 43 uint8_t pubkey [EDDSA_448_PUBLIC_BYTES], 44 const uint8_t privkey [EDDSA_448_PRIVATE_BYTES], 45 const char *propq); 46 47 /* 48 * EdDSA signing. 49 * 50 * signature (out): The signature. 51 * privkey (in): The private key. 52 * pubkey (in): The public key. 53 * message (in): The message to sign. 54 * message_len (in): The length of the message. 55 * prehashed (in): Nonzero if the message is actually the hash of something 56 * you want to sign. 57 * context (in): A "context" for this signature of up to 255 bytes. 58 * context_len (in): Length of the context. 59 * 60 * For Ed25519, it is unsafe to use the same key for both prehashed and 61 * non-prehashed messages, at least without some very careful protocol-level 62 * disambiguation. For Ed448 it is safe. 63 */ 64 c448_error_t 65 ossl_c448_ed448_sign(OSSL_LIB_CTX *ctx, 66 uint8_t signature[EDDSA_448_SIGNATURE_BYTES], 67 const uint8_t privkey[EDDSA_448_PRIVATE_BYTES], 68 const uint8_t pubkey[EDDSA_448_PUBLIC_BYTES], 69 const uint8_t *message, size_t message_len, 70 uint8_t prehashed, const uint8_t *context, 71 size_t context_len, 72 const char *propq); 73 74 /* 75 * EdDSA signing with prehash. 76 * 77 * signature (out): The signature. 78 * privkey (in): The private key. 79 * pubkey (in): The public key. 80 * hash (in): The hash of the message. This object will not be modified by the 81 * call. 82 * context (in): A "context" for this signature of up to 255 bytes. Must be the 83 * same as what was used for the prehash. 84 * context_len (in): Length of the context. 85 * 86 * For Ed25519, it is unsafe to use the same key for both prehashed and 87 * non-prehashed messages, at least without some very careful protocol-level 88 * disambiguation. For Ed448 it is safe. 89 */ 90 c448_error_t 91 ossl_c448_ed448_sign_prehash(OSSL_LIB_CTX *ctx, 92 uint8_t signature[EDDSA_448_SIGNATURE_BYTES], 93 const uint8_t privkey[EDDSA_448_PRIVATE_BYTES], 94 const uint8_t pubkey[EDDSA_448_PUBLIC_BYTES], 95 const uint8_t hash[64], 96 const uint8_t *context, 97 size_t context_len, 98 const char *propq); 99 100 /* 101 * EdDSA signature verification. 102 * 103 * Uses the standard (i.e. less-strict) verification formula. 104 * 105 * signature (in): The signature. 106 * pubkey (in): The public key. 107 * message (in): The message to verify. 108 * message_len (in): The length of the message. 109 * prehashed (in): Nonzero if the message is actually the hash of something you 110 * want to verify. 111 * context (in): A "context" for this signature of up to 255 bytes. 112 * context_len (in): Length of the context. 113 * 114 * For Ed25519, it is unsafe to use the same key for both prehashed and 115 * non-prehashed messages, at least without some very careful protocol-level 116 * disambiguation. For Ed448 it is safe. 117 */ 118 c448_error_t 119 ossl_c448_ed448_verify(OSSL_LIB_CTX *ctx, 120 const uint8_t 121 signature[EDDSA_448_SIGNATURE_BYTES], 122 const uint8_t 123 pubkey[EDDSA_448_PUBLIC_BYTES], 124 const uint8_t *message, size_t message_len, 125 uint8_t prehashed, const uint8_t *context, 126 uint8_t context_len, 127 const char *propq); 128 129 /* 130 * EdDSA signature verification. 131 * 132 * Uses the standard (i.e. less-strict) verification formula. 133 * 134 * signature (in): The signature. 135 * pubkey (in): The public key. 136 * hash (in): The hash of the message. This object will not be modified by the 137 * call. 138 * context (in): A "context" for this signature of up to 255 bytes. Must be the 139 * same as what was used for the prehash. 140 * context_len (in): Length of the context. 141 * 142 * For Ed25519, it is unsafe to use the same key for both prehashed and 143 * non-prehashed messages, at least without some very careful protocol-level 144 * disambiguation. For Ed448 it is safe. 145 */ 146 c448_error_t 147 ossl_c448_ed448_verify_prehash( 148 OSSL_LIB_CTX *ctx, 149 const uint8_t signature[EDDSA_448_SIGNATURE_BYTES], 150 const uint8_t pubkey[EDDSA_448_PUBLIC_BYTES], 151 const uint8_t hash[64], 152 const uint8_t *context, 153 uint8_t context_len, 154 const char *propq); 155 156 /* 157 * EdDSA point encoding. Used internally, exposed externally. 158 * Multiplies by C448_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 we handle this is to multiply by C448_EDDSA_DECODE_RATIO when 167 * decoding, and by C448_EDDSA_ENCODE_RATIO when encoding. The product of 168 * these ratios is always exactly the cofactor 4, so the cofactor ends up 169 * cleared one way or another. But exactly how that shakes out depends on the 170 * base points specified in RFC 8032. 171 * 172 * The upshot is that if you pass the Decaf/Ristretto base point to 173 * this function, you will get C448_EDDSA_ENCODE_RATIO times the 174 * EdDSA base point. 175 * 176 * enc (out): The encoded point. 177 * p (in): The point. 178 */ 179 void 180 ossl_curve448_point_mul_by_ratio_and_encode_like_eddsa( 181 uint8_t enc [EDDSA_448_PUBLIC_BYTES], 182 const curve448_point_t p); 183 184 /* 185 * EdDSA point decoding. Multiplies by C448_EDDSA_DECODE_RATIO, and 186 * ignores cofactor information. 187 * 188 * See notes on curve448_point_mul_by_ratio_and_encode_like_eddsa 189 * 190 * enc (out): The encoded point. 191 * p (in): The point. 192 */ 193 c448_error_t 194 ossl_curve448_point_decode_like_eddsa_and_mul_by_ratio( 195 curve448_point_t p, 196 const uint8_t enc[EDDSA_448_PUBLIC_BYTES]); 197 198 /* 199 * EdDSA to ECDH private key conversion 200 * Using the appropriate hash function, hash the EdDSA private key 201 * and keep only the lower bytes to get the ECDH private key 202 * 203 * x (out): The ECDH private key as in RFC7748 204 * ed (in): The EdDSA private key 205 */ 206 c448_error_t 207 ossl_c448_ed448_convert_private_key_to_x448( 208 OSSL_LIB_CTX *ctx, 209 uint8_t x[X448_PRIVATE_BYTES], 210 const uint8_t ed[EDDSA_448_PRIVATE_BYTES], 211 const char *propq); 212 213 #endif /* OSSL_CRYPTO_EC_CURVE448_ED448_H */ 214