Loading...
Searching...
No Matches
point_448.h File Reference

A group of prime order p, based on Ed448-Goldilocks. More...

Go to the source code of this file.

## Classes

struct | decaf_448_point_s
| Representation of a point on the elliptic curve. More...
struct | decaf_448_scalar_s
| Representation of an element of the scalar field. More...

## Macros

#define | DECAF_448_SCALAR_BITS 446
| The number of bits in a scalar.
#define | DECAF_448_SER_BYTES 56
| Number of bytes in a serialized point.
#define | DECAF_448_HASH_BYTES 56
| Number of bytes in an elligated point.
#define | DECAF_448_SCALAR_BYTES 56
| Number of bytes in a serialized scalar.
#define | DECAF_448_INVERT_ELLIGATOR_WHICH_BITS 3
| Number of bits in the "which" field of an elligator inverse.
#define | DECAF_448_REMOVED_COFACTOR 4
| The cofactor the curve would have, if we hadn't removed it.
#define | DECAF_X448_ENCODE_RATIO 2
| X448 encoding ratio.
#define | DECAF_X448_PUBLIC_BYTES 56
| Number of bytes in an x448 public key.
#define | DECAF_X448_PRIVATE_BYTES 56
| Number of bytes in an x448 private key.

## Typedefs

typedef struct decaf_448_point_s | decaf_448_point_t[1]
| Representation of a point on the elliptic curve.
typedef struct decaf_448_precomputed_s | decaf_448_precomputed_s
| Precomputed table based on a point.
typedef struct decaf_448_scalar_s | decaf_448_scalar_t[1]
| Representation of an element of the scalar field.

## Functions

