ecc

package module
v0.8.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 5, 2024 License: MIT Imports: 10 Imported by: 6

README

Elliptic Curve Groups

CI Go Reference codecov

  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 Go Reference

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/).

Index

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
Package debug provides tools to help debugging.
 Package debug provides tools to help debugging.
Package encoding provides serde utilities.
 Package encoding provides serde utilities.
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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.