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 21package 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 29import ( 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 45type 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) 51type combinedMult interface { 52 CombinedMult(bigX, bigY *big.Int, baseScalar, scalar []byte) (x, y *big.Int) 53} 54 55const ( 56 aesIV = "IV for ECDSA CTR" 57) 58 59// PublicKey represents an ECDSA public key. 60type 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. 73func (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. 87type PrivateKey struct { 88 PublicKey 89 D *big.Int 90} 91 92// Public returns the public key corresponding to priv. 93func (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. 100func (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. 115func (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 129var 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. 133func 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. 149func 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. 168func 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. 187func 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 193var 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. 200func 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 240func 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. 285func 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. 291func 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 305func 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. 339func 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 355type zr struct { 356 io.Reader 357} 358 359// Read replaces the contents of dst with zeros. 360func (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 367var zeroReader = &zr{} 368