secp256k1

package module
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: 15 Imported by: 67

README

secp256k1

Build Status ISC License Doc

Package secp256k1 implements optimized secp256k1 elliptic curve operations.

This package provides an optimized pure Go implementation of elliptic curve cryptography operations over the secp256k1 curve as well as data structures and functions for working with public and private secp256k1 keys. See https://www.secg.org/sec2-v2.pdf for details on the standard.

In addition, sub packages are provided to produce, verify, parse, and serialize ECDSA signatures and EC-Schnorr-DCRv0 (a custom Schnorr-based signature scheme specific to Decred) signatures. See the README.md files in the relevant sub packages for more details about those aspects.

An overview of the features provided by this package are as follows:

  • Private key generation, serialization, and parsing
  • Public key generation, serialization and parsing per ANSI X9.62-1998
    • Parses uncompressed, compressed, and hybrid public keys
    • Serializes uncompressed and compressed public keys
  • Specialized types for performing optimized and constant time field operations
    • FieldVal type for working modulo the secp256k1 field prime
    • ModNScalar type for working modulo the secp256k1 group order
  • Elliptic curve operations in Jacobian projective coordinates
    • Point addition
    • Point doubling
    • Scalar multiplication with an arbitrary point
    • Scalar multiplication with the base point (group generator)
  • Point decompression from a given x coordinate
  • Nonce generation via RFC6979 with support for extra data and version information that can be used to prevent nonce reuse between signing algorithms

It also provides an implementation of the Go standard library crypto/elliptic Curve interface via the S256 function so that it may be used with other packages in the standard library such as crypto/tls, crypto/x509, and crypto/ecdsa. However, in the case of ECDSA, it is highly recommended to use the ecdsa sub package of this package instead since it is optimized specifically for secp256k1 and is significantly faster as a result.

Although this package was primarily written for dcrd, it has intentionally been designed so it can be used as a standalone package for any projects needing to use optimized secp256k1 elliptic curve cryptography.

Finally, a comprehensive suite of tests is provided to provide a high level of quality assurance.

secp256k1 use in Decred

At the time of this writing, the primary public key cryptography in widespread use on the Decred network used to secure coins is based on elliptic curves defined by the secp256k1 domain parameters.

Installation and Updating

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

Examples

  • Encryption Demonstrates encrypting and decrypting a message using a shared key derived through ECDHE.

License

Package secp256k1 is licensed under the copyfree ISC License.

Documentation

Overview

Package secp256k1 implements optimized secp256k1 elliptic curve operations.

This package provides an optimized pure Go implementation of elliptic curve cryptography operations over the secp256k1 curve as well as data structures and functions for working with public and private secp256k1 keys. See https://www.secg.org/sec2-v2.pdf for details on the standard.

In addition, sub packages are provided to produce, verify, parse, and serialize ECDSA signatures and EC-Schnorr-DCRv0 (a custom Schnorr-based signature scheme specific to Decred) signatures. See the README.md files in the relevant sub packages for more details about those aspects.

An overview of the features provided by this package are as follows:

  • Private key generation, serialization, and parsing
  • Public key generation, serialization and parsing per ANSI X9.62-1998
  • Parses uncompressed, compressed, and hybrid public keys
  • Serializes uncompressed and compressed public keys
  • Specialized types for performing optimized and constant time field operations
  • FieldVal type for working modulo the secp256k1 field prime
  • ModNScalar type for working modulo the secp256k1 group order
  • Elliptic curve operations in Jacobian projective coordinates
  • Point addition
  • Point doubling
  • Scalar multiplication with an arbitrary point
  • Scalar multiplication with the base point (group generator)
  • Point decompression from a given x coordinate
  • Nonce generation via RFC6979 with support for extra data and version information that can be used to prevent nonce reuse between signing algorithms

It also provides an implementation of the Go standard library crypto/elliptic Curve interface via the S256 function so that it may be used with other packages in the standard library such as crypto/tls, crypto/x509, and crypto/ecdsa. However, in the case of ECDSA, it is highly recommended to use the ecdsa sub package of this package instead since it is optimized specifically for secp256k1 and is significantly faster as a result.

Although this package was primarily written for dcrd, it has intentionally been designed so it can be used as a standalone package for any projects needing to use optimized secp256k1 elliptic curve cryptography.

Finally, a comprehensive suite of tests is provided to provide a high level of quality assurance.

Use of secp256k1 in Decred

At the time of this writing, the primary public key cryptography in widespread use on the Decred network used to secure coins is based on elliptic curves defined by the secp256k1 domain parameters.

Example (EncryptDecryptMessage)

This example demonstrates use of GenerateSharedSecret to encrypt a message for a recipient's public key, and subsequently decrypt the message using the recipient's private key. 

newAEAD := func(key []byte) (cipher.AEAD, error) {
	block, err := aes.NewCipher(key)
	if err != nil {
		return nil, err
	}
	return cipher.NewGCM(block)
}

// Decode the hex-encoded pubkey of the recipient.
pubKeyBytes, err := hex.DecodeString("04115c42e757b2efb7671c578530ec191a1" +
	"359381e6a71127a9d37c486fd30dae57e76dc58f693bd7e7010358ce6b165e483a29" +
	"21010db67ac11b1b51b651953d2") // uncompressed pubkey
if err != nil {
	fmt.Println(err)
	return
}
pubKey, err := secp256k1.ParsePubKey(pubKeyBytes)
if err != nil {
	fmt.Println(err)
	return
}

// Derive an ephemeral public/private keypair for performing ECDHE with
// the recipient.
ephemeralPrivKey, err := secp256k1.GeneratePrivateKey()
if err != nil {
	fmt.Println(err)
	return
}
ephemeralPubKey := ephemeralPrivKey.PubKey().SerializeCompressed()

// Using ECDHE, derive a shared symmetric key for encryption of the plaintext.
cipherKey := sha256.Sum256(secp256k1.GenerateSharedSecret(ephemeralPrivKey, pubKey))

