ecdsa

Documentation

Overview

Package ecdsa provides ECDSA signature scheme on the secp256k1 curve.

The implementation is adapted from https://pkg.go.dev/crypto/ecdsa. Copyright 2011 The Go Authors. All rights reserved. Use of this source code is governed by a BSD-style license that can be found in the LICENSE file.

Documentation: - Wikipedia: https://en.wikipedia.org/wiki/Elliptic_Curve_Digital_Signature_Algorithm - FIPS 186-4: https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-4.pdf - SEC 1, v-2: https://www.secg.org/sec1-v2.pdf

Index

• Variables
• func HashToInt(hash []byte) *big.Int
• type PrivateKey
  • func GenerateKey(rand io.Reader) (*PrivateKey, error)
  • func (privKey *PrivateKey) Bytes() []byte
  • func (privKey *PrivateKey) Public() signature.PublicKey
  • func (privKey *PrivateKey) SetBytes(buf []byte) (int, error)
  • func (privKey *PrivateKey) Sign(message []byte, hFunc hash.Hash) ([]byte, error)
  • func (privKey *PrivateKey) SignForRecover(message []byte, hFunc hash.Hash) (v uint, r, s *big.Int, err error)
• type PublicKey
  • func (pk *PublicKey) Bytes() []byte
  • func (pub *PublicKey) Equal(x signature.PublicKey) bool
  • func (pk *PublicKey) RecoverFrom(msg []byte, v uint, r, s *big.Int) error
  • func (pk *PublicKey) SetBytes(buf []byte) (int, error)
  • func (publicKey *PublicKey) Verify(sigBin, message []byte, hFunc hash.Hash) (bool, error)
• type Signature
  • func (sig *Signature) Bytes() []byte
  • func (sig *Signature) SetBytes(buf []byte) (int, error)

Variables

var (
	// ErrNoSqrtR is returned when x^3+ax+b is not a square in the field. This
	// is used for public key recovery and allows to detect if the signature is
	// valid or not.
	ErrNoSqrtR = errors.New("x^3+ax+b is not a square in the field")
)

Functions

func HashToInt

func HashToInt(hash []byte) *big.Int

HashToInt converts a hash value to an integer. Per FIPS 186-4, Section 6.4, we use the left-most bits of the hash to match the bit-length of the order of the curve. This also performs Step 5 of SEC 1, Version 2.0, Section 4.1.3.

Types

type PrivateKey

type PrivateKey struct {
	PublicKey PublicKey
	// contains filtered or unexported fields
}

PrivateKey represents an ECDSA private key

func GenerateKey

func GenerateKey(rand io.Reader) (*PrivateKey, error)

GenerateKey generates a public and private key pair.

func (*PrivateKey) Bytes

func (privKey *PrivateKey) Bytes() []byte

Bytes returns the binary representation of pk, as byte array publicKey||scalar where publicKey is as publicKey.Bytes(), and scalar is in big endian, of size sizeFr.

func (*PrivateKey) Public

func (privKey *PrivateKey) Public() signature.PublicKey

Public returns the public key associated to the private key.

func (*PrivateKey) SetBytes

func (privKey *PrivateKey) SetBytes(buf []byte) (int, error)

SetBytes sets pk from buf, where buf is interpreted as publicKey||scalar where publicKey is as publicKey.Bytes(), and scalar is in big endian, of size sizeFr. It returns the number byte read.

func (*PrivateKey) Sign

func (privKey *PrivateKey) Sign(message []byte, hFunc hash.Hash) ([]byte, error)

Sign performs the ECDSA signature

k ← 𝔽r (random) P = k ⋅ g1Gen r = x_P (mod order) s = k⁻¹ . (m + sk ⋅ r) signature = {r, s}

SEC 1, Version 2.0, Section 4.1.3

func (*PrivateKey) SignForRecover

func (privKey *PrivateKey) SignForRecover(message []byte, hFunc hash.Hash) (v uint, r, s *big.Int, err error)

SignForRecover performs the ECDSA signature and returns public key recovery information

k ← 𝔽r (random) P = k ⋅ g1Gen r = x_P (mod order) s = k⁻¹ . (m + sk ⋅ r) v = (div(x_P, order)<<1) || y_P[-1]

SEC 1, Version 2.0, Section 4.1.3

type PublicKey

type PublicKey struct {
	A secp256k1.G1Affine
}

PublicKey represents an ECDSA public key

func (*PublicKey) Bytes

func (pk *PublicKey) Bytes() []byte

Bytes returns the binary representation of the public key follows https://tools.ietf.org/html/rfc8032#section-3.1 and returns a compressed representation of the point (x,y)

x, y are the coordinates of the point on the curve as big endian integers. compressed representation store x with a parity bit to recompute y

func (*PublicKey) Equal

func (pub *PublicKey) Equal(x signature.PublicKey) bool

Equal compares 2 public keys

func (*PublicKey) RecoverFrom

func (pk *PublicKey) RecoverFrom(msg []byte, v uint, r, s *big.Int) error

RecoverFrom recovers the public key from the message msg, recovery information v and decompose signature {r,s}. If recovery succeeded, the methods sets the current public key to the recovered value. Otherwise returns error and leaves current public key unchanged.

func (*PublicKey) SetBytes

func (pk *PublicKey) SetBytes(buf []byte) (int, error)

SetBytes sets p from binary representation in buf. buf represents a public key as x||y where x, y are interpreted as big endian binary numbers corresponding to the coordinates of a point on the curve. It returns the number of bytes read from the buffer.

func (*PublicKey) Verify

func (publicKey *PublicKey) Verify(sigBin, message []byte, hFunc hash.Hash) (bool, error)

Verify validates the ECDSA signature

R ?= (s⁻¹ ⋅ m ⋅ Base + s⁻¹ ⋅ R ⋅ publiKey)_x

SEC 1, Version 2.0, Section 4.1.4

type Signature

type Signature struct {
	R, S [sizeFr]byte
}

Signature represents an ECDSA signature

func (*Signature) Bytes

func (sig *Signature) Bytes() []byte

Bytes returns the binary representation of sig as a byte array of size 2*sizeFr r||s

func (*Signature) SetBytes

func (sig *Signature) SetBytes(buf []byte) (int, error)

SetBytes sets sig from a buffer in binary. buf is read interpreted as r||s It returns the number of bytes read from buf.