Package ecdsa
Overview ▸
Index ▸
func Sign
func Sign(rand io.Reader, priv *PrivateKey, hash []byte) (r, s *big.Int, err error)
Sign signs a hash (which should be the result of hashing a larger message) using the private key, priv. If the hash is longer than the bit-length of the private key's curve order, the hash will be truncated to that length. It returns the signature as a pair of integers. Most applications should use SignASN1 instead of dealing directly with r, s.
func SignASN1
func SignASN1(rand io.Reader, priv *PrivateKey, hash []byte) ([]byte, error)
SignASN1 signs a hash (which should be the result of hashing a larger message) using the private key, priv. If the hash is longer than the bit-length of the private key's curve order, the hash will be truncated to that length. It returns the ASN.1 encoded signature.
The signature is randomized. Most applications should use crypto/rand.Reader as rand. Note that the returned signature does not depend deterministically on the bytes read from rand, and may change between calls and/or between versions.
func Verify
func Verify(pub *PublicKey, hash []byte, r, s *big.Int) bool
Verify verifies the signature in r, s of hash using the public key, pub. Its return value records whether the signature is valid. Most applications should use VerifyASN1 instead of dealing directly with r, s.
The inputs are not considered confidential, and may leak through timing side channels, or if an attacker has control of part of the inputs.
func VerifyASN1
func VerifyASN1(pub *PublicKey, hash, sig []byte) bool
VerifyASN1 verifies the ASN.1 encoded signature, sig, of hash using the public key, pub. Its return value records whether the signature is valid.
The inputs are not considered confidential, and may leak through timing side channels, or if an attacker has control of part of the inputs.
type PrivateKey
PrivateKey represents an ECDSA private key.
type PrivateKey struct {
PublicKey
// D is the private scalar value.
//
// Modifying the raw value can produce invalid keys, and may
// invalidate internal optimizations; moreover, [big.Int] methods are not
// suitable for operating on cryptographic values. To encode and decode
// PrivateKey values, use [PrivateKey.Bytes] and [ParseRawPrivateKey]
// or [x509.MarshalPKCS8PrivateKey] and [x509.ParsePKCS8PrivateKey].
// For ECDH, use [crypto/ecdh].
//
// This field will be deprecated in Go 1.26.
D *big.Int
}
func GenerateKey
func GenerateKey(c elliptic.Curve, rand io.Reader) (*PrivateKey, error)
GenerateKey generates a new ECDSA private key for the specified curve.
Most applications should use crypto/rand.Reader as rand. Note that the returned key does not depend deterministically on the bytes read from rand, and may change between calls and/or between versions.
func ParseRawPrivateKey
func ParseRawPrivateKey(curve elliptic.Curve, data []byte) (*PrivateKey, error)
ParseRawPrivateKey parses a private key encoded as a fixed-length big-endian integer, according to SEC 1, Version 2.0, Section 2.3.6 (sometimes referred to as the raw format). It returns an error if the value is not reduced modulo the curve's order, or if it's zero.
curve must be one of elliptic.P224, elliptic.P256, elliptic.P384, or elliptic.P521, or ParseRawPrivateKey returns an error.
ParseRawPrivateKey accepts the same format as ecdh.Curve.NewPrivateKey does for NIST curves, but returns a PrivateKey instead of an ecdh.PrivateKey.
Note that private keys are more commonly encoded in ASN.1 or PKCS#8 format, which can be parsed with [x509.ParseECPrivateKey] or [x509.ParsePKCS8PrivateKey] (and encoding/pem).
func (*PrivateKey) Bytes
func (priv *PrivateKey) Bytes() ([]byte, error)
Bytes encodes the private key as a fixed-length big-endian integer according to SEC 1, Version 2.0, Section 2.3.6 (sometimes referred to as the raw format). It returns an error if the private key is invalid.
PrivateKey.Curve must be one of elliptic.P224, elliptic.P256, elliptic.P384, or elliptic.P521, or Bytes returns an error.
Bytes returns the same format as ecdh.PrivateKey.Bytes does for NIST curves.
Note that private keys are more commonly encoded in ASN.1 or PKCS#8 format, which can be generated with [x509.MarshalECPrivateKey] or [x509.MarshalPKCS8PrivateKey] (and encoding/pem).
func (*PrivateKey) ECDH
func (k *PrivateKey) ECDH() (*ecdh.PrivateKey, error)
ECDH returns k as a ecdh.PrivateKey. It returns an error if the key is invalid according to the definition of ecdh.Curve.NewPrivateKey, or if the Curve is not supported by crypto/ecdh.
func (*PrivateKey) Equal
func (priv *PrivateKey) Equal(x crypto.PrivateKey) bool
Equal reports whether priv and x have the same value.
See PublicKey.Equal for details on how Curve is compared.
func (*PrivateKey) Public
func (priv *PrivateKey) Public() crypto.PublicKey
Public returns the public key corresponding to priv.
func (*PrivateKey) Sign
func (priv *PrivateKey) Sign(rand io.Reader, digest []byte, opts crypto.SignerOpts) ([]byte, error)
Sign signs a hash (which should be the result of hashing a larger message with opts.HashFunc()) using the private key, priv. If the hash is longer than the bit-length of the private key's curve order, the hash will be truncated to that length. It returns the ASN.1 encoded signature, like SignASN1.
If rand is not nil, the signature is randomized. Most applications should use crypto/rand.Reader as rand. Note that the returned signature does not depend deterministically on the bytes read from rand, and may change between calls and/or between versions.
If rand is nil, Sign will produce a deterministic signature according to RFC 6979. When producing a deterministic signature, opts.HashFunc() must be the function used to produce digest and priv.Curve must be one of elliptic.P224, elliptic.P256, elliptic.P384, or elliptic.P521.
type PublicKey
PublicKey represents an ECDSA public key.
type PublicKey struct {
elliptic.Curve
// X, Y are the coordinates of the public key point.
//
// Modifying the raw coordinates can produce invalid keys, and may
// invalidate internal optimizations; moreover, [big.Int] methods are not
// suitable for operating on cryptographic values. To encode and decode
// PublicKey values, use [PublicKey.Bytes] and [ParseUncompressedPublicKey]
// or [x509.MarshalPKIXPublicKey] and [x509.ParsePKIXPublicKey]. For ECDH,
// use [crypto/ecdh]. For lower-level elliptic curve operations, use a
// third-party module like filippo.io/nistec.
//
// These fields will be deprecated in Go 1.26.
X, Y *big.Int
}
func ParseUncompressedPublicKey
func ParseUncompressedPublicKey(curve elliptic.Curve, data []byte) (*PublicKey, error)
ParseUncompressedPublicKey parses a public key encoded as an uncompressed point according to SEC 1, Version 2.0, Section 2.3.3 (also known as the X9.62 uncompressed format). It returns an error if the point is not in uncompressed form, is not on the curve, or is the point at infinity.
curve must be one of elliptic.P224, elliptic.P256, elliptic.P384, or elliptic.P521, or ParseUncompressedPublicKey returns an error.
ParseUncompressedPublicKey accepts the same format as ecdh.Curve.NewPublicKey does for NIST curves, but returns a PublicKey instead of an ecdh.PublicKey.
Note that public keys are more commonly encoded in DER (or PEM) format, which can be parsed with [x509.ParsePKIXPublicKey] (and encoding/pem).
func (*PublicKey) Bytes
func (pub *PublicKey) Bytes() ([]byte, error)
Bytes encodes the public key as an uncompressed point according to SEC 1, Version 2.0, Section 2.3.3 (also known as the X9.62 uncompressed format). It returns an error if the public key is invalid.
PublicKey.Curve must be one of elliptic.P224, elliptic.P256, elliptic.P384, or elliptic.P521, or Bytes returns an error.
Bytes returns the same format as ecdh.PublicKey.Bytes does for NIST curves.
Note that public keys are more commonly encoded in DER (or PEM) format, which can be generated with [x509.MarshalPKIXPublicKey] (and encoding/pem).
func (*PublicKey) ECDH
func (k *PublicKey) ECDH() (*ecdh.PublicKey, error)
ECDH returns k as a ecdh.PublicKey. It returns an error if the key is invalid according to the definition of ecdh.Curve.NewPublicKey, or if the Curve is not supported by crypto/ecdh.
func (*PublicKey) Equal
func (pub *PublicKey) Equal(x crypto.PublicKey) bool
Equal reports whether pub and x have the same value.
Two keys are only considered to have the same value if they have the same Curve value. Note that for example elliptic.P256 and elliptic.P256().Params() are different values, as the latter is a generic not constant time implementation.