decaf_error_t DECAF_API_VIS | decaf_448_scalar_decode (decaf_448_scalar_t out, const unsigned char ser[DECAF_448_SCALAR_BYTES]) DECAF_WARN_UNUSED DECAF_NONNULL DECAF_NOINLINE
| Read a scalar from wire format or from bytes.
void DECAF_API_VIS | decaf_448_scalar_decode_long (decaf_448_scalar_t out, const unsigned char *ser, size_t ser_len) DECAF_NONNULL DECAF_NOINLINE
| Read a scalar from wire format or from bytes.
void DECAF_API_VIS | decaf_448_scalar_encode (unsigned char ser[DECAF_448_SCALAR_BYTES], const decaf_448_scalar_t s) DECAF_NONNULL DECAF_NOINLINE DECAF_NOINLINE
| Serialize a scalar to wire format.
void DECAF_API_VIS | decaf_448_scalar_add (decaf_448_scalar_t out, const decaf_448_scalar_t a, const decaf_448_scalar_t b) DECAF_NONNULL DECAF_NOINLINE
| Add two scalars.
decaf_bool_t DECAF_API_VIS | decaf_448_scalar_eq (const decaf_448_scalar_t a, const decaf_448_scalar_t b) DECAF_WARN_UNUSED DECAF_NONNULL DECAF_NOINLINE
| Compare two scalars.
void DECAF_API_VIS | decaf_448_scalar_sub (decaf_448_scalar_t out, const decaf_448_scalar_t a, const decaf_448_scalar_t b) DECAF_NONNULL DECAF_NOINLINE
| Subtract two scalars.
void DECAF_API_VIS | decaf_448_scalar_mul (decaf_448_scalar_t out, const decaf_448_scalar_t a, const decaf_448_scalar_t b) DECAF_NONNULL DECAF_NOINLINE
| Multiply two scalars.
void DECAF_API_VIS | decaf_448_scalar_halve (decaf_448_scalar_t out, const decaf_448_scalar_t a) DECAF_NONNULL DECAF_NOINLINE
| Halve a scalar.
decaf_error_t DECAF_API_VIS | decaf_448_scalar_invert (decaf_448_scalar_t out, const decaf_448_scalar_t a) DECAF_WARN_UNUSED DECAF_NONNULL DECAF_NOINLINE
| Invert a scalar.
void DECAF_API_VIS | decaf_448_scalar_set_unsigned (decaf_448_scalar_t out, uint64_t a) DECAF_NONNULL
| Set a scalar to an unsigned 64-bit integer.
void DECAF_API_VIS | decaf_448_point_encode (uint8_t ser[DECAF_448_SER_BYTES], const decaf_448_point_t pt) DECAF_NONNULL DECAF_NOINLINE
| Encode a point as a sequence of bytes.
decaf_error_t DECAF_API_VIS | decaf_448_point_decode (decaf_448_point_t pt, const uint8_t ser[DECAF_448_SER_BYTES], decaf_bool_t allow_identity) DECAF_WARN_UNUSED DECAF_NONNULL DECAF_NOINLINE
| Decode a point from a sequence of bytes.
decaf_bool_t DECAF_API_VIS | decaf_448_point_eq (const decaf_448_point_t a, const decaf_448_point_t b) DECAF_WARN_UNUSED DECAF_NONNULL DECAF_NOINLINE
| Test whether two points are equal.
void DECAF_API_VIS | decaf_448_point_add (decaf_448_point_t sum, const decaf_448_point_t a, const decaf_448_point_t b) DECAF_NONNULL
| Add two points to produce a third point.
void DECAF_API_VIS | decaf_448_point_double (decaf_448_point_t two_a, const decaf_448_point_t a) DECAF_NONNULL
| Double a point.
void DECAF_API_VIS | decaf_448_point_sub (decaf_448_point_t diff, const decaf_448_point_t a, const decaf_448_point_t b) DECAF_NONNULL
| Subtract two points to produce a third point.
void DECAF_API_VIS | decaf_448_point_negate (decaf_448_point_t nega, const decaf_448_point_t a) DECAF_NONNULL
| Negate a point to produce another point.
void DECAF_API_VIS | decaf_448_point_scalarmul (decaf_448_point_t scaled, const decaf_448_point_t base, const decaf_448_scalar_t scalar) DECAF_NONNULL DECAF_NOINLINE
| Multiply a base point by a scalar: scaled = scalar*base.
decaf_error_t DECAF_API_VIS | decaf_448_direct_scalarmul (uint8_t scaled[DECAF_448_SER_BYTES], const uint8_t base[DECAF_448_SER_BYTES], const decaf_448_scalar_t scalar, decaf_bool_t allow_identity, decaf_bool_t short_circuit) DECAF_NONNULL DECAF_WARN_UNUSED DECAF_NOINLINE
| Multiply a base point by a scalar: scaled = scalar*base.
decaf_error_t DECAF_API_VIS | decaf_x448 (uint8_t shared[DECAF_X448_PUBLIC_BYTES], const uint8_t base[DECAF_X448_PUBLIC_BYTES], const uint8_t scalar[DECAF_X448_PRIVATE_BYTES]) DECAF_NONNULL DECAF_WARN_UNUSED DECAF_NOINLINE
| RFC 7748 Diffie-Hellman scalarmul, used to compute shared secrets.
void DECAF_API_VIS | decaf_448_point_mul_by_ratio_and_encode_like_x448 (uint8_t out[DECAF_X448_PUBLIC_BYTES], const decaf_448_point_t p) DECAF_NONNULL
| Multiply a point by DECAF_X448_ENCODE_RATIO, then encode it like RFC 7748.
void DECAF_API_VIS | decaf_x448_generate_key (uint8_t out[DECAF_X448_PUBLIC_BYTES], const uint8_t scalar[DECAF_X448_PRIVATE_BYTES]) DECAF_NONNULL DECAF_NOINLINE DECAF_DEPRECATED("Renamed to decaf_x448_derive_public_key")
| RFC 7748 Diffie-Hellman base point scalarmul.
void DECAF_API_VIS | decaf_x448_derive_public_key (uint8_t out[DECAF_X448_PUBLIC_BYTES], const uint8_t scalar[DECAF_X448_PRIVATE_BYTES]) DECAF_NONNULL DECAF_NOINLINE
| RFC 7748 Diffie-Hellman base point scalarmul.
void DECAF_API_VIS | decaf_448_precompute (decaf_448_precomputed_s *a, const decaf_448_point_t b) DECAF_NONNULL DECAF_NOINLINE
| Precompute a table for fast scalar multiplication.
void DECAF_API_VIS | decaf_448_precomputed_scalarmul (decaf_448_point_t scaled, const decaf_448_precomputed_s *base, const decaf_448_scalar_t scalar) DECAF_NONNULL DECAF_NOINLINE
| Multiply a precomputed base point by a scalar: scaled = scalar*base.
void DECAF_API_VIS | decaf_448_point_double_scalarmul (decaf_448_point_t combo, const decaf_448_point_t base1, const decaf_448_scalar_t scalar1, const decaf_448_point_t base2, const decaf_448_scalar_t scalar2) DECAF_NONNULL DECAF_NOINLINE
| Multiply two base points by two scalars: scaled = scalar1*base1 + scalar2*base2.
void DECAF_API_VIS | decaf_448_point_dual_scalarmul (decaf_448_point_t a1, decaf_448_point_t a2, const decaf_448_point_t base1, const decaf_448_scalar_t scalar1, const decaf_448_scalar_t scalar2) DECAF_NONNULL DECAF_NOINLINE
| Multiply one base point by two scalars:
void DECAF_API_VIS | decaf_448_base_double_scalarmul_non_secret (decaf_448_point_t combo, const decaf_448_scalar_t scalar1, const decaf_448_point_t base2, const decaf_448_scalar_t scalar2) DECAF_NONNULL DECAF_NOINLINE
| Multiply two base points by two scalars: scaled = scalar1*decaf_448_point_base + scalar2*base2.
void DECAF_API_VIS | decaf_448_point_cond_sel (decaf_448_point_t out, const decaf_448_point_t a, const decaf_448_point_t b, decaf_word_t pick_b) DECAF_NONNULL DECAF_NOINLINE
| Constant-time decision between two points.
void DECAF_API_VIS | decaf_448_scalar_cond_sel (decaf_448_scalar_t out, const decaf_448_scalar_t a, const decaf_448_scalar_t b, decaf_word_t pick_b) DECAF_NONNULL DECAF_NOINLINE
| Constant-time decision between two scalars.
decaf_bool_t DECAF_API_VIS | decaf_448_point_valid (const decaf_448_point_t to_test) DECAF_WARN_UNUSED DECAF_NONNULL DECAF_NOINLINE
| Test that a point is valid, for debugging purposes.
void DECAF_API_VIS | decaf_448_point_debugging_torque (decaf_448_point_t q, const decaf_448_point_t p) DECAF_NONNULL DECAF_NOINLINE
| Torque a point, for debugging purposes.
void DECAF_API_VIS | decaf_448_point_debugging_pscale (decaf_448_point_t q, const decaf_448_point_t p, const unsigned char factor[DECAF_448_SER_BYTES]) DECAF_NONNULL DECAF_NOINLINE
| Projectively scale a point, for debugging purposes.
void DECAF_API_VIS | decaf_448_point_from_hash_nonuniform (decaf_448_point_t pt, const unsigned char hashed_data[DECAF_448_HASH_BYTES]) DECAF_NONNULL DECAF_NOINLINE
| Almost-Elligator-like hash to curve.
void DECAF_API_VIS | decaf_448_point_from_hash_uniform (decaf_448_point_t pt, const unsigned char hashed_data[2 *DECAF_448_HASH_BYTES]) DECAF_NONNULL DECAF_NOINLINE
| Indifferentiable hash function encoding to curve.
decaf_error_t DECAF_API_VIS | decaf_448_invert_elligator_nonuniform (unsigned char recovered_hash[DECAF_448_HASH_BYTES], const decaf_448_point_t pt, uint32_t which) DECAF_NONNULL DECAF_NOINLINE DECAF_WARN_UNUSED
| Inverse of elligator-like hash to curve.
decaf_error_t DECAF_API_VIS | decaf_448_invert_elligator_uniform (unsigned char recovered_hash[2 *DECAF_448_HASH_BYTES], const decaf_448_point_t pt, uint32_t which) DECAF_NONNULL DECAF_NOINLINE DECAF_WARN_UNUSED
| Inverse of elligator-like hash to curve.
void DECAF_API_VIS | decaf_448_scalar_destroy (decaf_448_scalar_t scalar) DECAF_NONNULL
| Securely erase a scalar.
void DECAF_API_VIS | decaf_448_point_destroy (decaf_448_point_t point) DECAF_NONNULL
| Securely erase a point by overwriting it with zeros.
void DECAF_API_VIS | decaf_448_precomputed_destroy (decaf_448_precomputed_s *pre) DECAF_NONNULL
| Securely erase a precomputed table by overwriting it with zeros.

