Explicitly document EVP_PKEY_size vs EVP_PKEY_bits.

They do not quite measure the same value for EC keys. "size" is a really weird
notion to generalize on so we should document what it means for each key type.
EVP_PKEY_size's meaning is most tied to signatures, thanks to EVP_SignFinal
implicitly using it as output bounds.

Change-Id: I7504c142818f8f90f8bcf6891c97a6adaf2d574e
Reviewed-on: https://boringssl-review.googlesource.com/4000
Reviewed-by: Adam Langley <agl@google.com>

1 files changed, 7 insertions, 4 deletions

diff --git a/include/openssl/evp.h b/include/openssl/evp.h
index b1497f13..f82a7117 100644
--- a/include/openssl/evp.h
+++ b/include/openssl/evp.h
@@ -119,12 +119,15 @@ OPENSSL_EXPORT int EVP_PKEY_copy_parameters(EVP_PKEY *to, const EVP_PKEY *from);
  * parameters or zero if not, or if the algorithm doesn't take parameters. */
 OPENSSL_EXPORT int EVP_PKEY_missing_parameters(const EVP_PKEY *pkey);
 
-/* EVP_PKEY_size returns the "size", in bytes, of |pkey|. For example, for an
- * RSA key this returns the number of bytes needed to represent the modulus. */
+/* EVP_PKEY_size returns the maximum size, in bytes, of a signature signed by
+ * |pkey|. For an RSA key, this returns the number of bytes needed to represent
+ * the modulus. For an EC key, this returns the maximum size of a DER-encoded
+ * ECDSA signature. */
 OPENSSL_EXPORT int EVP_PKEY_size(const EVP_PKEY *pkey);
 
-/* EVP_PKEY_bits returns the "size", in bits, of |pkey|. For example, for an
- * RSA key, this returns the bit length of the modulus. */
+/* EVP_PKEY_bits returns the "size", in bits, of |pkey|. For an RSA key, this
+ * returns the bit length of the modulus. For an EC key, this returns the bit
+ * length of the group order. */
 OPENSSL_EXPORT int EVP_PKEY_bits(EVP_PKEY *pkey);
 
 /* EVP_PKEY_id returns the type of |pkey|, which is one of the |EVP_PKEY_*|