internal

Documentation

Overview

Package internal defines simple and abstract APIs to group Elements and Scalars.

Package internal defines simple and abstract APIs to group Elements and Scalars.

Package internal defines simple and abstract APIs to group Elements and Scalars.

Index

• Variables
• func RandomBytes(length int) []byte
• type Decoder
• type Element
• type Encoder
• type Group
• type Scalar

Variables

var (
	// ErrInvalidGroup indicates usage of an unavailable or invalid group.
	ErrInvalidGroup = errors.New("invalid group")

	// ErrParamNilScalar indicates a forbidden nil or empty scalar.
	ErrParamNilScalar = errors.New("nil or empty scalar")

	// ErrParamScalarLength indicates an invalid scalar length.
	ErrParamScalarLength = errors.New("invalid scalar length")

	// ErrParamNilPoint indicated a forbidden nil or empty point.
	ErrParamNilPoint = errors.New("nil or empty point")

	// ErrParamInvalidPointEncoding indicates an invalid point encoding has been provided.
	ErrParamInvalidPointEncoding = errors.New("invalid point encoding")

	// ErrCastElement indicates a failed attempt to cast to a point.
	ErrCastElement = errors.New("could not cast to same group element (wrong group ?)")

	// ErrCastScalar indicates a failed attempt to cast to a scalar.
	ErrCastScalar = errors.New("could not cast to same group scalar (wrong group ?)")

	// ErrWrongField indicates an incompatible field has been encountered.
	ErrWrongField = errors.New("incompatible fields")

	// ErrIdentity indicates that the identity point (or point at infinity) has been encountered.
	ErrIdentity = errors.New("infinity/identity point")

	// ErrBigIntConversion reports an error in converting to a *big.int.
	ErrBigIntConversion = errors.New("conversion error")

	// ErrParamNegScalar reports an error when the input scalar is negative.
	ErrParamNegScalar = errors.New("negative scalar")

	// ErrParamScalarTooBig reports an error when the input scalar is too big.
	ErrParamScalarTooBig = errors.New("scalar too big")

	// ErrParamScalarInvalidEncoding indicates an invalid scalar encoding has been provided, or that it's too big.
	ErrParamScalarInvalidEncoding = errors.New("invalid scalar encoding")

	// ErrUInt64TooBig indicates that the scalar is higher than the allowed values for uint64.
	ErrUInt64TooBig = errors.New("scalar is too big to be uint64")

	// ErrDecodingInvalidLength indicates an invalid encoding length.
	ErrDecodingInvalidLength = errors.New("invalid encoding length")

	// ErrDecodingInvalidJSONEncoding indicates an invalid JSON encoding.
	ErrDecodingInvalidJSONEncoding = errors.New("invalid JSON encoding")
)

Functions

func RandomBytes

func RandomBytes(length int) []byte

RandomBytes returns random bytes of length len (wrapper for crypto/rand).

Types

type Decoder

type Decoder interface {
	// Decode sets the receiver to a decoding of the input data, and returns an error on failure.
	Decode(data []byte) error

	// DecodeHex sets the receiver to the decoding of the hex encoded input.
	DecodeHex(h string) error

	// BinaryUnmarshaler implementation.
	encoding.BinaryUnmarshaler
}

A Decoder can encode itself to machine or human-readable forms.

type Element

type Element interface {
	// Group returns the group's Identifier.
	Group() byte

	// Base sets the element to the group's base point a.k.a. canonical generator.
	Base() Element

	// Identity sets the element to the point at infinity of the Group's underlying curve.
	Identity() Element

	// Add sets the receiver to the sum of the input and the receiver, and returns the receiver.
	Add(Element) Element

	// Double sets the receiver to its double, and returns it.
	Double() Element

	// Negate sets the receiver to its negation, and returns it.
	Negate() Element

	// Subtract subtracts the input from the receiver, and returns the receiver.
	Subtract(Element) Element

	// Multiply sets the receiver to the scalar multiplication of the receiver with the given Scalar, and returns it.
	Multiply(Scalar) Element

	// Equal returns 1 if the elements are equivalent, and 0 otherwise.
	Equal(Element) int

	// IsIdentity returns whether the Element is the point at infinity of the Group's underlying curve.
	IsIdentity() bool

	// Set sets the receiver to the value of the argument, and returns the receiver.
	Set(Element) Element

	// Copy returns a copy of the receiver.
	Copy() Element

	// Encode returns the compressed byte encoding of the element.
	Encode() []byte

	// XCoordinate returns the encoded x coordinate of the element.
	XCoordinate() []byte

	// Decode sets the receiver to a decoding of the input data, and returns an error on failure.
	Decode(data []byte) error

	// Hex returns the fixed-sized hexadecimal encoding of e.
	Hex() string

	// DecodeHex sets e to the decoding of the hex encoded element.
	DecodeHex(h string) error
}