// Seal the message using an AEAD.  Here we use AES-256-GCM.
// The ephemeral public key must be included in this message, and becomes
// the authenticated data for the AEAD.
//
// Note that unless a unique nonce can be guaranteed, the ephemeral
// and/or shared keys must not be reused to encrypt different messages.
// Doing so destroys the security of the scheme.  Random nonces may be
// used if XChaCha20-Poly1305 is used instead, but the message must then
// also encode the nonce (which we don't do here).
plaintext := []byte("test message")
aead, err := newAEAD(cipherKey[:])
if err != nil {
	fmt.Println(err)
	return
}
nonce := make([]byte, aead.NonceSize())
ciphertext := make([]byte, 4+len(ephemeralPubKey))
binary.LittleEndian.PutUint32(ciphertext, uint32(len(ephemeralPubKey)))
copy(ciphertext[4:], ephemeralPubKey)
ciphertext = aead.Seal(ciphertext, nonce, plaintext, ephemeralPubKey)

// The remainder of this example is performed by the recipient on the
// ciphertext shared by the sender.

// Decode the hex-encoded private key.
pkBytes, err := hex.DecodeString("a11b0a4e1a132305652ee7a8eb7848f6ad" +
	"5ea381e3ce20a2c086a2e388230811")
if err != nil {
	fmt.Println(err)
	return
}
privKey := secp256k1.PrivKeyFromBytes(pkBytes)

// Read the sender's ephemeral public key from the start of the message.
// Error handling for inappropriate pubkey lengths is elided here for
// brevity.
pubKeyLen := binary.LittleEndian.Uint32(ciphertext[:4])
senderPubKeyBytes := ciphertext[4 : 4+pubKeyLen]
senderPubKey, err := secp256k1.ParsePubKey(senderPubKeyBytes)
if err != nil {
	fmt.Println(err)
	return
}

// Derive the key used to seal the message, this time from the
// recipient's private key and the sender's public key.
recoveredCipherKey := sha256.Sum256(secp256k1.GenerateSharedSecret(privKey, senderPubKey))

// Open the sealed message.
aead, err = newAEAD(recoveredCipherKey[:])
if err != nil {
	fmt.Println(err)
	return
}
nonce = make([]byte, aead.NonceSize())
recoveredPlaintext, err := aead.Open(nil, nonce, ciphertext[4+pubKeyLen:], senderPubKeyBytes)
if err != nil {
	fmt.Println(err)
	return
}

fmt.Println(string(recoveredPlaintext))

Output:

test message

Index

Examples

Constants

View Source 
const (
	// PubKeyBytesLenCompressed is the number of bytes of a serialized
	// compressed public key.
	PubKeyBytesLenCompressed = 33

	// PubKeyBytesLenCompressed is the number of bytes of a serialized
	// uncompressed public key.
	PubKeyBytesLenUncompressed = 65

	// PubKeyFormatCompressedEven is the identifier prefix byte for a public key
	// whose Y coordinate is even when serialized in the compressed format per
	// section 2.3.4 of [SEC1](https://secg.org/sec1-v2.pdf#subsubsection.2.3.4).
	PubKeyFormatCompressedEven byte = 0x02

	// PubKeyFormatCompressedOdd is the identifier prefix byte for a public key
	// whose Y coordinate is odd when serialized in the compressed format per
	// section 2.3.4 of [SEC1](https://secg.org/sec1-v2.pdf#subsubsection.2.3.4).
	PubKeyFormatCompressedOdd byte = 0x03

	// PubKeyFormatUncompressed is the identifier prefix byte for a public key
	// when serialized according in the uncompressed format per section 2.3.3 of
	// [SEC1](https://secg.org/sec1-v2.pdf#subsubsection.2.3.3).
	PubKeyFormatUncompressed byte = 0x04

	// PubKeyFormatHybridEven is the identifier prefix byte for a public key
	// whose Y coordinate is even when serialized according to the hybrid format
	// per section 4.3.6 of [ANSI X9.62-1998].
	//
	// NOTE: This format makes little sense in practice an therefore this
	// package will not produce public keys serialized in this format.  However,
	// it will parse them since they exist in the wild.
	PubKeyFormatHybridEven byte = 0x06

	// PubKeyIDHybridEven is the identifier prefix byte for a public key whose Y
	// coordingate is odd when serialized according to the hybrid format per
	// section 4.3.6 of [ANSI X9.62-1998].
	//
	// NOTE: This format makes little sense in practice an therefore this
	// package will not produce public keys serialized in this format.  However,
	// it will parse them since they exist in the wild.
	PubKeyFormatHybridOdd byte = 0x07
)
View Source 
const PrivKeyBytesLen = 32

PrivKeyBytesLen defines the length in bytes of a serialized private key.

Variables

This section is empty.

Functions

func AddNonConst 

func AddNonConst(p1, p2, result *JacobianPoint)

AddNonConst adds the passed Jacobian points together and stores the result in the provided result param in *non-constant* time.

NOTE: The points must be normalized for this function to return the correct result. The resulting point will be normalized.

func DecompressY 

func DecompressY(x *FieldVal, odd bool, resultY *FieldVal) bool

DecompressY attempts to calculate the Y coordinate for the given X coordinate such that the result pair is a point on the secp256k1 curve. It adjusts Y based on the desired oddness and returns whether or not it was successful since not all X coordinates are valid.

The magnitude of the provided X coordinate field val must be a max of 8 for a correct result. The resulting Y field val will have a max magnitude of 2.

func DoubleNonConst 

func DoubleNonConst(p, result *JacobianPoint)

DoubleNonConst doubles the passed Jacobian point and stores the result in the provided result parameter in *non-constant* time.

NOTE: The point must be normalized for this function to return the correct result. The resulting point will be normalized.

func GenerateSharedSecret 

func GenerateSharedSecret(privkey *PrivateKey, pubkey *PublicKey) []byte

