libdecaf
Public Types | Public Member Functions | Static Public Member Functions | Public Attributes | Static Public Attributes | List of all members
decaf::Ristretto::Point Class Reference

Element of prime-order elliptic curve group. More...

Inheritance diagram for decaf::Ristretto::Point:
decaf::Serializable< Point >

Public Types

typedef decaf_255_point_t Wrapped
 Wrapped C type.
 

Public Member Functions

 Point (const Wrapped &q=decaf_255_point_identity) DECAF_NOEXCEPT
 Constructor sets to identity by default. More...
 
 Point (const Point &q) DECAF_NOEXCEPT
 Copy constructor. More...
 
Pointoperator= (const Point &q) DECAF_NOEXCEPT
 Assignment. More...
 
 ~Point () DECAF_NOEXCEPT
 Destructor securely zeorizes the point. More...
 
 Point (Rng &rng, bool uniform=true) DECAF_NOEXCEPT
 Construct from RNG.
 
 Point (const FixedBlock< SER_BYTES > &buffer, bool allow_identity=true)
 Initialize from a fixed-length byte string. More...
 
decaf_error_t DECAF_WARN_UNUSED decode (const FixedBlock< SER_BYTES > &buffer, bool allow_identity=true) DECAF_NOEXCEPT
 Initialize from C++ fixed-length byte string. More...
 
decaf_error_t DECAF_WARN_UNUSED decode_like_eddsa_and_mul_by_ratio_noexcept (const FixedBlock< DECAF_EDDSA_25519_PUBLIC_BYTES > &buffer) DECAF_NOEXCEPT
 Initialize from C++ fixed-length byte string, like EdDSA. More...
 
void decode_like_eddsa_and_mul_by_ratio (const FixedBlock< DECAF_EDDSA_25519_PUBLIC_BYTES > &buffer)
 Decode from EDDSA, multiply by EDDSA_DECODE_RATIO, and ignore any remaining cofactor information. More...
 
SecureBuffer mul_by_ratio_and_encode_like_eddsa () const
 Multiply by EDDSA_ENCODE_RATIO and encode like EdDSA. More...
 
void mul_by_ratio_and_encode_like_eddsa (FixedBuffer< DECAF_EDDSA_25519_PUBLIC_BYTES > &out) const
 Multiply by EDDSA_ENCODE_RATIO and encode like EdDSA. More...
 
SecureBuffer mul_by_ratio_and_encode_like_ladder () const
 Multiply by LADDER_ENCODE_RATIO and encode like X25519/X448. More...
 
void mul_by_ratio_and_encode_like_ladder (FixedBuffer< LADDER_BYTES > &out) const
 Multiply by LADDER_ENCODE_RATIO and encode like X25519/X448. More...
 
void set_to_hash (const Block &s) DECAF_NOEXCEPT
 Map to the curve from a hash buffer. More...
 
 operator SecureBuffer () const
 Encode to string. More...
 
size_t ser_size () const DECAF_NOEXCEPT
 Serializable instance.
 
void serialize_into (unsigned char *buffer) const DECAF_NOEXCEPT
 Serializable instance.
 
Point operator+ (const Point &q) const DECAF_NOEXCEPT
 Point add. More...
 
Pointoperator+= (const Point &q) DECAF_NOEXCEPT
 Point add. More...
 
Point operator- (const Point &q) const DECAF_NOEXCEPT
 Point subtract. More...
 
Pointoperator-= (const Point &q) DECAF_NOEXCEPT
 Point subtract. More...
 
Point operator- () const DECAF_NOEXCEPT
 Point negate. More...
 
Point times_two () const DECAF_NOEXCEPT
 Double the point out of place. More...
 
Pointdouble_in_place () DECAF_NOEXCEPT
 Double the point in place. More...
 
bool operator!= (const Point &q) const DECAF_NOEXCEPT
 Constant-time compare. More...
 
bool operator== (const Point &q) const DECAF_NOEXCEPT
 Constant-time compare. More...
 
Point operator* (const Scalar &s) const DECAF_NOEXCEPT
 Scalar multiply. More...
 
Pointoperator*= (const Scalar &s) DECAF_NOEXCEPT
 Scalar multiply in place. More...
 
Point operator/ (const Scalar &s) const
 Multiply by s.inverse(). More...
 
Pointoperator/= (const Scalar &s)
 Multiply by s.inverse(). More...
 
