schnorr

Documentation

Overview

Package schnorr provides custom Schnorr signing and verification via secp256k1.

This package provides data structures and functions necessary to produce and verify deterministic canonical Schnorr signatures using a custom scheme named EC-Schnorr-DCRv0 that is described herein. The signatures and implementation are optimized specifically for the secp256k1 curve. See https://www.secg.org/sec2-v2.pdf for details on the secp256k1 standard.

It also provides functions to parse and serialize the Schnorr signatures according to the specification described herein.

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

Overview

A Schnorr signature is a digital signature scheme that is known for its simplicity, provable security and efficient generation of short signatures.

It provides many advantages over ECDSA signatures that make them ideal for use with the only real downside being that they are not well standardized at the time of this writing.

Some of the advantages over ECDSA include:

• They are linear which makes them easier to aggregate and use in protocols that build on them such as multi-party signatures, threshold signatures, adaptor signatures, and blind signatures
• They are provably secure with weaker assumptions than the best known security proofs for ECDSA
• Specifically Schnorr signatures are provably secure under SUF-CMA (Strong Existential Unforgeability under Chosen Message Attack) in the ROM (Random Oracle Model) which guarantees that as long as the hash function behaves ideally, the only way to break Schnorr signatures is by solving the ECDLP (Elliptic Curve Discrete Logarithm Problem).
• Their relatively straightforward and efficient aggregation properties make them excellent for scalability and allow them to provide some nice secacy characteristics
• They support faster batch verification unlike the standardized version of ECDSA signatures

Custom Schnorr-based Signature Scheme

As mentioned in the overview, the primary downside of Schnorr signatures for elliptic curves is that they are not standardized as well as ECDSA signatures which means there are a number of variations that are not compatible with each other.

In addition, many of the standardization attempts have various disadvantages that make them unsuitable for use in Decred. Some of these details and some insight into the design decisions made are discussed further in the README.md file.

Consequently, this package implements a custom Schnorr-based signature scheme named EC-Schnorr-DCRv0 suitable for use in Decred.

The following provides a high-level overview of the key design features of the scheme:

• Uses signatures of the form (R, s)
• Produces 64-byte signatures by only encoding the x coordinate of R
• Enforces even y coordinates for R to support efficient verification by disambiguating the two possible y coordinates
• Canonically encodes by both components of the signature with 32-bytes each
• Uses BLAKE-256 with 14 rounds for the hash function to calculate challenge e
• Uses RFC6979 to obviate the need for an entropy source at signing time
• Produces deterministic signatures for a given message and secret key pair

EC-Schnorr-DCRv0 Specification

See the README.md file for the specific details of the signing and verification algorithm as well as the signature serialization format.

Future Design Considerations

It is worth noting that there are some additional optimizations and modifications that have been identified since the introduction of EC-Schnorr-DCRv0 that can be made to further harden security for multi-party and threshold signature use cases as well provide the opportunity for faster signature verification with a sufficiently optimized implementation.

However, the v0 scheme is used in the existing consensus rules and any changes to the signature scheme would invalidate existing uses. Therefore changes in this regard will need to come in the form of a v1 signature scheme and be accompanied by the necessary consensus updates.

Schnorr use in Decred

At the time of this writing, Schnorr signatures are not yet in widespread use on the Decred network, largely due to the current lack of support in wallets and infrastructure for secure multi-party and threshold signatures.

However, the consensus rules and scripting engine supports the necessary primitives and given many of the beneficial properties of Schnorr signatures, a good goal is to work towards providing the additional infrastructure to increase their usage.

Index

• Constants
• func ParsePubKey(pubKeyStr []byte) (*ec.PublicKey, error)
• func SerializePubKey(pub *ec.PublicKey) []byte
• type Error
  • func (err Error) Error() string
  • func (err Error) Unwrap() (ee error)
• type ErrorKind
  • func (err ErrorKind) Error() string
• type SignOption
  • func CustomNonce(auxData [32]byte) SignOption
  • func FastSign() SignOption
• type Signature
  • func NewSignature(r *ec.FieldVal, s *ec.ModNScalar) *Signature
  • func ParseSignature(sig []byte) (*Signature, error)
  • func Sign(privKey *ec.SecretKey, hash []byte, signOpts ...SignOption) (*Signature, error)
  • func (sig Signature) IsEqual(otherSig *Signature) bool
  • func (sig Signature) Serialize() []byte
  • func (sig *Signature) Verify(hash []byte, pubKey *ec.PublicKey) bool

Constants