GenerateSharedSecret generates a shared secret based on a private key and a public key using Diffie-Hellman key exchange (ECDH) (RFC 5903). RFC5903 Section 9 states we should only return x.

It is recommended to securily hash the result before using as a cryptographic key.

func ScalarBaseMultNonConst 

func ScalarBaseMultNonConst(k *ModNScalar, result *JacobianPoint)

ScalarBaseMultNonConst multiplies k*G where G is the base point of the group and k is a big endian integer. The result is stored in Jacobian coordinates (x1, y1, z1).

NOTE: The resulting point will be normalized.

func ScalarMultNonConst 

func ScalarMultNonConst(k *ModNScalar, point, result *JacobianPoint)

ScalarMultNonConst multiplies k*P where k is a big endian integer modulo the curve order and P is a point in Jacobian projective coordinates and stores the result in the provided Jacobian point.

NOTE: The point must be normalized for this function to return the correct result. The resulting point will be normalized.

Types

type CurveParams 

type CurveParams struct {
	// P is the prime used in the secp256k1 field.
	P *big.Int

	// N is the order of the secp256k1 curve group generated by the base point.
	N *big.Int

	// Gx and Gy are the x and y coordinate of the base point, respectively.
	Gx, Gy *big.Int

	// BitSize is the size of the underlying secp256k1 field in bits.
	BitSize int

	// H is the cofactor of the secp256k1 curve.
	H int

	// ByteSize is simply the bit size / 8 and is provided for convenience
	// since it is calculated repeatedly.
	ByteSize int
}

CurveParams contains the parameters for the secp256k1 curve.

func Params 

func Params() *CurveParams

Params returns the secp256k1 curve parameters for convenience.

type Error 

type Error struct {
	ErrorCode   ErrorCode // Describes the kind of error
	Description string    // Human readable description of the issue
}

Error identifies a pubkey-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 pubkey-related 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 (
	// ErrPubKeyInvalidLen indicates that the length of a serialized public
	// key is not one of the allowed lengths.
	ErrPubKeyInvalidLen ErrorCode = iota

	// ErrPubKeyInvalidFormat indicates an attempt was made to parse a public
	// key that does not specify one of the supported formats.
	ErrPubKeyInvalidFormat

	// ErrPubKeyXTooBig indicates that the x coordinate for a public key
	// is greater than or equal to the prime of the field underlying the group.
	ErrPubKeyXTooBig

	// ErrPubKeyYTooBig indicates that the y coordinate for a public key is
	// greater than or equal to the prime of the field underlying the group.
	ErrPubKeyYTooBig

	// ErrPubKeyNotOnCurve indicates that a public key is not a point on the
	// secp256k1 curve.
	ErrPubKeyNotOnCurve

	// ErrPubKeyMismatchedOddness indicates that a hybrid public key specified
	// an oddness of the y coordinate that does not match the actual oddness of
	// the provided y coordinate.
	ErrPubKeyMismatchedOddness
)

These constants are used to identify a specific RuleError.

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 FieldVal 

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

FieldVal implements optimized fixed-precision arithmetic over the secp256k1 finite field. This means all arithmetic is performed modulo 0xfffffffffffffffffffffffffffffffffffffffffffffffffffffffefffffc2f.

WARNING: Since it is so important for the field arithmetic to be extremely fast for high performance crypto, this type does not perform any validation of documented preconditions where it ordinarily would. As a result, it is IMPERATIVE for callers to understand some key concepts that are described below and ensure the methods are called with the necessary preconditions that each method is documented with. For example, some methods only give the correct result if the field value is normalized and others require the field values involved to have a maximum magnitude and THERE ARE NO EXPLICIT CHECKS TO ENSURE THOSE PRECONDITIONS ARE SATISFIED. This does, unfortunately, make the type more difficult to use correctly and while I typically prefer to ensure all state and input is valid for most code, this is a bit of an exception because those extra checks really add up in what ends up being critical hot paths.

The first key concept when working with this type is normalization. In order to avoid the need to propagate a ton of carries, the internal representation provides additional overflow bits for each word of the overall 256-bit value. This means that there are multiple internal representations for the same value and, as a result, any methods that rely on comparison of the value, such as equality and oddness determination, require the caller to provide a normalized value.

The second key concept when working with this type is magnitude. As previously mentioned, the internal representation provides additional overflow bits which means that the more math operations that are performed on the field value between normalizations, the more those overflow bits accumulate. The magnitude is effectively that maximum possible number of those overflow bits that could possibly be required as a result of a given operation. Since there are only a limited number of overflow bits available, this implies that the max possible magnitude MUST be tracked by the caller and the caller MUST normalize the field value if a given operation would cause the magnitude of the result to exceed the max allowed value.

IMPORTANT: The max allowed magnitude of a field value is 64.

func (*FieldVal) Add 

func (f *FieldVal) Add(val *FieldVal) *FieldVal

Add adds the passed value to the existing field value and stores the result in f in constant time.

The field value is returned to support chaining. This enables syntax like: f.Add(f2).AddInt(1) so that f = f + f2 + 1.

Preconditions:

  • The sum of the magnitudes of the two field values MUST be a max of 64

Output Normalized: No Output Max Magnitude: Sum of the magnitude of the two individual field values

func (*FieldVal) Add2 

func (f *FieldVal) Add2(val *FieldVal, val2 *FieldVal) *FieldVal

Add2 adds the passed two field values together and stores the result in f in constant time.

The field value is returned to support chaining. This enables syntax like: f3.Add2(f, f2).AddInt(1) so that f3 = f + f2 + 1.

Preconditions:

  • The sum of the magnitudes of the two field values MUST be a max of 64

Output Normalized: No Output Max Magnitude: Sum of the magnitude of the two field values

func (*FieldVal) AddInt 

func (f *FieldVal) AddInt(ui uint16) *FieldVal

AddInt adds the passed integer to the existing field value and stores the result in f in constant time. This is a convenience function since it is fairly common to perform some arithmetic with small native integers.

