1 /* 2 * Copyright 2017-2018 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 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 c448_ed448_derive_public_key( 41 uint8_t pubkey [EDDSA_448_PUBLIC_BYTES], 42 const uint8_t privkey [EDDSA_448_PRIVATE_BYTES]); 43 44 /* 45 * EdDSA signing. 46 * 47 * signature (out): The signature. 48 * privkey (in): The private key. 49 * pubkey (in): The public key. 50 * message (in): The message to sign. 51 * message_len (in): The length of the message. 52 * prehashed (in): Nonzero if the message is actually the hash of something 53 * you want to sign. 54 * context (in): A "context" for this signature of up to 255 bytes. 55 * context_len (in): Length of the context. 56 * 57 * For Ed25519, it is unsafe to use the same key for both prehashed and 58 * non-prehashed messages, at least without some very careful protocol-level 59 * disambiguation. For Ed448 it is safe. 60 */ 61 c448_error_t c448_ed448_sign( 62 uint8_t signature[EDDSA_448_SIGNATURE_BYTES], 63 const uint8_t privkey[EDDSA_448_PRIVATE_BYTES], 64 const uint8_t pubkey[EDDSA_448_PUBLIC_BYTES], 65 const uint8_t *message, size_t message_len, 66 uint8_t prehashed, const uint8_t *context, 67 size_t context_len); 68 69 /* 70 * EdDSA signing with prehash. 71 * 72 * signature (out): The signature. 73 * privkey (in): The private key. 74 * pubkey (in): The public key. 75 * hash (in): The hash of the message. This object will not be modified by the 76 * call. 77 * context (in): A "context" for this signature of up to 255 bytes. Must be the 78 * same as what was used for the prehash. 79 * context_len (in): Length of the context. 80 * 81 * For Ed25519, it is unsafe to use the same key for both prehashed and 82 * non-prehashed messages, at least without some very careful protocol-level 83 * disambiguation. For Ed448 it is safe. 84 */ 85 c448_error_t c448_ed448_sign_prehash( 86 uint8_t signature[EDDSA_448_SIGNATURE_BYTES], 87 const uint8_t privkey[EDDSA_448_PRIVATE_BYTES], 88 const uint8_t pubkey[EDDSA_448_PUBLIC_BYTES], 89 const uint8_t hash[64], 90 const uint8_t *context, 91 size_t context_len); 92 93 /* 94 * EdDSA signature verification. 95 * 96 * Uses the standard (i.e. less-strict) verification formula. 97 * 98 * signature (in): The signature. 99 * pubkey (in): The public key. 100 * message (in): The message to verify. 101 * message_len (in): The length of the message. 102 * prehashed (in): Nonzero if the message is actually the hash of something you 103 * want to verify. 104 * context (in): A "context" for this signature of up to 255 bytes. 105 * context_len (in): Length of the context. 106 * 107 * For Ed25519, it is unsafe to use the same key for both prehashed and 108 * non-prehashed messages, at least without some very careful protocol-level 109 * disambiguation. For Ed448 it is safe. 110 */ 111 c448_error_t c448_ed448_verify(const uint8_t 112 signature[EDDSA_448_SIGNATURE_BYTES], 113 const uint8_t 114 pubkey[EDDSA_448_PUBLIC_BYTES], 115 const uint8_t *message, size_t message_len, 116 uint8_t prehashed, const uint8_t *context, 117 uint8_t context_len); 118 119 /* 120 * EdDSA signature verification. 121 * 122 * Uses the standard (i.e. less-strict) verification formula. 123 * 124 * signature (in): The signature. 125 * pubkey (in): The public key. 126 * hash (in): The hash of the message. This object will not be modified by the 127 * call. 128 * context (in): A "context" for this signature of up to 255 bytes. Must be the 129 * same as what was used for the prehash. 130 * context_len (in): Length of the context. 131 * 132 * For Ed25519, it is unsafe to use the same key for both prehashed and 133 * non-prehashed messages, at least without some very careful protocol-level 134 * disambiguation. For Ed448 it is safe. 135 */ 136 c448_error_t c448_ed448_verify_prehash( 137 const uint8_t signature[EDDSA_448_SIGNATURE_BYTES], 138 const uint8_t pubkey[EDDSA_448_PUBLIC_BYTES], 139 const uint8_t hash[64], 140 const uint8_t *context, 141 uint8_t context_len); 142 143 /* 144 * EdDSA point encoding. Used internally, exposed externally. 145 * Multiplies by C448_EDDSA_ENCODE_RATIO first. 146 * 147 * The multiplication is required because the EdDSA encoding represents 148 * the cofactor information, but the Decaf encoding ignores it (which 149 * is the whole point). So if you decode from EdDSA and re-encode to 150 * EdDSA, the cofactor info must get cleared, because the intermediate 151 * representation doesn't track it. 152 * 153 * The way we handle this is to multiply by C448_EDDSA_DECODE_RATIO when 154 * decoding, and by C448_EDDSA_ENCODE_RATIO when encoding. The product of 155 * these ratios is always exactly the cofactor 4, so the cofactor ends up 156 * cleared one way or another. But exactly how that shakes out depends on the 157 * base points specified in RFC 8032. 158 * 159 * The upshot is that if you pass the Decaf/Ristretto base point to 160 * this function, you will get C448_EDDSA_ENCODE_RATIO times the 161 * EdDSA base point. 162 * 163 * enc (out): The encoded point. 164 * p (in): The point. 165 */ 166 void curve448_point_mul_by_ratio_and_encode_like_eddsa( 167 uint8_t enc [EDDSA_448_PUBLIC_BYTES], 168 const curve448_point_t p); 169 170 /* 171 * EdDSA point decoding. Multiplies by C448_EDDSA_DECODE_RATIO, and 172 * ignores cofactor information. 173 * 174 * See notes on curve448_point_mul_by_ratio_and_encode_like_eddsa 175 * 176 * enc (out): The encoded point. 177 * p (in): The point. 178 */ 179 c448_error_t curve448_point_decode_like_eddsa_and_mul_by_ratio( 180 curve448_point_t p, 181 const uint8_t enc[EDDSA_448_PUBLIC_BYTES]); 182 183 /* 184 * EdDSA to ECDH private key conversion 185 * Using the appropriate hash function, hash the EdDSA private key 186 * and keep only the lower bytes to get the ECDH private key 187 * 188 * x (out): The ECDH private key as in RFC7748 189 * ed (in): The EdDSA private key 190 */ 191 c448_error_t c448_ed448_convert_private_key_to_x448( 192 uint8_t x[X448_PRIVATE_BYTES], 193 const uint8_t ed[EDDSA_448_PRIVATE_BYTES]); 194 195 #endif /* OSSL_CRYPTO_EC_CURVE448_ED448_H */ 196