crypto/ec/curve448/point_448.h

   1 /**
   2  * @file decaf/point_448.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 Ed448-Goldilocks.
  10  *
  11  * @warning This file was automatically generated in Python.
  12  * Please do not edit it.
  13  */
  14
  15 #ifndef __DECAF_POINT_448_H__
  16 #define __DECAF_POINT_448_H__ 1
  17
  18 #include "curve448utils.h"
  19
  20 #ifdef __cplusplus
  21 extern "C" {
  22 #endif
  23
  24 /** @cond internal */
  25 #define DECAF_448_SCALAR_LIMBS ((446-1)/DECAF_WORD_BITS+1)
  26 /** @endcond */
  27
  28 /** The number of bits in a scalar */
  29 #define DECAF_448_SCALAR_BITS 446
  30
  31 /** @cond internal */
  32 #ifndef __DECAF_448_GF_DEFINED__
  33 #define __DECAF_448_GF_DEFINED__ 1
  34 /** @brief Galois field element internal structure */
  35 typedef struct gf_448_s {
  36     decaf_word_t limb[512/DECAF_WORD_BITS];
  37 } __attribute__((aligned(32))) gf_448_s, gf_448_t[1];
  38 #endif /* __DECAF_448_GF_DEFINED__ */
  39 /** @endcond */
  40
  41 /** Number of bytes in a serialized point. */
  42 #define DECAF_448_SER_BYTES 56
  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_448_HASH_BYTES 56
  48
  49 /** Number of bytes in a serialized scalar. */
  50 #define DECAF_448_SCALAR_BYTES 56
  51
  52 /** Number of bits in the "which" field of an elligator inverse */
  53 #define DECAF_448_INVERT_ELLIGATOR_WHICH_BITS 3
  54
  55 /** The cofactor the curve would have, if we hadn't removed it */
  56 #define DECAF_448_REMOVED_COFACTOR 4
  57
  58 /** X448 encoding ratio. */
  59 #define DECAF_X448_ENCODE_RATIO 2
  60
  61 /** Number of bytes in an x448 public key */
  62 #define DECAF_X448_PUBLIC_BYTES 56
  63
  64 /** Number of bytes in an x448 private key */
  65 #define DECAF_X448_PRIVATE_BYTES 56
  66
  67 /** Twisted Edwards extended homogeneous coordinates */
  68 typedef struct decaf_448_point_s {
  69     /** @cond internal */
  70     gf_448_t x,y,z,t;
  71     /** @endcond */
  72 } decaf_448_point_t[1];
  73
  74 /** Precomputed table based on a point.  Can be trivial implementation. */
  75 struct decaf_448_precomputed_s;
  76
  77 /** Precomputed table based on a point.  Can be trivial implementation. */
  78 typedef struct decaf_448_precomputed_s decaf_448_precomputed_s;
  79
  80 /** Size and alignment of precomputed point tables. */
  81 extern const size_t decaf_448_sizeof_precomputed_s DECAF_API_VIS, decaf_448_alignof_precomputed_s DECAF_API_VIS;
  82
  83 /** Scalar is stored packed, because we don't need the speed. */
  84 typedef struct decaf_448_scalar_s {
  85     /** @cond internal */
  86     decaf_word_t limb[DECAF_448_SCALAR_LIMBS];
  87     /** @endcond */
  88 } decaf_448_scalar_t[1];
  89
  90 /** A scalar equal to 1. */
  91 extern const decaf_448_scalar_t decaf_448_scalar_one DECAF_API_VIS;
  92
  93 /** A scalar equal to 0. */
  94 extern const decaf_448_scalar_t decaf_448_scalar_zero DECAF_API_VIS;
  95
  96 /** The identity point on the curve. */
  97 extern const decaf_448_point_t decaf_448_point_identity DECAF_API_VIS;
  98
  99 /** An arbitrarily chosen base point on the curve. */
 100 extern const decaf_448_point_t decaf_448_point_base DECAF_API_VIS;
 101
 102 /** Precomputed table for the base point on the curve. */
 103 extern const struct decaf_448_precomputed_s *decaf_448_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_448_scalar_decode (
 116     decaf_448_scalar_t out,
 117     const unsigned char ser[DECAF_448_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_448_scalar_decode_long (
 129     decaf_448_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_448_scalar_encode (
 141     unsigned char ser[DECAF_448_SCALAR_BYTES],
 142     const decaf_448_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_448_scalar_add (
 152     decaf_448_scalar_t out,
 153     const decaf_448_scalar_t a,
 154     const decaf_448_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_448_scalar_eq (
 165     const decaf_448_scalar_t a,
 166     const decaf_448_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_448_scalar_sub (
 176     decaf_448_scalar_t out,
 177     const decaf_448_scalar_t a,
 178     const decaf_448_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_448_scalar_mul (
 188     decaf_448_scalar_t out,
 189     const decaf_448_scalar_t a,
 190     const decaf_448_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_448_scalar_halve (
 199    decaf_448_scalar_t out,
 200    const decaf_448_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_448_scalar_invert (
 210     decaf_448_scalar_t out,
 211     const decaf_448_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_448_scalar_copy (
 221     decaf_448_scalar_t out,
 222     const decaf_448_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_448_scalar_set_unsigned (
 233     decaf_448_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_448_point_encode (
 244     uint8_t ser[DECAF_448_SER_BYTES],
 245     const decaf_448_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_448_point_decode (
 263     decaf_448_point_t pt,
 264     const uint8_t ser[DECAF_448_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_448_point_copy (
 276     decaf_448_point_t a,
 277     const decaf_448_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_448_point_eq (
 292     const decaf_448_point_t a,
 293     const decaf_448_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_448_point_add (
 306     decaf_448_point_t sum,
 307     const decaf_448_point_t a,
 308     const decaf_448_point_t b
 309 ) DECAF_API_VIS DECAF_NONNULL;
 310
 311 /**
 312  * @brief Double a point.  Equivalent to
 313  * decaf_448_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_448_point_double (
 319     decaf_448_point_t two_a,
 320     const decaf_448_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_448_point_sub (
 333     decaf_448_point_t diff,
 334     const decaf_448_point_t a,
 335     const decaf_448_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_448_point_negate (
 346    decaf_448_point_t nega,
 347    const decaf_448_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_448_point_scalarmul (
 358     decaf_448_point_t scaled,
 359     const decaf_448_point_t base,
 360     const decaf_448_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_448_direct_scalarmul (
 381     uint8_t scaled[DECAF_448_SER_BYTES],
 382     const uint8_t base[DECAF_448_SER_BYTES],
 383     const decaf_448_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_x448 (
 401     uint8_t out[DECAF_X448_PUBLIC_BYTES],
 402     const uint8_t base[DECAF_X448_PUBLIC_BYTES],
 403     const uint8_t scalar[DECAF_X448_PRIVATE_BYTES]
 404 ) DECAF_API_VIS DECAF_NONNULL DECAF_WARN_UNUSED DECAF_NOINLINE;
 405
 406 /**
 407  * @brief Multiply a point by DECAF_X448_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_X448_ENCODE_RATIO times the X448
 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_448_point_mul_by_ratio_and_encode_like_x448 (
 427     uint8_t out[DECAF_X448_PUBLIC_BYTES],
 428     const decaf_448_point_t p
 429 ) DECAF_API_VIS DECAF_NONNULL;
 430
 431 /** The base point for X448 Diffie-Hellman */
 432 extern const uint8_t decaf_x448_base_point[DECAF_X448_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  * Does exactly the same thing as decaf_x448_generate_key,
 439  * but has a better name.
 440  *
 441  * @param [out] scaled The scaled point base*scalar
 442  * @param [in] scalar The scalar to multiply by.
 443  */
 444 void decaf_x448_derive_public_key (
 445     uint8_t out[DECAF_X448_PUBLIC_BYTES],
 446     const uint8_t scalar[DECAF_X448_PRIVATE_BYTES]
 447 ) DECAF_API_VIS DECAF_NONNULL DECAF_NOINLINE;
 448
 449 /* FUTURE: uint8_t decaf_448_encode_like_curve448) */
 450
 451 /**
 452  * @brief Precompute a table for fast scalar multiplication.
 453  * Some implementations do not include precomputed points; for
 454  * those implementations, this implementation simply copies the
 455  * point.
 456  *
 457  * @param [out] a A precomputed table of multiples of the point.
 458  * @param [in] b Any point.
 459  */
 460 void decaf_448_precompute (
 461     decaf_448_precomputed_s *a,
 462     const decaf_448_point_t b
 463 ) DECAF_API_VIS DECAF_NONNULL DECAF_NOINLINE;
 464
 465 /**
 466  * @brief Multiply a precomputed base point by a scalar:
 467  * scaled = scalar*base.
 468  * Some implementations do not include precomputed points; for
 469  * those implementations, this function is the same as
 470  * decaf_448_point_scalarmul
 471  *
 472  * @param [out] scaled The scaled point base*scalar
 473  * @param [in] base The point to be scaled.
 474  * @param [in] scalar The scalar to multiply by.
 475  */
 476 void decaf_448_precomputed_scalarmul (
 477     decaf_448_point_t scaled,
 478     const decaf_448_precomputed_s *base,
 479     const decaf_448_scalar_t scalar
 480 ) DECAF_API_VIS DECAF_NONNULL DECAF_NOINLINE;
 481
 482 /**
 483  * @brief Multiply two base points by two scalars:
 484  * scaled = scalar1*base1 + scalar2*base2.
 485  *
 486  * Equivalent to two calls to decaf_448_point_scalarmul, but may be
 487  * faster.
 488  *
 489  * @param [out] combo The linear combination scalar1*base1 + scalar2*base2.
 490  * @param [in] base1 A first point to be scaled.
 491  * @param [in] scalar1 A first scalar to multiply by.
 492  * @param [in] base2 A second point to be scaled.
 493  * @param [in] scalar2 A second scalar to multiply by.
 494  */
 495 void decaf_448_point_double_scalarmul (
 496     decaf_448_point_t combo,
 497     const decaf_448_point_t base1,
 498     const decaf_448_scalar_t scalar1,
 499     const decaf_448_point_t base2,
 500     const decaf_448_scalar_t scalar2
 501 ) DECAF_API_VIS DECAF_NONNULL DECAF_NOINLINE;
 502
 503 /**
 504  * Multiply one base point by two scalars:
 505  *
 506  * a1 = scalar1 * base
 507  * a2 = scalar2 * base
 508  *
 509  * Equivalent to two calls to decaf_448_point_scalarmul, but may be
 510  * faster.
 511  *
 512  * @param [out] a1 The first multiple.  It may be the same as the input point.
 513  * @param [out] a2 The second multiple.  It may be the same as the input point.
 514  * @param [in] base1 A point to be scaled.
 515  * @param [in] scalar1 A first scalar to multiply by.
 516  * @param [in] scalar2 A second scalar to multiply by.
 517  */
 518 void decaf_448_point_dual_scalarmul (
 519     decaf_448_point_t a1,
 520     decaf_448_point_t a2,
 521     const decaf_448_point_t base1,
 522     const decaf_448_scalar_t scalar1,
 523     const decaf_448_scalar_t scalar2
 524 ) DECAF_API_VIS DECAF_NONNULL DECAF_NOINLINE;
 525
 526 /**
 527  * @brief Multiply two base points by two scalars:
 528  * scaled = scalar1*decaf_448_point_base + scalar2*base2.
 529  *
 530  * Otherwise equivalent to decaf_448_point_double_scalarmul, but may be
 531  * faster at the expense of being variable time.
 532  *
 533  * @param [out] combo The linear combination scalar1*base + scalar2*base2.
 534  * @param [in] scalar1 A first scalar to multiply by.
 535  * @param [in] base2 A second point to be scaled.
 536  * @param [in] scalar2 A second scalar to multiply by.
 537  *
 538  * @warning: This function takes variable time, and may leak the scalars
 539  * used.  It is designed for signature verification.
 540  */
 541 void decaf_448_base_double_scalarmul_non_secret (
 542     decaf_448_point_t combo,
 543     const decaf_448_scalar_t scalar1,
 544     const decaf_448_point_t base2,
 545     const decaf_448_scalar_t scalar2
 546 ) DECAF_API_VIS DECAF_NONNULL DECAF_NOINLINE;
 547
 548 /**
 549  * @brief Constant-time decision between two points.  If pick_b
 550  * is zero, out = a; else out = b.
 551  *
 552  * @param [out] out The output.  It may be the same as either input.
 553  * @param [in] a Any point.
 554  * @param [in] b Any point.
 555  * @param [in] pick_b If nonzero, choose point b.
 556  */
 557 void decaf_448_point_cond_sel (
 558     decaf_448_point_t out,
 559     const decaf_448_point_t a,
 560     const decaf_448_point_t b,
 561     decaf_word_t pick_b
 562 ) DECAF_API_VIS DECAF_NONNULL DECAF_NOINLINE;
 563
 564 /**
 565  * @brief Constant-time decision between two scalars.  If pick_b
 566  * is zero, out = a; else out = b.
 567  *
 568  * @param [out] out The output.  It may be the same as either input.
 569  * @param [in] a Any scalar.
 570  * @param [in] b Any scalar.
 571  * @param [in] pick_b If nonzero, choose scalar b.
 572  */
 573 void decaf_448_scalar_cond_sel (
 574     decaf_448_scalar_t out,
 575     const decaf_448_scalar_t a,
 576     const decaf_448_scalar_t b,
 577     decaf_word_t pick_b
 578 ) DECAF_API_VIS DECAF_NONNULL DECAF_NOINLINE;
 579
 580 /**
 581  * @brief Test that a point is valid, for debugging purposes.
 582  *
 583  * @param [in] to_test The point to test.
 584  * @retval DECAF_TRUE The point is valid.
 585  * @retval DECAF_FALSE The point is invalid.
 586  */
 587 decaf_bool_t decaf_448_point_valid (
 588     const decaf_448_point_t to_test
 589 ) DECAF_API_VIS DECAF_WARN_UNUSED DECAF_NONNULL DECAF_NOINLINE;
 590
 591 /**
 592  * @brief Torque a point, for debugging purposes.  The output
 593  * will be equal to the input.
 594  *
 595  * @param [out] q The point to torque.
 596  * @param [in] p The point to torque.
 597  */
 598 void decaf_448_point_debugging_torque (
 599     decaf_448_point_t q,
 600     const decaf_448_point_t p
 601 ) DECAF_API_VIS DECAF_NONNULL DECAF_NOINLINE;
 602
 603 /**
 604  * @brief Projectively scale a point, for debugging purposes.
 605  * The output will be equal to the input, and will be valid
 606  * even if the factor is zero.
 607  *
 608  * @param [out] q The point to scale.
 609  * @param [in] p The point to scale.
 610  * @param [in] factor Serialized GF factor to scale.
 611  */
 612 void decaf_448_point_debugging_pscale (
 613     decaf_448_point_t q,
 614     const decaf_448_point_t p,
 615     const unsigned char factor[DECAF_448_SER_BYTES]
 616 ) DECAF_API_VIS DECAF_NONNULL DECAF_NOINLINE;
 617
 618 /**
 619  * @brief Almost-Elligator-like hash to curve.
 620  *
 621  * Call this function with the output of a hash to make a hash to the curve.
 622  *
 623  * This function runs Elligator2 on the decaf_448 Jacobi quartic model.  It then
 624  * uses the isogeny to put the result in twisted Edwards form.  As a result,
 625  * it is safe (cannot produce points of order 4), and would be compatible with
 626  * hypothetical other implementations of Decaf using a Montgomery or untwisted
 627  * Edwards model.
 628  *
 629  * Unlike Elligator, this function may be up to 4:1 on [0,(p-1)/2]:
 630  *   A factor of 2 due to the isogeny.
 631  *   A factor of 2 because we quotient out the 2-torsion.
 632  *
 633  * This makes it about 8:1 overall, or 16:1 overall on curves with cofactor 8.
 634  *
 635  * Negating the input (mod q) results in the same point.  Inverting the input
 636  * (mod q) results in the negative point.  This is the same as Elligator.
 637  *
 638  * This function isn't quite indifferentiable from a random oracle.
 639  * However, it is suitable for many protocols, including SPEKE and SPAKE2 EE.
 640  * Furthermore, calling it twice with independent seeds and adding the results
 641  * is indifferentiable from a random oracle.
 642  *
 643  * @param [in] hashed_data Output of some hash function.
 644  * @param [out] pt The data hashed to the curve.
 645  */
 646 void
 647 decaf_448_point_from_hash_nonuniform (
 648     decaf_448_point_t pt,
 649     const unsigned char hashed_data[DECAF_448_HASH_BYTES]
 650 ) DECAF_API_VIS DECAF_NONNULL DECAF_NOINLINE;
 651
 652 /**
 653  * @brief Indifferentiable hash function encoding to curve.
 654  *
 655  * Equivalent to calling decaf_448_point_from_hash_nonuniform twice and adding.
 656  *
 657  * @param [in] hashed_data Output of some hash function.
 658  * @param [out] pt The data hashed to the curve.
 659  */
 660 void decaf_448_point_from_hash_uniform (
 661     decaf_448_point_t pt,
 662     const unsigned char hashed_data[2*DECAF_448_HASH_BYTES]
 663 ) DECAF_API_VIS DECAF_NONNULL DECAF_NOINLINE;
 664
 665 /**
 666  * @brief Inverse of elligator-like hash to curve.
 667  *
 668  * This function writes to the buffer, to make it so that
 669  * decaf_448_point_from_hash_nonuniform(buffer) = pt if
 670  * possible.  Since there may be multiple preimages, the
 671  * "which" parameter chooses between them.  To ensure uniform
 672  * inverse sampling, this function succeeds or fails
 673  * independently for different "which" values.
 674  *
 675  * This function isn't guaranteed to find every possible
 676  * preimage, but it finds all except a small finite number.
 677  * In particular, when the number of bits in the modulus isn't
 678  * a multiple of 8 (i.e. for curve25519), it sets the high bits
 679  * independently, which enables the generated data to be uniform.
 680  * But it doesn't add p, so you'll never get exactly p from this
 681  * function.  This might change in the future, especially if
 682  * we ever support eg Brainpool curves, where this could cause
 683  * real nonuniformity.
 684  *
 685  * @param [out] recovered_hash Encoded data.
 686  * @param [in] pt The point to encode.
 687  * @param [in] which A value determining which inverse point
 688  * to return.
 689  *
 690  * @retval DECAF_SUCCESS The inverse succeeded.
 691  * @retval DECAF_FAILURE The inverse failed.
 692  */
 693 decaf_error_t
 694 decaf_448_invert_elligator_nonuniform (
 695     unsigned char recovered_hash[DECAF_448_HASH_BYTES],
 696     const decaf_448_point_t pt,
 697     uint32_t which
 698 ) DECAF_API_VIS DECAF_NONNULL DECAF_NOINLINE DECAF_WARN_UNUSED;
 699
 700 /**
 701  * @brief Inverse of elligator-like hash to curve.
 702  *
 703  * This function writes to the buffer, to make it so that
 704  * decaf_448_point_from_hash_uniform(buffer) = pt if
 705  * possible.  Since there may be multiple preimages, the
 706  * "which" parameter chooses between them.  To ensure uniform
 707  * inverse sampling, this function succeeds or fails
 708  * independently for different "which" values.
 709  *
 710  * @param [out] recovered_hash Encoded data.
 711  * @param [in] pt The point to encode.
 712  * @param [in] which A value determining which inverse point
 713  * to return.
 714  *
 715  * @retval DECAF_SUCCESS The inverse succeeded.
 716  * @retval DECAF_FAILURE The inverse failed.
 717  */
 718 decaf_error_t
 719 decaf_448_invert_elligator_uniform (
 720     unsigned char recovered_hash[2*DECAF_448_HASH_BYTES],
 721     const decaf_448_point_t pt,
 722     uint32_t which
 723 ) DECAF_API_VIS DECAF_NONNULL DECAF_NOINLINE DECAF_WARN_UNUSED;
 724
 725 /**
 726  * @brief Overwrite scalar with zeros.
 727  */
 728 void decaf_448_scalar_destroy (
 729     decaf_448_scalar_t scalar
 730 ) DECAF_NONNULL DECAF_API_VIS;
 731
 732 /**
 733  * @brief Overwrite point with zeros.
 734  */
 735 void decaf_448_point_destroy (
 736     decaf_448_point_t point
 737 ) DECAF_NONNULL DECAF_API_VIS;
 738
 739 /**
 740  * @brief Overwrite precomputed table with zeros.
 741  */
 742 void decaf_448_precomputed_destroy (
 743     decaf_448_precomputed_s *pre
 744 ) DECAF_NONNULL DECAF_API_VIS;
 745
 746 #ifdef __cplusplus
 747 } /* extern "C" */
 748 #endif
 749
 750 #endif /* __DECAF_POINT_448_H__ */