ecc

package module

v0.8.2 Latest Latest Go to latest Published: Oct 5, 2024 License: MIT Imports: 10 Imported by: 5

Details

Valid go.mod file

The Go module system was introduced in Go 1.11 and is the official dependency management solution for Go.
Redistributable license

Redistributable licenses place minimal restrictions on how software can be used, modified, and redistributed.
Tagged version

Modules with tagged versions give importers more predictable builds.
Stable version

When a project reaches major version v1 it is considered stable.
Learn more about best practices

Repository

github.com/bytemare/ecc

Links

Open Source Insights

README ¶

Elliptic Curve Groups

  import "github.com/bytemare/ecc"

This package exposes abstract operations over opaque (prime-order) elliptic curve groups and their scalars and elements, and support hash-to-curve as per RFC 9380.

It makes using different elliptic curves easy, flexible, and without loosing performance or security. You don't have to care about the parameters. You can swap between primitives with no code change and only the Group identifier, a byte. The package is a wrapper to optimized and secure implementations that serve as backends, and to which you don't need to adapt and learn about.

The following table shows supported groups with hash-to-curve capability and links each one to the underlying implementations:

ID	Name	Prime-order	Backend
1	Ristretto255	yes	github.com/gtank/ristretto255
2	Decaf448	not supported	not supported
3	P-256	yes	filippo.io/nistec
4	P-384	yes	filippo.io/nistec
5	P-521	yes	filippo.io/nistec
6	Edwards25519	no	filippo.io/edwards25519
7	Secp256k1	yes	github.com/bytemare/secp256k1
9	Curve25519	not yet supported	not yet supported
8	Double-Odd	not yet supported	not yet supported

Group interface

This package exposes types that can handle different implementations under the hood, internally using an interface to the group and its scalars and elements, but you don't need to instantiate or implement anything. Just use the type in the top package.

Group

// Group abstracts operations in a prime-order group.
type Group interface {
	NewScalar() Scalar
	NewElement() Element
	Base() Element
	HashFunc() crypto.Hash
	HashToScalar(input, dst []byte) Scalar
	HashToGroup(input, dst []byte) Element
	EncodeToGroup(input, dst []byte) Element
	Ciphersuite() string
	ScalarLength() int
	ElementLength() int
	Order() []byte
}

Scalar interface

// Scalar interface abstracts common operations on scalars in a prime-order Group.
type Scalar interface {
	Group() Group
	Zero() Scalar
	One() Scalar
	MinusOne() Scalar
	Random() Scalar
	Add(Scalar) Scalar
	Subtract(Scalar) Scalar
	Multiply(Scalar) Scalar
	Pow(Scalar) Scalar
	Invert() Scalar
	Equal(Scalar) int
	LessOrEqual(Scalar) bool
	IsZero() bool
	Set(Scalar) Scalar
	SetUInt64(uint64) Scalar
	UInt64() (uint64, error)
	Copy() Scalar
	Encode() []byte
	Decode(in []byte) error
	Hex() string
	HexDecode([]byte) error
	MarshalJSON()
	UnmarshalJSON()
	encoding.BinaryMarshaler
	encoding.BinaryUnmarshaler
}

Element interface

// Element interface abstracts common operations on an Element in a prime-order Group.
type Element interface {
	Group() Group
	Base() Element
	Identity() Element
	Add(Element) Element
	Double() Element
	Negate() Element
	Subtract(Element) Element
	Multiply(Scalar) Element
	Equal(element Element) int
	IsIdentity() bool
	Set(Element) Element
	Copy() Element
	Encode() []byte
	XCoordinate() []byte
	Decode(data []byte) error
	Hex() string
	HexDecode([]byte) error
	MarshalJSON() ([]byte, error)
	UnmarshalJSON(data []byte) error
	encoding.BinaryMarshaler
	encoding.BinaryUnmarshaler
}

Documentation

You can find the documentation and usage examples in the package doc and the project wiki .

Versioning

SemVer is used for versioning. For the versions available, see the tags on the repository.

Contributing

Please read CONTRIBUTING.md for details on the code of conduct, and the process for submitting pull requests.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Documentation ¶

Overview ¶

Package ecc exposes a prime-order elliptic curve groups with additional hash-to-curve operations.

