Be clearer which signing inputs are digests.
We usually call the parameter 'digest', but people sometimes think they
can skip the hashing for short inputs are short. I also suspect the term
'digest' is less common. Add warnings about this.
There were also some cases where we called it 'in' and even 'msg'. This
CL fixes those to say 'digest'. Finally, RSA_{sign,verify}_raw are
documented to be building blocks of signature schemes, rather than
signature schemes themselves.
It's unfortunate that EVP_PKEY_sign means "sign a digest", while
EVP_DigestSign means "sign, likely internally digesting it as the first
step", but we're a bit stuck there.
Change-Id: I4c38afff9b6196e2789cf27653fe5e5e8c68c1bf
Reviewed-on: https://boringssl-review.googlesource.com/c/boringssl/+/47504
Reviewed-by: Adam Langley <agl@google.com>
diff --git a/include/openssl/ecdsa.h b/include/openssl/ecdsa.h
index 08950e3..5443ef5 100644
--- a/include/openssl/ecdsa.h
+++ b/include/openssl/ecdsa.h
@@ -73,6 +73,9 @@
// space. On successful exit, |*sig_len| is set to the actual number of bytes
// written. The |type| argument should be zero. It returns one on success and
// zero otherwise.
+//
+// WARNING: |digest| must be the output of some hash function on the data to be
+// signed. Passing unhashed inputs will not result in a secure signature scheme.
OPENSSL_EXPORT int ECDSA_sign(int type, const uint8_t *digest,
size_t digest_len, uint8_t *sig,
unsigned int *sig_len, const EC_KEY *key);
@@ -81,6 +84,10 @@
// signature by |key| of |digest|. (The |type| argument should be zero.) It
// returns one on success or zero if the signature is invalid or an error
// occurred.
+//
+// WARNING: |digest| must be the output of some hash function on the data to be
+// verified. Passing unhashed inputs will not result in a secure signature
+// scheme.
OPENSSL_EXPORT int ECDSA_verify(int type, const uint8_t *digest,
size_t digest_len, const uint8_t *sig,
size_t sig_len, const EC_KEY *key);
@@ -124,12 +131,19 @@
// ECDSA_do_sign signs |digest_len| bytes from |digest| with |key| and returns
// the resulting signature structure, or NULL on error.
+//
+// WARNING: |digest| must be the output of some hash function on the data to be
+// signed. Passing unhashed inputs will not result in a secure signature scheme.
OPENSSL_EXPORT ECDSA_SIG *ECDSA_do_sign(const uint8_t *digest,
size_t digest_len, const EC_KEY *key);
// ECDSA_do_verify verifies that |sig| constitutes a valid signature by |key|
// of |digest|. It returns one on success or zero if the signature is invalid
// or on error.
+//
+// WARNING: |digest| must be the output of some hash function on the data to be
+// verified. Passing unhashed inputs will not result in a secure signature
+// scheme.
OPENSSL_EXPORT int ECDSA_do_verify(const uint8_t *digest, size_t digest_len,
const ECDSA_SIG *sig, const EC_KEY *key);