bool validate () const DECAF_NOEXCEPT
 Validate / sanity check.
 
void dual_scalarmul (Point &q1, Point &q2, const Scalar &r1, const Scalar &r2) const DECAF_NOEXCEPT
 Dual-scalar multiply, equivalent to this*r1, this*r2 but faster. More...
 
Point non_secret_combo_with_base (const Scalar &s, const Scalar &s_base) DECAF_NOEXCEPT
 Double-scalar multiply: this point by the first scalar and base by the second scalar. More...
 
Point debugging_torque () const DECAF_NOEXCEPT
 Return a point equal to *this, whose internal data is rotated by a torsion element. More...
 
Point debugging_pscale (const FixedBlock< SER_BYTES > factor) const DECAF_NOEXCEPT
 Return a point equal to *this, whose internal data has a modified representation. More...
 
Point debugging_pscale (Rng &r) const DECAF_NOEXCEPT
 Return a point equal to *this, whose internal data has a randomized representation. More...
 
decaf_error_t invert_elligator (Buffer buf, uint32_t hint) const DECAF_NOEXCEPT
 Modify buffer so that Point::from_hash(Buffer) == *this, and return DECAF_SUCCESS; or leave buf unmodified and return DECAF_FAILURE.
 
SecureBuffer steg_encode (Rng &rng, size_t size=STEG_BYTES) const
 Steganographically encode this.
 
- Public Member Functions inherited from decaf::Serializable< Point >
size_t ser_size () const DECAF_NOEXCEPT
 Return the number of bytes needed to serialize this object.
 
void serialize_into (unsigned char *buf) const DECAF_NOEXCEPT
 Serialize this object into a buffer.
 
SecureBuffer serialize () const
 Serialize this object into a SecureBuffer and return it.
 

Static Public Member Functions

static Point from_hash (const Block &s) DECAF_NOEXCEPT
 Map uniformly to the curve from a hash buffer. More...
 
static Point double_scalarmul (const Point &q, const Scalar &qs, const Point &r, const Scalar &rs) DECAF_NOEXCEPT
 Double-scalar multiply, equivalent to q*qs + r*rs but faster. More...
 
static Point double_scalarmul (const Scalar &qs, const Point &q, const Scalar &rs, const Point &r) DECAF_NOEXCEPT
 Double-scalar multiply, equivalent to q*qs + r*rs but faster. More...
 
static const Point base () DECAF_NOEXCEPT
 Return the base point of the curve. More...
 
static const Point identity () DECAF_NOEXCEPT
 Return the identity point of the curve. More...
 

Public Attributes

Wrapped p
 The c-level object. More...
 

Static Public Attributes

static const size_t SER_BYTES = DECAF_255_SER_BYTES
 Size of a serialized element.
 
static const size_t HASH_BYTES = DECAF_255_HASH_BYTES
 Bytes required for hash.
 
static const size_t EDDSA_BYTES = DECAF_EDDSA_25519_PUBLIC_BYTES
 Bytes required for EdDSA encoding.
 
static const size_t LADDER_BYTES = DECAF_X25519_PUBLIC_BYTES
 Bytes required for EdDSA encoding.
 
static const int EDDSA_ENCODE_RATIO = DECAF_255_EDDSA_ENCODE_RATIO
 Ratio due to EdDSA encoding.
 
static const int EDDSA_DECODE_RATIO = DECAF_255_EDDSA_DECODE_RATIO
 Ratio due to EdDSA decoding.
 
static const int LADDER_ENCODE_RATIO = DECAF_X25519_ENCODE_RATIO
 Ratio due to ladder decoding.
 
static const size_t STEG_BYTES = HASH_BYTES * 2
 Size of a steganographically-encoded curve element. More...
 
static const unsigned int INVERT_ELLIGATOR_WHICH_BITS = DECAF_255_INVERT_ELLIGATOR_WHICH_BITS
 Number of bits in invert_elligator which are actually used. More...
 

Detailed Description

Element of prime-order elliptic curve group.

Constructor & Destructor Documentation

◆ Point() [1/3]

decaf::Ristretto::Point::Point ( const Wrapped q = decaf_255_point_identity)
inline

Constructor sets to identity by default.

◆ Point() [2/3]

decaf::Ristretto::Point::Point ( const Point q)
inline

Copy constructor.

