secp256k1_ellswift.h
1 #ifndef SECP256K1_ELLSWIFT_H 2 #define SECP256K1_ELLSWIFT_H 3 4 #include "secp256k1.h" 5 6 #ifdef __cplusplus 7 extern "C" { 8 #endif 9 10 /* This module provides an implementation of ElligatorSwift as well as a 11 * version of x-only ECDH using it (including compatibility with BIP324). 12 * 13 * ElligatorSwift is described in https://eprint.iacr.org/2022/759 by 14 * Chavez-Saab, Rodriguez-Henriquez, and Tibouchi. It permits encoding 15 * uniformly chosen public keys as 64-byte arrays which are indistinguishable 16 * from uniformly random arrays. 17 * 18 * Let f be the function from pairs of field elements to point X coordinates, 19 * defined as follows (all operations modulo p = 2^256 - 2^32 - 977) 20 * f(u,t): 21 * - Let C = 0xa2d2ba93507f1df233770c2a797962cc61f6d15da14ecd47d8d27ae1cd5f852, 22 * a square root of -3. 23 * - If u=0, set u=1 instead. 24 * - If t=0, set t=1 instead. 25 * - If u^3 + t^2 + 7 = 0, multiply t by 2. 26 * - Let X = (u^3 + 7 - t^2) / (2 * t) 27 * - Let Y = (X + t) / (C * u) 28 * - Return the first in [u + 4 * Y^2, (-X/Y - u) / 2, (X/Y - u) / 2] that is an 29 * X coordinate on the curve (at least one of them is, for any u and t). 30 * 31 * Then an ElligatorSwift encoding of x consists of the 32-byte big-endian 32 * encodings of field elements u and t concatenated, where f(u,t) = x. 33 * The encoding algorithm is described in the paper, and effectively picks a 34 * uniformly random pair (u,t) among those which encode x. 35 * 36 * If the Y coordinate is relevant, it is given the same parity as t. 37 * 38 * Changes w.r.t. the paper: 39 * - The u=0, t=0, and u^3+t^2+7=0 conditions result in decoding to the point 40 * at infinity in the paper. Here they are remapped to finite points. 41 * - The paper uses an additional encoding bit for the parity of y. Here the 42 * parity of t is used (negating t does not affect the decoded x coordinate, 43 * so this is possible). 44 * 45 * For mathematical background about the scheme, see the doc/ellswift.md file. 46 */ 47 48 /** A pointer to a function used by secp256k1_ellswift_xdh to hash the shared X 49 * coordinate along with the encoded public keys to a uniform shared secret. 50 * 51 * Returns: 1 if a shared secret was successfully computed. 52 * 0 will cause secp256k1_ellswift_xdh to fail and return 0. 53 * Other return values are not allowed, and the behaviour of 54 * secp256k1_ellswift_xdh is undefined for other return values. 55 * Out: output: pointer to an array to be filled by the function 56 * In: x32: pointer to the 32-byte serialized X coordinate 57 * of the resulting shared point (will not be NULL) 58 * ell_a64: pointer to the 64-byte encoded public key of party A 59 * (will not be NULL) 60 * ell_b64: pointer to the 64-byte encoded public key of party B 61 * (will not be NULL) 62 * data: arbitrary data pointer that is passed through 63 */ 64 typedef int (*secp256k1_ellswift_xdh_hash_function)( 65 unsigned char *output, 66 const unsigned char *x32, 67 const unsigned char *ell_a64, 68 const unsigned char *ell_b64, 69 void *data 70 ); 71 72 /** An implementation of an secp256k1_ellswift_xdh_hash_function which uses 73 * SHA256(prefix64 || ell_a64 || ell_b64 || x32), where prefix64 is the 64-byte 74 * array pointed to by data. */ 75 SECP256K1_API const secp256k1_ellswift_xdh_hash_function secp256k1_ellswift_xdh_hash_function_prefix; 76 77 /** An implementation of an secp256k1_ellswift_xdh_hash_function compatible with 78 * BIP324. It returns H_tag(ell_a64 || ell_b64 || x32), where H_tag is the 79 * BIP340 tagged hash function with tag "bip324_ellswift_xonly_ecdh". Equivalent 80 * to secp256k1_ellswift_xdh_hash_function_prefix with prefix64 set to 81 * SHA256("bip324_ellswift_xonly_ecdh")||SHA256("bip324_ellswift_xonly_ecdh"). 82 * The data argument is ignored. */ 83 SECP256K1_API const secp256k1_ellswift_xdh_hash_function secp256k1_ellswift_xdh_hash_function_bip324; 84 85 /** Construct a 64-byte ElligatorSwift encoding of a given pubkey. 86 * 87 * Returns: 1 always. 88 * Args: ctx: pointer to a context object 89 * Out: ell64: pointer to a 64-byte array to be filled 90 * In: pubkey: pointer to a secp256k1_pubkey containing an 91 * initialized public key 92 * rnd32: pointer to 32 bytes of randomness 93 * 94 * It is recommended that rnd32 consists of 32 uniformly random bytes, not 95 * known to any adversary trying to detect whether public keys are being 96 * encoded, though 16 bytes of randomness (padded to an array of 32 bytes, 97 * e.g., with zeros) suffice to make the result indistinguishable from 98 * uniform. The randomness in rnd32 must not be a deterministic function of 99 * the pubkey (it can be derived from the private key, though). 100 * 101 * It is not guaranteed that the computed encoding is stable across versions 102 * of the library, even if all arguments to this function (including rnd32) 103 * are the same. 104 * 105 * This function runs in variable time. 106 */ 107 SECP256K1_API int secp256k1_ellswift_encode( 108 const secp256k1_context *ctx, 109 unsigned char *ell64, 110 const secp256k1_pubkey *pubkey, 111 const unsigned char *rnd32 112 ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3) SECP256K1_ARG_NONNULL(4); 113 114 /** Decode a 64-bytes ElligatorSwift encoded public key. 115 * 116 * Returns: always 1 117 * Args: ctx: pointer to a context object 118 * Out: pubkey: pointer to a secp256k1_pubkey that will be filled 119 * In: ell64: pointer to a 64-byte array to decode 120 * 121 * This function runs in variable time. 122 */ 123 SECP256K1_API int secp256k1_ellswift_decode( 124 const secp256k1_context *ctx, 125 secp256k1_pubkey *pubkey, 126 const unsigned char *ell64 127 ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3); 128 129 /** Compute an ElligatorSwift public key for a secret key. 130 * 131 * Returns: 1: secret was valid, public key was stored. 132 * 0: secret was invalid, try again. 133 * Args: ctx: pointer to a context object (not secp256k1_context_static) 134 * Out: ell64: pointer to a 64-byte array to receive the ElligatorSwift 135 * public key 136 * In: seckey32: pointer to a 32-byte secret key 137 * auxrnd32: (optional) pointer to 32 bytes of randomness 138 * 139 * Constant time in seckey and auxrnd32, but not in the resulting public key. 140 * 141 * It is recommended that auxrnd32 contains 32 uniformly random bytes, though 142 * it is optional (and does result in encodings that are indistinguishable from 143 * uniform even without any auxrnd32). It differs from the (mandatory) rnd32 144 * argument to secp256k1_ellswift_encode in this regard. 145 * 146 * This function can be used instead of calling secp256k1_ec_pubkey_create 147 * followed by secp256k1_ellswift_encode. It is safer, as it uses the secret 148 * key as entropy for the encoding (supplemented with auxrnd32, if provided). 149 * 150 * Like secp256k1_ellswift_encode, this function does not guarantee that the 151 * computed encoding is stable across versions of the library, even if all 152 * arguments (including auxrnd32) are the same. 153 */ 154 SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ellswift_create( 155 const secp256k1_context *ctx, 156 unsigned char *ell64, 157 const unsigned char *seckey32, 158 const unsigned char *auxrnd32 159 ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3); 160 161 /** Given a private key, and ElligatorSwift public keys sent in both directions, 162 * compute a shared secret using x-only Elliptic Curve Diffie-Hellman (ECDH). 163 * 164 * Returns: 1: shared secret was successfully computed 165 * 0: secret was invalid or hashfp returned 0 166 * Args: ctx: pointer to a context object. 167 * Out: output: pointer to an array to be filled by hashfp. 168 * In: ell_a64: pointer to the 64-byte encoded public key of party A 169 * (will not be NULL) 170 * ell_b64: pointer to the 64-byte encoded public key of party B 171 * (will not be NULL) 172 * seckey32: pointer to our 32-byte secret key 173 * party: boolean indicating which party we are: zero if we are 174 * party A, non-zero if we are party B. seckey32 must be 175 * the private key corresponding to that party's ell_?64. 176 * This correspondence is not checked. 177 * hashfp: pointer to a hash function. 178 * data: arbitrary data pointer passed through to hashfp. 179 * 180 * Constant time in seckey32. 181 * 182 * This function is more efficient than decoding the public keys, and performing 183 * ECDH on them. 184 */ 185 SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ellswift_xdh( 186 const secp256k1_context *ctx, 187 unsigned char *output, 188 const unsigned char *ell_a64, 189 const unsigned char *ell_b64, 190 const unsigned char *seckey32, 191 int party, 192 secp256k1_ellswift_xdh_hash_function hashfp, 193 void *data 194 ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3) SECP256K1_ARG_NONNULL(4) SECP256K1_ARG_NONNULL(5) SECP256K1_ARG_NONNULL(7); 195 196 #ifdef __cplusplus 197 } 198 #endif 199 200 #endif /* SECP256K1_ELLSWIFT_H */