crypto: document that Signer.Sign does not hash

Fixes #13938.

Change-Id: I0b4842b8bc22dc79323d6894c123cde638f52d3f
Reviewed-on: https://go-review.googlesource.com/18856
Reviewed-by: Adam Langley <agl@golang.org>

diff --git a/src/crypto/crypto.go b/src/crypto/crypto.go
index 184ea9d4d62c74ae04419ca5cf8edb1f7f883d17..a80ebd36931eac75c9a841bd207edbf2b379df46 100644 (file)
--- a/src/crypto/crypto.go
+++ b/src/crypto/crypto.go
@@ -109,7 +109,7 @@ type Signer interface {
        // private key.
        Public() PublicKey
 
-       // Sign signs msg with the private key, possibly using entropy from
+       // Sign signs digest with the private key, possibly using entropy from
        // rand. For an RSA key, the resulting signature should be either a
        // PKCS#1 v1.5 or PSS signature (as indicated by opts). For an (EC)DSA
        // key, it should be a DER-serialised, ASN.1 signature structure.
@@ -118,7 +118,11 @@ type Signer interface {
        // simply pass in the hash function used as opts. Sign may also attempt
        // to type assert opts to other types in order to obtain algorithm
        // specific values. See the documentation in each package for details.
-       Sign(rand io.Reader, msg []byte, opts SignerOpts) (signature []byte, err error)
+       //
+       // Note that when a signature of a hash of a larger message is needed,
+       // the caller is responsible for hashing the larger message and passing
+       // the hash (as digest) and the hash function (as opts) to Sign.
+       Sign(rand io.Reader, digest []byte, opts SignerOpts) (signature []byte, err error)
 }
 
 // SignerOpts contains options for signing with a Signer.