◆ ~Point()

decaf::Ristretto::Point::~Point ( )
inline

Destructor securely zeorizes the point.

◆ Point() [3/3]

decaf::Ristretto::Point::Point ( const FixedBlock< SER_BYTES > &  buffer,
bool  allow_identity = true 
)
inlineexplicit

Initialize from a fixed-length byte string.

The all-zero string maps to the identity.

Exceptions
CryptoExceptionthe string was the wrong length, or wasn't the encoding of a point, or was the identity and allow_identity was DECAF_FALSE.

Member Function Documentation

◆ base()

static const Point decaf::Ristretto::Point::base ( )
inlinestatic

Return the base point of the curve.

◆ debugging_pscale() [1/2]

Point decaf::Ristretto::Point::debugging_pscale ( const FixedBlock< SER_BYTES factor) const
inline

Return a point equal to *this, whose internal data has a modified representation.

◆ debugging_pscale() [2/2]

Point decaf::Ristretto::Point::debugging_pscale ( Rng r) const
inline

Return a point equal to *this, whose internal data has a randomized representation.

◆ debugging_torque()

Point decaf::Ristretto::Point::debugging_torque ( ) const
inline

Return a point equal to *this, whose internal data is rotated by a torsion element.

◆ decode()

decaf_error_t DECAF_WARN_UNUSED decaf::Ristretto::Point::decode ( const FixedBlock< SER_BYTES > &  buffer,
bool  allow_identity = true 
)
inline

Initialize from C++ fixed-length byte string.

The all-zero string maps to the identity.

Return values
DECAF_SUCCESSthe string was successfully decoded.
Returns
DECAF_FAILURE the string was the wrong length, or wasn't the encoding of a point, or was the identity and allow_identity was DECAF_FALSE. Contents of the buffer are undefined.

◆ decode_like_eddsa_and_mul_by_ratio()

void decaf::Ristretto::Point::decode_like_eddsa_and_mul_by_ratio ( const FixedBlock< DECAF_EDDSA_25519_PUBLIC_BYTES > &  buffer)
inline

Decode from EDDSA, multiply by EDDSA_DECODE_RATIO, and ignore any remaining cofactor information.

Exceptions
CryptoExceptionif the input point was invalid.

◆ decode_like_eddsa_and_mul_by_ratio_noexcept()

decaf_error_t DECAF_WARN_UNUSED decaf::Ristretto::Point::decode_like_eddsa_and_mul_by_ratio_noexcept ( const FixedBlock< DECAF_EDDSA_25519_PUBLIC_BYTES > &  buffer)
inline

Initialize from C++ fixed-length byte string, like EdDSA.

The all-zero string maps to the identity.

Return values
DECAF_SUCCESSthe string was successfully decoded.
Returns
DECAF_FAILURE the string was the wrong length, or wasn't the encoding of a point. Contents of the point are undefined.

◆ double_in_place()

Point& decaf::Ristretto::Point::double_in_place ( )
inline

Double the point in place.

◆ double_scalarmul() [1/2]

static Point decaf::Ristretto::Point::double_scalarmul ( const Point q,
const Scalar qs,
const Point r,
const Scalar rs 
)
inlinestatic

Double-scalar multiply, equivalent to q*qs + r*rs but faster.

◆ double_scalarmul() [2/2]

static Point decaf::Ristretto::Point::double_scalarmul ( const Scalar qs,
const Point q,
const Scalar rs,
const Point r 
)
inlinestatic

Double-scalar multiply, equivalent to q*qs + r*rs but faster.

For those who like their scalars before the point.

◆ dual_scalarmul()

void decaf::Ristretto::Point::dual_scalarmul ( Point q1,
Point q2,
const Scalar r1,
const Scalar r2 
) const
inline

Dual-scalar multiply, equivalent to this*r1, this*r2 but faster.

◆ from_hash()

static Point decaf::Ristretto::Point::from_hash ( const Block s)
inlinestatic

Map uniformly to the curve from a hash buffer.

The empty or all-zero string maps to the identity, as does the string "\\x01". If the buffer is shorter than 2*HASH_BYTES, well, it won't be as uniform, but the buffer will be zero-padded on the right.

◆ identity()

static const Point decaf::Ristretto::Point::identity ( )
inlinestatic

Return the identity point of the curve.

◆ mul_by_ratio_and_encode_like_eddsa() [1/2]

