secp256k1

package module
v0.3.0 Latest Latest
Warning

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

 Go to latest Published: May 7, 2025 License: MIT Imports: 15 Imported by: 1

README

secp256k1

secp256k1 Go Reference codecov

  import "github.com/bytemare/secp256k1"

This package implements the secp256k1 prime-order elliptic curve group with

  • RFC9380 hash-to-curve capabilities
  • complete addition formulas
  • formally verified scalar and field arithmetics provided by Fiat-Crypto
  • square root in the field and inversions generated by addchain
  • great effort for constant-time operations where possible
  • no external dependencies outside the standard go library

Documentation Go Reference

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

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 secp256k1 allows simple and abstracted operations in the secp256k1 group.

Example (ScalarMult)

Example_ScalarMult shows how to do a scalar multiplication. 

package main

import (
	"github.com/bytemare/secp256k1"
)

func main() {
	// Get an element. Here, we're taking the group generator.
	g := secp256k1.Base()

	// Get a scalar, e.g. a random one.
	s := secp256k1.NewScalar().Random()

	// Multiply. Boom.
	g.Multiply(s)

}

Index

Examples

Constants

View Source 
const (
	// H2CSECP256K1 represents the hash-to-curve string identifier for secp256k1.
	H2CSECP256K1 = "secp256k1_XMD:SHA-256_SSWU_RO_"

	// E2CSECP256K1 represents the encode-to-curve string identifier for secp256k1.
	E2CSECP256K1 = "secp256k1_XMD:SHA-256_SSWU_NU_"
)

Variables

This section is empty.

Functions

func Ciphersuite 

func Ciphersuite() string

Ciphersuite returns the hash-to-curve ciphersuite identifier.

func ElementLength 

func ElementLength() int

ElementLength returns the byte size of an encoded element.

func Order 

func Order() []byte

Order returns the order of the canonical group of scalars.

func ScalarLength 

func ScalarLength() int

ScalarLength returns the byte size of an encoded Scalar.

func Secp256Polynomial added in v0.2.0 

func Secp256Polynomial(y, x *field.Element)

Secp256Polynomial applies y^2=x^3+ax+b (with a = 0) to recover y^2 from x.

Types

type Element 

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

Element implements the Element interface for the secp256k1 group element.

func Base 

func Base() *Element

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

func EncodeToGroup 

func 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 HashToGroup 

func 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 IsogenySecp256k13iso added in v0.2.1 

func IsogenySecp256k13iso(e *Element) *Element

IsogenySecp256k13iso is a 3-degree isogeny from secp256k1 3-ISO to the secp256k1 elliptic curve. It handles exceptional cases where inversions to denominators evaluate to 0.

func NewElement 

func NewElement() *Element

NewElement returns a new element set to the identity point.

func SSWU added in v0.2.1 

func SSWU(e *field.Element) *Element

SSWU applies the Simplified Shallue-van de Woestijne-Ulas (SWU) method to map e to a point on the secp256k1 3-ISO curve in affine coordinates. Note that calling IsogenySecp256k13iso() is necessary to then get a point on secpk256k1.

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.

Example

ExampleElement_Decode shows how to decode data into elements. 

package main

import (
	"encoding/hex"
	"fmt"

	"github.com/bytemare/secp256k1"
)

func main() {
	// Let's say we have this element.
	g := secp256k1.Base()

	// Let's have a look at it.
	fmt.Println(g.Hex())

	// Which yields the following:
	out := "0279be667ef9dcbbac55a06295ce870b07029bfcdb2dce28d959f2815b16f81798"

	// Let's get its byte representation.
	b, _ := hex.DecodeString(out)

	// And decode it into another element.
	e := secp256k1.NewElement()
	if err := e.Decode(b); err != nil {
		fmt.Println(err.Error())
	}

	// Let's check for completeness.
	if e.Equal(g) != 1 {
		fmt.Println("something went wrong")
	}

}