## Variables

DECAF_API_VIS const size_t | decaf_448_sizeof_precomputed_s
| Size and alignment of precomputed point tables.
DECAF_API_VIS const size_t | decaf_448_alignof_precomputed_s
DECAF_API_VIS const decaf_448_scalar_t | decaf_448_scalar_one
| The scalar 1.
DECAF_API_VIS const decaf_448_scalar_t | decaf_448_scalar_zero
| The scalar 0.
DECAF_API_VIS const decaf_448_point_t | decaf_448_point_identity
| The identity (zero) point on the curve.
DECAF_API_VIS const decaf_448_point_t | decaf_448_point_base
| An arbitrarily-chosen base point on the curve.
DECAF_API_VIS const struct decaf_448_precomputed_s * | decaf_448_precomputed_base
| Precomputed table of multiples of the base point on the curve.
const uint8_t DECAF_API_VIS | decaf_x448_base_point [DECAF_X448_PUBLIC_BYTES]
| The base point for X448 Diffie-Hellman.

## Detailed Description

A group of prime order p, based on Ed448-Goldilocks.

Author
  Mike Hamburg

Copyright
  Copyright (c) 2015-2016 Cryptography Research, Inc.
  Released under the MIT License. See LICENSE.txt for license information.

Warning
  This file was automatically generated in Python. Please do not edit it.

