Documentation
¶
Overview ¶
Package secec implements the common primitives on top of secp256k1, with an API that is close to the runtime library's `crypto/ecdsa` and `crypto/ecdh` packages.
Index ¶
- Constants
- func BuildASN1Signature(r, s *secp256k1.Scalar) []byte
- func BuildCompactRecoverableSignature(r, s *secp256k1.Scalar, v byte) []byte
- func BuildCompactSignature(r, s *secp256k1.Scalar) []byte
- func ParseASN1Signature(data []byte) (*secp256k1.Scalar, *secp256k1.Scalar, error)
- func ParseCompactRecoverableSignature(data []byte) (*secp256k1.Scalar, *secp256k1.Scalar, byte, error)
- func ParseCompactSignature(data []byte) (*secp256k1.Scalar, *secp256k1.Scalar, error)
- func RFC6979SHA256() io.Reader
- type ECDSAOptions
- type PrivateKey
- func (k *PrivateKey) Bytes() []byte
- func (k *PrivateKey) ECDH(remote *PublicKey) ([]byte, error)
- func (k *PrivateKey) Equal(x crypto.PrivateKey) bool
- func (k *PrivateKey) Public() crypto.PublicKey
- func (k *PrivateKey) PublicKey() *PublicKey
- func (k *PrivateKey) Scalar() *secp256k1.Scalar
- func (k *PrivateKey) Sign(rand io.Reader, digest []byte, opts crypto.SignerOpts) ([]byte, error)
- func (k *PrivateKey) SignRaw(rand io.Reader, digest []byte) (*secp256k1.Scalar, *secp256k1.Scalar, byte, error)
- type PublicKey
- func (k *PublicKey) ASN1Bytes() []byte
- func (k *PublicKey) Bytes() []byte
- func (k *PublicKey) CompressedBytes() []byte
- func (k *PublicKey) Equal(x crypto.PublicKey) bool
- func (k *PublicKey) Point() *secp256k1.Point
- func (k *PublicKey) Verify(digest, sig []byte, opts *ECDSAOptions) bool
- func (k *PublicKey) VerifyRaw(digest []byte, r, s *secp256k1.Scalar) bool
- type SignatureEncoding
Constants ¶
const ( // CompactSignatureSize is the size of a compact signature in bytes. CompactSignatureSize = 64 // CompactRecoverableSignatureSize is the size of a compact recoverable // signature in bytes. CompactRecoverableSignatureSize = 65 )
const PrivateKeySize = 32
PrivateKeySize is the size of a secp256k1 private key in bytes.
Variables ¶
This section is empty.
Functions ¶
func BuildASN1Signature ¶
func BuildASN1Signature(r, s *secp256k1.Scalar) []byte
BuildASN1Signature serializes `(r, s)` into an ASN.1 encoded signature as specified in SEC 1, Version 2.0, Appendix C.8.
func BuildCompactRecoverableSignature ¶
BuildCompactRecoverableSignature serializes `(r, s, v)` into a "compact" `[R | S | V]` signature.
func BuildCompactSignature ¶
func BuildCompactSignature(r, s *secp256k1.Scalar) []byte
BuildCompactSignature serializes `(r, s)` into a "compact" `[R | S]` signature.
func ParseASN1Signature ¶
ParseASN1Signature parses an ASN.1 encoded signature as specified in SEC 1, Version 2.0, Appendix C.8, and returns the scalars `(r, s)`.
Note: The signature MUST be `SEQUENCE { r INTEGER, s INTEGER }`, as in encoded as a `ECDSA-Sig-Value`, WITHOUT the optional `a` and `y` fields. Both `r` and `s` MUST be in the range `[1, n)`.
func ParseCompactRecoverableSignature ¶
func ParseCompactRecoverableSignature(data []byte) (*secp256k1.Scalar, *secp256k1.Scalar, byte, error)
ParseCompactRecoverableSignature parses a "compact" `[R | S | V]` signature, and returns the scalars `(r, s)` and recovery ID `v`. Both `r` and `s` MUST be in the range `[1, n)`. `v` MUST be in the range `[0,3]`.
func ParseCompactSignature ¶
ParseCompactSignature parses a "compact" `[R | S]` signature, and returns the scalars `(r, s)`. Both `r` and `s` MUST be in the range `[1, n)`.
func RFC6979SHA256 ¶
RFC6979SHA256 returns an io.Reader that will make the `Sign` and `SignRaw` ECDSA routines return deterministic signatures with the nonce generation algorithm as specified in RFC 6979, using SHA-256 as the hash function, when strict output compatibility with other implementations is required.
This option is not otherwise required or recommended, and providing an entropy source when available is likely better.
WARNING: This returns a non-functional placeholder reader that will panic if actually used. The returned reader is incompatible with non-ECDSA use cases.
Types ¶
type ECDSAOptions ¶
type ECDSAOptions struct {
// Hash is the digest algorithm used to hash the digest. It is
// used only for the purpose of validating input parameters. If
// unspecified, [crypto.SHA256] will be assumed.
Hash crypto.Hash
// Encoding selects the signature encoding format.
Encoding SignatureEncoding
// SelfVerify will cause the signing process to verify the
// signature after signing, to improve resilience against certain
// fault attacks.
//
// WARNING: If this is set, signing will be significantly more
// expensive.
SelfVerify bool
// RejectMalleable will cause the verification process to
// reject signatures where `s > n / 2`.
RejectMalleable bool
}
ECDSAOptions can be used with `PrivateKey.Sign` or `PublicKey.Verify` to select ECDSA options.
func (*ECDSAOptions) HashFunc ¶
func (opt *ECDSAOptions) HashFunc() crypto.Hash
HashFunc returns an identifier for the hash function used to produce the message passed to crypto.Signer.Sign, or else zero to indicate that no hashing was done.
type PrivateKey ¶
type PrivateKey struct {
// contains filtered or unexported fields
}
PrivateKey is a secp256k1 private key.
func GenerateKey ¶
func GenerateKey() (*PrivateKey, error)
GenerateKey generates a new PrivateKey, using crypto/rand.Reader as the entropy source.
func NewPrivateKey ¶
func NewPrivateKey(key []byte) (*PrivateKey, error)
NewPrivateKey checks that `key` is valid and returns a PrivateKey.
This follows SEC 1, Version 2.0, Section 2.3.6, which amounts to decoding the bytes as a fixed length big endian integer and checking that the result is lower than the order of the curve. The zero private key is also rejected, as the encoding of the corresponding public key would be irregular.
func NewPrivateKeyFromScalar ¶
func NewPrivateKeyFromScalar(s *secp256k1.Scalar) (*PrivateKey, error)
NewPrivateKeyFromScalar checks that `s` is valid and returns a PrivateKey.
func (*PrivateKey) Bytes ¶
func (k *PrivateKey) Bytes() []byte
Bytes returns a copy of the encoding of the private key.
func (*PrivateKey) ECDH ¶
func (k *PrivateKey) ECDH(remote *PublicKey) ([]byte, error)
ECDH performs a ECDH exchange and returns the shared secret as specified in SEC 1, Version 2.0, Section 3.3.1, and returns the x-coordinate encoded according to SEC 1, Version 2.0, Section 2.3.5. The result is never the point at infinity.
func (*PrivateKey) Equal ¶
func (k *PrivateKey) Equal(x crypto.PrivateKey) bool
Equal returns whether `x` represents the same private key as `k`. This check is performed in constant time as long as the key types match.
func (*PrivateKey) Public ¶
func (k *PrivateKey) Public() crypto.PublicKey
func (*PrivateKey) PublicKey ¶
func (k *PrivateKey) PublicKey() *PublicKey
PublicKey returns the ECDSA/ECDH public key corresponding to `k`.
func (*PrivateKey) Scalar ¶
func (k *PrivateKey) Scalar() *secp256k1.Scalar
Scalar returns a copy of the scalar underlying `k`.
func (*PrivateKey) Sign ¶
func (k *PrivateKey) Sign(rand io.Reader, digest []byte, opts crypto.SignerOpts) ([]byte, error)
Sign signs `digest` (which should be the result of hashing a larger message) using the PrivateKey `k`, using the signing procedure as specified in SEC 1, Version 2.0, Section 4.1.3. It returns the byte-encoded signature. If `opts` is not a `*ECDSAOptions` the output encoding will default to `EncodingASN1`.
Notes: If `rand` is nil, crypto/rand.Reader will be used. `s` will always be less than or equal to `n / 2`.
func (*PrivateKey) SignRaw ¶
func (k *PrivateKey) SignRaw(rand io.Reader, digest []byte) (*secp256k1.Scalar, *secp256k1.Scalar, byte, error)
SignRaw signs `digest` (which should be the result of hashing a larger message) using the PrivateKey `k`, using the signing procedure as specified in SEC 1, Version 2.0, Section 4.1.3. It returns the tuple `(r, s, recovery_id)`.
Notes: If `rand` is nil, crypto/rand.Reader will be used. `s` will always be less than or equal to `n / 2`. `recovery_id` will always be in the range `[0, 3]`.
type PublicKey ¶
type PublicKey struct {
// contains filtered or unexported fields
}
PublicKey is a secp256k1 public key.
func NewPublicKey ¶
NewPublicKey checks that `key` is valid and returns a PublicKey.
This decodes an encoded point according to SEC 1, Version 2.0, Section 2.3.4. The point at infinity is rejected.
func NewPublicKeyFromPoint ¶
NewPublicKeyFromPoint checks that `point` is valid, and returns a PublicKey.
func ParseASN1PublicKey ¶
ParseASN1PublicKey parses an ASN.1 encoded public key as specified in SEC 1, Version 2.0, Appendix C.3.
WARNING: This is incomplete and "best-effort". In particular parsing the case where the curve is parameterized as part of the public key is not, and will not be supported.
func RecoverPublicKey ¶
RecoverPublicKey recovers the public key from the signature `(r, s, recoveryID)` over `digest`. `recoverID` MUST be in the range `[0,3]`.
Note: `s` in the range `[1, n)` is considered valid here. It is the caller's responsibility to check `s.IsGreaterThanHalfN()` as required.
func (*PublicKey) ASN1Bytes ¶
ASN1Bytes returns a copy of the ASN.1 encoding of the public key, as specified in SEC 1, Version 2.0, Appendix C.3.
func (*PublicKey) CompressedBytes ¶
CompressedBytes returns a copy of the compressed encoding of the public key.
func (*PublicKey) Equal ¶
Equal returns whether `x` represents the same public key as `k`. This check is performed in constant time as long as the key types match.
func (*PublicKey) Point ¶
func (k *PublicKey) Point() *secp256k1.Point
Point returns a copy of the point underlying `k`.
func (*PublicKey) Verify ¶
func (k *PublicKey) Verify(digest, sig []byte, opts *ECDSAOptions) bool
Verify verifies the byte encoded signature `sig` of `digest`, using the PublicKey `k`, using the verification procedure as specified in SEC 1, Version 2.0, Section 4.1.4. Its return value records whether the signature is valid. If `opts` is nil, the input encoding will default to `EncodingASN1`, and `s` in the range `[1,n)` will be accepted.
type SignatureEncoding ¶
type SignatureEncoding int
SignatureEncoding is a ECDSA signature encoding method.
const ( // EncodingASN1 is an ASN.1 `SEQUENCE { r INTEGER, s INTEGER }`. EncodingASN1 SignatureEncoding = iota // EncodingCompact is `[R | S]`, with the scalars encoded as // 32-byte big-endian integers. EncodingCompact // EncodingCompactRecoverable is `[R | S | V]`, with the scalars // encoded as 32-byte big-endian integers, and `V` being in the // range `[0,3]`. EncodingCompactRecoverable )
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package bitcoin implements the bitcoin specific primitives.
|
Package bitcoin implements the bitcoin specific primitives. |
|
Package h2c implements Hashing to Elliptic Curves as specified in RFC 9380.
|
Package h2c implements Hashing to Elliptic Curves as specified in RFC 9380. |