libdecaf
Classes | Macros | Typedefs | Functions | Variables
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. More...
 
#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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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: More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 

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_sdecaf_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
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

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]comboThe linear combination scalar1*base + scalar2*base2.
[in]scalar1A first scalar to multiply by.
[in]base2A second point to be scaled.
[in]scalar2A 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]scaledThe scaled point base*scalar
[in]baseThe point to be scaled.
[in]scalarThe scalar to multiply by.
[in]allow_identityAllow the input to be the identity.
[in]short_circuitAllow a fast return if the input is illegal.
Return values
DECAF_SUCCESSThe scalarmul succeeded.
DECAF_FAILUREThe 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_hashEncoded data.
[in]ptThe point to encode.
[in]whichA value determining which inverse point to return.
Return values
DECAF_SUCCESSThe inverse succeeded.
DECAF_FAILUREThe 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_hashEncoded data.
[in]ptThe point to encode.
[in]whichA value determining which inverse point to return.
Return values
DECAF_SUCCESSThe inverse succeeded.
DECAF_FAILUREThe 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]sumThe sum a+b.
[in]aAn addend.
[in]bAn 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]outThe output. It may be the same as either input.
[in]aAny point.
[in]bAny point.
[in]pick_bIf 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]qThe point to scale.
[in]pThe point to scale.
[in]factorSerialized 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]qThe point to torque.
[in]pThe 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]ptThe decoded point.
[in]serThe serialized version of the point.
[in]allow_identityDECAF_TRUE if the identity is a legal input.
Return values
DECAF_SUCCESSThe decoding succeeded.
DECAF_FAILUREThe 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_aThe sum a+a.
[in]aA 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]comboThe linear combination scalar1*base1 + scalar2*base2.
[in]base1A first point to be scaled.
[in]scalar1A first scalar to multiply by.
[in]base2A second point to be scaled.
[in]scalar2A 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]a1The first multiple. It may be the same as the input point.
[out]a2The second multiple. It may be the same as the input point.
[in]base1A point to be scaled.
[in]scalar1A first scalar to multiply by.
[in]scalar2A 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]serThe byte representation of the point.
[in]ptThe 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]aA point.
[in]bAnother point.
Return values
DECAF_TRUEThe points are equal.
DECAF_FALSEThe 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_dataOutput of some hash function.
[out]ptThe 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_dataOutput of some hash function.
[out]ptThe 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]outThe scaled and encoded point.
[in]pThe 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]negaThe negated input point
[in]aThe 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]scaledThe scaled point base*scalar
[in]baseThe point to be scaled.
[in]scalarThe 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]diffThe difference a-b.
[in]aThe minuend.
[in]bThe 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_testThe point to test.
Return values
DECAF_TRUEThe point is valid.
DECAF_FALSEThe 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]aA precomputed table of multiples of the point.
[in]bAny 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]scaledThe scaled point base*scalar
[in]baseThe point to be scaled.
[in]scalarThe 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]aOne scalar.
[in]bAnother scalar.
[out]outa+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]outThe output. It may be the same as either input.
[in]aAny scalar.
[in]bAny scalar.
[in]pick_bIf 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]serSerialized form of a scalar.
[out]outDeserialized form.
Return values
DECAF_SUCCESSThe scalar was correctly encoded.
DECAF_FAILUREThe 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]serSerialized form of a scalar.
[in]ser_lenLength of serialized form.
[out]outDeserialized 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]serSerialized form of a scalar.
[in]sDeserialized 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]aOne scalar.
[in]bAnother scalar.
Return values
DECAF_TRUEThe scalars are equal.
DECAF_FALSEThe 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]aA scalar.
[out]outa/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]aA scalar.
[out]out1/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]aOne scalar.
[in]bAnother scalar.
[out]outa*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]aAn integer.
[out]outWill 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]aOne scalar.
[in]bAnother scalar.
[out]outa-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]sharedThe shared secret base*scalar
[in]baseThe other party's public key, used as the base of the scalarmul.
[in]scalarThe private scalar to multiply by.
Return values
DECAF_SUCCESSThe scalarmul succeeded.
DECAF_FAILUREThe 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]outThe public key base*scalar
[in]scalarThe 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]outThe public key base*scalar.
[in]scalarThe private scalar.