## Macro Definition Documentation

## DECAF_448_HASH_BYTES

#define DECAF_448_HASH_BYTES 56

Number of bytes in an elligated point.

For now set the same as SER_BYTES but could be different for other curves.

## Typedef Documentation

## decaf_448_precomputed_s

typedef struct decaf_448_precomputed_s decaf_448_precomputed_s

Precomputed table based on a point.

Can be trivial implementation.

## Function Documentation

## decaf_448_base_double_scalarmul_non_secret()

void DECAF_API_VIS decaf_448_base_double_scalarmul_non_secret | ( | decaf_448_point_t | combo,
|  | const decaf_448_scalar_t | scalar1,
|  | const decaf_448_point_t | base2,
|  | const decaf_448_scalar_t | scalar2
| ) |  |

Multiply two base points by two scalars: scaled = scalar1*decaf_448_point_base + scalar2*base2.

Otherwise equivalent to decaf_448_point_double_scalarmul, but may be faster at the expense of being variable time.

Parameters

  [out] | combo | The linear combination scalar1*base + scalar2*base2.
  [in] | scalar1 | A first scalar to multiply by.
  [in] | base2 | A second point to be scaled.
  [in] | scalar2 | A second scalar to multiply by.

Warning
  : This function takes variable time, and may leak the scalars used. It is designed for signature verification.

## decaf_448_direct_scalarmul()

decaf_error_t DECAF_API_VIS decaf_448_direct_scalarmul | ( | uint8_t | scaled[DECAF_448_SER_BYTES],
|  | const uint8_t | base[DECAF_448_SER_BYTES],
|  | const decaf_448_scalar_t | scalar,
|  | decaf_bool_t | allow_identity,
|  | decaf_bool_t | short_circuit
| ) |  |

Multiply a base point by a scalar: scaled = scalar*base.

This function operates directly on serialized forms.

Warning
  This function is experimental. It may not be supported long-term.

Parameters

  [out] | scaled | The scaled point base*scalar
  [in] | base | The point to be scaled.
  [in] | scalar | The scalar to multiply by.
  [in] | allow_identity | Allow the input to be the identity.
  [in] | short_circuit | Allow a fast return if the input is illegal.

Return values

  DECAF_SUCCESS | The scalarmul succeeded.
  DECAF_FAILURE | The scalarmul didn't succeed, because base does not represent a point.

## decaf_448_invert_elligator_nonuniform()

decaf_error_t DECAF_API_VIS decaf_448_invert_elligator_nonuniform | ( | unsigned char | recovered_hash[DECAF_448_HASH_BYTES],
|  | const decaf_448_point_t | pt,
|  | uint32_t | which
| ) |  |

Inverse of elligator-like hash to curve.

This function writes to the buffer, to make it so that decaf_448_point_from_hash_nonuniform(buffer) = pt if possible. Since there may be multiple preimages, the "which" parameter chooses between them. To ensure uniform inverse sampling, this function succeeds or fails independently for different "which" values.

This function isn't guaranteed to find every possible preimage, but it finds all except a small finite number. In particular, when the number of bits in the modulus isn't a multiple of 8 (i.e. for curve25519), it sets the high bits independently, which enables the generated data to be uniform. But it doesn't add p, so you'll never get exactly p from this function. This might change in the future, especially if we ever support eg Brainpool curves, where this could cause real nonuniformity.

Parameters

  [out] | recovered_hash | Encoded data.
  [in] | pt | The point to encode.
  [in] | which | A value determining which inverse point to return.

Return values

  DECAF_SUCCESS | The inverse succeeded.
  DECAF_FAILURE | The inverse failed.

## decaf_448_invert_elligator_uniform()

decaf_error_t DECAF_API_VIS decaf_448_invert_elligator_uniform | ( | unsigned char | recovered_hash[2 *DECAF_448_HASH_BYTES],
|  | const decaf_448_point_t | pt,
|  | uint32_t | which
| ) |  |

Inverse of elligator-like hash to curve.

This function writes to the buffer, to make it so that decaf_448_point_from_hash_uniform(buffer) = pt if possible. Since there may be multiple preimages, the "which" parameter chooses between them. To ensure uniform inverse sampling, this function succeeds or fails independently for different "which" values.