Output:
0279be667ef9dcbbac55a06295ce870b07029bfcdb2dce28d959f2815b16f81798

func (*Element) DecodeCompressed added in v0.2.0 

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

DecodeCompressed sets the receiver to a decoding of the input data in compressed form, and returns an error on failure.

func (*Element) DecodeCoordinates added in v0.2.0 

func (e *Element) DecodeCoordinates(x, y [32]byte) error

DecodeCoordinates set the receiver to the decoding of the affine coordinates given by x and y, and returns an error on failure.

func (*Element) DecodeHex added in v0.1.4 

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

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

func (*Element) DecodeUncompressed added in v0.2.0 

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

DecodeUncompressed sets the receiver to a decoding of the input data in uncompressed form, and returns an error on failure.

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

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

EncodeUncompressed returns the uncompressed 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.1.4 

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 value of 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 

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

XCoordinate returns the encoded x coordinate of the element, which is the same as Encode() without the header.

type Scalar 

type Scalar struct {
	S scalar.MontgomeryDomainFieldElement
	// contains filtered or unexported fields
}

Scalar implements the Scalar interface for Edwards25519 group scalars.

func HashToScalar 

func 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 NewScalar 

func NewScalar() *Scalar

NewScalar returns a new Scalar set to 0.

func (*Scalar) Add 

func (s *Scalar) Add(t *Scalar) *Scalar

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

func (*Scalar) Bits added in v0.2.0 

func (s *Scalar) Bits() [256]uint8

Bits returns the bit expansion of the receiver.

func (*Scalar) CSelect added in v0.2.0 

func (s *Scalar) CSelect(cond uint64, u, v *Scalar) error

CSelect sets the receiver to u if cond == 0, and to v otherwise, in constant-time.

func (*Scalar) Copy 

func (s *Scalar) Copy() *Scalar

Copy returns a copy of the receiver.

func (*Scalar) Decode 

func (s *Scalar) Decode(in []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.1.4 

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(t *Scalar) int

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

func (*Scalar) Hex added in v0.1.4 

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

func (*Scalar) IsOne added in v0.2.0 

func (s *Scalar) IsOne() bool

IsOne returns whether s == 1.

func (*Scalar) IsZero 

func (s *Scalar) IsZero() bool

IsZero returns whether the Scalar is 0.

func (*Scalar) LessOrEqual 

func (s *Scalar) LessOrEqual(t *Scalar) uint64

LessOrEqual returns 1 if s <= t and 0 otherwise.

func (*Scalar) MarshalBinary 

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

MarshalBinary returns the compressed byte encoding of the Scalar.

func (*Scalar) MinusOne added in v0.1.5 

func (s *Scalar) MinusOne() *Scalar

MinusOne sets the Scalar to -1 = p-1, and returns it.

func (*Scalar) Multiply 

func (s *Scalar) Multiply(t *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(t *Scalar) *Scalar

Pow sets s to s^t modulo the group order, and returns s. If t is nil or equals 0, s is set to 1. Now using variable time big.Int because for some reason I can't get the constant time algorithm to work on Fiat.

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(t *Scalar) *Scalar

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

func (*Scalar) SetUInt64 added in v0.1.3 

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

SetUInt64 sets s to i modulo the group order, and returns it.

func (*Scalar) Square added in v0.2.0 

func (s *Scalar) Square() *Scalar

Square sets the receiver to its square.

func (*Scalar) Subtract 

func (s *Scalar) Subtract(t *Scalar) *Scalar

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

func (*Scalar) UnmarshalBinary 

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

UnmarshalBinary sets e to the decoding of the byte encoded 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
field
Package field implements the base field for elements on the curve SECP256k1 building on Fiat-Crypto.
 Package field implements the base field for elements on the curve SECP256k1 building on Fiat-Crypto.
scalar
Package scalar implements prime-order scalar operations in the SECP256k1 group building on Fiat-Crypto.
 Package scalar implements prime-order scalar operations in the SECP256k1 group building on Fiat-Crypto.

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.