These constants are used to identify a specific RuleError.
const (
// ErrPubKeyInvalidLen indicates that the length of a serialized public
// key is not one of the allowed lengths.
ErrPubKeyInvalidLen = ErrorKind("ErrPubKeyInvalidLen")
// ErrPubKeyInvalidFormat indicates an attempt was made to parse a public
// key that does not specify one of the supported formats.
ErrPubKeyInvalidFormat = ErrorKind("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 = ErrorKind("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 = ErrorKind("ErrPubKeyYTooBig")
// ErrPubKeyNotOnCurve indicates that a public key is not a point on the
// secp256k1 curve.
ErrPubKeyNotOnCurve = ErrorKind("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 = ErrorKind("ErrPubKeyMismatchedOddness")
)
const (
// PubKeyBytesLenCompressed is the number of bytes of a serialized
// compressed public key.
PubKeyBytesLenCompressed = 33
// PubKeyBytesLenUncompressed 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
// 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.
PubKeyFormatHybridOdd byte = 0x07
)
PrivKeyBytesLen defines the length in bytes of a serialized private key.
const PrivKeyBytesLen = 32
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(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(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(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 securely hash the result before using as a cryptographic key.
func ScalarBaseMultNonConst(k *ModNScalar, result *JacobianPoint)
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.
func ScalarMultNonConst(k *ModNScalar, point, result *JacobianPoint)
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.
CurveParams contains the parameters for the secp256k1 curve.
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
}
func Params() *CurveParams
Params returns the secp256k1 curve parameters for convenience.
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.
type Error struct {
Err error
Description string
}
func (e Error) Error() string
Error satisfies the error interface and prints human-readable errors.
func (e Error) Unwrap() error
Unwrap returns the underlying wrapped error.
ErrorKind identifies a kind of error. It has full support for errors.Is and errors.As, so the caller can directly check against an error kind when determining the reason for an error.
type ErrorKind string
func (e ErrorKind) Error() string
Error satisfies the error interface and prints human-readable errors.
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.
type FieldVal struct {
// contains filtered or unexported fields
}
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 (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 (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 (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 (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 (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 (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 (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 (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 (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 (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 (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 (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 (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 (f *FieldVal) Mul2(val *FieldVal, val2 *FieldVal) *FieldVal
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
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 (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 (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 (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 (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 (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 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 (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 (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 (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 (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 (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 (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 (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 (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 (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
JacobianPoint is an element of the group formed by the secp256k1 curve in Jacobian projective coordinates and thus represents a point on the curve.
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
}
func MakeJacobianPoint(x, y, z *FieldVal) JacobianPoint
MakeJacobianPoint returns a Jacobian point with the provided X, Y, and Z coordinates.
func (p *JacobianPoint) Set(other *JacobianPoint)
Set sets the Jacobian point to the provided point.
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.
KoblitzCurve provides an implementation for secp256k1 that fits the ECC Curve interface from crypto/elliptic.
type KoblitzCurve struct {
*elliptic.CurveParams
}
func S256() *KoblitzCurve
S256 returns an elliptic.Curve which implements secp256k1.
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 (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 (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 (curve *KoblitzCurve) Params() *elliptic.CurveParams
Params returns the parameters for the curve.
This is part of the elliptic.Curve interface implementation.
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 (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.
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.
type ModNScalar struct {
// contains filtered or unexported fields
}
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 (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 (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 (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 (s *ModNScalar) Equals(val *ModNScalar) bool
Equals returns whether or not the two scalars are the same in constant time.
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 (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 (s *ModNScalar) IsOdd() bool
IsOdd returns whether or not the scalar is an odd number in constant time.
func (s *ModNScalar) IsOverHalfOrder() bool
IsOverHalfOrder returns whether or not the scalar exceeds the group order divided by 2 in constant time.
func (s *ModNScalar) IsZero() bool
IsZero returns whether or not the scalar is equal to zero in constant time.
func (s *ModNScalar) IsZeroBit() uint32
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.
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 (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 (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 (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 (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 (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 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:
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 (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 (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 (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 (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 (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 (s ModNScalar) String() string
String returns the scalar as a human-readable hex string.
This is NOT constant time.
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.
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.
type PrivateKey struct {
Key ModNScalar
}
func GeneratePrivateKey() (*PrivateKey, error)
GeneratePrivateKey generates and returns a new cryptographically secure private key that is suitable for use with secp256k1.
func GeneratePrivateKeyFromRand(rand io.Reader) (*PrivateKey, error)
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.
func NewPrivateKey(key *ModNScalar) *PrivateKey
NewPrivateKey instantiates a new private key from a scalar encoded as a big integer.
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.
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.
func (p *PrivateKey) PubKey() *PublicKey
PubKey computes and returns the public key corresponding to this private key.
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 (p *PrivateKey) ToECDSA() *ecdsa.PrivateKey
ToECDSA returns the private key as a *ecdsa.PrivateKey.
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.
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.
type PublicKey struct {
// contains filtered or unexported fields
}
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(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 (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 (p *PublicKey) IsEqual(otherPubKey *PublicKey) bool
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.
func (p *PublicKey) IsOnCurve() bool
IsOnCurve returns whether or not the public key represents a point on the secp256k1 curve.
func (p PublicKey) SerializeCompressed() []byte
SerializeCompressed serializes a public key in the 33-byte compressed format.
func (p PublicKey) SerializeUncompressed() []byte
SerializeUncompressed serializes a public key in the 65-byte uncompressed format.
func (p *PublicKey) ToECDSA() *ecdsa.PublicKey
ToECDSA returns the public key as a *ecdsa.PublicKey.
func (p *PublicKey) X() *big.Int
X returns the x coordinate of the public key.
func (p *PublicKey) Y() *big.Int
Y returns the y coordinate of the public key.