Parameters

  [out] | recovered_hash | Encoded data.
  [in] | pt | The point to encode.
  [in] | which | A value determining which inverse point to return.

Return values

  DECAF_SUCCESS | The inverse succeeded.
  DECAF_FAILURE | The inverse failed.

## decaf_448_point_add()

void DECAF_API_VIS decaf_448_point_add | ( | decaf_448_point_t | sum,
|  | const decaf_448_point_t | a,
|  | const decaf_448_point_t | b
| ) |  |

Add two points to produce a third point.

The input points and output point can be pointers to the same memory.

Parameters

  [out] | sum | The sum a+b.
  [in] | a | An addend.
  [in] | b | An addend.

## decaf_448_point_cond_sel()

void DECAF_API_VIS decaf_448_point_cond_sel | ( | decaf_448_point_t | out,
|  | const decaf_448_point_t | a,
|  | const decaf_448_point_t | b,
|  | decaf_word_t | pick_b
| ) |  |

Constant-time decision between two points.

If pick_b is zero, out = a; else out = b.

Parameters

  [out] | out | The output. It may be the same as either input.
  [in] | a | Any point.
  [in] | b | Any point.
  [in] | pick_b | If nonzero, choose point b.

## decaf_448_point_debugging_pscale()

void DECAF_API_VIS decaf_448_point_debugging_pscale | ( | decaf_448_point_t | q,
|  | const decaf_448_point_t | p,
|  | const unsigned char | factor[DECAF_448_SER_BYTES]
| ) |  |

Projectively scale a point, for debugging purposes.

The output will be equal to the input, and will be valid even if the factor is zero.

Parameters

  [out] | q | The point to scale.
  [in] | p | The point to scale.
  [in] | factor | Serialized GF factor to scale.

## decaf_448_point_debugging_torque()

void DECAF_API_VIS decaf_448_point_debugging_torque | ( | decaf_448_point_t | q,
|  | const decaf_448_point_t | p
| ) |  |

Torque a point, for debugging purposes.

The output will be equal to the input.

Parameters

  [out] | q | The point to torque.
  [in] | p | The point to torque.

## decaf_448_point_decode()

decaf_error_t DECAF_API_VIS decaf_448_point_decode | ( | decaf_448_point_t | pt,
|  | const uint8_t | ser[DECAF_448_SER_BYTES],
|  | decaf_bool_t | allow_identity
| ) |  |

Decode a point from a sequence of bytes.

Every point has a unique encoding, so not every sequence of bytes is a valid encoding. If an invalid encoding is given, the output is undefined.

Parameters

  [out] | pt | The decoded point.
  [in] | ser | The serialized version of the point.
  [in] | allow_identity | DECAF_TRUE if the identity is a legal input.

Return values

  DECAF_SUCCESS | The decoding succeeded.
  DECAF_FAILURE | The decoding didn't succeed, because ser does not represent a point.

## decaf_448_point_destroy()

void DECAF_API_VIS decaf_448_point_destroy | ( | decaf_448_point_t | point | ) |

Securely erase a point by overwriting it with zeros.

Warning
  This causes the point object to become invalid.

## decaf_448_point_double()

void DECAF_API_VIS decaf_448_point_double | ( | decaf_448_point_t | two_a,
|  | const decaf_448_point_t | a
| ) |  |

Double a point.

Equivalent to decaf_448_point_add(two_a,a,a), but potentially faster.

Parameters

  [out] | two_a | The sum a+a.
  [in] | a | A point.

## decaf_448_point_double_scalarmul()

void DECAF_API_VIS decaf_448_point_double_scalarmul | ( | decaf_448_point_t | combo,
|  | const decaf_448_point_t | base1,
|  | const decaf_448_scalar_t | scalar1,
|  | const decaf_448_point_t | base2,
|  | const decaf_448_scalar_t | scalar2
| ) |  |

Multiply two base points by two scalars: scaled = scalar1*base1 + scalar2*base2.

Equivalent to two calls to decaf_448_point_scalarmul, but may be faster.

Parameters

  [out] | combo | The linear combination scalar1*base1 + scalar2*base2.
  [in] | base1 | A first point to be scaled.
  [in] | scalar1 | A first scalar to multiply by.
  [in] | base2 | A second point to be scaled.
  [in] | scalar2 | A second scalar to multiply by.

## decaf_448_point_dual_scalarmul()

void DECAF_API_VIS decaf_448_point_dual_scalarmul | ( | decaf_448_point_t | a1,
|  | decaf_448_point_t | a2,
|  | const decaf_448_point_t | base1,
|  | const decaf_448_scalar_t | scalar1,
|  | const decaf_448_scalar_t | scalar2
| ) |  |