Element interface abstracts common operations on an Element in a prime-order Group.

type Encoder

type Encoder interface {
	// Encode returns the compressed byte encoding.
	Encode() []byte

	// Hex returns the fixed-sized hexadecimal encoding.
	Hex() string

	// BinaryMarshaler implementation.
	encoding.BinaryMarshaler
}

An Encoder can encode itself to machine or human-readable forms.

type Group

type Group interface {
	// NewScalar returns a new scalar set to 0.
	NewScalar() Scalar

	// NewElement returns the identity element (point at infinity).
	NewElement() Element

	// Base returns the group's base point a.k.a. canonical generator.
	Base() Element

	// HashFunc returns the RFC9380 associated hash function of the group.
	HashFunc() crypto.Hash

	// HashToScalar returns a safe mapping of the arbitrary input to a Scalar.
	// The DST must not be empty or nil, and is recommended to be longer than 16 bytes.
	HashToScalar(input, dst []byte) Scalar

	// HashToGroup returns a safe mapping of the arbitrary input to an Element in the Group.
	// The DST must not be empty or nil, and is recommended to be longer than 16 bytes.
	HashToGroup(input, dst []byte) Element

	// EncodeToGroup returns a non-uniform mapping of the arbitrary input to an Element in the Group.
	// The DST must not be empty or nil, and is recommended to be longer than 16 bytes.
	EncodeToGroup(input, dst []byte) Element

	// Ciphersuite returns the hash-to-curve ciphersuite identifier.
	Ciphersuite() string

	// ScalarLength returns the byte size of an encoded scalar.
	ScalarLength() int

	// ElementLength returns the byte size of an encoded element.
	ElementLength() int

	// Order returns the order of the canonical group of scalars.
	Order() []byte
}

Group abstracts operations in a prime-order group.

type Scalar

type Scalar interface {
	// Group returns the group's Identifier.
	Group() byte

	// Zero sets the scalar to 0, and returns it.
	Zero() Scalar

	// One sets the scalar to 1, and returns it.
	One() Scalar

	// MinusOne sets the scalar to order-1, and returns it.
	MinusOne() Scalar

	// Random sets the current scalar to a new random scalar and returns it.
	// The random source is crypto/rand, and this functions is guaranteed to return a non-zero scalar.
	Random() Scalar

	// Add sets the receiver to the sum of the input and the receiver, and returns the receiver.
	Add(Scalar) Scalar

	// Subtract subtracts the input from the receiver, and returns the receiver.
	Subtract(Scalar) Scalar

	// Multiply multiplies the receiver with the input, and returns the receiver.
	Multiply(Scalar) Scalar

	// Pow sets s to s**scalar modulo the group order, and returns s. If scalar is nil, it returns 1.
	Pow(scalar Scalar) Scalar

	// Invert sets the receiver to the scalar's modular inverse ( 1 / scalar ), and returns it.
	Invert() Scalar

	// Equal returns 1 if the scalars are equal, and 0 otherwise.
	Equal(Scalar) int

	// LessOrEqual returns 1 if s <= scalar, and 0 otherwise.
	LessOrEqual(scalar Scalar) int

	// IsZero returns whether the scalar is 0.
	IsZero() bool

	// Set sets the receiver to the value of the argument scalar, and returns the receiver.
	Set(Scalar) Scalar

	// SetUInt64 sets s to i modulo the field order, and returns an error if one occurs.
	SetUInt64(i uint64) Scalar

	// UInt64 returns the uint64 representation of the scalar,
	// or an error if its value is higher than the authorized limit for uint64.
	UInt64() (uint64, error)

	// Copy returns a copy of the receiver.
	Copy() Scalar

	// Encode returns the compressed byte encoding of the scalar.
	Encode() []byte

	// Decode sets the receiver to a decoding of the input data, and returns an error on failure.
	Decode(in []byte) error

	// Hex returns the fixed-sized hexadecimal encoding of s.
	Hex() string

	// DecodeHex sets s to the decoding of the hex encoded scalar.
	DecodeHex(h string) error
}

Scalar interface abstracts common operations on scalars in a prime-order Group.