crypto

package module

v0.7.5 Latest Latest Go to latest Published: Jul 7, 2024 License: MIT Imports: 10 Imported by: 9

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/bytemare/crypto

Links

Open Source Insights

README ¶

Prime-order Elliptic Curve Groups

  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

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.

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.

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) MarshalJSON ¶ added in v0.7.2

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

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

UnmarshalJSON unmarshals the input into the 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) MarshalJSON ¶ added in v0.7.2

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

MarshalJSON marshals the scalar into valid JSON.

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) UnmarshalJSON ¶ added in v0.7.2

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

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