Multiply one base point by two scalars:

a1 = scalar1 * base a2 = scalar2 * base

Equivalent to two calls to decaf_448_point_scalarmul, but may be faster.

Parameters

  [out] | a1 | The first multiple. It may be the same as the input point.
  [out] | a2 | The second multiple. It may be the same as the input point.
  [in] | base1 | A point to be scaled.
  [in] | scalar1 | A first scalar to multiply by.
  [in] | scalar2 | A second scalar to multiply by.

## decaf_448_point_encode()

void DECAF_API_VIS decaf_448_point_encode | ( | uint8_t | ser[DECAF_448_SER_BYTES],
|  | const decaf_448_point_t | pt
| ) |  |

Encode a point as a sequence of bytes.

Parameters

  [out] | ser | The byte representation of the point.
  [in] | pt | The point to encode.

## decaf_448_point_eq()

decaf_bool_t DECAF_API_VIS decaf_448_point_eq | ( | const decaf_448_point_t | a,
|  | const decaf_448_point_t | b
| ) |  |

Test whether two points are equal.

If yes, return DECAF_TRUE, else return DECAF_FALSE.

Parameters

  [in] | a | A point.
  [in] | b | Another point.

Return values

  DECAF_TRUE | The points are equal.
  DECAF_FALSE | The points are not equal.

## decaf_448_point_from_hash_nonuniform()

void DECAF_API_VIS decaf_448_point_from_hash_nonuniform | ( | decaf_448_point_t | pt,
|  | const unsigned char | hashed_data[DECAF_448_HASH_BYTES]
| ) |  |

Almost-Elligator-like hash to curve.

Call this function with the output of a hash to make a hash to the curve.

This function runs Elligator2 on the decaf_448 Jacobi quartic model. It then uses the isogeny to put the result in twisted Edwards form. As a result, it is safe (cannot produce points of order 4), and would be compatible with hypothetical other implementations of Decaf using a Montgomery or untwisted Edwards model.

Unlike Elligator, this function may be up to 4:1 on [0,(p-1)/2]: A factor of 2 due to the isogeny. A factor of 2 because we quotient out the 2-torsion.

This makes it about 8:1 overall, or 16:1 overall on curves with cofactor 8.

Negating the input (mod q) results in the same point. Inverting the input (mod q) results in the negative point. This is the same as Elligator.

This function isn't quite indifferentiable from a random oracle. However, it is suitable for many protocols, including SPEKE and SPAKE2 EE. Furthermore, calling it twice with independent seeds and adding the results is indifferentiable from a random oracle.

Parameters

  [in] | hashed_data | Output of some hash function.
  [out] | pt | The data hashed to the curve.

## decaf_448_point_from_hash_uniform()

void DECAF_API_VIS decaf_448_point_from_hash_uniform | ( | decaf_448_point_t | pt,
|  | const unsigned char | hashed_data[2 *DECAF_448_HASH_BYTES]
| ) |  |

Indifferentiable hash function encoding to curve.

Equivalent to calling decaf_448_point_from_hash_nonuniform twice and adding.

Parameters

  [in] | hashed_data | Output of some hash function.
  [out] | pt | The data hashed to the curve.

## decaf_448_point_mul_by_ratio_and_encode_like_x448()

void DECAF_API_VIS decaf_448_point_mul_by_ratio_and_encode_like_x448 | ( | uint8_t | out[DECAF_X448_PUBLIC_BYTES],
|  | const decaf_448_point_t | p
| ) |  |

Multiply a point by DECAF_X448_ENCODE_RATIO, then encode it like RFC 7748.

This function is mainly used internally, but is exported in case it will be useful.

The ratio is necessary because the internal representation doesn't track the cofactor information, so on output we must clear the cofactor. This would multiply by the cofactor, but in fact internally libdecaf's points are always even, so it multiplies by half the cofactor instead.

As it happens, this aligns with the base point definitions; that is, if you pass the Decaf/Ristretto base point to this function, the result will be DECAF_X448_ENCODE_RATIO times the X448 base point.

Parameters

  [out] | out | The scaled and encoded point.
  [in] | p | The point to be scaled and encoded.

## decaf_448_point_negate()

void DECAF_API_VIS decaf_448_point_negate | ( | decaf_448_point_t | nega,
|  | const decaf_448_point_t | a
| ) |  |

Negate a point to produce another point.

The input and output points can use the same memory.

Parameters

  [out] | nega | The negated input point
  [in] | a | The input point.

## decaf_448_point_scalarmul()

void DECAF_API_VIS decaf_448_point_scalarmul | ( | decaf_448_point_t | scaled,
|  | const decaf_448_point_t | base,
|  | const decaf_448_scalar_t | scalar
| ) |  |

Multiply a base point by a scalar: scaled = scalar*base.

Parameters

  [out] | scaled | The scaled point base*scalar
  [in] | base | The point to be scaled.
  [in] | scalar | The scalar to multiply by.

## decaf_448_point_sub()

void DECAF_API_VIS decaf_448_point_sub | ( | decaf_448_point_t | diff,
|  | const decaf_448_point_t | a,
|  | const decaf_448_point_t | b
| ) |  |

Subtract two points to produce a third point.

The input points and output point can be pointers to the same memory.

Parameters

  [out] | diff | The difference a-b.
  [in] | a | The minuend.
  [in] | b | The subtrahend.

## decaf_448_point_valid()

decaf_bool_t DECAF_API_VIS decaf_448_point_valid | ( | const decaf_448_point_t | to_test | ) |

Test that a point is valid, for debugging purposes.

Parameters

  [in] | to_test | The point to test.

Return values

  DECAF_TRUE | The point is valid.
  DECAF_FALSE | The point is invalid.

## decaf_448_precompute()

void DECAF_API_VIS decaf_448_precompute | ( | decaf_448_precomputed_s * | a,
|  | const decaf_448_point_t | b
| ) |  |

Precompute a table for fast scalar multiplication.

Some implementations do not include precomputed points; for those implementations, this implementation simply copies the point.

Parameters

  [out] | a | A precomputed table of multiples of the point.
  [in] | b | Any point.

## decaf_448_precomputed_destroy()

void DECAF_API_VIS decaf_448_precomputed_destroy | ( | decaf_448_precomputed_s * | pre | ) |

Securely erase a precomputed table by overwriting it with zeros.

Warning
  This causes the table object to become invalid.

## decaf_448_precomputed_scalarmul()

void DECAF_API_VIS decaf_448_precomputed_scalarmul | ( | decaf_448_point_t | scaled,
|  | const decaf_448_precomputed_s * | base,
|  | const decaf_448_scalar_t | scalar
| ) |  |

Multiply a precomputed base point by a scalar: scaled = scalar*base.

Some implementations do not include precomputed points; for those implementations, this function is the same as decaf_448_point_scalarmul

Parameters

  [out] | scaled | The scaled point base*scalar
  [in] | base | The point to be scaled.
  [in] | scalar | The scalar to multiply by.

## decaf_448_scalar_add()

void DECAF_API_VIS decaf_448_scalar_add | ( | decaf_448_scalar_t | out,
|  | const decaf_448_scalar_t | a,
|  | const decaf_448_scalar_t | b
| ) |  |

Add two scalars.

The scalars may use the same memory.

Parameters

  [in] | a | One scalar.
  [in] | b | Another scalar.
  [out] | out | a+b.

## decaf_448_scalar_cond_sel()

void DECAF_API_VIS decaf_448_scalar_cond_sel | ( | decaf_448_scalar_t | out,
|  | const decaf_448_scalar_t | a,
|  | const decaf_448_scalar_t | b,
|  | decaf_word_t | pick_b
| ) |  |

Constant-time decision between two scalars.

If pick_b is zero, out = a; else out = b.

Parameters

  [out] | out | The output. It may be the same as either input.
  [in] | a | Any scalar.
  [in] | b | Any scalar.
  [in] | pick_b | If nonzero, choose scalar b.

## decaf_448_scalar_decode()

decaf_error_t DECAF_API_VIS decaf_448_scalar_decode | ( | decaf_448_scalar_t | out,
|  | const unsigned char | ser[DECAF_448_SCALAR_BYTES]
| ) |  |

Read a scalar from wire format or from bytes.

Parameters

  [in] | ser | Serialized form of a scalar.
  [out] | out | Deserialized form.

Return values

  DECAF_SUCCESS | The scalar was correctly encoded.
  DECAF_FAILURE | The scalar was greater than the modulus, and has been reduced modulo that modulus.

## decaf_448_scalar_decode_long()

void DECAF_API_VIS decaf_448_scalar_decode_long | ( | decaf_448_scalar_t | out,
|  | const unsigned char * | ser,
|  | size_t | ser_len
| ) |  |

Read a scalar from wire format or from bytes.

Reduces mod scalar prime.

Parameters

  [in] | ser | Serialized form of a scalar.
  [in] | ser_len | Length of serialized form.
  [out] | out | Deserialized form.

## decaf_448_scalar_encode()

void DECAF_API_VIS decaf_448_scalar_encode | ( | unsigned char | ser[DECAF_448_SCALAR_BYTES],
|  | const decaf_448_scalar_t | s
| ) |  |