const (
	// ErrInvalidHashLen indicates that the input hash to sign or verify is not
	// the required length.
	ErrInvalidHashLen = ErrorKind("ErrInvalidHashLen")

	// ErrSecretKeyIsZero indicates an attempt was made to sign a message with
	// a secret key that is equal to zero.
	ErrSecretKeyIsZero = ErrorKind("ErrSecretKeyIsZero")

	ErrPrivateKeyIsZero = ErrSecretKeyIsZero

	// ErrSchnorrHashValue indicates that the hash of (R || m) was too large and
	// so a new nonce should be used.
	ErrSchnorrHashValue = ErrorKind("ErrSchnorrHashValue")

	// ErrPubKeyNotOnCurve indicates that a point was not on the given elliptic
	// curve.
	ErrPubKeyNotOnCurve = ErrorKind("ErrPubKeyNotOnCurve")

	// ErrSigRYIsOdd indicates that the calculated Y value of R was odd.
	ErrSigRYIsOdd = ErrorKind("ErrSigRYIsOdd")

	// ErrSigRNotOnCurve indicates that the calculated or given point R for some
	// signature was not on the curve.
	ErrSigRNotOnCurve = ErrorKind("ErrSigRNotOnCurve")

	// ErrUnequalRValues indicates that the calculated point R for some
	// signature was not the same as the given R value for the signature.
	ErrUnequalRValues = ErrorKind("ErrUnequalRValues")

	// ErrSigTooShort is returned when a signature that should be a Schnorr
	// signature is too short.
	ErrSigTooShort = ErrorKind("ErrSigTooShort")

	// ErrSigTooLong is returned when a signature that should be a Schnorr
	// signature is too long.
	ErrSigTooLong = ErrorKind("ErrSigTooLong")

	// ErrSigRTooBig is returned when a signature has r with a value that is
	// greater than or equal to the prime of the field underlying the group.
	ErrSigRTooBig = ErrorKind("ErrSigRTooBig")

	// ErrSigSTooBig is returned when a signature has s with a value that is
	// greater than or equal to the group order.
	ErrSigSTooBig = ErrorKind("ErrSigSTooBig")
)

These constants are used to identify a specific RuleError.

const (
	PubKeyBytesLen = 32
)

const (
	// SignatureSize is the size of an encoded Schnorr signature.
	SignatureSize = 64
)

Functions

func ParsePubKey

func ParsePubKey(pubKeyStr []byte) (*ec.PublicKey, error)

ParsePubKey parses a public key for a koblitz curve from a bytestring into a btcec.Publickey, verifying that it is valid. It only supports public keys in the BIP-340 32-byte format.

func SerializePubKey

func SerializePubKey(pub *ec.PublicKey) []byte

SerializePubKey serializes a public key as specified by BIP 340. Public keys in this format are 32 bytes in length, and are assumed to have an even y coordinate.

Types

type Error

type Error struct {
	Err         error
	Description string
}

Error identifies an error related to a schnorr signature. 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.

func (Error) Error

func (err Error) Error() string

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

func (Error) Unwrap

func (err Error) Unwrap() (ee error)

Unwrap returns the underlying wrapped error.

type ErrorKind

type ErrorKind string

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

func (ErrorKind) Error

func (err ErrorKind) Error() string

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

type SignOption

type SignOption func(*signOptions)

SignOption is a functional option arguemnt that allows callers to modify the way we generate BIP-340 schnorr signatues.

func CustomNonce

func CustomNonce(auxData [32]byte) SignOption

CustomNonce allows users to pass in a custom set of auxData that's used as input randomness to generate the nonce used during signing. Users may want to specify this custom value when using multi-signatures schemes such as Mu-Sig2. If this option isn't set, then rfc6979 will be used to generate the nonce material.

func FastSign

func FastSign() SignOption

FastSign forces signing to skip the extra verification step at the end. Peformance sensitive applications may opt to use this option to speed up the signing operation.

type Signature

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

Signature is a type representing a Schnorr signature.

func NewSignature

func NewSignature(r *ec.FieldVal, s *ec.ModNScalar) *Signature

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

func ParseSignature

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

ParseSignature parses a signature according to the BIP-340 specification and enforces the following additional restrictions specific to secp256k1:

- The r component must be in the valid range for secp256k1 field elements - The s component must be in the valid range for secp256k1 scalars

func Sign

func Sign(privKey *ec.SecretKey, hash []byte,
	signOpts ...SignOption) (*Signature, error)

Sign generates an BIP-340 signature over the secp256k1 curve for the provided hash (which should be the result of hashing a larger message) using the given secret key. The produced signature is deterministic (same message and same key yield the same signature) and canonical.

Note that the current signing implementation has a few remaining variable time aspects which make use of the secret key and the generated nonce, which can expose the signer to constant time attacks. As a result, this function should not be used in situations where there is the possibility of someone having EM field/cache/etc access.

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 Schnorr signature in the more strict format.

The signatures are encoded as

sig[0:32]  x coordinate of the point R, encoded as a big-endian uint256
sig[32:64] s, encoded also as big-endian uint256

func (*Signature) Verify

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

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