Involved Source Filescompressedbytepoints.gocurve.gocurve_precompute.go Package secp256k1 implements optimized secp256k1 elliptic curve operations in
pure Go.
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.ecdh.goellipticadaptor.goerror.gofield.goloadprecomputed.gomodnscalar.gononce.goprivkey.gopubkey.go
CurveParams contains the parameters for the secp256k1 curve. BitSize is the size of the underlying secp256k1 field in bits. ByteSize is simply the bit size / 8 and is provided for convenience
since it is calculated repeatedly. Gx and Gy are the x and y coordinate of the base point, respectively. Gx and Gy are the x and y coordinate of the base point, respectively. H is the cofactor of the secp256k1 curve. N is the order of the secp256k1 curve group generated by the base point. P is the prime used in the secp256k1 field.
func Params() *CurveParams
Error identifies an error related to public key cryptography using a
sec256k1 curve. 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.DescriptionstringErrerror Error satisfies the error interface and prints human-readable errors. Unwrap returns the underlying wrapped error.
Error : error
Error : golang.org/x/xerrors.Wrapper
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 32. 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 32
Output Normalized: No
Output Max Magnitude: Sum of the magnitude of the two individual field values 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 32
Output Normalized: No
Output Max Magnitude: Sum of the magnitude of the two field values 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 31
- The integer MUST be a max of 32767
Output Normalized: No
Output Max Magnitude: Existing field magnitude + 1 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 Equals returns whether or not the two field values are the same in constant
time.
Preconditions:
- Both field values being compared MUST be normalized 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 IsGtOrEqPrimeMinusOrder returns whether or not the field value is greater
than or equal to the field prime minus the secp256k1 group order in constant
time.
Preconditions:
- The field value MUST be normalized IsOdd returns whether or not the field value is an odd number in constant
time.
Preconditions:
- The field value MUST be normalized 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 IsOne returns whether or not the field value is equal to one in constant
time.
Preconditions:
- The field value MUST be normalized 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 IsZero returns whether or not the field value is equal to zero in constant
time.
Preconditions:
- The field value MUST be normalized 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 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 Mul2 multiplies the passed two field values together 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:
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 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 32
Output Normalized: No
Output Max Magnitude: Existing field magnitude times the provided integer val Negate negates the field value in constant time. The existing field value is
modified. The caller must provide the maximum 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 31
Output Normalized: No
Output Max Magnitude: Input magnitude + 1 NegateVal negates the passed value and stores the result in f in constant
time. The caller must provide the maximum 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 31
Output Normalized: No
Output Max Magnitude: Input magnitude + 1 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 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 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
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 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 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 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 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 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 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 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 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 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
FieldVal : expvar.Var
FieldVal : fmt.Stringer
*FieldVal : gopkg.in/yaml.v3.IsZeroer
func (*FieldVal).Add(val *FieldVal) *FieldVal
func (*FieldVal).Add2(val *FieldVal, val2 *FieldVal) *FieldVal
func (*FieldVal).AddInt(ui uint16) *FieldVal
func (*FieldVal).Inverse() *FieldVal
func (*FieldVal).Mul(val *FieldVal) *FieldVal
func (*FieldVal).Mul2(val *FieldVal, val2 *FieldVal) *FieldVal
func (*FieldVal).MulInt(val uint8) *FieldVal
func (*FieldVal).Negate(magnitude uint32) *FieldVal
func (*FieldVal).NegateVal(val *FieldVal, magnitude uint32) *FieldVal
func (*FieldVal).Normalize() *FieldVal
func (*FieldVal).Set(val *FieldVal) *FieldVal
func (*FieldVal).SetInt(ui uint16) *FieldVal
func (*FieldVal).Square() *FieldVal
func (*FieldVal).SquareVal(val *FieldVal) *FieldVal
func DecompressY(x *FieldVal, odd bool, resultY *FieldVal) bool
func DecompressY(x *FieldVal, odd bool, resultY *FieldVal) bool
func MakeJacobianPoint(x, y, z *FieldVal) JacobianPoint
func NewPublicKey(x, y *FieldVal) *PublicKey
func (*FieldVal).Add(val *FieldVal) *FieldVal
func (*FieldVal).Add2(val *FieldVal, val2 *FieldVal) *FieldVal
func (*FieldVal).Add2(val *FieldVal, val2 *FieldVal) *FieldVal
func (*FieldVal).Equals(val *FieldVal) bool
func (*FieldVal).Mul(val *FieldVal) *FieldVal
func (*FieldVal).Mul2(val *FieldVal, val2 *FieldVal) *FieldVal
func (*FieldVal).Mul2(val *FieldVal, val2 *FieldVal) *FieldVal
func (*FieldVal).NegateVal(val *FieldVal, magnitude uint32) *FieldVal
func (*FieldVal).Set(val *FieldVal) *FieldVal
func (*FieldVal).SquareRootVal(val *FieldVal) bool
func (*FieldVal).SquareVal(val *FieldVal) *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. The X coordinate in Jacobian projective coordinates. The affine point is
X/z^2. The Y coordinate in Jacobian projective coordinates. The affine point is
Y/z^3. The Z coordinate in Jacobian projective coordinates. EquivalentNonConst returns whether or not two Jacobian points represent the
same affine point in *non-constant* time. Set sets the Jacobian point to the provided point. 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.
func MakeJacobianPoint(x, y, z *FieldVal) JacobianPoint
func AddNonConst(p1, p2, result *JacobianPoint)
func DoubleNonConst(p, result *JacobianPoint)
func ScalarBaseMultNonConst(k *ModNScalar, result *JacobianPoint)
func ScalarMultNonConst(k *ModNScalar, point, result *JacobianPoint)
func (*JacobianPoint).EquivalentNonConst(other *JacobianPoint) bool
func (*JacobianPoint).Set(other *JacobianPoint)
func (*PublicKey).AsJacobian(result *JacobianPoint)
KoblitzCurve provides an implementation for secp256k1 that fits the ECC Curve
interface from crypto/elliptic.CurveParams*elliptic.CurveParams // the constant of the curve equation // the size of the underlying field // (x,y) of the base point // (x,y) of the base point // the order of the base point // the canonical name of the curve // the order of the underlying field Add returns the sum of (x1,y1) and (x2,y2).
This is part of the elliptic.Curve interface implementation. Double returns 2*(x1,y1).
This is part of the elliptic.Curve interface implementation. 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. Params returns the parameters for the curve.
This is part of the elliptic.Curve interface implementation. 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. ScalarMult returns k*(bx, by) where k is a big endian integer.
This is part of the elliptic.Curve interface implementation.
*KoblitzCurve : crypto/elliptic.Curve
func S256() *KoblitzCurve
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. 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. 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. 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. Equals returns whether or not the two scalars are the same in constant time. 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. 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. IsOdd returns whether or not the scalar is an odd number in constant time. IsOverHalfOrder returns whether or not the scalar exceeds the group order
divided by 2 in constant time. IsZero returns whether or not the scalar is equal to zero in constant time. IsZeroBit returns 1 when the scalar 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. 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. 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. 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. 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. 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. PutBytesUnchecked unpacks the scalar to a 32-byte big-endian value directly
into the passed byte slice in constant time. The target slice 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 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. 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. 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. 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. 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. 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. String returns the scalar as a human-readable hex string.
This is NOT constant time. 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.
ModNScalar : expvar.Var
ModNScalar : fmt.Stringer
*ModNScalar : gopkg.in/yaml.v3.IsZeroer
func NonceRFC6979(privKey []byte, hash []byte, extra []byte, version []byte, extraIterations uint32) *ModNScalar
func (*ModNScalar).Add(val *ModNScalar) *ModNScalar
func (*ModNScalar).Add2(val1, val2 *ModNScalar) *ModNScalar
func (*ModNScalar).InverseNonConst() *ModNScalar
func (*ModNScalar).InverseValNonConst(val *ModNScalar) *ModNScalar
func (*ModNScalar).Mul(val *ModNScalar) *ModNScalar
func (*ModNScalar).Mul2(val, val2 *ModNScalar) *ModNScalar
func (*ModNScalar).Negate() *ModNScalar
func (*ModNScalar).NegateVal(val *ModNScalar) *ModNScalar
func (*ModNScalar).Set(val *ModNScalar) *ModNScalar
func (*ModNScalar).SetInt(ui uint32) *ModNScalar
func (*ModNScalar).Square() *ModNScalar
func (*ModNScalar).SquareVal(val *ModNScalar) *ModNScalar
func github.com/decred/dcrd/dcrec/secp256k1/v4/ecdsa.(*Signature).R() ModNScalar
func github.com/decred/dcrd/dcrec/secp256k1/v4/ecdsa.(*Signature).S() ModNScalar
func NewPrivateKey(key *ModNScalar) *PrivateKey
func ScalarBaseMultNonConst(k *ModNScalar, result *JacobianPoint)
func ScalarMultNonConst(k *ModNScalar, point, result *JacobianPoint)
func (*ModNScalar).Add(val *ModNScalar) *ModNScalar
func (*ModNScalar).Add2(val1, val2 *ModNScalar) *ModNScalar
func (*ModNScalar).Equals(val *ModNScalar) bool
func (*ModNScalar).InverseValNonConst(val *ModNScalar) *ModNScalar
func (*ModNScalar).Mul(val *ModNScalar) *ModNScalar
func (*ModNScalar).Mul2(val, val2 *ModNScalar) *ModNScalar
func (*ModNScalar).NegateVal(val *ModNScalar) *ModNScalar
func (*ModNScalar).Set(val *ModNScalar) *ModNScalar
func (*ModNScalar).SquareVal(val *ModNScalar) *ModNScalar
func github.com/decred/dcrd/dcrec/secp256k1/v4/ecdsa.NewSignature(r, s *ModNScalar) *ecdsa.Signature
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.KeyModNScalar PubKey computes and returns the public key corresponding to this private key. Serialize returns the private key as a 256-bit big-endian binary-encoded
number, padded to a length of 32 bytes. ToECDSA returns the private key as a *ecdsa.PrivateKey. 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.
func GeneratePrivateKey() (*PrivateKey, error)
func GeneratePrivateKeyFromRand(rand io.Reader) (*PrivateKey, error)
func NewPrivateKey(key *ModNScalar) *PrivateKey
func PrivKeyFromBytes(privKeyBytes []byte) *PrivateKey
func GenerateSharedSecret(privkey *PrivateKey, pubkey *PublicKey) []byte
func github.com/decred/dcrd/dcrec/secp256k1/v4/ecdsa.Sign(key *PrivateKey, hash []byte) *ecdsa.Signature
func github.com/decred/dcrd/dcrec/secp256k1/v4/ecdsa.SignCompact(key *PrivateKey, hash []byte, isCompressedKey bool) []byte
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. 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. IsEqual compares this public key instance to the one passed, returning true
if both public keys are equivalent. A public key is equivalent to another,
if they both have the same X and Y coordinates. IsOnCurve returns whether or not the public key represents a point on the
secp256k1 curve. SerializeCompressed serializes a public key in the 33-byte compressed format. SerializeUncompressed serializes a public key in the 65-byte uncompressed
format. ToECDSA returns the public key as a *ecdsa.PublicKey. X returns the x coordinate of the public key. Y returns the y coordinate of the public key.
func NewPublicKey(x, y *FieldVal) *PublicKey
func ParsePubKey(serialized []byte) (key *PublicKey, err error)
func (*PrivateKey).PubKey() *PublicKey
func github.com/decred/dcrd/dcrec/secp256k1/v4/ecdsa.RecoverCompact(signature, hash []byte) (*PublicKey, bool, error)
func GenerateSharedSecret(privkey *PrivateKey, pubkey *PublicKey) []byte
func (*PublicKey).IsEqual(otherPubKey *PublicKey) bool
func github.com/decred/dcrd/dcrec/secp256k1/v4/ecdsa.(*Signature).Verify(hash []byte, pubKey *PublicKey) bool
Package-Level Functions (total 16)
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.
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 value must be a max of 8 for
a correct result. The resulting Y field value will have a magnitude of 1.
Preconditions:
- The input field value MUST have a max magnitude of 8
Output Normalized: Yes if the func returns true, no otherwise
Output Max Magnitude: 1
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.
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. The
provided reader must be a source of cryptographically secure randomness, such
as [crypto/rand.Reader], to avoid weak private keys.
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 securely hash the result before using as a cryptographic
key.
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.
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.
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.
Params returns the secp256k1 curve parameters for convenience.
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.
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.
WARNING: This means passing a slice with more than 32 bytes is truncated and
that truncated value is reduced modulo N. Further, 0 is not a valid private
key. It is up to the caller to provide a value in the appropriate range of
[1, N-1]. Failure to do so will either result in an invalid private key or
potentially weak private keys that have bias that could be exploited.
This function primarily exists to provide a mechanism for converting
serialized private keys that are already known to be good.
Typically callers should make use of GeneratePrivateKey or
GeneratePrivateKeyFromRand when creating private keys since they properly
handle generation of appropriate values.
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.
NOTE: The resulting point will be normalized.
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.
NOTE: The point must be normalized for this function to return the correct
result. The resulting point will be normalized.
Package-Level Constants (total 14)
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.
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].
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 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.
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).
The pages are generated with Goldsv0.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.