The field value is returned to support chaining. This enables syntax like: f.AddInt(1).Add(f2) so that f = f + 1 + f2.

Preconditions:

  • The field value MUST have a max magnitude of 63

Output Normalized: No Output Max Magnitude: Existing field magnitude + 1

func (*FieldVal) Bytes 

func (f *FieldVal) Bytes() *[32]byte

Bytes unpacks the field value to a 32-byte big-endian value in constant time.

See PutBytes and PutBytesUnchecked for variants that allow an array or slice to be passed which can be useful to cut down on the number of allocations by allowing the caller to reuse a buffer or write directly into part of a larger buffer.

Preconditions:

  • The field value MUST be normalized

func (*FieldVal) Equals 

func (f *FieldVal) Equals(val *FieldVal) bool

Equals returns whether or not the two field values are the same in constant time.

Preconditions:

  • Both field values being compared MUST be normalized

func (*FieldVal) Inverse 

func (f *FieldVal) Inverse() *FieldVal

Inverse finds the modular multiplicative inverse of the field value in constant time. The existing field value is modified.

The field value is returned to support chaining. This enables syntax like: f.Inverse().Mul(f2) so that f = f^-1 * f2.

Preconditions:

  • The field value MUST have a max magnitude of 8

Output Normalized: No Output Max Magnitude: 1

func (*FieldVal) IsGtOrEqPrimeMinusOrder 

func (f *FieldVal) IsGtOrEqPrimeMinusOrder() bool

IsGtOrEqPrimeMinusOrder returns whether or not the field value exceeds the group order divided by 2 in constant time.

Preconditions:

  • The field value MUST be normalized

func (*FieldVal) IsOdd 

func (f *FieldVal) IsOdd() bool

IsOdd returns whether or not the field value is an odd number in constant time.

Preconditions:

  • The field value MUST be normalized

func (*FieldVal) IsOddBit 

func (f *FieldVal) IsOddBit() uint32

IsOddBit returns 1 when the field value is an odd number or 0 otherwise in constant time.

Note that a bool is not used here because it is not possible in Go to convert from a bool to numeric value in constant time and many constant-time operations require a numeric value. See IsOdd for the version that returns a bool.

Preconditions:

  • The field value MUST be normalized

func (*FieldVal) IsOne 

func (f *FieldVal) IsOne() bool

IsOne returns whether or not the field value is equal to one in constant time.

Preconditions:

  • The field value MUST be normalized

func (*FieldVal) IsOneBit 

func (f *FieldVal) IsOneBit() uint32

IsOneBit returns 1 when the field value is equal to one or 0 otherwise in constant time.

Note that a bool is not used here because it is not possible in Go to convert from a bool to numeric value in constant time and many constant-time operations require a numeric value. See IsOne for the version that returns a bool.

Preconditions:

  • The field value MUST be normalized

func (*FieldVal) IsZero 

func (f *FieldVal) IsZero() bool

IsZero returns whether or not the field value is equal to zero in constant time.

Preconditions:

  • The field value MUST be normalized

func (*FieldVal) IsZeroBit 

func (f *FieldVal) IsZeroBit() uint32

IsZeroBit returns 1 when the field value is equal to zero or 0 otherwise in constant time.

Note that a bool is not used here because it is not possible in Go to convert from a bool to numeric value in constant time and many constant-time operations require a numeric value. See IsZero for the version that returns a bool.

Preconditions:

  • The field value MUST be normalized

func (*FieldVal) Mul 

func (f *FieldVal) Mul(val *FieldVal) *FieldVal

Mul multiplies the passed value to the existing field value and stores the result in f in constant time. Note that this function can overflow if multiplying any of the individual words exceeds a max uint32. In practice, this means the magnitude of either value involved in the multiplication must be a max of 8.

The field value is returned to support chaining. This enables syntax like: f.Mul(f2).AddInt(1) so that f = (f * f2) + 1.

Preconditions:

  • Both field values MUST have a max magnitude of 8

Output Normalized: No Output Max Magnitude: 1

func (*FieldVal) Mul2 

func (f *FieldVal) Mul2(val *FieldVal, val2 *FieldVal) *FieldVal

Mul2 multiplies the passed two field values together and stores the result result in f in constant time. Note that this function can overflow if multiplying any of the individual words exceeds a max uint32. In practice, this means the magnitude of either value involved in the multiplication must be a max of 8.

The field value is returned to support chaining. This enables syntax like: f3.Mul2(f, f2).AddInt(1) so that f3 = (f * f2) + 1.

Preconditions:

  • Both input field values MUST have a max magnitude of 8

Output Normalized: No Output Max Magnitude: 1

func (*FieldVal) MulInt 

func (f *FieldVal) MulInt(val uint8) *FieldVal

MulInt multiplies the field value by the passed int and stores the result in f in constant time. Note that this function can overflow if multiplying the value by any of the individual words exceeds a max uint32. Therefore it is important that the caller ensures no overflows will occur before using this function.

The field value is returned to support chaining. This enables syntax like: f.MulInt(2).Add(f2) so that f = 2 * f + f2.

Preconditions:

  • The field value magnitude multiplied by given val MUST be a max of 64

Output Normalized: No Output Max Magnitude: Existing field magnitude times the provided integer val

func (*FieldVal) Negate 

func (f *FieldVal) Negate(magnitude uint32) *FieldVal

Negate negates the field value in constant time. The existing field value is modified. The caller must provide the magnitude of the field value for a correct result.

The field value is returned to support chaining. This enables syntax like: f.Negate().AddInt(1) so that f = -f + 1.

Preconditions:

  • The max magnitude MUST be 63

Output Normalized: No Output Max Magnitude: Input magnitude + 1

func (*FieldVal) NegateVal 

func (f *FieldVal) NegateVal(val *FieldVal, magnitude uint32) *FieldVal

