README
¶
filippo.io/edwards25519
import "filippo.io/edwards25519"
This library implements the edwards25519 elliptic curve, exposing the necessary APIs to build a wide array of higher-level primitives. Read the docs at pkg.go.dev/filippo.io/edwards25519.
The code is originally derived from Adam Langley's internal implementation in the Go standard library, and includes George Tankersley's performance improvements. It was then further developed by Henry de Valence for use in ristretto255, and was finally merged back into the Go standard library as of Go 1.17. It now tracks the upstream codebase and extends it with additional functionality.
Most users don't need this package, and should instead use crypto/ed25519 for signatures, golang.org/x/crypto/curve25519 for Diffie-Hellman, or github.com/gtank/ristretto255 for prime order group logic. However, for anyone currently using a fork of crypto/internal/edwards25519/crypto/ed25519/internal/edwards25519 or github.com/agl/edwards25519, this package should be a safer, faster, and more powerful alternative.
Since this package is meant to curb proliferation of edwards25519 implementations in the Go ecosystem, it welcomes requests for new APIs or reviewable performance improvements.
Documentation
¶
Overview ¶
Package edwards25519 implements group logic for the twisted Edwards curve
-x^2 + y^2 = 1 + -(121665/121666)*x^2*y^2
This is better known as the Edwards curve equivalent to Curve25519, and is the curve used by the Ed25519 signature scheme.
Most users don't need this package, and should instead use crypto/ed25519 for signatures, golang.org/x/crypto/curve25519 for Diffie-Hellman, or github.com/gtank/ristretto255 for prime order group logic.
However, developers who do need to interact with low-level edwards25519 operations can use this package, which is an extended version of crypto/internal/edwards25519 from the standard library repackaged as an importable module.
Index ¶
- type Point
- func (v *Point) Add(p, q *Point) *Point
- func (v *Point) Bytes() []byte
- func (v *Point) BytesMontgomery() []byte
- func (v *Point) CheckInitialized() bool
- func (v *Point) Equal(u *Point) int
- func (v *Point) ExtendedCoordinates() (X, Y, Z, T *field.Element)
- func (v *Point) MultByCofactor(p *Point) *Point
- func (v *Point) MultiScalarMult(scalars []*Scalar, points []*Point) *Point
- func (v *Point) Negate(p *Point) *Point
- func (v *Point) ScalarBaseMult(x *Scalar) *Point
- func (v *Point) ScalarMult(x *Scalar, q *Point) *Point
- func (v *Point) Set(u *Point) *Point
- func (v *Point) SetBytes(x []byte) (*Point, error)
- func (v *Point) SetExtendedCoordinates(X, Y, Z, T *field.Element) (*Point, error)
- func (v *Point) Subtract(p, q *Point) *Point
- func (v *Point) VarTimeDoubleScalarBaseMult(a *Scalar, A *Point, b *Scalar) *Point
- func (v *Point) VarTimeMultiScalarMult(scalars []*Scalar, points []*Point) *Point
- type Scalar
- func (s *Scalar) Add(x, y *Scalar) *Scalar
- func (s *Scalar) Bytes() []byte
- func (s *Scalar) Equal(t *Scalar) int
- func (s *Scalar) Invert(t *Scalar) *Scalar
- func (s *Scalar) Multiply(x, y *Scalar) *Scalar
- func (s *Scalar) MultiplyAdd(x, y, z *Scalar) *Scalar
- func (s *Scalar) Negate(x *Scalar) *Scalar
- func (s *Scalar) Set(x *Scalar) *Scalar
- func (s *Scalar) SetBytesWithClamping(x []byte) (*Scalar, error)
- func (s *Scalar) SetCanonicalBytes(x []byte) (*Scalar, error)
- func (s *Scalar) SetUniformBytes(x []byte) (*Scalar, error)
- func (s *Scalar) Subtract(x, y *Scalar) *Scalar
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Point ¶
type Point struct {
// contains filtered or unexported fields
}
Point represents a point on the edwards25519 curve.
This type works similarly to math/big.Int, and all arguments and receivers are allowed to alias.
The zero value is NOT valid, and it may be used only as a receiver.
func NewGeneratorPoint ¶
func NewGeneratorPoint() *Point
NewGeneratorPoint returns a new Point set to the canonical generator.
func NewIdentityPoint ¶
func NewIdentityPoint() *Point
NewIdentityPoint returns a new Point set to the identity.
func (*Point) Bytes ¶
Bytes returns the canonical 32-byte encoding of v, according to RFC 8032, Section 5.1.2.
func (*Point) BytesMontgomery ¶
BytesMontgomery converts v to a point on the birationally-equivalent Curve25519 Montgomery curve, and returns its canonical 32 bytes encoding according to RFC 7748.
Note that BytesMontgomery only encodes the u-coordinate, so v and -v encode to the same value. If v is the identity point, BytesMontgomery returns 32 zero bytes, analogously to the X25519 function.
The lack of an inverse operation (such as SetMontgomeryBytes) is deliberate: while every valid edwards25519 point has a unique u-coordinate Montgomery encoding, X25519 accepts inputs on the quadratic twist, which don't correspond to any edwards25519 point, and every other X25519 input corresponds to two edwards25519 points.
func (*Point) CheckInitialized ¶
func (*Point) ExtendedCoordinates ¶
ExtendedCoordinates returns v in extended coordinates (X:Y:Z:T) where x = X/Z, y = Y/Z, and xy = T/Z as in https://eprint.iacr.org/2008/522.
func (*Point) MultByCofactor ¶
MultByCofactor sets v = 8 * p, and returns v.
func (*Point) MultiScalarMult ¶
MultiScalarMult sets v = sum(scalars[i] * points[i]), and returns v.
Execution time depends only on the lengths of the two slices, which must match.
func (*Point) ScalarBaseMult ¶
ScalarBaseMult sets v = x * B, where B is the canonical generator, and returns v.
The scalar multiplication is done in constant time.
func (*Point) ScalarMult ¶
ScalarMult sets v = x * q, and returns v.
The scalar multiplication is done in constant time.
func (*Point) SetBytes ¶
SetBytes sets v = x, where x is a 32-byte encoding of v. If x does not represent a valid point on the curve, SetBytes returns nil and an error and the receiver is unchanged. Otherwise, SetBytes returns v.
Note that SetBytes accepts all non-canonical encodings of valid points. That is, it follows decoding rules that match most implementations in the ecosystem rather than RFC 8032.
func (*Point) SetExtendedCoordinates ¶
SetExtendedCoordinates sets v = (X:Y:Z:T) in extended coordinates where x = X/Z, y = Y/Z, and xy = T/Z as in https://eprint.iacr.org/2008/522.
If the coordinates are invalid or don't represent a valid point on the curve, SetExtendedCoordinates returns nil and an error and the receiver is unchanged. Otherwise, SetExtendedCoordinates returns v.
func (*Point) VarTimeDoubleScalarBaseMult ¶
VarTimeDoubleScalarBaseMult sets v = a * A + b * B, where B is the canonical generator, and returns v.
Execution time depends on the inputs.
type Scalar ¶
type Scalar struct {
// contains filtered or unexported fields
}
A Scalar is an integer modulo
l = 2^252 + 27742317777372353535851937790883648493
which is the prime order of the edwards25519 group.
This type works similarly to math/big.Int, and all arguments and receivers are allowed to alias.
The zero value is a valid zero element.
func (*Scalar) Invert ¶
Invert sets s to the inverse of a nonzero scalar v, and returns s.
If t is zero, Invert returns zero.
func (*Scalar) MultiplyAdd ¶
MultiplyAdd sets s = x * y + z mod l, and returns s. It is equivalent to using Multiply and then Add.
func (*Scalar) SetBytesWithClamping ¶
SetBytesWithClamping applies the buffer pruning described in RFC 8032, Section 5.1.5 (also known as clamping) and sets s to the result. The input must be 32 bytes, and it is not modified. If x is not of the right length, SetBytesWithClamping returns nil and an error, and the receiver is unchanged.
Note that since Scalar values are always reduced modulo the prime order of the curve, the resulting value will not preserve any of the cofactor-clearing properties that clamping is meant to provide. It will however work as expected as long as it is applied to points on the prime order subgroup, like in Ed25519. In fact, it is lost to history why RFC 8032 adopted the irrelevant RFC 7748 clamping, but it is now required for compatibility.
func (*Scalar) SetCanonicalBytes ¶
SetCanonicalBytes sets s = x, where x is a 32-byte little-endian encoding of s, and returns s. If x is not a canonical encoding of s, SetCanonicalBytes returns nil and an error, and the receiver is unchanged.
func (*Scalar) SetUniformBytes ¶
SetUniformBytes sets s = x mod l, where x is a 64-byte little-endian integer. If x is not of the right length, SetUniformBytes returns nil and an error, and the receiver is unchanged.
SetUniformBytes can be used to set s to a uniformly distributed value given 64 uniformly distributed random bytes.
Source Files
Directories