It implements the latest hash-to-curve specification to date (https://datatracker.ietf.org/doc/draft-irtf-cfrg-hash-to-curve/).

Constants ¶

This section is empty.

Variables ¶

This section is empty.

Functions ¶

This section is empty.

Types ¶

type Element ¶

type Element struct {
	internal.Element
	// contains filtered or unexported fields
}

Element represents an element on the curve of the prime-order group.

func (*Element) Add ¶

func (e *Element) Add(element *Element) *Element

Add sets the receiver to the sum of the input and the receiver, and returns the receiver.

func (*Element) Base ¶

func (e *Element) Base() *Element

Base sets the element to the group's base point a.k.a. canonical generator.

func (*Element) Copy ¶

func (e *Element) Copy() *Element

Copy returns a copy of the receiver.

func (*Element) Decode ¶

func (e *Element) Decode(data []byte) error

Decode sets the receiver to a decoding of the input data, and returns an error on failure.

func (*Element) DecodeHex ¶

func (e *Element) DecodeHex(h string) error

DecodeHex sets e to the decoding of the hex encoded element.

func (*Element) Double ¶

func (e *Element) Double() *Element

Double sets the receiver to its double, and returns it.

func (*Element) Encode ¶

func (e *Element) Encode() []byte

Encode returns the compressed byte encoding of the element.

func (*Element) Equal ¶

func (e *Element) Equal(element *Element) bool

Equal returns true if the elements are equivalent, and false otherwise.

func (*Element) Group ¶

func (e *Element) Group() Group

Group returns the group's Identifier.

func (*Element) Hex ¶

func (e *Element) Hex() string

Hex returns the fixed-sized hexadecimal encoding of e.

func (*Element) Identity ¶

func (e *Element) Identity() *Element

Identity sets the element to the point at infinity of the Group's underlying curve.

func (*Element) IsIdentity ¶

func (e *Element) IsIdentity() bool

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

func (*Element) MarshalBinary ¶

func (e *Element) MarshalBinary() ([]byte, error)

MarshalBinary returns the compressed byte encoding of the element.

func (*Element) MarshalJSON ¶

func (e *Element) MarshalJSON() ([]byte, error)

MarshalJSON marshals the element into valid JSON.

func (*Element) Multiply ¶

func (e *Element) Multiply(scalar *Scalar) *Element

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

func (*Element) Negate ¶

func (e *Element) Negate() *Element

Negate sets the receiver to its negation, and returns it.

func (*Element) Set ¶

func (e *Element) Set(element *Element) *Element

Set sets the receiver to the argument, and returns the receiver.

func (*Element) Subtract ¶

func (e *Element) Subtract(element *Element) *Element

Subtract subtracts the input from the receiver, and returns the receiver.

func (*Element) UnmarshalBinary ¶

func (e *Element) UnmarshalBinary(data []byte) error

UnmarshalBinary sets e to the decoding of the byte encoded element.

func (*Element) UnmarshalJSON ¶

func (e *Element) UnmarshalJSON(data []byte) error

UnmarshalJSON unmarshals the input into the element.

func (*Element) XCoordinate ¶

func (e *Element) XCoordinate() []byte

XCoordinate returns the encoded x coordinate of the element.

type Group ¶

type Group byte

Group identifies prime-order groups over elliptic curves with hash-to-group operations.

const (
	// Ristretto255Sha512 identifies the Ristretto255 group with SHA2-512 hash-to-group hashing.
	Ristretto255Sha512 Group = 1 + iota

	// P256Sha256 identifies a group over P256 with SHA2-256 hash-to-group hashing.
	P256Sha256

	// P384Sha384 identifies a group over P384 with SHA2-384 hash-to-group hashing.
	P384Sha384

	// P521Sha512 identifies a group over P521 with SHA2-512 hash-to-group hashing.
	P521Sha512

	// Edwards25519Sha512 identifies the Edwards25519 group with SHA2-512 hash-to-group hashing.
	Edwards25519Sha512

	// Secp256k1Sha256 identifies the SECp256k1 group with SHA2-256 hash-to-group hashing.
	Secp256k1Sha256
)

func (Group) Available ¶

func (g Group) Available() bool

Available reports whether the given Group is linked into the binary.

func (Group) Base ¶

func (g Group) Base() *Element

Base returns the group's base point a.k.a. canonical generator.

func (Group) ElementLength ¶

func (g Group) ElementLength() int

ElementLength returns the byte size of an encoded element.

func (Group) EncodeToGroup ¶

func (g Group) EncodeToGroup(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.

func (Group) HashFunc ¶

func (g Group) HashFunc() crypto.Hash

HashFunc returns the RFC9380 associated hash function of the group.

func (Group) HashToGroup ¶

func (g Group) HashToGroup(input, dst []byte) *Element

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.

func (Group) HashToScalar ¶

func (g Group) HashToScalar(input, dst []byte) *Scalar

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.

func (Group) MakeDST ¶

func (g Group) MakeDST(app string, version uint8) []byte

MakeDST builds a domain separation tag in the form of <app>-V<version>-CS<id>-<hash-to-curve-ID>, and returns no error.

func (Group) NewElement ¶

func (g Group) NewElement() *Element

NewElement returns the identity element (point at infinity).

func (Group) NewScalar ¶

func (g Group) NewScalar() *Scalar

NewScalar returns a new scalar set to 0.

func (Group) Order ¶

func (g Group) Order() []byte

Order returns the order of the canonical group of scalars.

func (Group) ScalarLength ¶

func (g Group) ScalarLength() int

ScalarLength returns the byte size of an encoded scalar.

func (Group) String ¶

func (g Group) String() string

String returns the hash-to-curve string identifier of the ciphersuite.

type Scalar ¶

type Scalar struct {
	internal.Scalar
	// contains filtered or unexported fields
}

Scalar represents a scalar in the prime-order group.

func (*Scalar) Add ¶

func (s *Scalar) Add(scalar *Scalar) *Scalar

Add sets the receiver to the sum of the input and the receiver, and returns the receiver.

func (*Scalar) Copy ¶

func (s *Scalar) Copy() *Scalar

Copy returns a copy of the receiver.

func (*Scalar) Decode ¶

func (s *Scalar) Decode(data []byte) error

Decode sets the receiver to a decoding of the input data, and returns an error on failure.

func (*Scalar) DecodeHex ¶

func (s *Scalar) DecodeHex(h string) error

DecodeHex sets s to the decoding of the hex encoded scalar.

func (*Scalar) Encode ¶

func (s *Scalar) Encode() []byte

Encode returns the compressed byte encoding of the scalar.

func (*Scalar) Equal ¶

func (s *Scalar) Equal(scalar *Scalar) bool

Equal returns true if the elements are equivalent, and false otherwise.

func (*Scalar) Group ¶

func (s *Scalar) Group() Group

Group returns the group's Identifier.

func (*Scalar) Hex ¶

func (s *Scalar) Hex() string

Hex returns the fixed-sized hexadecimal encoding of s.

func (*Scalar) Invert ¶

func (s *Scalar) Invert() *Scalar

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

func (*Scalar) IsZero ¶

func (s *Scalar) IsZero() bool

IsZero returns whether the scalar is 0.

func (*Scalar) LessOrEqual ¶

func (s *Scalar) LessOrEqual(scalar *Scalar) bool

LessOrEqual returns 1 if s <= scalar, and 0 otherwise.

func (*Scalar) MarshalBinary ¶

func (s *Scalar) MarshalBinary() ([]byte, error)

MarshalBinary implements the encoding.BinaryMarshaler interface.

func (*Scalar) MarshalJSON ¶

func (s *Scalar) MarshalJSON() ([]byte, error)

MarshalJSON marshals the scalar into valid JSON.

func (*Scalar) MinusOne ¶

func (s *Scalar) MinusOne() *Scalar

MinusOne sets the scalar to order-1, and returns it.

func (*Scalar) Multiply ¶

func (s *Scalar) Multiply(scalar *Scalar) *Scalar

Multiply multiplies the receiver with the input, and returns the receiver.

func (*Scalar) One ¶

func (s *Scalar) One() *Scalar

One sets the scalar to 1, and returns it.

func (*Scalar) Pow ¶

func (s *Scalar) Pow(scalar *Scalar) *Scalar

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

func (*Scalar) Random ¶

func (s *Scalar) Random() *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.

func (*Scalar) Set ¶

func (s *Scalar) Set(scalar *Scalar) *Scalar

Set sets the receiver to the value of the argument scalar, and returns the receiver.

func (*Scalar) SetUInt64 ¶

func (s *Scalar) SetUInt64(i uint64) *Scalar

SetUInt64 sets s to i modulo the field order, and returns an error if one occurs.

func (*Scalar) Subtract ¶

func (s *Scalar) Subtract(scalar *Scalar) *Scalar

Subtract subtracts the input from the receiver, and returns the receiver.

func (*Scalar) UInt64 ¶

func (s *Scalar) UInt64() (uint64, error)

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

func (*Scalar) UnmarshalBinary ¶

func (s *Scalar) UnmarshalBinary(data []byte) error

UnmarshalBinary implements the encoding.BinaryUnmarshaler interface.

func (*Scalar) UnmarshalJSON ¶

func (s *Scalar) UnmarshalJSON(data []byte) error

UnmarshalJSON unmarshals the input into the scalar.

func (*Scalar) Zero ¶

func (s *Scalar) Zero() *Scalar

Zero sets the scalar to 0, and returns it.

Source Files ¶

View all Source files

Directories ¶

Path	Synopsis
debug Package debug provides tools to help debugging.	Package debug provides tools to help debugging.
encoding Package encoding provides serde utilities.	Package encoding provides serde utilities.
internal Package internal defines simple and abstract APIs to group Elements and Scalars.	Package internal defines simple and abstract APIs to group Elements and Scalars.
edwards25519 Package edwards25519 allows simple and abstracted operations in the Edwards25519 group.	Package edwards25519 allows simple and abstracted operations in the Edwards25519 group.
field Package field provides modular operations over very high integers.	Package field provides modular operations over very high integers.
nist Package nist allows simple and abstracted operations in the NIST P-256, P-384, and P-521 groups, wrapping filippo.io/nistec.	Package nist allows simple and abstracted operations in the NIST P-256, P-384, and P-521 groups, wrapping filippo.io/nistec.
ristretto Package ristretto allows simple and abstracted operations in the Ristretto255 group.	Package ristretto allows simple and abstracted operations in the Ristretto255 group.
secp256k1 Package secp256k1 allows simple and abstracted operations in the Secp256k1 group.	Package secp256k1 allows simple and abstracted operations in the Secp256k1 group.

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL