ecdsa

package
v3.0.1 Latest Latest
Warning

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

 Go to latest Published: Jun 10, 2023 License: ISC Imports: 3 Imported by: 35

README

ecdsa

Build Status ISC License GoDoc

Package ecdsa provides secp256k1-optimized ECDSA signing and verification.

This package provides data structures and functions necessary to produce and verify deterministic canonical signatures in accordance with RFC6979 and BIP0062, optimized specifically for the secp256k1 curve using the Elliptic Curve Digital Signature Algorithm (ECDSA), as defined in FIPS 186-3. See https://www.secg.org/sec2-v2.pdf for details on the secp256k1 standard.

It also provides functions to parse and serialize the ECDSA signatures with the more strict Distinguished Encoding Rules (DER) of ISO/IEC 8825-1 and some additional restrictions specific to secp256k1.

In addition, it supports a custom "compact" signature format which allows efficient recovery of the public key from a given valid signature and message hash combination.

A comprehensive suite of tests is provided to ensure proper functionality.

ECDSA use in Decred

At the time of this writing, ECDSA signatures are heavily used for proving coin ownership in Decred as the vast majority of transactions consist of what is effectively transferring ownership of coins to a public key associated with a private key only known to the recipient of the coins along with an encumbrance that requires an ECDSA signature that proves the new owner possesses the private key without actually revealing it.

Installation and Updating

$ go get -u github.com/decred/dcrd/dcrec/secp25k1/v3/ecdsa

Examples

  • Sign Message
    Demonstrates signing a message with a secp256k1 private key that is first parsed from raw bytes and serializing the generated signature.

  • Verify Signature
    Demonstrates verifying a secp256k1 signature against a public key that is first parsed from raw bytes. The signature is also parsed from raw bytes.

License

Package ecdsa is licensed under the copyfree ISC License.

Documentation

Overview

Package ecdsa provides secp256k1-optimized ECDSA signing and verification.

This package provides data structures and functions necessary to produce and verify deterministic canonical signatures in accordance with RFC6979 and BIP0062, optimized specifically for the secp256k1 curve using the Elliptic Curve Digital Signature Algorithm (ECDSA), as defined in FIPS 186-3. See https://www.secg.org/sec2-v2.pdf for details on the secp256k1 standard.

It also provides functions to parse and serialize the ECDSA signatures with the more strict Distinguished Encoding Rules (DER) of ISO/IEC 8825-1 and some additional restrictions specific to secp256k1.

In addition, it supports a custom "compact" signature format which allows efficient recovery of the public key from a given valid signature and message hash combination.

A comprehensive suite of tests is provided to ensure proper functionality.

ECDSA use in Decred

At the time of this writing, ECDSA signatures are heavily used for proving coin ownership in Decred as the vast majority of transactions consist of what is effectively transferring ownership of coins to a public key associated with a private key only known to the recipient of the coins along with an encumbrance that requires an ECDSA signature that proves the new owner possesses the private key without actually revealing it.

Errors

Errors returned by this package are of type ecdsa.Error and fully support the standard library errors.Is and errors.As functions. This allows the caller to programmatically determine the specific error by examining the ErrorCode field of the type asserted ecdsa.Error while still providing rich error messages with contextual information. See ErrorCode in the package documentation for a full list.

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

func RecoverCompact 

func RecoverCompact(signature, hash []byte) (*secp256k1.PublicKey, bool, error)

RecoverCompact attempts to recover the secp256k1 public key from the provided compact signature and message hash. It first verifies the signature, and, if the signature matches then the recovered public key will be returned as well as a boolean indicating whether or not the original key was compressed.

func SignCompact 

func SignCompact(key *secp256k1.PrivateKey, hash []byte, isCompressedKey bool) []byte

SignCompact produces a compact ECDSA signature over the secp256k1 curve for the provided hash (which should be the result of hashing a larger message) using the given private key. The isCompressedKey parameter specifies if the produced signature should reference a compressed public key or not.

Compact signature format: <1-byte compact sig recovery code><32-byte R><32-byte S>

The compact sig recovery code is the value 27 + public key recovery code + 4 if the compact signature was created with a compressed public key.

Types

type Error 

type Error struct {
	ErrorCode   ErrorCode
	Description string
}

Error identifies a signature-related error. It has full support for errors.Is and errors.As, so the caller can ascertain the specific reason for the error by checking the underlying error code.

func (Error) Error 

func (e Error) Error() string

Error satisfies the error interface and prints human-readable errors.

func (Error) Is 

func (e Error) Is(target error) bool

Is implements the interface to work with the standard library's errors.Is.

It returns true in the following cases: - The target is a Error and the error codes match - The target is a ErrorCode and it the error codes match

func (Error) Unwrap 

func (e Error) Unwrap() error

Unwrap returns the underlying wrapped error code.

type ErrorCode 

type ErrorCode int

ErrorCode identifies a kind of signature error. It has full support for errors.Is and errors.As, so the caller can directly check against an error code when determining the reason for an error. 

const (
	// ErrSigTooShort is returned when a signature that should be a DER
	// signature is too short.
	ErrSigTooShort ErrorCode = iota

	// ErrSigTooLong is returned when a signature that should be a DER signature
	// is too long.
	ErrSigTooLong

	// ErrSigInvalidSeqID is returned when a signature that should be a DER
	// signature does not have the expected ASN.1 sequence ID.
	ErrSigInvalidSeqID

	// ErrSigInvalidDataLen is returned when a signature that should be a DER
	// signature does not specify the correct number of remaining bytes for the
	// R and S portions.
	ErrSigInvalidDataLen

	// ErrSigMissingSTypeID is returned when a signature that should be a DER
	// signature does not provide the ASN.1 type ID for S.
	ErrSigMissingSTypeID

	// ErrSigMissingSLen is returned when a signature that should be a DER
	// signature does not provide the length of S.
	ErrSigMissingSLen

	// ErrSigInvalidSLen is returned when a signature that should be a DER
	// signature does not specify the correct number of bytes for the S portion.
	ErrSigInvalidSLen

	// ErrSigInvalidRIntID is returned when a signature that should be a DER
	// signature does not have the expected ASN.1 integer ID for R.
	ErrSigInvalidRIntID

	// ErrSigZeroRLen is returned when a signature that should be a DER
	// signature has an R length of zero.
	ErrSigZeroRLen

	// ErrSigNegativeR is returned when a signature that should be a DER
	// signature has a negative value for R.
	ErrSigNegativeR

	// ErrSigTooMuchRPadding is returned when a signature that should be a DER
	// signature has too much padding for R.
	ErrSigTooMuchRPadding

	// ErrSigRIsZero is returned when a signature has R set to the value zero.
	ErrSigRIsZero

	// ErrSigRTooBig is returned when a signature has R with a value that is
	// greater than or equal to the group order.
	ErrSigRTooBig

	// ErrSigInvalidSIntID is returned when a signature that should be a DER
	// signature does not have the expected ASN.1 integer ID for S.
	ErrSigInvalidSIntID

	// ErrSigZeroSLen is returned when a signature that should be a DER
	// signature has an S length of zero.
	ErrSigZeroSLen

	// ErrSigNegativeS is returned when a signature that should be a DER
	// signature has a negative value for S.
	ErrSigNegativeS

	// ErrSigTooMuchSPadding is returned when a signature that should be a DER
	// signature has too much padding for S.
	ErrSigTooMuchSPadding

	// ErrSigSIsZero is returned when a signature has S set to the value zero.
	ErrSigSIsZero

	// ErrSigSTooBig is returned when a signature has S with a value that is
	// greater than or equal to the group order.
	ErrSigSTooBig
)

These constants are used to identify a specific Error.

func (ErrorCode) Error 

func (e ErrorCode) Error() string

Error implements the error interface.

func (ErrorCode) Is 

func (e ErrorCode) Is(target error) bool

Is implements the interface to work with the standard library's errors.Is.

It returns true in the following cases: - The target is a Error and the error codes match - The target is a ErrorCode and the error codes match

func (ErrorCode) String 

func (e ErrorCode) String() string

String returns the ErrorCode as a human-readable name.

type Signature 

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

Signature is a type representing an ECDSA signature.

func NewSignature 

func NewSignature(r, s *secp256k1.ModNScalar) *Signature

