Black Lives Matter. Support the Equal Justice Initiative.

Source file src/crypto/ecdsa/ecdsa.go

Documentation: crypto/ecdsa

     1  // Copyright 2011 The Go Authors. All rights reserved.
     2  // Use of this source code is governed by a BSD-style
     3  // license that can be found in the LICENSE file.
     4  
     5  // Package ecdsa implements the Elliptic Curve Digital Signature Algorithm, as
     6  // defined in FIPS 186-3.
     7  //
     8  // This implementation derives the nonce from an AES-CTR CSPRNG keyed by:
     9  //
    10  // SHA2-512(priv.D || entropy || hash)[:32]
    11  //
    12  // The CSPRNG key is indifferentiable from a random oracle as shown in
    13  // [Coron], the AES-CTR stream is indifferentiable from a random oracle
    14  // under standard cryptographic assumptions (see [Larsson] for examples).
    15  //
    16  // References:
    17  //   [Coron]
    18  //     https://cs.nyu.edu/~dodis/ps/merkle.pdf
    19  //   [Larsson]
    20  //     https://www.nada.kth.se/kurser/kth/2D1441/semteo03/lecturenotes/assump.pdf
    21  package ecdsa
    22  
    23  // Further references:
    24  //   [NSA]: Suite B implementer's guide to FIPS 186-3
    25  //     https://apps.nsa.gov/iaarchive/library/ia-guidance/ia-solutions-for-classified/algorithm-guidance/suite-b-implementers-guide-to-fips-186-3-ecdsa.cfm
    26  //   [SECG]: SECG, SEC1
    27  //     http://www.secg.org/sec1-v2.pdf
    28  
    29  import (
    30  	"crypto"
    31  	"crypto/aes"
    32  	"crypto/cipher"
    33  	"crypto/elliptic"
    34  	"crypto/internal/randutil"
    35  	"crypto/sha512"
    36  	"errors"
    37  	"io"
    38  	"math/big"
    39  
    40  	"golang.org/x/crypto/cryptobyte"
    41  	"golang.org/x/crypto/cryptobyte/asn1"
    42  )
    43  
    44  // A invertible implements fast inverse mod Curve.Params().N
    45  type invertible interface {
    46  	// Inverse returns the inverse of k in GF(P)
    47  	Inverse(k *big.Int) *big.Int
    48  }
    49  
    50  // combinedMult implements fast multiplication S1*g + S2*p (g - generator, p - arbitrary point)
    51  type combinedMult interface {
    52  	CombinedMult(bigX, bigY *big.Int, baseScalar, scalar []byte) (x, y *big.Int)
    53  }
    54  
    55  const (
    56  	aesIV = "IV for ECDSA CTR"
    57  )
    58  
    59  // PublicKey represents an ECDSA public key.
    60  type PublicKey struct {
    61  	elliptic.Curve
    62  	X, Y *big.Int
    63  }
    64  
    65  // Any methods implemented on PublicKey might need to also be implemented on
    66  // PrivateKey, as the latter embeds the former and will expose its methods.
    67  
    68  // Equal reports whether pub and x have the same value.
    69  //
    70  // Two keys are only considered to have the same value if they have the same Curve value.
    71  // Note that for example elliptic.P256() and elliptic.P256().Params() are different
    72  // values, as the latter is a generic not constant time implementation.
    73  func (pub *PublicKey) Equal(x crypto.PublicKey) bool {
    74  	xx, ok := x.(*PublicKey)
    75  	if !ok {
    76  		return false
    77  	}
    78  	return pub.X.Cmp(xx.X) == 0 && pub.Y.Cmp(xx.Y) == 0 &&
    79  		// Standard library Curve implementations are singletons, so this check
    80  		// will work for those. Other Curves might be equivalent even if not
    81  		// singletons, but there is no definitive way to check for that, and
    82  		// better to err on the side of safety.
    83  		pub.Curve == xx.Curve
    84  }
    85  
    86  // PrivateKey represents an ECDSA private key.
    87  type PrivateKey struct {
    88  	PublicKey
    89  	D *big.Int
    90  }
    91  
    92  // Public returns the public key corresponding to priv.
    93  func (priv *PrivateKey) Public() crypto.PublicKey {
    94  	return &priv.PublicKey
    95  }
    96  
    97  // Equal reports whether priv and x have the same value.
    98  //
    99  // See PublicKey.Equal for details on how Curve is compared.
   100  func (priv *PrivateKey) Equal(x crypto.PrivateKey) bool {
   101  	xx, ok := x.(*PrivateKey)
   102  	if !ok {
   103  		return false
   104  	}
   105  	return priv.PublicKey.Equal(&xx.PublicKey) && priv.D.Cmp(xx.D) == 0
   106  }
   107  
   108  // Sign signs digest with priv, reading randomness from rand. The opts argument
   109  // is not currently used but, in keeping with the crypto.Signer interface,
   110  // should be the hash function used to digest the message.
   111  //
   112  // This method implements crypto.Signer, which is an interface to support keys
   113  // where the private part is kept in, for example, a hardware module. Common
   114  // uses should use the Sign function in this package directly.
   115  func (priv *PrivateKey) Sign(rand io.Reader, digest []byte, opts crypto.SignerOpts) ([]byte, error) {
   116  	r, s, err := Sign(rand, priv, digest)
   117  	if err != nil {
   118  		return nil, err
   119  	}
   120  
   121  	var b cryptobyte.Builder
   122  	b.AddASN1(asn1.SEQUENCE, func(b *cryptobyte.Builder) {
   123  		b.AddASN1BigInt(r)
   124  		b.AddASN1BigInt(s)
   125  	})
   126  	return b.Bytes()
   127  }
   128  
   129  var one = new(big.Int).SetInt64(1)
   130  
   131  // randFieldElement returns a random element of the field underlying the given
   132  // curve using the procedure given in [NSA] A.2.1.
   133  func randFieldElement(c elliptic.Curve, rand io.Reader) (k *big.Int, err error) {
   134  	params := c.Params()
   135  	b := make([]byte, params.BitSize/8+8)
   136  	_, err = io.ReadFull(rand, b)
   137  	if err != nil {
   138  		return
   139  	}
   140  
   141  	k = new(big.Int).SetBytes(b)
   142  	n := new(big.Int).Sub(params.N, one)
   143  	k.Mod(k, n)
   144  	k.Add(k, one)
   145  	return
   146  }
   147  
   148  // GenerateKey generates a public and private key pair.
   149  func GenerateKey(c elliptic.Curve, rand io.Reader) (*PrivateKey, error) {
   150  	k, err := randFieldElement(c, rand)
   151  	if err != nil {
   152  		return nil, err
   153  	}
   154  
   155  	priv := new(PrivateKey)
   156  	priv.PublicKey.Curve = c
   157  	priv.D = k
   158  	priv.PublicKey.X, priv.PublicKey.Y = c.ScalarBaseMult(k.Bytes())
   159  	return priv, nil
   160  }
   161  
   162  // hashToInt converts a hash value to an integer. There is some disagreement
   163  // about how this is done. [NSA] suggests that this is done in the obvious
   164  // manner, but [SECG] truncates the hash to the bit-length of the curve order
   165  // first. We follow [SECG] because that's what OpenSSL does. Additionally,
   166  // OpenSSL right shifts excess bits from the number if the hash is too large
   167  // and we mirror that too.
   168  func hashToInt(hash []byte, c elliptic.Curve) *big.Int {
   169  	orderBits := c.Params().N.BitLen()
   170  	orderBytes := (orderBits + 7) / 8
   171  	if len(hash) > orderBytes {
   172  		hash = hash[:orderBytes]
   173  	}
   174  
   175  	ret := new(big.Int).SetBytes(hash)
   176  	excess := len(hash)*8 - orderBits
   177  	if excess > 0 {
   178  		ret.Rsh(ret, uint(excess))
   179  	}
   180  	return ret
   181  }
   182  
   183  // fermatInverse calculates the inverse of k in GF(P) using Fermat's method.
   184  // This has better constant-time properties than Euclid's method (implemented
   185  // in math/big.Int.ModInverse) although math/big itself isn't strictly
   186  // constant-time so it's not perfect.
   187  func fermatInverse(k, N *big.Int) *big.Int {
   188  	two := big.NewInt(2)
   189  	nMinus2 := new(big.Int).Sub(N, two)
   190  	return new(big.Int).Exp(k, nMinus2, N)
   191  }
   192  
   193  var errZeroParam = errors.New("zero parameter")
   194  
   195  // Sign signs a hash (which should be the result of hashing a larger message)
   196  // using the private key, priv. If the hash is longer than the bit-length of the
   197  // private key's curve order, the hash will be truncated to that length. It
   198  // returns the signature as a pair of integers. The security of the private key
   199  // depends on the entropy of rand.
   200  func Sign(rand io.Reader, priv *PrivateKey, hash []byte) (r, s *big.Int, err error) {
   201  	randutil.MaybeReadByte(rand)
   202  
   203  	// Get min(log2(q) / 2, 256) bits of entropy from rand.
   204  	entropylen := (priv.Curve.Params().BitSize + 7) / 16
   205  	if entropylen > 32 {
   206  		entropylen = 32
   207  	}
   208  	entropy := make([]byte, entropylen)
   209  	_, err = io.ReadFull(rand, entropy)
   210  	if err != nil {
   211  		return
   212  	}
   213  
   214  	// Initialize an SHA-512 hash context; digest ...
   215  	md := sha512.New()
   216  	md.Write(priv.D.Bytes()) // the private key,
   217  	md.Write(entropy)        // the entropy,
   218  	md.Write(hash)           // and the input hash;
   219  	key := md.Sum(nil)[:32]  // and compute ChopMD-256(SHA-512),
   220  	// which is an indifferentiable MAC.
   221  
   222  	// Create an AES-CTR instance to use as a CSPRNG.
   223  	block, err := aes.NewCipher(key)
   224  	if err != nil {
   225  		return nil, nil, err
   226  	}
   227  
   228  	// Create a CSPRNG that xors a stream of zeros with
   229  	// the output of the AES-CTR instance.
   230  	csprng := cipher.StreamReader{
   231  		R: zeroReader,
   232  		S: cipher.NewCTR(block, []byte(aesIV)),
   233  	}
   234  
   235  	// See [NSA] 3.4.1
   236  	c := priv.PublicKey.Curve
   237  	return sign(priv, &csprng, c, hash)
   238  }
   239  
   240  func signGeneric(priv *PrivateKey, csprng *cipher.StreamReader, c elliptic.Curve, hash []byte) (r, s *big.Int, err error) {
   241  	N := c.Params().N
   242  	if N.Sign() == 0 {
   243  		return nil, nil, errZeroParam
   244  	}
   245  	var k, kInv *big.Int
   246  	for {
   247  		for {
   248  			k, err = randFieldElement(c, *csprng)
   249  			if err != nil {
   250  				r = nil
   251  				return
   252  			}
   253  
   254  			if in, ok := priv.Curve.(invertible); ok {
   255  				kInv = in.Inverse(k)
   256  			} else {
   257  				kInv = fermatInverse(k, N) // N != 0
   258  			}
   259  
   260  			r, _ = priv.Curve.ScalarBaseMult(k.Bytes())
   261  			r.Mod(r, N)
   262  			if r.Sign() != 0 {
   263  				break
   264  			}
   265  		}
   266  
   267  		e := hashToInt(hash, c)
   268  		s = new(big.Int).Mul(priv.D, r)
   269  		s.Add(s, e)
   270  		s.Mul(s, kInv)
   271  		s.Mod(s, N) // N != 0
   272  		if s.Sign() != 0 {
   273  			break
   274  		}
   275  	}
   276  
   277  	return
   278  }
   279  
   280  // SignASN1 signs a hash (which should be the result of hashing a larger message)
   281  // using the private key, priv. If the hash is longer than the bit-length of the
   282  // private key's curve order, the hash will be truncated to that length. It
   283  // returns the ASN.1 encoded signature. The security of the private key
   284  // depends on the entropy of rand.
   285  func SignASN1(rand io.Reader, priv *PrivateKey, hash []byte) ([]byte, error) {
   286  	return priv.Sign(rand, hash, nil)
   287  }
   288  
   289  // Verify verifies the signature in r, s of hash using the public key, pub. Its
   290  // return value records whether the signature is valid.
   291  func Verify(pub *PublicKey, hash []byte, r, s *big.Int) bool {
   292  	// See [NSA] 3.4.2
   293  	c := pub.Curve
   294  	N := c.Params().N
   295  
   296  	if r.Sign() <= 0 || s.Sign() <= 0 {
   297  		return false
   298  	}
   299  	if r.Cmp(N) >= 0 || s.Cmp(N) >= 0 {
   300  		return false
   301  	}
   302  	return verify(pub, c, hash, r, s)
   303  }
   304  
   305  func verifyGeneric(pub *PublicKey, c elliptic.Curve, hash []byte, r, s *big.Int) bool {
   306  	e := hashToInt(hash, c)
   307  	var w *big.Int
   308  	N := c.Params().N
   309  	if in, ok := c.(invertible); ok {
   310  		w = in.Inverse(s)
   311  	} else {
   312  		w = new(big.Int).ModInverse(s, N)
   313  	}
   314  
   315  	u1 := e.Mul(e, w)
   316  	u1.Mod(u1, N)
   317  	u2 := w.Mul(r, w)
   318  	u2.Mod(u2, N)
   319  
   320  	// Check if implements S1*g + S2*p
   321  	var x, y *big.Int
   322  	if opt, ok := c.(combinedMult); ok {
   323  		x, y = opt.CombinedMult(pub.X, pub.Y, u1.Bytes(), u2.Bytes())
   324  	} else {
   325  		x1, y1 := c.ScalarBaseMult(u1.Bytes())
   326  		x2, y2 := c.ScalarMult(pub.X, pub.Y, u2.Bytes())
   327  		x, y = c.Add(x1, y1, x2, y2)
   328  	}
   329  
   330  	if x.Sign() == 0 && y.Sign() == 0 {
   331  		return false
   332  	}
   333  	x.Mod(x, N)
   334  	return x.Cmp(r) == 0
   335  }
   336  
   337  // VerifyASN1 verifies the ASN.1 encoded signature, sig, of hash using the
   338  // public key, pub. Its return value records whether the signature is valid.
   339  func VerifyASN1(pub *PublicKey, hash, sig []byte) bool {
   340  	var (
   341  		r, s  = &big.Int{}, &big.Int{}
   342  		inner cryptobyte.String
   343  	)
   344  	input := cryptobyte.String(sig)
   345  	if !input.ReadASN1(&inner, asn1.SEQUENCE) ||
   346  		!input.Empty() ||
   347  		!inner.ReadASN1Integer(r) ||
   348  		!inner.ReadASN1Integer(s) ||
   349  		!inner.Empty() {
   350  		return false
   351  	}
   352  	return Verify(pub, hash, r, s)
   353  }
   354  
   355  type zr struct {
   356  	io.Reader
   357  }
   358  
   359  // Read replaces the contents of dst with zeros.
   360  func (z *zr) Read(dst []byte) (n int, err error) {
   361  	for i := range dst {
   362  		dst[i] = 0
   363  	}
   364  	return len(dst), nil
   365  }
   366  
   367  var zeroReader = &zr{}
   368  

View as plain text