secec

package
v0.0.0-...-f261603 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 25, 2023 License: BSD-3-Clause Imports: 16 Imported by: 13

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

View Source 
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
)
View Source 
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 

func BuildCompactRecoverableSignature(r, s *secp256k1.Scalar, v byte) []byte

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 

func ParseASN1Signature(data []byte) (*secp256k1.Scalar, *secp256k1.Scalar, error)

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 

func ParseCompactSignature(data []byte) (*secp256k1.Scalar, *secp256k1.Scalar, error)

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 

func RFC6979SHA256() io.Reader

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 

func NewPublicKey(key []byte) (*PublicKey, error)

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 

func NewPublicKeyFromPoint(point *secp256k1.Point) (*PublicKey, error)

NewPublicKeyFromPoint checks that `point` is valid, and returns a PublicKey.

func ParseASN1PublicKey 

func ParseASN1PublicKey(data []byte) (*PublicKey, error)

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 

func RecoverPublicKey(digest []byte, r, s *secp256k1.Scalar, recoveryID byte) (*PublicKey, error)

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 

func (k *PublicKey) ASN1Bytes() []byte

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) Bytes 

func (k *PublicKey) Bytes() []byte

Bytes returns a copy of the uncompressed encoding of the public key.

func (*PublicKey) CompressedBytes 

func (k *PublicKey) CompressedBytes() []byte

CompressedBytes returns a copy of the compressed encoding of the public key.

func (*PublicKey) Equal 

func (k *PublicKey) Equal(x crypto.PublicKey) bool

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.

func (*PublicKey) VerifyRaw 

func (k *PublicKey) VerifyRaw(digest []byte, r, s *secp256k1.Scalar) bool

VerifyRaw verifies the `(r, s)` signature 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.

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

View all 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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.