NegateVal negates the passed value and stores the result in f in constant time. The caller must provide the magnitude of the passed value for a correct result.

The field value is returned to support chaining. This enables syntax like: f.NegateVal(f2).AddInt(1) so that f = -f2 + 1.

Preconditions:

  • The max magnitude MUST be 63

Output Normalized: No Output Max Magnitude: Input magnitude + 1

func (*FieldVal) Normalize 

func (f *FieldVal) Normalize() *FieldVal

Normalize normalizes the internal field words into the desired range and performs fast modular reduction over the secp256k1 prime by making use of the special form of the prime in constant time.

Preconditions: None Output Normalized: Yes Output Max Magnitude: 1

func (*FieldVal) PutBytes 

func (f *FieldVal) PutBytes(b *[32]byte)

PutBytes unpacks the field value to a 32-byte big-endian value using the passed byte array in constant time.

There is a similar function, PutBytesUnchecked, which unpacks the field value into a slice that must have at least 32 bytes available. This version is provided since it can be useful to write directly into an array that is type checked.

Alternatively, there is also Bytes, which unpacks the field value into a new array and returns that which can sometimes be more ergonomic in applications that aren't concerned about an additional copy.

Preconditions:

  • The field value MUST be normalized

func (*FieldVal) PutBytesUnchecked 

func (f *FieldVal) PutBytesUnchecked(b []byte)

PutBytesUnchecked unpacks the field value to a 32-byte big-endian value directly into the passed byte slice in constant time. The target slice must must have at least 32 bytes available or it will panic.

There is a similar function, PutBytes, which unpacks the field value into a 32-byte array directly. This version is provided since it can be useful to write directly into part of a larger buffer without needing a separate allocation.

Preconditions:

  • The field value MUST be normalized
  • The target slice MUST have at least 32 bytes available

func (*FieldVal) Set 

func (f *FieldVal) Set(val *FieldVal) *FieldVal

Set sets the field value equal to the passed value in constant time. The normalization and magnitude of the two fields will be identical.

The field value is returned to support chaining. This enables syntax like: f := new(FieldVal).Set(f2).Add(1) so that f = f2 + 1 where f2 is not modified.

Preconditions: None Output Normalized: Same as input value Output Max Magnitude: Same as input value

func (*FieldVal) SetByteSlice 

func (f *FieldVal) SetByteSlice(b []byte) bool

SetByteSlice interprets the provided slice as a 256-bit big-endian unsigned integer (meaning it is truncated to the first 32 bytes), packs it into the internal field value representation, and returns whether or not the resulting truncated 256-bit integer is greater than or equal to the field prime (aka it overflowed) in constant time.

Note that since passing a slice with more than 32 bytes is truncated, it is possible that the truncated value is less than the field prime and hence it will not be reported as having overflowed in that case. It is up to the caller to decide whether it needs to provide numbers of the appropriate size or it if is acceptable to use this function with the described truncation and overflow behavior.

Preconditions: None Output Normalized: Yes if no overflow, no otherwise Output Max Magnitude: 1

func (*FieldVal) SetBytes 

func (f *FieldVal) SetBytes(b *[32]byte) uint32

SetBytes packs the passed 32-byte big-endian value into the internal field value representation in constant time. SetBytes interprets the provided array as a 256-bit big-endian unsigned integer, packs it into the internal field value representation, and returns either 1 if it is greater than or equal to the field prime (aka it overflowed) or 0 otherwise in constant time.

Note that a bool is not used here because it is not possible in Go to convert from a bool to numeric value in constant time and many constant-time operations require a numeric value.

Preconditions: None Output Normalized: Yes if no overflow, no otherwise Output Max Magnitude: 1

func (*FieldVal) SetInt 

func (f *FieldVal) SetInt(ui uint16) *FieldVal

SetInt sets the field value to the passed integer in constant time. This is a convenience function since it is fairly common to perform some arithmetic with small native integers.

The field value is returned to support chaining. This enables syntax such as f := new(FieldVal).SetInt(2).Mul(f2) so that f = 2 * f2.

Preconditions: None Output Normalized: Yes Output Max Magnitude: 1

func (*FieldVal) Square 

func (f *FieldVal) Square() *FieldVal

Square squares the field value in constant time. The existing field value is modified. Note that this function can overflow if multiplying any of the individual words exceeds a max uint32. In practice, this means the magnitude of the field must be a max of 8 to prevent overflow.

The field value is returned to support chaining. This enables syntax like: f.Square().Mul(f2) so that f = f^2 * f2.

Preconditions:

  • The field value MUST have a max magnitude of 8

Output Normalized: No Output Max Magnitude: 1

func (*FieldVal) SquareRootVal 

func (f *FieldVal) SquareRootVal(val *FieldVal) bool

SquareRootVal either calculates the square root of the passed value when it exists or the square root of the negation of the value when it does not exist and stores the result in f in constant time. The return flag is true when the calculated square root is for the passed value itself and false when it is for its negation.

Note that this function can overflow if multiplying any of the individual words exceeds a max uint32. In practice, this means the magnitude of the field must be a max of 8 to prevent overflow. The magnitude of the result will be 1.

Preconditions:

  • The input field value MUST have a max magnitude of 8

Output Normalized: No Output Max Magnitude: 1

func (*FieldVal) SquareVal 

func (f *FieldVal) SquareVal(val *FieldVal) *FieldVal

SquareVal squares the passed value and stores the result in f in constant time. Note that this function can overflow if multiplying any of the individual words exceeds a max uint32. In practice, this means the magnitude of the field being squared must be a max of 8 to prevent overflow.

The field value is returned to support chaining. This enables syntax like: f3.SquareVal(f).Mul(f) so that f3 = f^2 * f = f^3.

Preconditions:

  • The input field value MUST have a max magnitude of 8

Output Normalized: No Output Max Magnitude: 1

func (FieldVal) String 

func (f FieldVal) String() string

String returns the field value as a normalized human-readable hex string.

Preconditions: None Output Normalized: Field is not modified -- same as input value Output Max Magnitude: Field is not modified -- same as input value

func (*FieldVal) Zero 

func (f *FieldVal) Zero()

Zero sets the field value to zero in constant time. A newly created field value is already set to zero. This function can be useful to clear an existing field value for reuse.

Preconditions: None Output Normalized: Yes Output Max Magnitude: 1

type JacobianPoint 

type JacobianPoint struct {
	// The X coordinate in Jacobian projective coordinates.  The affine point is
	// X/z^2.
	X FieldVal

	// The Y coordinate in Jacobian projective coordinates.  The affine point is
	// Y/z^3.
	Y FieldVal

	// The Z coordinate in Jacobian projective coordinates.
	Z FieldVal
}

JacobianPoint is an element of the group formed by the secp256k1 curve in Jacobian projective coordinates and thus represents a point on the curve.

func MakeJacobianPoint 

func MakeJacobianPoint(x, y, z *FieldVal) JacobianPoint

MakeJacobianPoint returns a Jacobian point with the provided X, Y, and Z coordinates.

func (*JacobianPoint) Set 

func (p *JacobianPoint) Set(other *JacobianPoint)

Set sets the Jacobian point to the provided point.

func (*JacobianPoint) ToAffine 

func (p *JacobianPoint) ToAffine()

ToAffine reduces the Z value of the existing point to 1 effectively making it an affine coordinate in constant time. The point will be normalized.

type KoblitzCurve 

type KoblitzCurve struct {
	*elliptic.CurveParams
	// contains filtered or unexported fields
}

KoblitzCurve provides an implementation for secp256k1 that fits the ECC Curve interface from crypto/elliptic.

func S256 

func S256() *KoblitzCurve

S256 returns a Curve which implements secp256k1.

func (*KoblitzCurve) Add 

func (curve *KoblitzCurve) Add(x1, y1, x2, y2 *big.Int) (*big.Int, *big.Int)

Add returns the sum of (x1,y1) and (x2,y2).

This is part of the elliptic.Curve interface implementation.

func (*KoblitzCurve) Double 

func (curve *KoblitzCurve) Double(x1, y1 *big.Int) (*big.Int, *big.Int)

Double returns 2*(x1,y1).

This is part of the elliptic.Curve interface implementation.

func (*KoblitzCurve) IsOnCurve 

func (curve *KoblitzCurve) IsOnCurve(x, y *big.Int) bool

IsOnCurve returns whether or not the affine point (x,y) is on the curve.

This is part of the elliptic.Curve interface implementation. This function differs from the crypto/elliptic algorithm since a = 0 not -3.

func (*KoblitzCurve) Params 

func (curve *KoblitzCurve) Params() *elliptic.CurveParams

Params returns the parameters for the curve.

This is part of the elliptic.Curve interface implementation.

func (*KoblitzCurve) ScalarBaseMult 

func (curve *KoblitzCurve) ScalarBaseMult(k []byte) (*big.Int, *big.Int)

ScalarBaseMult returns k*G where G is the base point of the group and k is a big endian integer.

This is part of the elliptic.Curve interface implementation.

func (*KoblitzCurve) ScalarMult 

func (curve *KoblitzCurve) ScalarMult(Bx, By *big.Int, k []byte) (*big.Int, *big.Int)

ScalarMult returns k*(Bx, By) where k is a big endian integer.

This is part of the elliptic.Curve interface implementation.

type ModNScalar 

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

ModNScalar implements optimized 256-bit constant-time fixed-precision arithmetic over the secp256k1 group order. This means all arithmetic is performed modulo: 

0xfffffffffffffffffffffffffffffffebaaedce6af48a03bbfd25e8cd0364141

It only implements the arithmetic needed for elliptic curve operations, however, the operations that are not implemented can typically be worked around if absolutely needed. For example, subtraction can be performed by adding the negation.

Should it be absolutely necessary, conversion to the standard library math/big.Int can be accomplished by using the Bytes method, slicing the resulting fixed-size array, and feeding it to big.Int.SetBytes. However, that should typically be avoided when possible as conversion to big.Ints requires allocations, is not constant time, and is slower when working modulo the group order.

func NonceRFC6979 

func NonceRFC6979(privKey []byte, hash []byte, extra []byte, version []byte, extraIterations uint32) *ModNScalar

NonceRFC6979 generates a nonce deterministically according to RFC 6979 using HMAC-SHA256 for the hashing function. It takes a 32-byte hash as an input and returns a 32-byte nonce to be used for deterministic signing. The extra and version arguments are optional, but allow additional data to be added to the input of the HMAC. When provided, the extra data must be 32-bytes and version must be 16 bytes or they will be ignored.

Finally, the extraIterations parameter provides a method to produce a stream of deterministic nonces to ensure the signing code is able to produce a nonce that results in a valid signature in the extremely unlikely event the original nonce produced results in an invalid signature (e.g. R == 0). Signing code should start with 0 and increment it if necessary.

func (*ModNScalar) Add 

func (s *ModNScalar) Add(val *ModNScalar) *ModNScalar

Add adds the passed scalar to the existing one modulo the group order in constant time and stores the result in s.

The scalar is returned to support chaining. This enables syntax like: s.Add(s2).AddInt(1) so that s = s + s2 + 1.

func (*ModNScalar) Add2 

func (s *ModNScalar) Add2(val1, val2 *ModNScalar) *ModNScalar

Add2 adds the passed two scalars together modulo the group order in constant time and stores the result in s.

The scalar is returned to support chaining. This enables syntax like: s3.Add2(s, s2).AddInt(1) so that s3 = s + s2 + 1.

func (*ModNScalar) Bytes 

func (s *ModNScalar) Bytes() [32]byte

Bytes unpacks the scalar to a 32-byte big-endian value in constant time.

See PutBytes and PutBytesUnchecked for variants that allow an array or slice to be passed which can be useful to cut down on the number of allocations by allowing the caller to reuse a buffer or write directly into part of a larger buffer.

func (*ModNScalar) Equals 

func (s *ModNScalar) Equals(val *ModNScalar) bool

Equals returns whether or not the two scalars are the same in constant time.

func (*ModNScalar) InverseNonConst 

func (s *ModNScalar) InverseNonConst() *ModNScalar

InverseNonConst finds the modular multiplicative inverse of the scalar in *non-constant* time. The existing scalar is modified.

The scalar is returned to support chaining. This enables syntax like: s.Inverse().Mul(s2) so that s = s^-1 * s2.

func (*ModNScalar) InverseValNonConst 

func (s *ModNScalar) InverseValNonConst(val *ModNScalar) *ModNScalar

InverseValNonConst finds the modular multiplicative inverse of the passed scalar and stores result in s in *non-constant* time.

The scalar is returned to support chaining. This enables syntax like: s3.InverseVal(s1).Mul(s2) so that s3 = s1^-1 * s2.

func (*ModNScalar) IsOdd 

func (s *ModNScalar) IsOdd() bool

IsOdd returns whether or not the scalar is an odd number in constant time.

func (*ModNScalar) IsOverHalfOrder 

func (s *ModNScalar) IsOverHalfOrder() bool

IsOverHalfOrder returns whether or not the scalar exceeds the group order divided by 2 in constant time.

func (*ModNScalar) IsZero 

func (s *ModNScalar) IsZero() bool

IsZero returns whether or not the scalar is equal to zero in constant time.

func (*ModNScalar) Mul 

func (s *ModNScalar) Mul(val *ModNScalar) *ModNScalar

Mul multiplies the passed scalar with the existing one modulo the group order in constant time and stores the result in s.

The scalar is returned to support chaining. This enables syntax like: s.Mul(s2).AddInt(1) so that s = (s * s2) + 1.

func (*ModNScalar) Mul2 

func (s *ModNScalar) Mul2(val, val2 *ModNScalar) *ModNScalar

Mul2 multiplies the passed two scalars together modulo the group order in constant time and stores the result in s.

The scalar is returned to support chaining. This enables syntax like: s3.Mul2(s, s2).AddInt(1) so that s3 = (s * s2) + 1.

func (*ModNScalar) Negate 

func (s *ModNScalar) Negate() *ModNScalar

Negate negates the scalar modulo the group order in constant time. The existing scalar is modified.

The scalar is returned to support chaining. This enables syntax like: s.Negate().AddInt(1) so that s = -s + 1.

func (*ModNScalar) NegateVal 

func (s *ModNScalar) NegateVal(val *ModNScalar) *ModNScalar

NegateVal negates the passed scalar modulo the group order and stores the result in s in constant time.

The scalar is returned to support chaining. This enables syntax like: s.NegateVal(s2).AddInt(1) so that s = -s2 + 1.

func (*ModNScalar) PutBytes 

func (s *ModNScalar) PutBytes(b *[32]byte)

PutBytes unpacks the scalar to a 32-byte big-endian value using the passed byte array in constant time.

There is a similar function, PutBytesUnchecked, which unpacks the scalar into a slice that must have at least 32 bytes available. This version is provided since it can be useful to write directly into an array that is type checked.

Alternatively, there is also Bytes, which unpacks the scalar into a new array and returns that which can sometimes be more ergonomic in applications that aren't concerned about an additional copy.

func (*ModNScalar) PutBytesUnchecked 

func (s *ModNScalar) PutBytesUnchecked(b []byte)

PutBytesUnchecked unpacks the scalar to a 32-byte big-endian value directly into the passed byte slice in constant time. The target slice must must have at least 32 bytes available or it will panic.

There is a similar function, PutBytes, which unpacks the scalar into a 32-byte array directly. This version is provided since it can be useful to write directly into part of a larger buffer without needing a separate allocation.

Preconditions:

  • The target slice MUST have at least 32 bytes available

func (*ModNScalar) Set 

func (s *ModNScalar) Set(val *ModNScalar) *ModNScalar

Set sets the scalar equal to a copy of the passed one in constant time.

The scalar is returned to support chaining. This enables syntax like: s := new(ModNScalar).Set(s2).Add(1) so that s = s2 + 1 where s2 is not modified.

func (*ModNScalar) SetByteSlice 

func (s *ModNScalar) SetByteSlice(b []byte) bool

SetByteSlice interprets the provided slice as a 256-bit big-endian unsigned integer (meaning it is truncated to the first 32 bytes), reduces it modulo the group order, sets the scalar to the result, and returns whether or not the resulting truncated 256-bit integer overflowed in constant time.

Note that since passing a slice with more than 32 bytes is truncated, it is possible that the truncated value is less than the order of the curve and hence it will not be reported as having overflowed in that case. It is up to the caller to decide whether it needs to provide numbers of the appropriate size or it is acceptable to use this function with the described truncation and overflow behavior.

func (*ModNScalar) SetBytes 

func (s *ModNScalar) SetBytes(b *[32]byte) uint32

SetBytes interprets the provided array as a 256-bit big-endian unsigned integer, reduces it modulo the group order, sets the scalar to the result, and returns either 1 if it was reduced (aka it overflowed) or 0 otherwise in constant time.

Note that a bool is not used here because it is not possible in Go to convert from a bool to numeric value in constant time and many constant-time operations require a numeric value.

func (*ModNScalar) SetInt 

func (s *ModNScalar) SetInt(ui uint32) *ModNScalar

SetInt sets the scalar to the passed integer in constant time. This is a convenience function since it is fairly common to perform some arithmetic with small native integers.

The scalar is returned to support chaining. This enables syntax like: s := new(ModNScalar).SetInt(2).Mul(s2) so that s = 2 * s2.

func (*ModNScalar) Square 

func (s *ModNScalar) Square() *ModNScalar

Square squares the scalar modulo the group order in constant time. The existing scalar is modified.

The scalar is returned to support chaining. This enables syntax like: s.Square().Mul(s2) so that s = s^2 * s2.

func (*ModNScalar) SquareVal 

func (s *ModNScalar) SquareVal(val *ModNScalar) *ModNScalar

SquareVal squares the passed scalar modulo the group order in constant time and stores the result in s.

The scalar is returned to support chaining. This enables syntax like: s3.SquareVal(s).Mul(s) so that s3 = s^2 * s = s^3.

func (ModNScalar) String 

func (s ModNScalar) String() string

String returns the scalar as a human-readable hex string.

This is NOT constant time.

func (*ModNScalar) Zero 

func (s *ModNScalar) Zero()

Zero sets the scalar to zero in constant time. A newly created scalar is already set to zero. This function can be useful to clear an existing scalar for reuse.

type PrivateKey 

type PrivateKey struct {
	Key ModNScalar
}

PrivateKey provides facilities for working with secp256k1 private keys within this package and includes functionality such as serializing and parsing them as well as computing their associated public key.

func GeneratePrivateKey 

func GeneratePrivateKey() (*PrivateKey, error)

GeneratePrivateKey returns a private key that is suitable for use with secp256k1.

func NewPrivateKey 

func NewPrivateKey(key *ModNScalar) *PrivateKey

NewPrivateKey instantiates a new private key from a scalar encoded as a big integer.

func PrivKeyFromBytes 

func PrivKeyFromBytes(privKeyBytes []byte) *PrivateKey

PrivKeyFromBytes returns a private based on the provided byte slice which is interpreted as an unsigned 256-bit big-endian integer in the range [0, N-1], where N is the order of the curve.

Note that this means passing a slice with more than 32 bytes is truncated and that truncated value is reduced modulo N. It is up to the caller to either provide a value in the appropriate range or choose to accept the described behavior.

Typically callers should simply make use of GeneratePrivateKey when creating private keys which properly handles generation of appropriate values.

func (*PrivateKey) PubKey 

func (p *PrivateKey) PubKey() *PublicKey

PubKey computes and returns the public key corresponding to this private key. PubKey returns the PublicKey corresponding to this private key.

func (PrivateKey) Serialize 

func (p PrivateKey) Serialize() []byte

Serialize returns the private key as a 256-bit big-endian binary-encoded number, padded to a length of 32 bytes.

func (*PrivateKey) ToECDSA 

func (p *PrivateKey) ToECDSA() *ecdsa.PrivateKey

ToECDSA returns the private key as a *ecdsa.PrivateKey.

func (*PrivateKey) Zero 

func (p *PrivateKey) Zero()

Zero manually clears the memory associated with the private key. This can be used to explicitly clear key material from memory for enhanced security against memory scraping.

type PublicKey 

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

PublicKey provides facilities for efficiently working with secp256k1 public keys within this package and includes functions to serialize in both uncompressed and compressed SEC (Standards for Efficient Cryptography) formats.

func NewPublicKey 

func NewPublicKey(x, y *FieldVal) *PublicKey

NewPublicKey instantiates a new public key with the given x and y coordinates.

It should be noted that, unlike ParsePubKey, since this accepts arbitrary x and y coordinates, it allows creation of public keys that are not valid points on the secp256k1 curve. The IsOnCurve method of the returned instance can be used to determine validity.

func ParsePubKey 

func ParsePubKey(serialized []byte) (key *PublicKey, err error)

ParsePubKey parses a secp256k1 public key encoded according to the format specified by ANSI X9.62-1998, which means it is also compatible with the SEC (Standards for Efficient Cryptography) specification which is a subset of the former. In other words, it supports the uncompressed, compressed, and hybrid formats as follows:

Compressed: 

<format byte = 0x02/0x03><32-byte X coordinate>

Uncompressed: 

<format byte = 0x04><32-byte X coordinate><32-byte Y coordinate>

Hybrid: 

<format byte = 0x05/0x06><32-byte X coordinate><32-byte Y coordinate>

NOTE: The hybrid format makes little sense in practice an therefore this package will not produce public keys serialized in this format. However, this function will properly parse them since they exist in the wild.

func (*PublicKey) AsJacobian 

func (p *PublicKey) AsJacobian(result *JacobianPoint)

AsJacobian converts the public key into a Jacobian point with Z=1 and stores the result in the provided result param. This allows the public key to be treated a Jacobian point in the secp256k1 group in calculations.

func (*PublicKey) IsEqual 

func (p *PublicKey) IsEqual(otherPubKey *PublicKey) bool

IsEqual compares this PublicKey instance to the one passed, returning true if both PublicKeys are equivalent. A PublicKey is equivalent to another, if they both have the same X and Y coordinate.

func (*PublicKey) IsOnCurve 

func (p *PublicKey) IsOnCurve() bool

IsOnCurve returns whether or not the public key represents a point on the secp256k1 curve.

func (PublicKey) SerializeCompressed 

func (p PublicKey) SerializeCompressed() []byte

SerializeCompressed serializes a public key in the 33-byte compressed format.

func (PublicKey) SerializeUncompressed 

func (p PublicKey) SerializeUncompressed() []byte

SerializeUncompressed serializes a public key in the 65-byte uncompressed format.

func (*PublicKey) ToECDSA 

func (p *PublicKey) ToECDSA() *ecdsa.PublicKey

ToECDSA returns the public key as a *ecdsa.PublicKey.

func (*PublicKey) X 

func (p *PublicKey) X() *big.Int

X returns the x coordinate of the public key.

func (*PublicKey) Y 

func (p *PublicKey) Y() *big.Int

Y returns the y coordinate of the public key.

Source Files

View all Source files

Directories

Path Synopsis
Package ecdsa provides secp256k1-optimized ECDSA signing and verification.
 Package ecdsa provides secp256k1-optimized ECDSA signing and verification.
Package schnorr provides custom Schnorr signing and verification via secp256k1.
 Package schnorr provides custom Schnorr signing and verification via secp256k1.

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.