package ecdsa

Import Path
	github.com/decred/dcrd/dcrec/secp256k1/v4/ecdsa (on go.dev)

Dependency Relation
	imports 2 packages, and imported by one package

Involved Source Files

	  d doc.go
		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
		
		The 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 ErrorKind
		field of the type asserted ecdsa.Error while still providing rich error messages
		with contextual information.  See ErrorKind in the package documentation for a
		full list.

	    error.go
	    signature.go
Code Examples

	Sign
	  {
	  
	  	pkBytes, err := hex.DecodeString("22a47fa09a223f2aa079edf85a7c2d4f87" +
	  		"20ee63e502ee2869afab7de234b80c")
	  	if err != nil {
	  		fmt.Println(err)
	  		return
	  	}
	  	privKey := secp256k1.PrivKeyFromBytes(pkBytes)
	  
	  	message := "test message"
	  	messageHash := blake256.Sum256([]byte(message))
	  	signature := ecdsa.Sign(privKey, messageHash[:])
	  
	  	fmt.Printf("Serialized Signature: %x\n", signature.Serialize())
	  
	  	pubKey := privKey.PubKey()
	  	verified := signature.Verify(messageHash[:], pubKey)
	  	fmt.Printf("Signature Verified? %v\n", verified)
	  
	  }
	Signature_Verify
	  {
	  
	  	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
	  	}
	  
	  	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
	  	}
	  
	  	message := "test message"
	  	messageHash := blake256.Sum256([]byte(message))
	  	verified := signature.Verify(messageHash[:], pubKey)
	  	fmt.Println("Signature Verified?", verified)
	  
	  }

Package-Level Type Names (total 3)

	/* sort by: alphabet | popularity */
	 type Error (struct)
		Error identifies an error related to an ECDSA 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.

		Fields (total 2)
			Description string
			Err error
		Methods (total 2)
			( Error) Error() string
				Error satisfies the error interface and prints human-readable errors.

			( Error) Unwrap() error
				Unwrap returns the underlying wrapped error.

		Implements (at least 2)
			 Error : error
			 Error : golang.org/x/xerrors.Wrapper

	 type ErrorKind string (basic type)
		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.

		Methods (only one)
			( ErrorKind) Error() string
				Error satisfies the error interface and prints human-readable errors.

		Implements (at least one exported)
			 ErrorKind : error
		As Types Of (total 23)
			const ErrPointNotOnCurve
			const ErrSigInvalidDataLen
			const ErrSigInvalidLen
			const ErrSigInvalidRecoveryCode
			const ErrSigInvalidRIntID
			const ErrSigInvalidSeqID
			const ErrSigInvalidSIntID
			const ErrSigInvalidSLen
			const ErrSigMissingSLen
			const ErrSigMissingSTypeID
			const ErrSigNegativeR
			const ErrSigNegativeS
			const ErrSigOverflowsPrime
			const ErrSigRIsZero
			const ErrSigRTooBig
			const ErrSigSIsZero
			const ErrSigSTooBig
			const ErrSigTooLong
			const ErrSigTooMuchRPadding
			const ErrSigTooMuchSPadding
			const ErrSigTooShort
			const ErrSigZeroRLen
			const ErrSigZeroSLen

	 type Signature (struct)
		Signature is a type representing an ECDSA signature.

		Methods (total 5)
			(*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.

			(*Signature) R() secp256k1.ModNScalar
				R returns the r value of the signature.

			(*Signature) S() secp256k1.ModNScalar
				S returns the s value of the signature.

			(*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.

			(*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.

		As Outputs Of (at least 3)
			func NewSignature(r, s *secp256k1.ModNScalar) *Signature
			func ParseDERSignature(sig []byte) (*Signature, error)
			func Sign(key *secp256k1.PrivateKey, hash []byte) *Signature
		As Inputs Of (at least one exported)
			func (*Signature).IsEqual(otherSig *Signature) bool


Package-Level Functions (total 5)

	 func NewSignature(r, s *secp256k1.ModNScalar) *Signature
		NewSignature instantiates a new signature given some r and s values.

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

	 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.


Package-Level Constants (total 23)

	const ErrPointNotOnCurve ErrorKind = "ErrPointNotOnCurve"
		ErrPointNotOnCurve is returned when attempting to recover a public key
		from a compact signature results in a point that is not on the elliptic
		curve.

	const ErrSigInvalidDataLen ErrorKind = "ErrSigInvalidDataLen"
		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.

	const ErrSigInvalidLen ErrorKind = "ErrSigInvalidLen"
		ErrSigInvalidLen is returned when a signature that should be a compact
		signature is not the required length.

	const ErrSigInvalidRecoveryCode ErrorKind = "ErrSigInvalidRecoveryCode"
		ErrSigInvalidRecoveryCode is returned when a signature that should be a
		compact signature has an invalid value for the public key recovery code.

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

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

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

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

	const ErrSigMissingSLen ErrorKind = "ErrSigMissingSLen"
		ErrSigMissingSLen is returned when a signature that should be a DER
		signature does not provide the length of S.

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

	const ErrSigNegativeR ErrorKind = "ErrSigNegativeR"
		ErrSigNegativeR is returned when a signature that should be a DER
		signature has a negative value for R.

	const ErrSigNegativeS ErrorKind = "ErrSigNegativeS"
		ErrSigNegativeS is returned when a signature that should be a DER
		signature has a negative value for S.

	const ErrSigOverflowsPrime ErrorKind = "ErrSigOverflowsPrime"
		ErrSigOverflowsPrime is returned when a signature that should be a
		compact signature has the overflow bit set but adding the order to it
		would overflow the underlying field prime.

	const ErrSigRIsZero ErrorKind = "ErrSigRIsZero"
		ErrSigRIsZero is returned when a signature has R set to the value zero.

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

	const ErrSigSIsZero ErrorKind = "ErrSigSIsZero"
		ErrSigSIsZero is returned when a signature has S set to the value zero.

	const ErrSigSTooBig ErrorKind = "ErrSigSTooBig"
		ErrSigSTooBig is returned when a signature has S with a value that is
		greater than or equal to the group order.

	const ErrSigTooLong ErrorKind = "ErrSigTooLong"
		ErrSigTooLong is returned when a signature that should be a DER signature
		is too long.

	const ErrSigTooMuchRPadding ErrorKind = "ErrSigTooMuchRPadding"
		ErrSigTooMuchRPadding is returned when a signature that should be a DER
		signature has too much padding for R.

	const ErrSigTooMuchSPadding ErrorKind = "ErrSigTooMuchSPadding"
		ErrSigTooMuchSPadding is returned when a signature that should be a DER
		signature has too much padding for S.

	const ErrSigTooShort ErrorKind = "ErrSigTooShort"
		ErrSigTooShort is returned when a signature that should be a DER
		signature is too short.

	const ErrSigZeroRLen ErrorKind = "ErrSigZeroRLen"
		ErrSigZeroRLen is returned when a signature that should be a DER
		signature has an R length of zero.

	const ErrSigZeroSLen ErrorKind = "ErrSigZeroSLen"
		ErrSigZeroSLen is returned when a signature that should be a DER
		signature has an S length of zero.

The pages are generated with Golds v0.8.2. (GOOS=linux GOARCH=amd64)
Golds is a Go 101 project developed by Tapir Liu.
PR and bug reports are welcome and can be submitted to the issue list.
Please follow @zigo_101 (reachable from the left QR code) to get the latest news of Golds.