NewSignature instantiates a new signature given some r and s values.

func ParseDERSignature 

func ParseDERSignature(sig []byte) (*Signature, error)

ParseDERSignature parses a signature in the Distinguished Encoding Rules (DER) format per section 10 of [ISO/IEC 8825-1] and enforces the following additional restrictions specific to secp256k1:

- The R and S values must be in the valid range for secp256k1 scalars:

  • Negative values are rejected
  • Zero is rejected
  • Values greater than or equal to the secp256k1 group order are rejected

func Sign 

func Sign(key *secp256k1.PrivateKey, hash []byte) *Signature

Sign generates an ECDSA signature over the secp256k1 curve for the provided hash (which should be the result of hashing a larger message) using the given private key. The produced signature is deterministic (same message and same key yield the same signature) and canonical in accordance with RFC6979 and BIP0062.

Example

This example demonstrates signing a message with a secp256k1 private key that is first parsed from raw bytes and serializing the generated signature. 

// Decode a hex-encoded private key.
pkBytes, err := hex.DecodeString("22a47fa09a223f2aa079edf85a7c2d4f87" +
	"20ee63e502ee2869afab7de234b80c")
if err != nil {
	fmt.Println(err)
	return
}
privKey := secp256k1.PrivKeyFromBytes(pkBytes)

// Sign a message using the private key.
message := "test message"
messageHash := chainhash.HashB([]byte(message))
signature := ecdsa.Sign(privKey, messageHash)

// Serialize and display the signature.
fmt.Printf("Serialized Signature: %x\n", signature.Serialize())

// Verify the signature for the message using the public key.
pubKey := privKey.PubKey()
verified := signature.Verify(messageHash, pubKey)
fmt.Printf("Signature Verified? %v\n", verified)

Output:

Serialized Signature: 3045022100fcc0a8768cfbcefcf2cadd7cfb0fb18ed08dd2e2ae84bef1a474a3d351b26f0302200fc1a350b45f46fa00101391302818d748c2b22615511a3ffd5bb638bd777207
Signature Verified? true

func (*Signature) IsEqual 

func (sig *Signature) IsEqual(otherSig *Signature) bool

IsEqual compares this Signature instance to the one passed, returning true if both Signatures are equivalent. A signature is equivalent to another, if they both have the same scalar value for R and S.

func (*Signature) Serialize 

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

Serialize returns the ECDSA signature in the Distinguished Encoding Rules (DER) format per section 10 of [ISO/IEC 8825-1] and such that the S component of the signature is less than or equal to the half order of the group.

Note that the serialized bytes returned do not include the appended hash type used in Decred signature scripts.

func (*Signature) Verify 

func (sig *Signature) Verify(hash []byte, pubKey *secp256k1.PublicKey) bool

Verify returns whether or not the signature is valid for the provided hash and secp256k1 public key.

Example

This example demonstrates verifying a secp256k1 signature against a public key that is first parsed from raw bytes. The signature is also parsed from raw bytes. 

// Decode hex-encoded serialized public key.
pubKeyBytes, err := hex.DecodeString("02a673638cb9587cb68ea08dbef685c" +
	"6f2d2a751a8b3c6f2a7e9a4999e6e4bfaf5")
if err != nil {
	fmt.Println(err)
	return
}
pubKey, err := secp256k1.ParsePubKey(pubKeyBytes)
if err != nil {
	fmt.Println(err)
	return
}

// Decode hex-encoded serialized signature.
sigBytes, err := hex.DecodeString("3045022100fcc0a8768cfbcefcf2cadd7cfb0" +
	"fb18ed08dd2e2ae84bef1a474a3d351b26f0302200fc1a350b45f46fa0010139130" +
	"2818d748c2b22615511a3ffd5bb638bd777207")
if err != nil {
	fmt.Println(err)
	return
}
signature, err := ecdsa.ParseDERSignature(sigBytes)
if err != nil {
	fmt.Println(err)
	return
}

// Verify the signature for the message using the public key.
message := "test message"
messageHash := chainhash.HashB([]byte(message))
verified := signature.Verify(messageHash, pubKey)
fmt.Println("Signature Verified?", verified)

Output:

Signature Verified? true

Source Files

View all Source files

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.