Serialize a scalar to wire format.

Parameters

  [out] | ser | Serialized form of a scalar.
  [in] | s | Deserialized scalar.

## decaf_448_scalar_eq()

decaf_bool_t DECAF_API_VIS decaf_448_scalar_eq | ( | const decaf_448_scalar_t | a,
|  | const decaf_448_scalar_t | b
| ) |  |

Compare two scalars.

Parameters

  [in] | a | One scalar.
  [in] | b | Another scalar.

Return values

  DECAF_TRUE | The scalars are equal.
  DECAF_FALSE | The scalars are not equal.

## decaf_448_scalar_halve()

void DECAF_API_VIS decaf_448_scalar_halve | ( | decaf_448_scalar_t | out,
|  | const decaf_448_scalar_t | a
| ) |  |

Halve a scalar.

The scalars may use the same memory.

Parameters

  [in] | a | A scalar.
  [out] | out | a/2.

## decaf_448_scalar_invert()

decaf_error_t DECAF_API_VIS decaf_448_scalar_invert | ( | decaf_448_scalar_t | out,
|  | const decaf_448_scalar_t | a
| ) |  |

Invert a scalar.

When passed zero, return 0. The input and output may alias.

Parameters

  [in] | a | A scalar.
  [out] | out | 1/a.

Returns
  DECAF_SUCCESS The input is nonzero.

## decaf_448_scalar_mul()

void DECAF_API_VIS decaf_448_scalar_mul | ( | decaf_448_scalar_t | out,
|  | const decaf_448_scalar_t | a,
|  | const decaf_448_scalar_t | b
| ) |  |

Multiply two scalars.

The scalars may use the same memory.

Parameters

  [in] | a | One scalar.
  [in] | b | Another scalar.
  [out] | out | a*b.

## decaf_448_scalar_set_unsigned()

void DECAF_API_VIS decaf_448_scalar_set_unsigned | ( | decaf_448_scalar_t | out,
|  | uint64_t | a
| ) |  |

Set a scalar to an unsigned 64-bit integer.

Parameters

  [in] | a | An integer.
  [out] | out | Will become equal to a.

## decaf_448_scalar_sub()

void DECAF_API_VIS decaf_448_scalar_sub | ( | decaf_448_scalar_t | out,
|  | const decaf_448_scalar_t | a,
|  | const decaf_448_scalar_t | b
| ) |  |

Subtract two scalars.

The scalars may use the same memory.

Parameters

  [in] | a | One scalar.
  [in] | b | Another scalar.
  [out] | out | a-b.

## decaf_x448()

decaf_error_t DECAF_API_VIS decaf_x448 | ( | uint8_t | shared[DECAF_X448_PUBLIC_BYTES],
|  | const uint8_t | base[DECAF_X448_PUBLIC_BYTES],
|  | const uint8_t | scalar[DECAF_X448_PRIVATE_BYTES]
| ) |  |

RFC 7748 Diffie-Hellman scalarmul, used to compute shared secrets.

This function uses a different (non-Decaf) encoding.

Parameters

  [out] | shared | The shared secret base*scalar
  [in] | base | The other party's public key, used as the base of the scalarmul.
  [in] | scalar | The private scalar to multiply by.

Return values

  DECAF_SUCCESS | The scalarmul succeeded.
  DECAF_FAILURE | The scalarmul didn't succeed, because the base point is in a small subgroup.

## decaf_x448_derive_public_key()

void DECAF_API_VIS decaf_x448_derive_public_key | ( | uint8_t | out[DECAF_X448_PUBLIC_BYTES],
|  | const uint8_t | scalar[DECAF_X448_PRIVATE_BYTES]
| ) |  |

RFC 7748 Diffie-Hellman base point scalarmul.

This function uses a different (non-Decaf) encoding.

Does exactly the same thing as decaf_x448_generate_key, but has a better name.

Parameters

  [out] | out | The public key base*scalar
  [in] | scalar | The private scalar.

## decaf_x448_generate_key()

void DECAF_API_VIS decaf_x448_generate_key | ( | uint8_t | out[DECAF_X448_PUBLIC_BYTES],
|  | const uint8_t | scalar[DECAF_X448_PRIVATE_BYTES]
| ) |  |

RFC 7748 Diffie-Hellman base point scalarmul.

This function uses a different (non-Decaf) encoding.

Deprecated:
  Renamed to decaf_x448_derive_public_key. I have no particular timeline for removing this name.

Parameters

  [out] | out | The public key base*scalar.
  [in] | scalar | The private scalar.