SecureBuffer decaf::Ristretto::Point::mul_by_ratio_and_encode_like_eddsa ( ) const
inline

Multiply by EDDSA_ENCODE_RATIO and encode like EdDSA.

◆ mul_by_ratio_and_encode_like_eddsa() [2/2]

void decaf::Ristretto::Point::mul_by_ratio_and_encode_like_eddsa ( FixedBuffer< DECAF_EDDSA_25519_PUBLIC_BYTES > &  out) const
inline

Multiply by EDDSA_ENCODE_RATIO and encode like EdDSA.

◆ mul_by_ratio_and_encode_like_ladder() [1/2]

SecureBuffer decaf::Ristretto::Point::mul_by_ratio_and_encode_like_ladder ( ) const
inline

Multiply by LADDER_ENCODE_RATIO and encode like X25519/X448.

◆ mul_by_ratio_and_encode_like_ladder() [2/2]

void decaf::Ristretto::Point::mul_by_ratio_and_encode_like_ladder ( FixedBuffer< LADDER_BYTES > &  out) const
inline

Multiply by LADDER_ENCODE_RATIO and encode like X25519/X448.

◆ non_secret_combo_with_base()

Point decaf::Ristretto::Point::non_secret_combo_with_base ( const Scalar s,
const Scalar s_base 
)
inline

Double-scalar multiply: this point by the first scalar and base by the second scalar.

Warning
This function takes variable time, and may leak the scalars (or points, but currently it doesn't).

◆ operator SecureBuffer()

decaf::Ristretto::Point::operator SecureBuffer ( ) const
inline

Encode to string.

The identity encodes to the all-zero string.

◆ operator!=()

bool decaf::Ristretto::Point::operator!= ( const Point q) const
inline

Constant-time compare.

◆ operator*()

Point decaf::Ristretto::Point::operator* ( const Scalar s) const
inline

Scalar multiply.

◆ operator*=()

Point& decaf::Ristretto::Point::operator*= ( const Scalar s)
inline

Scalar multiply in place.

◆ operator+()

Point decaf::Ristretto::Point::operator+ ( const Point q) const
inline

Point add.

◆ operator+=()

Point& decaf::Ristretto::Point::operator+= ( const Point q)
inline

Point add.

◆ operator-() [1/2]

Point decaf::Ristretto::Point::operator- ( const Point q) const
inline

Point subtract.

◆ operator-() [2/2]

Point decaf::Ristretto::Point::operator- ( ) const
inline

Point negate.

◆ operator-=()

Point& decaf::Ristretto::Point::operator-= ( const Point q)
inline

Point subtract.

◆ operator/()

Point decaf::Ristretto::Point::operator/ ( const Scalar s) const
inline

Multiply by s.inverse().

If s=0, maps to the identity.

◆ operator/=()

Point& decaf::Ristretto::Point::operator/= ( const Scalar s)
inline

Multiply by s.inverse().

If s=0, maps to the identity.

◆ operator=()

Point& decaf::Ristretto::Point::operator= ( const Point q)
inline

Assignment.

◆ operator==()

bool decaf::Ristretto::Point::operator== ( const Point q) const
inline

Constant-time compare.

◆ set_to_hash()

void decaf::Ristretto::Point::set_to_hash ( const Block s)
inline

Map to the curve from a hash buffer.

The empty or all-zero string maps to the identity, as does the string "\\x01". If the buffer is shorter than 2*HASH_BYTES, well, it won't be as uniform, but the buffer will be zero-padded on the right.

◆ times_two()

Point decaf::Ristretto::Point::times_two ( ) const
inline

Double the point out of place.

Member Data Documentation

◆ INVERT_ELLIGATOR_WHICH_BITS

const unsigned int decaf::Ristretto::Point::INVERT_ELLIGATOR_WHICH_BITS = DECAF_255_INVERT_ELLIGATOR_WHICH_BITS
static

Number of bits in invert_elligator which are actually used.

◆ p

Wrapped decaf::Ristretto::Point::p

The c-level object.

◆ STEG_BYTES

const size_t decaf::Ristretto::Point::STEG_BYTES = HASH_BYTES * 2
static

Size of a steganographically-encoded curve element.

If the point is random, the encoding should look statistically close to a uniformly-random sequnece of STEG_BYTES bytes.


The documentation for this class was generated from the following file: