# README
secp256k1
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 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
FieldValtype for working modulo the secp256k1 field primeModNScalartype 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.
This package also 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.
Finally, a comprehensive suite of tests is provided to provide a high level of quality assurance.
Examples
-
Encryption Demonstrates encrypting and decrypting a message using a shared key derived through ECDHE.
-
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 secp256k1 is licensed under the copyfree ISC License.
# Functions
AddNonConst adds the passed Jacobian points together and stores the result in the provided result param in *non-constant* time.
DecompressY attempts to calculate the Y coordinate for the given X coordinate such that the result pair is a point on the secp256k1 curve.
DoubleNonConst doubles the passed Jacobian point and stores the result in the provided result parameter in *non-constant* time.
GeneratePrivateKey generates and returns a new cryptographically secure private key that is suitable for use with secp256k1.
GeneratePrivateKeyFromRand generates a private key that is suitable for use with secp256k1 using the provided reader as a source of entropy.
GenerateSharedSecret generates a shared secret based on a private key and a public key using Diffie-Hellman key exchange (ECDH) (RFC 5903).
MakeJacobianPoint returns a Jacobian point with the provided X, Y, and Z coordinates.
NewPrivateKey instantiates a new private key from a scalar encoded as a big integer.
NewPublicKey instantiates a new public key with the given x and y coordinates.
NewSignature instantiates a new signature given some r and s values.
NewSignatureWithRecoveryCode instantiates a new signature given some r and s values and a recovery code.
NonceRFC6979 generates a nonce deterministically according to RFC 6979 using HMAC-SHA256 for the hashing function.
Params returns the secp256k1 curve parameters for convenience.
No description provided by the author
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.
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.
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.
RecoverCompact attempts to recover the secp256k1 public key from the provided compact signature and message hash.
S256 returns an elliptic.Curve which implements secp256k1.
ScalarBaseMultNonConst multiplies k*G where k is a scalar modulo the curve order and G is the base point of the group and stores the result in the provided Jacobian point.
ScalarMultNonConst multiplies k*P where k is a scalar modulo the curve order and P is a point in Jacobian projective coordinates and stores the result in the provided Jacobian point.
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.
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.
# Constants
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.
ErrPubKeyInvalidFormat indicates an attempt was made to parse a public key that does not specify one of the supported formats.
ErrPubKeyInvalidLen indicates that the length of a serialized public key is not one of the allowed lengths.
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.
ErrPubKeyNotOnCurve indicates that a public key is not a point on the secp256k1 curve.
ErrPubKeyXTooBig indicates that the x coordinate for a public key is greater than or equal to the prime of the field underlying the group.
ErrPubKeyYTooBig indicates that the y coordinate for a public key is greater than or equal to the prime of the field underlying the group.
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.
ErrSigInvalidLen is returned when a signature that should be a compact signature is not the required length.
ErrSigInvalidRecoveryCode is returned when a signature that should be a compact signature has an invalid value for the public key recovery code.
ErrSigInvalidRIntID is returned when a signature that should be a DER signature does not have the expected ASN.1 integer ID for R.
ErrSigInvalidSeqID is returned when a signature that should be a DER signature does not have the expected ASN.1 sequence ID.
ErrSigInvalidSIntID is returned when a signature that should be a DER signature does not have the expected ASN.1 integer ID for S.
ErrSigInvalidSLen is returned when a signature that should be a DER signature does not specify the correct number of bytes for the S portion.
ErrSigMissingSLen is returned when a signature that should be a DER signature does not provide the length of S.
ErrSigMissingSTypeID is returned when a signature that should be a DER signature does not provide the ASN.1 type ID for S.
ErrSigNegativeR is returned when a signature that should be a DER signature has a negative value for R.
ErrSigNegativeS is returned when a signature that should be a DER signature has a negative value for S.
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.
ErrSigRIsZero is returned when a signature has R set to the value zero.
ErrSigRTooBig is returned when a signature has R with a value that is greater than or equal to the group order.
ErrSigSIsZero is returned when a signature has S set to the value zero.
ErrSigSTooBig is returned when a signature has S with a value that is greater than or equal to the group order.
ErrSigTooLong is returned when a signature that should be a DER signature is too long.
ErrSigTooMuchRPadding is returned when a signature that should be a DER signature has too much padding for R.
ErrSigTooMuchSPadding is returned when a signature that should be a DER signature has too much padding for S.
ErrSigTooShort is returned when a signature that should be a DER signature is too short.
ErrSigZeroRLen is returned when a signature that should be a DER signature has an R length of zero.
ErrSigZeroSLen is returned when a signature that should be a DER signature has an S length of zero.
PrivKeyBytesLen defines the length in bytes of a serialized private key.
PubKeyBytesLenCompressed is the number of bytes of a serialized compressed public key.
PubKeyBytesLenUncompressed is the number of bytes of a serialized uncompressed public key.
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).
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).
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].
PubKeyFormatHybridOdd 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].
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).
No description provided by the author
DER format by default.
# Structs
CurveParams contains the parameters for the secp256k1 curve.
Error identifies an error related to public key cryptography using a sec256k1 curve.
FieldVal implements optimized fixed-precision arithmetic over the secp256k1 finite field.
JacobianPoint is an element of the group formed by the secp256k1 curve in Jacobian projective coordinates and thus represents a point on the curve.
KoblitzCurve provides an implementation for secp256k1 that fits the ECC Curve interface from crypto/elliptic.
ModNScalar implements optimized 256-bit constant-time fixed-precision arithmetic over the secp256k1 group order.
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.
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.
Signature is a type representing an ECDSA signature.
No description provided by the author