ecdsa package - crypto/ecdsa - Go Packages

Package ecdsa implements the Elliptic Curve Digital Signature Algorithm, as defined in FIPS 186-5.

Signatures generated by this package are not deterministic, but entropy is mixed with the private key and the message, achieving the same level of security in case of randomness source failure.

Operations involving private keys are implemented using constant-time algorithms, as long as an elliptic.Curve returned by elliptic.P224, elliptic.P256, elliptic.P384, or elliptic.P521 is used.

package main

import (
	"crypto/ecdsa"
	"crypto/elliptic"
	"crypto/rand"
	"crypto/sha256"
	"fmt"
)

func main() {
	privateKey, err := ecdsa.GenerateKey(elliptic.P256(), rand.Reader)
	if err != nil {
		panic(err)
	}

	msg := "hello, world"
	hash := sha256.Sum256([]byte(msg))

	sig, err := ecdsa.SignASN1(rand.Reader, privateKey, hash[:])
	if err != nil {
		panic(err)
	}
	fmt.Printf("signature: %x\n", sig)

	valid := ecdsa.VerifyASN1(&privateKey.PublicKey, hash[:], sig)
	fmt.Println("signature verified:", valid)
}

Package

This section is empty.

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.

The signature is randomized. Since Go 1.26, a secure source of random bytes is always used, and the Reader is ignored unless GODEBUG=cryptocustomrand=1 is set. This setting will be removed in a future Go release. Instead, use testing/cryptotest.SetGlobalRandom.

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.

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(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 struct {
	PublicKey

	
	
	
	
	
	
	
	
	D *big.Int
}

PrivateKey represents an ECDSA private key.

GenerateKey generates a new ECDSA private key for the specified curve.

Since Go 1.26, a secure source of random bytes is always used, and the Reader is ignored unless GODEBUG=cryptocustomrand=1 is set. This setting will be removed in a future Go release. Instead, use testing/cryptotest.SetGlobalRandom.

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 crypto/x509.ParseECPrivateKey or crypto/x509.ParsePKCS8PrivateKey (and encoding/pem).

Equal reports whether priv and x have the same value.

See PublicKey.Equal for details on how Curve is compared.

Public returns the public key corresponding to priv.

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 random is not nil, the signature is randomized. Most applications should use crypto/rand.Reader as random, but unless GODEBUG=cryptocustomrand=1 is set, a secure source of random bytes is always used, and the actual Reader is ignored. The GODEBUG setting will be removed in a future Go release. Instead, use testing/cryptotest.SetGlobalRandom.

If random 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.

PublicKey represents an ECDSA public key.

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 crypto/x509.ParsePKIXPublicKey (and encoding/pem).

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.