crypto/ec/curve448/GENERATED/include/decaf/point_255.h

   1 /**
   2  * @file decaf/point_255.h
   3  * @author Mike Hamburg
   4  *
   5  * @copyright
   6  *   Copyright (c) 2015-2016 Cryptography Research, Inc.  \n
   7  *   Released under the MIT License.  See LICENSE.txt for license information.
   8  *
   9  * @brief A group of prime order p, based on Curve25519.
  10  *
  11  * @warning This file was automatically generated in Python.
  12  * Please do not edit it.
  13  */
  14
  15 #ifndef __DECAF_POINT_255_H__
  16 #define __DECAF_POINT_255_H__ 1
  17
  18 #include <decaf/common.h>
  19
  20 #ifdef __cplusplus
  21 extern "C" {
  22 #endif
  23
  24 /** @cond internal */
  25 #define DECAF_255_SCALAR_LIMBS ((253-1)/DECAF_WORD_BITS+1)
  26 /** @endcond */
  27
  28 /** The number of bits in a scalar */
  29 #define DECAF_255_SCALAR_BITS 253
  30
  31 /** @cond internal */
  32 #ifndef __DECAF_25519_GF_DEFINED__
  33 #define __DECAF_25519_GF_DEFINED__ 1
  34 /** @brief Galois field element internal structure */
  35 typedef struct gf_25519_s {
  36     decaf_word_t limb[320/DECAF_WORD_BITS];
  37 } __attribute__((aligned(32))) gf_25519_s, gf_25519_t[1];
  38 #endif /* __DECAF_25519_GF_DEFINED__ */
  39 /** @endcond */
  40
  41 /** Number of bytes in a serialized point. */
  42 #define DECAF_255_SER_BYTES 32
  43
  44 /** Number of bytes in an elligated point.  For now set the same as SER_BYTES
  45  * but could be different for other curves.
  46  */
  47 #define DECAF_255_HASH_BYTES 32
  48
  49 /** Number of bytes in a serialized scalar. */
  50 #define DECAF_255_SCALAR_BYTES 32
  51
  52 /** Number of bits in the "which" field of an elligator inverse */
  53 #define DECAF_255_INVERT_ELLIGATOR_WHICH_BITS 5
  54
  55 /** The cofactor the curve would have, if we hadn't removed it */
  56 #define DECAF_255_REMOVED_COFACTOR 8
  57
  58 /** X25519 encoding ratio. */
  59 #define DECAF_X25519_ENCODE_RATIO 4
  60
  61 /** Number of bytes in an x25519 public key */
  62 #define DECAF_X25519_PUBLIC_BYTES 32
  63
  64 /** Number of bytes in an x25519 private key */
  65 #define DECAF_X25519_PRIVATE_BYTES 32
  66
  67 /** Twisted Edwards extended homogeneous coordinates */
  68 typedef struct decaf_255_point_s {
  69     /** @cond internal */
  70     gf_25519_t x,y,z,t;
  71     /** @endcond */
  72 } decaf_255_point_t[1];
  73
  74 /** Precomputed table based on a point.  Can be trivial implementation. */
  75 struct decaf_255_precomputed_s;
  76
  77 /** Precomputed table based on a point.  Can be trivial implementation. */
  78 typedef struct decaf_255_precomputed_s decaf_255_precomputed_s;
  79
  80 /** Size and alignment of precomputed point tables. */
  81 extern const size_t decaf_255_sizeof_precomputed_s DECAF_API_VIS, decaf_255_alignof_precomputed_s DECAF_API_VIS;
  82
  83 /** Scalar is stored packed, because we don't need the speed. */
  84 typedef struct decaf_255_scalar_s {
  85     /** @cond internal */
  86     decaf_word_t limb[DECAF_255_SCALAR_LIMBS];
  87     /** @endcond */
  88 } decaf_255_scalar_t[1];
  89
  90 /** A scalar equal to 1. */
  91 extern const decaf_255_scalar_t decaf_255_scalar_one DECAF_API_VIS;
  92
  93 /** A scalar equal to 0. */
  94 extern const decaf_255_scalar_t decaf_255_scalar_zero DECAF_API_VIS;
  95
  96 /** The identity point on the curve. */
  97 extern const decaf_255_point_t decaf_255_point_identity DECAF_API_VIS;
  98
  99 /** An arbitrarily chosen base point on the curve. */
 100 extern const decaf_255_point_t decaf_255_point_base DECAF_API_VIS;
 101
 102 /** Precomputed table for the base point on the curve. */
 103 extern const struct decaf_255_precomputed_s *decaf_255_precomputed_base DECAF_API_VIS;
 104
 105 /**
 106  * @brief Read a scalar from wire format or from bytes.
 107  *
 108  * @param [in] ser Serialized form of a scalar.
 109  * @param [out] out Deserialized form.
 110  *
 111  * @retval DECAF_SUCCESS The scalar was correctly encoded.
 112  * @retval DECAF_FAILURE The scalar was greater than the modulus,
 113  * and has been reduced modulo that modulus.
 114  */
 115 decaf_error_t decaf_255_scalar_decode (
 116     decaf_255_scalar_t out,
 117     const unsigned char ser[DECAF_255_SCALAR_BYTES]
 118 ) DECAF_API_VIS DECAF_WARN_UNUSED DECAF_NONNULL DECAF_NOINLINE;
 119
 120 /**
 121  * @brief Read a scalar from wire format or from bytes.  Reduces mod
 122  * scalar prime.
 123  *
 124  * @param [in] ser Serialized form of a scalar.
 125  * @param [in] ser_len Length of serialized form.
 126  * @param [out] out Deserialized form.
 127  */
 128 void decaf_255_scalar_decode_long (
 129     decaf_255_scalar_t out,
 130     const unsigned char *ser,
 131     size_t ser_len
 132 ) DECAF_API_VIS DECAF_NONNULL DECAF_NOINLINE;
 133
 134 /**
 135  * @brief Serialize a scalar to wire format.
 136  *
 137  * @param [out] ser Serialized form of a scalar.
 138  * @param [in] s Deserialized scalar.
 139  */
 140 void decaf_255_scalar_encode (
 141     unsigned char ser[DECAF_255_SCALAR_BYTES],
 142     const decaf_255_scalar_t s
 143 ) DECAF_API_VIS DECAF_NONNULL DECAF_NOINLINE DECAF_NOINLINE;
 144
 145 /**
 146  * @brief Add two scalars.  The scalars may use the same memory.
 147  * @param [in] a One scalar.
 148  * @param [in] b Another scalar.
 149  * @param [out] out a+b.
 150  */
 151 void decaf_255_scalar_add (
 152     decaf_255_scalar_t out,
 153     const decaf_255_scalar_t a,
 154     const decaf_255_scalar_t b
 155 ) DECAF_API_VIS DECAF_NONNULL DECAF_NOINLINE;
 156
 157 /**
 158  * @brief Compare two scalars.
 159  * @param [in] a One scalar.
 160  * @param [in] b Another scalar.
 161  * @retval DECAF_TRUE The scalars are equal.
 162  * @retval DECAF_FALSE The scalars are not equal.
 163  */
 164 decaf_bool_t decaf_255_scalar_eq (
 165     const decaf_255_scalar_t a,
 166     const decaf_255_scalar_t b
 167 ) DECAF_API_VIS DECAF_WARN_UNUSED DECAF_NONNULL DECAF_NOINLINE;
 168
 169 /**
 170  * @brief Subtract two scalars.  The scalars may use the same memory.
 171  * @param [in] a One scalar.
 172  * @param [in] b Another scalar.
 173  * @param [out] out a-b.
 174  */
 175 void decaf_255_scalar_sub (
 176     decaf_255_scalar_t out,
 177     const decaf_255_scalar_t a,
 178     const decaf_255_scalar_t b
 179 ) DECAF_API_VIS DECAF_NONNULL DECAF_NOINLINE;
 180
 181 /**
 182  * @brief Multiply two scalars.  The scalars may use the same memory.
 183  * @param [in] a One scalar.
 184  * @param [in] b Another scalar.
 185  * @param [out] out a*b.
 186  */
 187 void decaf_255_scalar_mul (
 188     decaf_255_scalar_t out,
 189     const decaf_255_scalar_t a,
 190     const decaf_255_scalar_t b
 191 ) DECAF_API_VIS DECAF_NONNULL DECAF_NOINLINE;
 192
 193 /**
 194 * @brief Halve a scalar.  The scalars may use the same memory.
 195 * @param [in] a A scalar.
 196 * @param [out] out a/2.
 197 */
 198 void decaf_255_scalar_halve (
 199    decaf_255_scalar_t out,
 200    const decaf_255_scalar_t a
 201 ) DECAF_API_VIS DECAF_NONNULL DECAF_NOINLINE;
 202
 203 /**
 204  * @brief Invert a scalar.  When passed zero, return 0.  The input and output may alias.
 205  * @param [in] a A scalar.
 206  * @param [out] out 1/a.
 207  * @return DECAF_SUCCESS The input is nonzero.
 208  */
 209 decaf_error_t decaf_255_scalar_invert (
 210     decaf_255_scalar_t out,
 211     const decaf_255_scalar_t a
 212 ) DECAF_API_VIS DECAF_WARN_UNUSED DECAF_NONNULL DECAF_NOINLINE;
 213
 214 /**
 215  * @brief Copy a scalar.  The scalars may use the same memory, in which
 216  * case this function does nothing.
 217  * @param [in] a A scalar.
 218  * @param [out] out Will become a copy of a.
 219  */
 220 static inline void DECAF_NONNULL decaf_255_scalar_copy (
 221     decaf_255_scalar_t out,
 222     const decaf_255_scalar_t a
 223 ) {
 224     *out = *a;
 225 }
 226
 227 /**
 228  * @brief Set a scalar to an unsigned 64-bit integer.
 229  * @param [in] a An integer.
 230  * @param [out] out Will become equal to a.
 231  */
 232 void decaf_255_scalar_set_unsigned (
 233     decaf_255_scalar_t out,
 234     uint64_t a
 235 ) DECAF_API_VIS DECAF_NONNULL;
 236
 237 /**
 238  * @brief Encode a point as a sequence of bytes.
 239  *
 240  * @param [out] ser The byte representation of the point.
 241  * @param [in] pt The point to encode.
 242  */
 243 void decaf_255_point_encode (
 244     uint8_t ser[DECAF_255_SER_BYTES],
 245     const decaf_255_point_t pt
 246 ) DECAF_API_VIS DECAF_NONNULL DECAF_NOINLINE;
 247
 248 /**
 249  * @brief Decode a point from a sequence of bytes.
 250  *
 251  * Every point has a unique encoding, so not every
 252  * sequence of bytes is a valid encoding.  If an invalid
 253  * encoding is given, the output is undefined.
 254  *
 255  * @param [out] pt The decoded point.
 256  * @param [in] ser The serialized version of the point.
 257  * @param [in] allow_identity DECAF_TRUE if the identity is a legal input.
 258  * @retval DECAF_SUCCESS The decoding succeeded.
 259  * @retval DECAF_FAILURE The decoding didn't succeed, because
 260  * ser does not represent a point.
 261  */
 262 decaf_error_t decaf_255_point_decode (
 263     decaf_255_point_t pt,
 264     const uint8_t ser[DECAF_255_SER_BYTES],
 265     decaf_bool_t allow_identity
 266 ) DECAF_API_VIS DECAF_WARN_UNUSED DECAF_NONNULL DECAF_NOINLINE;
 267
 268 /**
 269  * @brief Copy a point.  The input and output may alias,
 270  * in which case this function does nothing.
 271  *
 272  * @param [out] a A copy of the point.
 273  * @param [in] b Any point.
 274  */
 275 static inline void DECAF_NONNULL decaf_255_point_copy (
 276     decaf_255_point_t a,
 277     const decaf_255_point_t b
 278 ) {
 279     *a=*b;
 280 }
 281
 282 /**
 283  * @brief Test whether two points are equal.  If yes, return
 284  * DECAF_TRUE, else return DECAF_FALSE.
 285  *
 286  * @param [in] a A point.
 287  * @param [in] b Another point.
 288  * @retval DECAF_TRUE The points are equal.
 289  * @retval DECAF_FALSE The points are not equal.
 290  */
 291 decaf_bool_t decaf_255_point_eq (
 292     const decaf_255_point_t a,
 293     const decaf_255_point_t b
 294 ) DECAF_API_VIS DECAF_WARN_UNUSED DECAF_NONNULL DECAF_NOINLINE;
 295
 296 /**
 297  * @brief Add two points to produce a third point.  The
 298  * input points and output point can be pointers to the same
 299  * memory.
 300  *
 301  * @param [out] sum The sum a+b.
 302  * @param [in] a An addend.
 303  * @param [in] b An addend.
 304  */
 305 void decaf_255_point_add (
 306     decaf_255_point_t sum,
 307     const decaf_255_point_t a,
 308     const decaf_255_point_t b
 309 ) DECAF_API_VIS DECAF_NONNULL;
 310
 311 /**
 312  * @brief Double a point.  Equivalent to
 313  * decaf_255_point_add(two_a,a,a), but potentially faster.
 314  *
 315  * @param [out] two_a The sum a+a.
 316  * @param [in] a A point.
 317  */
 318 void decaf_255_point_double (
 319     decaf_255_point_t two_a,
 320     const decaf_255_point_t a
 321 ) DECAF_API_VIS DECAF_NONNULL;
 322
 323 /**
 324  * @brief Subtract two points to produce a third point.  The
 325  * input points and output point can be pointers to the same
 326  * memory.
 327  *
 328  * @param [out] diff The difference a-b.
 329  * @param [in] a The minuend.
 330  * @param [in] b The subtrahend.
 331  */
 332 void decaf_255_point_sub (
 333     decaf_255_point_t diff,
 334     const decaf_255_point_t a,
 335     const decaf_255_point_t b
 336 ) DECAF_API_VIS DECAF_NONNULL;
 337
 338 /**
 339  * @brief Negate a point to produce another point.  The input
 340  * and output points can use the same memory.
 341  *
 342  * @param [out] nega The negated input point
 343  * @param [in] a The input point.
 344  */
 345 void decaf_255_point_negate (
 346    decaf_255_point_t nega,
 347    const decaf_255_point_t a
 348 ) DECAF_API_VIS DECAF_NONNULL;
 349
 350 /**
 351  * @brief Multiply a base point by a scalar: scaled = scalar*base.
 352  *
 353  * @param [out] scaled The scaled point base*scalar
 354  * @param [in] base The point to be scaled.
 355  * @param [in] scalar The scalar to multiply by.
 356  */
 357 void decaf_255_point_scalarmul (
 358     decaf_255_point_t scaled,
 359     const decaf_255_point_t base,
 360     const decaf_255_scalar_t scalar
 361 ) DECAF_API_VIS DECAF_NONNULL DECAF_NOINLINE;
 362
 363 /**
 364  * @brief Multiply a base point by a scalar: scaled = scalar*base.
 365  * This function operates directly on serialized forms.
 366  *
 367  * @warning This function is experimental.  It may not be supported
 368  * long-term.
 369  *
 370  * @param [out] scaled The scaled point base*scalar
 371  * @param [in] base The point to be scaled.
 372  * @param [in] scalar The scalar to multiply by.
 373  * @param [in] allow_identity Allow the input to be the identity.
 374  * @param [in] short_circuit Allow a fast return if the input is illegal.
 375  *
 376  * @retval DECAF_SUCCESS The scalarmul succeeded.
 377  * @retval DECAF_FAILURE The scalarmul didn't succeed, because
 378  * base does not represent a point.
 379  */
 380 decaf_error_t decaf_255_direct_scalarmul (
 381     uint8_t scaled[DECAF_255_SER_BYTES],
 382     const uint8_t base[DECAF_255_SER_BYTES],
 383     const decaf_255_scalar_t scalar,
 384     decaf_bool_t allow_identity,
 385     decaf_bool_t short_circuit
 386 ) DECAF_API_VIS DECAF_NONNULL DECAF_WARN_UNUSED DECAF_NOINLINE;
 387
 388 /**
 389  * @brief RFC 7748 Diffie-Hellman scalarmul.  This function uses a different
 390  * (non-Decaf) encoding.
 391  *
 392  * @param [out] scaled The scaled point base*scalar
 393  * @param [in] base The point to be scaled.
 394  * @param [in] scalar The scalar to multiply by.
 395  *
 396  * @retval DECAF_SUCCESS The scalarmul succeeded.
 397  * @retval DECAF_FAILURE The scalarmul didn't succeed, because the base
 398  * point is in a small subgroup.
 399  */
 400 decaf_error_t decaf_x25519 (
 401     uint8_t out[DECAF_X25519_PUBLIC_BYTES],
 402     const uint8_t base[DECAF_X25519_PUBLIC_BYTES],
 403     const uint8_t scalar[DECAF_X25519_PRIVATE_BYTES]
 404 ) DECAF_API_VIS DECAF_NONNULL DECAF_WARN_UNUSED DECAF_NOINLINE;
 405
 406 /**
 407  * @brief Multiply a point by DECAF_X25519_ENCODE_RATIO,
 408  * then encode it like RFC 7748.
 409  *
 410  * This function is mainly used internally, but is exported in case
 411  * it will be useful.
 412  *
 413  * The ratio is necessary because the internal representation doesn't
 414  * track the cofactor information, so on output we must clear the cofactor.
 415  * This would multiply by the cofactor, but in fact internally libdecaf's
 416  * points are always even, so it multiplies by half the cofactor instead.
 417  *
 418  * As it happens, this aligns with the base point definitions; that is,
 419  * if you pass the Decaf/Ristretto base point to this function, the result
 420  * will be DECAF_X25519_ENCODE_RATIO times the X25519
 421  * base point.
 422  *
 423  * @param [out] out The scaled and encoded point.
 424  * @param [in] p The point to be scaled and encoded.
 425  */
 426 void decaf_255_point_mul_by_ratio_and_encode_like_x25519 (
 427     uint8_t out[DECAF_X25519_PUBLIC_BYTES],
 428     const decaf_255_point_t p
 429 ) DECAF_API_VIS DECAF_NONNULL;
 430
 431 /** The base point for X25519 Diffie-Hellman */
 432 extern const uint8_t decaf_x25519_base_point[DECAF_X25519_PUBLIC_BYTES] DECAF_API_VIS;
 433
 434 /**
 435  * @brief RFC 7748 Diffie-Hellman base point scalarmul.  This function uses
 436  * a different (non-Decaf) encoding.
 437  *
 438  * @deprecated Renamed to decaf_x25519_derive_public_key.
 439  * I have no particular timeline for removing this name.
 440  *
 441  * @param [out] scaled The scaled point base*scalar
 442  * @param [in] scalar The scalar to multiply by.
 443  */
 444 void decaf_x25519_generate_key (
 445     uint8_t out[DECAF_X25519_PUBLIC_BYTES],
 446     const uint8_t scalar[DECAF_X25519_PRIVATE_BYTES]
 447 ) DECAF_API_VIS DECAF_NONNULL DECAF_NOINLINE DECAF_DEPRECATED("Renamed to decaf_x25519_derive_public_key");
 448
 449 /**
 450  * @brief RFC 7748 Diffie-Hellman base point scalarmul.  This function uses
 451  * a different (non-Decaf) encoding.
 452  *
 453  * Does exactly the same thing as decaf_x25519_generate_key,
 454  * but has a better name.
 455  *
 456  * @param [out] scaled The scaled point base*scalar
 457  * @param [in] scalar The scalar to multiply by.
 458  */
 459 void decaf_x25519_derive_public_key (
 460     uint8_t out[DECAF_X25519_PUBLIC_BYTES],
 461     const uint8_t scalar[DECAF_X25519_PRIVATE_BYTES]
 462 ) DECAF_API_VIS DECAF_NONNULL DECAF_NOINLINE;
 463
 464 /* FUTURE: uint8_t decaf_255_encode_like_curve25519) */
 465
 466 /**
 467  * @brief Precompute a table for fast scalar multiplication.
 468  * Some implementations do not include precomputed points; for
 469  * those implementations, this implementation simply copies the
 470  * point.
 471  *
 472  * @param [out] a A precomputed table of multiples of the point.
 473  * @param [in] b Any point.
 474  */
 475 void decaf_255_precompute (
 476     decaf_255_precomputed_s *a,
 477     const decaf_255_point_t b
 478 ) DECAF_API_VIS DECAF_NONNULL DECAF_NOINLINE;
 479
 480 /**
 481  * @brief Multiply a precomputed base point by a scalar:
 482  * scaled = scalar*base.
 483  * Some implementations do not include precomputed points; for
 484  * those implementations, this function is the same as
 485  * decaf_255_point_scalarmul
 486  *
 487  * @param [out] scaled The scaled point base*scalar
 488  * @param [in] base The point to be scaled.
 489  * @param [in] scalar The scalar to multiply by.
 490  */
 491 void decaf_255_precomputed_scalarmul (
 492     decaf_255_point_t scaled,
 493     const decaf_255_precomputed_s *base,
 494     const decaf_255_scalar_t scalar
 495 ) DECAF_API_VIS DECAF_NONNULL DECAF_NOINLINE;
 496
 497 /**
 498  * @brief Multiply two base points by two scalars:
 499  * scaled = scalar1*base1 + scalar2*base2.
 500  *
 501  * Equivalent to two calls to decaf_255_point_scalarmul, but may be
 502  * faster.
 503  *
 504  * @param [out] combo The linear combination scalar1*base1 + scalar2*base2.
 505  * @param [in] base1 A first point to be scaled.
 506  * @param [in] scalar1 A first scalar to multiply by.
 507  * @param [in] base2 A second point to be scaled.
 508  * @param [in] scalar2 A second scalar to multiply by.
 509  */
 510 void decaf_255_point_double_scalarmul (
 511     decaf_255_point_t combo,
 512     const decaf_255_point_t base1,
 513     const decaf_255_scalar_t scalar1,
 514     const decaf_255_point_t base2,
 515     const decaf_255_scalar_t scalar2
 516 ) DECAF_API_VIS DECAF_NONNULL DECAF_NOINLINE;
 517
 518 /**
 519  * Multiply one base point by two scalars:
 520  *
 521  * a1 = scalar1 * base
 522  * a2 = scalar2 * base
 523  *
 524  * Equivalent to two calls to decaf_255_point_scalarmul, but may be
 525  * faster.
 526  *
 527  * @param [out] a1 The first multiple.  It may be the same as the input point.
 528  * @param [out] a2 The second multiple.  It may be the same as the input point.
 529  * @param [in] base1 A point to be scaled.
 530  * @param [in] scalar1 A first scalar to multiply by.
 531  * @param [in] scalar2 A second scalar to multiply by.
 532  */
 533 void decaf_255_point_dual_scalarmul (
 534     decaf_255_point_t a1,
 535     decaf_255_point_t a2,
 536     const decaf_255_point_t base1,
 537     const decaf_255_scalar_t scalar1,
 538     const decaf_255_scalar_t scalar2
 539 ) DECAF_API_VIS DECAF_NONNULL DECAF_NOINLINE;
 540
 541 /**
 542  * @brief Multiply two base points by two scalars:
 543  * scaled = scalar1*decaf_255_point_base + scalar2*base2.
 544  *
 545  * Otherwise equivalent to decaf_255_point_double_scalarmul, but may be
 546  * faster at the expense of being variable time.
 547  *
 548  * @param [out] combo The linear combination scalar1*base + scalar2*base2.
 549  * @param [in] scalar1 A first scalar to multiply by.
 550  * @param [in] base2 A second point to be scaled.
 551  * @param [in] scalar2 A second scalar to multiply by.
 552  *
 553  * @warning: This function takes variable time, and may leak the scalars
 554  * used.  It is designed for signature verification.
 555  */
 556 void decaf_255_base_double_scalarmul_non_secret (
 557     decaf_255_point_t combo,
 558     const decaf_255_scalar_t scalar1,
 559     const decaf_255_point_t base2,
 560     const decaf_255_scalar_t scalar2
 561 ) DECAF_API_VIS DECAF_NONNULL DECAF_NOINLINE;
 562
 563 /**
 564  * @brief Constant-time decision between two points.  If pick_b
 565  * is zero, out = a; else out = b.
 566  *
 567  * @param [out] out The output.  It may be the same as either input.
 568  * @param [in] a Any point.
 569  * @param [in] b Any point.
 570  * @param [in] pick_b If nonzero, choose point b.
 571  */
 572 void decaf_255_point_cond_sel (
 573     decaf_255_point_t out,
 574     const decaf_255_point_t a,
 575     const decaf_255_point_t b,
 576     decaf_word_t pick_b
 577 ) DECAF_API_VIS DECAF_NONNULL DECAF_NOINLINE;
 578
 579 /**
 580  * @brief Constant-time decision between two scalars.  If pick_b
 581  * is zero, out = a; else out = b.
 582  *
 583  * @param [out] out The output.  It may be the same as either input.
 584  * @param [in] a Any scalar.
 585  * @param [in] b Any scalar.
 586  * @param [in] pick_b If nonzero, choose scalar b.
 587  */
 588 void decaf_255_scalar_cond_sel (
 589     decaf_255_scalar_t out,
 590     const decaf_255_scalar_t a,
 591     const decaf_255_scalar_t b,
 592     decaf_word_t pick_b
 593 ) DECAF_API_VIS DECAF_NONNULL DECAF_NOINLINE;
 594
 595 /**
 596  * @brief Test that a point is valid, for debugging purposes.
 597  *
 598  * @param [in] to_test The point to test.
 599  * @retval DECAF_TRUE The point is valid.
 600  * @retval DECAF_FALSE The point is invalid.
 601  */
 602 decaf_bool_t decaf_255_point_valid (
 603     const decaf_255_point_t to_test
 604 ) DECAF_API_VIS DECAF_WARN_UNUSED DECAF_NONNULL DECAF_NOINLINE;
 605
 606 /**
 607  * @brief Torque a point, for debugging purposes.  The output
 608  * will be equal to the input.
 609  *
 610  * @param [out] q The point to torque.
 611  * @param [in] p The point to torque.
 612  */
 613 void decaf_255_point_debugging_torque (
 614     decaf_255_point_t q,
 615     const decaf_255_point_t p
 616 ) DECAF_API_VIS DECAF_NONNULL DECAF_NOINLINE;
 617
 618 /**
 619  * @brief Projectively scale a point, for debugging purposes.
 620  * The output will be equal to the input, and will be valid
 621  * even if the factor is zero.
 622  *
 623  * @param [out] q The point to scale.
 624  * @param [in] p The point to scale.
 625  * @param [in] factor Serialized GF factor to scale.
 626  */
 627 void decaf_255_point_debugging_pscale (
 628     decaf_255_point_t q,
 629     const decaf_255_point_t p,
 630     const unsigned char factor[DECAF_255_SER_BYTES]
 631 ) DECAF_API_VIS DECAF_NONNULL DECAF_NOINLINE;
 632
 633 /**
 634  * @brief Almost-Elligator-like hash to curve.
 635  *
 636  * Call this function with the output of a hash to make a hash to the curve.
 637  *
 638  * This function runs Elligator2 on the decaf_255 Jacobi quartic model.  It then
 639  * uses the isogeny to put the result in twisted Edwards form.  As a result,
 640  * it is safe (cannot produce points of order 4), and would be compatible with
 641  * hypothetical other implementations of Decaf using a Montgomery or untwisted
 642  * Edwards model.
 643  *
 644  * Unlike Elligator, this function may be up to 4:1 on [0,(p-1)/2]:
 645  *   A factor of 2 due to the isogeny.
 646  *   A factor of 2 because we quotient out the 2-torsion.
 647  *
 648  * This makes it about 8:1 overall, or 16:1 overall on curves with cofactor 8.
 649  *
 650  * Negating the input (mod q) results in the same point.  Inverting the input
 651  * (mod q) results in the negative point.  This is the same as Elligator.
 652  *
 653  * This function isn't quite indifferentiable from a random oracle.
 654  * However, it is suitable for many protocols, including SPEKE and SPAKE2 EE.
 655  * Furthermore, calling it twice with independent seeds and adding the results
 656  * is indifferentiable from a random oracle.
 657  *
 658  * @param [in] hashed_data Output of some hash function.
 659  * @param [out] pt The data hashed to the curve.
 660  */
 661 void
 662 decaf_255_point_from_hash_nonuniform (
 663     decaf_255_point_t pt,
 664     const unsigned char hashed_data[DECAF_255_HASH_BYTES]
 665 ) DECAF_API_VIS DECAF_NONNULL DECAF_NOINLINE;
 666
 667 /**
 668  * @brief Indifferentiable hash function encoding to curve.
 669  *
 670  * Equivalent to calling decaf_255_point_from_hash_nonuniform twice and adding.
 671  *
 672  * @param [in] hashed_data Output of some hash function.
 673  * @param [out] pt The data hashed to the curve.
 674  */
 675 void decaf_255_point_from_hash_uniform (
 676     decaf_255_point_t pt,
 677     const unsigned char hashed_data[2*DECAF_255_HASH_BYTES]
 678 ) DECAF_API_VIS DECAF_NONNULL DECAF_NOINLINE;
 679
 680 /**
 681  * @brief Inverse of elligator-like hash to curve.
 682  *
 683  * This function writes to the buffer, to make it so that
 684  * decaf_255_point_from_hash_nonuniform(buffer) = pt if
 685  * possible.  Since there may be multiple preimages, the
 686  * "which" parameter chooses between them.  To ensure uniform
 687  * inverse sampling, this function succeeds or fails
 688  * independently for different "which" values.
 689  *
 690  * This function isn't guaranteed to find every possible
 691  * preimage, but it finds all except a small finite number.
 692  * In particular, when the number of bits in the modulus isn't
 693  * a multiple of 8 (i.e. for curve25519), it sets the high bits
 694  * independently, which enables the generated data to be uniform.
 695  * But it doesn't add p, so you'll never get exactly p from this
 696  * function.  This might change in the future, especially if
 697  * we ever support eg Brainpool curves, where this could cause
 698  * real nonuniformity.
 699  *
 700  * @param [out] recovered_hash Encoded data.
 701  * @param [in] pt The point to encode.
 702  * @param [in] which A value determining which inverse point
 703  * to return.
 704  *
 705  * @retval DECAF_SUCCESS The inverse succeeded.
 706  * @retval DECAF_FAILURE The inverse failed.
 707  */
 708 decaf_error_t
 709 decaf_255_invert_elligator_nonuniform (
 710     unsigned char recovered_hash[DECAF_255_HASH_BYTES],
 711     const decaf_255_point_t pt,
 712     uint32_t which
 713 ) DECAF_API_VIS DECAF_NONNULL DECAF_NOINLINE DECAF_WARN_UNUSED;
 714
 715 /**
 716  * @brief Inverse of elligator-like hash to curve.
 717  *
 718  * This function writes to the buffer, to make it so that
 719  * decaf_255_point_from_hash_uniform(buffer) = pt if
 720  * possible.  Since there may be multiple preimages, the
 721  * "which" parameter chooses between them.  To ensure uniform
 722  * inverse sampling, this function succeeds or fails
 723  * independently for different "which" values.
 724  *
 725  * @param [out] recovered_hash Encoded data.
 726  * @param [in] pt The point to encode.
 727  * @param [in] which A value determining which inverse point
 728  * to return.
 729  *
 730  * @retval DECAF_SUCCESS The inverse succeeded.
 731  * @retval DECAF_FAILURE The inverse failed.
 732  */
 733 decaf_error_t
 734 decaf_255_invert_elligator_uniform (
 735     unsigned char recovered_hash[2*DECAF_255_HASH_BYTES],
 736     const decaf_255_point_t pt,
 737     uint32_t which
 738 ) DECAF_API_VIS DECAF_NONNULL DECAF_NOINLINE DECAF_WARN_UNUSED;
 739
 740 /**
 741  * @brief Overwrite scalar with zeros.
 742  */
 743 void decaf_255_scalar_destroy (
 744     decaf_255_scalar_t scalar
 745 ) DECAF_NONNULL DECAF_API_VIS;
 746
 747 /**
 748  * @brief Overwrite point with zeros.
 749  */
 750 void decaf_255_point_destroy (
 751     decaf_255_point_t point
 752 ) DECAF_NONNULL DECAF_API_VIS;
 753
 754 /**
 755  * @brief Overwrite precomputed table with zeros.
 756  */
 757 void decaf_255_precomputed_destroy (
 758     decaf_255_precomputed_s *pre
 759 ) DECAF_NONNULL DECAF_API_VIS;
 760
 761 #ifdef __cplusplus
 762 } /* extern "C" */
 763 #endif
 764
 765 #endif /* __DECAF_POINT_255_H__ */