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://web.archive.org/web/20040719170906/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