crypto/*: document use or non-use of constant-time algorithms

Fixes #16821.

Change-Id: I63d5f3d7cfba1c76259912d754025c5f3cbe4a56
Reviewed-on: https://go-review.googlesource.com/31573
Run-TryBot: Russ Cox <rsc@golang.org>
TryBot-Result: Gobot Gobot <gobot@golang.org>
Reviewed-by: Brad Fitzpatrick <bradfitz@golang.org>

diff --git a/src/crypto/aes/const.go b/src/crypto/aes/const.go
index aee73a7c52c75eb2f6d2c1e451c3905949debfd1..cbac5ff0ea155feaa14bfbdf372876aaf56cb0e5 100644 (file)
--- a/src/crypto/aes/const.go
+++ b/src/crypto/aes/const.go
@@ -4,6 +4,13 @@
 
 // Package aes implements AES encryption (formerly Rijndael), as defined in
 // U.S. Federal Information Processing Standards Publication 197.
+//
+// The AES operations in this package are not implemented using constant-time algorithms.
+// An exception is when running on systems with enabled hardware support for AES
+// that makes these operations constant-time. Examples include amd64 systems using AES-NI
+// extensions and s390x systems using Message-Security-Assist extensions.
+// On such systems, when the result of NewCipher is passed to cipher.NewGCM,
+// the GHASH operation used by GCM is also constant-time.
 package aes
 
 // This file contains AES constants - 8720 bytes of initialized data.

diff --git a/src/crypto/cipher/gcm.go b/src/crypto/cipher/gcm.go
index cfc5769a80e7718377965ab2f824a49296ac7b98..793a4459e5364b4dbb9380c3ee56cd682f767157 100644 (file)
--- a/src/crypto/cipher/gcm.go
+++ b/src/crypto/cipher/gcm.go
@@ -74,6 +74,10 @@ type gcm struct {
 
 // NewGCM returns the given 128-bit, block cipher wrapped in Galois Counter Mode
 // with the standard nonce length.
+//
+// In general, the GHASH operation performed by this implementation of GCM is not constant-time.
+// An exception is when the underlying Block was created by aes.NewCipher
+// on systems with hardware support for AES. See the crypto/aes package documentation for details.
 func NewGCM(cipher Block) (AEAD, error) {
        return NewGCMWithNonceSize(cipher, gcmStandardNonceSize)
 }

diff --git a/src/crypto/dsa/dsa.go b/src/crypto/dsa/dsa.go
index 633c1f4a66c2fb755781153083b9e5d63bbc2319..bc0c3e34629d377e6d0ea125d3f7333ab79ad635 100644 (file)
--- a/src/crypto/dsa/dsa.go
+++ b/src/crypto/dsa/dsa.go
@@ -3,6 +3,8 @@
 // license that can be found in the LICENSE file.
 
 // Package dsa implements the Digital Signature Algorithm, as defined in FIPS 186-3.
+//
+// The DSA operations in this package are not implemented using constant-time algorithms.
 package dsa
 
 import (

diff --git a/src/crypto/elliptic/elliptic.go b/src/crypto/elliptic/elliptic.go
index c02df45d10502d129bf3bf48406593492d8d85c9..d3527243e78a4f5fc755a91ed556b5f266eab101 100644 (file)
--- a/src/crypto/elliptic/elliptic.go
+++ b/src/crypto/elliptic/elliptic.go
@@ -367,18 +367,24 @@ func initP521() {
 }
 
 // P256 returns a Curve which implements P-256 (see FIPS 186-3, section D.2.3)
+//
+// The cryptographic operations are implemented using constant-time algorithms.
 func P256() Curve {
        initonce.Do(initAll)
        return p256
 }
 
 // P384 returns a Curve which implements P-384 (see FIPS 186-3, section D.2.4)
+//
+// The cryptographic operations do not use constant-time algorithms.
 func P384() Curve {
        initonce.Do(initAll)
        return p384
 }
 
 // P521 returns a Curve which implements P-521 (see FIPS 186-3, section D.2.5)
+//
+// The cryptographic operations do not use constant-time algorithms.
 func P521() Curve {
        initonce.Do(initAll)
        return p521

diff --git a/src/crypto/elliptic/p224.go b/src/crypto/elliptic/p224.go
index de266ca77a773efd404da2668c666d0b79b738b8..22d0e2429cdfb292106804d7b23b24eb3b5087bb 100644 (file)
--- a/src/crypto/elliptic/p224.go
+++ b/src/crypto/elliptic/p224.go
@@ -35,7 +35,9 @@ func initP224() {
        p224FromBig(&p224.b, p224.B)
 }
 
-// P224 returns a Curve which implements P-224 (see FIPS 186-3, section D.2.2)
+// P224 returns a Curve which implements P-224 (see FIPS 186-3, section D.2.2).
+//
+// The cryptographic operations are implemented using constant-time algorithms.
 func P224() Curve {
        initonce.Do(initAll)
        return p224

diff --git a/src/crypto/rsa/rsa.go b/src/crypto/rsa/rsa.go
index f809a9b9bc888e186fe9176124a16f5d9f479393..1de4fcb473eab9dda4bc88b0c2fe0a13dcb27662 100644 (file)
--- a/src/crypto/rsa/rsa.go
+++ b/src/crypto/rsa/rsa.go
@@ -18,6 +18,8 @@
 // with v1.5/OAEP and signing/verifying with v1.5/PSS. If one needs to abstract
 // over the public-key primitive, the PrivateKey struct implements the
 // Decrypter and Signer interfaces from the crypto package.
+//
+// The RSA operations in this package are not implemented using constant-time algorithms.
 package rsa
 
 import (

diff --git a/src/math/big/int.go b/src/math/big/int.go
index a2c1b580f524e453a61d8ed45cfdbb4ead2f1ab5..1d8dabce12b65ad0bdaa03b2aac66c2d6dfe972b 100644 (file)
--- a/src/math/big/int.go
+++ b/src/math/big/int.go
@@ -404,8 +404,11 @@ func (x *Int) BitLen() int {
 
 // Exp sets z = x**y mod |m| (i.e. the sign of m is ignored), and returns z.
 // If y <= 0, the result is 1 mod |m|; if m == nil or m == 0, z = x**y.
-// See Knuth, volume 2, section 4.6.3.
+//
+// Modular exponentation of inputs of a particular size is not a
+// cryptographically constant-time operation.
 func (z *Int) Exp(x, y, m *Int) *Int {
+       // See Knuth, volume 2, section 4.6.3.
        var yWords nat
        if !y.neg {
                yWords = y.abs