crypto

package module
v0.7.1 Latest Latest
Warning

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

 Go to latest Published: Jun 13, 2024 License: MIT Imports: 9 Imported by: 9

README

Prime-order Elliptic Curve Groups

CI Go Reference codecov

  import "github.com/bytemare/crypto"

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 is made so you can swap between primitives with no code change and only the Group identifier. The package serves as an interface to optimized and secure implementations that serve as backends, and to which you don't need to adapt.

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

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

Prime-order 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 interface
// 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() string
}
Scalar interface
// Scalar interface abstracts common operations on scalars in a prime-order Group.
type Scalar interface {
    Zero() Scalar
    One() Scalar
    Random() Scalar
    Add(Scalar) Scalar
    Subtract(Scalar) Scalar
    Multiply(Scalar) Scalar
    Pow(Scalar) Scalar
    Invert() Scalar
    Equal(Scalar) int
    LessOrEqual(Scalar) int
    IsZero() bool
    Set(Scalar) Scalar
    SetUInt64(uint64) Scalar
    UInt64() (uint64, error)
    Copy() Scalar
    Encode() []byte
    Decode(in []byte) error
	Hex() string
	HexDecode([]byte) error
    encoding.BinaryMarshaler
    encoding.BinaryUnmarshaler
}
Element interface
// Element interface abstracts common operations on an Element in a prime-order Group.
type Element interface {
    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
    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 crypto exposes a prime-order elliptic curve groups with additional hash-to-curve operations.

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

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

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 added in v0.7.0 

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) int

Equal returns 1 if the elements are equivalent, and 0 otherwise.

func (*Element) Hex added in v0.7.0 

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) 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) XCoordinate added in v0.4.0 

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

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

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 added in v0.7.1 

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 added in v0.3.3 

func (g Group) Order() string

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 added in v0.7.0 

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) int

Equal returns 1 if the scalars are equal, and 0 otherwise.

func (*Scalar) Hex added in v0.7.0 

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 added in v0.3.4 

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

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) 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 added in v0.3.4 

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 added in v0.7.0 

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 added in v0.7.0 

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) 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 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.
 Package nist allows simple and abstracted operations in the NIST P-256, P-384, and P-521 groups.
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.