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