ecdsa
packagestandard library
This package is not in the latest version of its module.
Details
Validgo.mod file
The Go module system was introduced in Go 1.11 and is the official dependency management solution for Go.
- Redistributable license
Redistributable licenses place minimal restrictions on how software can be used, modified, and redistributed.
- Tagged version
Modules with tagged versions give importers more predictable builds.
- Stable version
When a project reaches major version v1 it is considered stable.
- Learn more about best practices
Repository
Links
Report a Vulnerability
Documentation¶
Overview¶
Package ecdsa implements the Elliptic Curve Digital Signature Algorithm, asdefined inFIPS 186-5.
Signatures generated by this package are not deterministic, but entropy ismixed with the private key and the message, achieving the same level ofsecurity in case of randomness source failure.
Operations involving private keys are implemented using constant-timealgorithms, as long as anelliptic.Curve returned byelliptic.P224,elliptic.P256,elliptic.P384, orelliptic.P521 is used.
Example¶
package mainimport ("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)}Index¶
- func Sign(rand io.Reader, priv *PrivateKey, hash []byte) (r, s *big.Int, err error)
- func SignASN1(rand io.Reader, priv *PrivateKey, hash []byte) ([]byte, error)
- func Verify(pub *PublicKey, hash []byte, r, s *big.Int) bool
- func VerifyASN1(pub *PublicKey, hash, sig []byte) bool
- type PrivateKey
- func (priv *PrivateKey) Bytes() ([]byte, error)
- func (k *PrivateKey) ECDH() (*ecdh.PrivateKey, error)
- func (priv *PrivateKey) Equal(x crypto.PrivateKey) bool
- func (priv *PrivateKey) Public() crypto.PublicKey
- func (priv *PrivateKey) Sign(rand io.Reader, digest []byte, opts crypto.SignerOpts) ([]byte, error)
- type PublicKey
Examples¶
Constants¶
This section is empty.
Variables¶
This section is empty.
Functions¶
funcSign¶
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 theprivate key's curve order, the hash will be truncated to that length. Itreturns the signature as a pair of integers. Most applications should useSignASN1 instead of dealing directly with r, s.
funcSignASN1¶added ingo1.15
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 theprivate key's curve order, the hash will be truncated to that length. Itreturns the ASN.1 encoded signature.
The signature is randomized. Most applications should usecrypto/rand.Readeras rand. Note that the returned signature does not depend deterministically onthe bytes read from rand, and may change between calls and/or between versions.
funcVerify¶
Verify verifies the signature in r, s of hash using the public key, pub. Itsreturn value records whether the signature is valid. Most applications shoulduse VerifyASN1 instead of dealing directly with r, s.
The inputs are not considered confidential, and may leak through timing sidechannels, or if an attacker has control of part of the inputs.
funcVerifyASN1¶added ingo1.15
VerifyASN1 verifies the ASN.1 encoded signature, sig, of hash using thepublic key, pub. Its return value records whether the signature is valid.
The inputs are not considered confidential, and may leak through timing sidechannels, or if an attacker has control of part of the inputs.
Types¶
typePrivateKey¶
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// [crypto/x509.MarshalPKCS8PrivateKey] and [crypto/x509.ParsePKCS8PrivateKey].// For ECDH, use [crypto/ecdh].//// This field will be deprecated in Go 1.26.D *big.Int}PrivateKey represents an ECDSA private key.
funcGenerateKey¶
GenerateKey generates a new ECDSA private key for the specified curve.
Most applications should usecrypto/rand.Reader as rand. Note that thereturned key does not depend deterministically on the bytes read from rand,and may change between calls and/or between versions.
funcParseRawPrivateKey¶added ingo1.25.0
func ParseRawPrivateKey(curveelliptic.Curve, data []byte) (*PrivateKey,error)
ParseRawPrivateKey parses a private key encoded as a fixed-length big-endianinteger, according to SEC 1, Version 2.0, Section 2.3.6 (sometimes referredto as the raw format). It returns an error if the value is not reduced modulothe curve's order, or if it's zero.
curve must be one ofelliptic.P224,elliptic.P256,elliptic.P384, orelliptic.P521, or ParseRawPrivateKey returns an error.
ParseRawPrivateKey accepts the same format asecdh.Curve.NewPrivateKey doesfor NIST curves, but returns aPrivateKey instead of anecdh.PrivateKey.
Note that private keys are more commonly encoded in ASN.1 or PKCS#8 format,which can be parsed withcrypto/x509.ParseECPrivateKey orcrypto/x509.ParsePKCS8PrivateKey (andencoding/pem).
func (*PrivateKey)Bytes¶added ingo1.25.0
func (priv *PrivateKey) Bytes() ([]byte,error)
Bytes encodes the private key as a fixed-length big-endian integer accordingto SEC 1, Version 2.0, Section 2.3.6 (sometimes referred to as the rawformat). It returns an error if the private key is invalid.
PrivateKey.Curve must be one ofelliptic.P224,elliptic.P256,elliptic.P384, orelliptic.P521, or Bytes returns an error.
Bytes returns the same format asecdh.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 withcrypto/x509.MarshalECPrivateKey orcrypto/x509.MarshalPKCS8PrivateKey (andencoding/pem).
func (*PrivateKey)ECDH¶added ingo1.20
func (k *PrivateKey) ECDH() (*ecdh.PrivateKey,error)
ECDH returns k as aecdh.PrivateKey. It returns an error if the key isinvalid according to the definition ofecdh.Curve.NewPrivateKey, or if theCurve is not supported bycrypto/ecdh.
func (*PrivateKey)Equal¶added ingo1.15
func (priv *PrivateKey) Equal(xcrypto.PrivateKey)bool
Equal reports whether priv and x have the same value.
SeePublicKey.Equal for details on how Curve is compared.
func (*PrivateKey)Public¶added ingo1.4
func (priv *PrivateKey) Public()crypto.PublicKey
Public returns the public key corresponding to priv.
func (*PrivateKey)Sign¶added ingo1.4
func (priv *PrivateKey) Sign(randio.Reader, digest []byte, optscrypto.SignerOpts) ([]byte,error)
Sign signs a hash (which should be the result of hashing a larger messagewith opts.HashFunc()) using the private key, priv. If the hash is longer thanthe bit-length of the private key's curve order, the hash will be truncatedto that length. It returns the ASN.1 encoded signature, likeSignASN1.
If rand is not nil, the signature is randomized. Most applications should usecrypto/rand.Reader as rand. Note that the returned signature does notdepend deterministically on the bytes read from rand, and may change betweencalls and/or between versions.
If rand is nil, Sign will produce a deterministic signature according toRFC6979. When producing a deterministic signature, opts.HashFunc() must be thefunction used to produce digest and priv.Curve must be one ofelliptic.P224,elliptic.P256,elliptic.P384, orelliptic.P521.
typePublicKey¶
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 [crypto/x509.MarshalPKIXPublicKey] and [crypto/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}PublicKey represents an ECDSA public key.
funcParseUncompressedPublicKey¶added ingo1.25.0
ParseUncompressedPublicKey parses a public key encoded as an uncompressedpoint according to SEC 1, Version 2.0, Section 2.3.3 (also known as the X9.62uncompressed format). It returns an error if the point is not in uncompressedform, is not on the curve, or is the point at infinity.
curve must be one ofelliptic.P224,elliptic.P256,elliptic.P384, orelliptic.P521, or ParseUncompressedPublicKey returns an error.
ParseUncompressedPublicKey accepts the same format asecdh.Curve.NewPublicKey does for NIST curves, but returns aPublicKeyinstead of anecdh.PublicKey.
Note that public keys are more commonly encoded in DER (or PEM) format, whichcan be parsed withcrypto/x509.ParsePKIXPublicKey (andencoding/pem).
func (*PublicKey)Bytes¶added ingo1.25.0
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 ofelliptic.P224,elliptic.P256,elliptic.P384, orelliptic.P521, or Bytes returns an error.
Bytes returns the same format asecdh.PublicKey.Bytes does for NIST curves.
Note that public keys are more commonly encoded in DER (or PEM) format, whichcan be generated withcrypto/x509.MarshalPKIXPublicKey (andencoding/pem).
func (*PublicKey)ECDH¶added ingo1.20
ECDH returns k as aecdh.PublicKey. It returns an error if the key isinvalid according to the definition ofecdh.Curve.NewPublicKey, or if theCurve is not supported by crypto/ecdh.
func (*PublicKey)Equal¶added ingo1.15
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 exampleelliptic.P256 and elliptic.P256().Params() are differentvalues, as the latter is a generic not constant time implementation.
Source Files