Document error behavior of various functions

- Document error behavior of:
  - EVP_PKEY_assign_XXX
  - EVP_PKEY_set1_XXX
  - EVP_PKEY_assign
  - EVP_PKEY_set_type
  - EC_GROUP_new_by_curve_name
  - EC_KEY_set_group
  - ECDSA_size
  - HMAC_Final
- Document that EVP_parse_public_key sets the curve for EC keys

Change-Id: I498ae19a8729680216fee518f97bd0cbaab94c40
Reviewed-on: https://boringssl-review.googlesource.com/30985
Reviewed-by: David Benjamin <davidben@google.com>
Commit-Queue: David Benjamin <davidben@google.com>
CQ-Verified: CQ bot account: commit-bot@chromium.org <commit-bot@chromium.org>

include/openssl/ec.h

@@ -102,7 +102,7 @@ typedef enum {
 // Elliptic curve groups.
 
 // EC_GROUP_new_by_curve_name returns a fresh EC_GROUP object for the elliptic
-// curve specified by |nid|, or NULL on error.
+// curve specified by |nid|, or NULL on unsupported NID or allocation failure.
 //
 // The supported NIDs are:
 //   NID_secp224r1 (P-224),

include/openssl/ec_key.h

@@ -113,8 +113,8 @@ OPENSSL_EXPORT int EC_KEY_is_opaque(const EC_KEY *key);
 OPENSSL_EXPORT const EC_GROUP *EC_KEY_get0_group(const EC_KEY *key);
 
 // EC_KEY_set_group sets the |EC_GROUP| object that |key| will use to |group|.
-// It returns one on success and zero otherwise. If |key| already has a group,
+// It returns one on success and zero if |key| is already configured with a
-// it is an error to change to a different one.
+// different group.
 OPENSSL_EXPORT int EC_KEY_set_group(EC_KEY *key, const EC_GROUP *group);
 
 // EC_KEY_get0_private_key returns a pointer to the private key inside |key|.

include/openssl/ecdsa.h

@@ -86,7 +86,7 @@ OPENSSL_EXPORT int ECDSA_verify(int type, const uint8_t *digest,
                                 size_t sig_len, const EC_KEY *key);
 
 // ECDSA_size returns the maximum size of an ECDSA signature using |key|. It
-// returns zero on error.
+// returns zero if |key| is NULL or if it doesn't have a group set.
 OPENSSL_EXPORT size_t ECDSA_size(const EC_KEY *key);
 
 

include/openssl/evp.h

@@ -136,11 +136,11 @@ OPENSSL_EXPORT int EVP_PKEY_type(int nid);
 //
 // The following functions get and set the underlying public key in an
 // |EVP_PKEY| object. The |set1| functions take an additional reference to the
-// underlying key and return one on success or zero on error. The |assign|
+// underlying key and return one on success or zero if |key| is NULL. The
-// functions adopt the caller's reference. The |get1| functions return a fresh
+// |assign| functions adopt the caller's reference and return one on success or
-// reference to the underlying object or NULL if |pkey| is not of the correct
+// zero if |key| is NULL. The |get1| functions return a fresh reference to the
-// type. The |get0| functions behave the same but return a non-owning
+// underlying object or NULL if |pkey| is not of the correct type. The |get0|
-// pointer.
+// functions behave the same but return a non-owning pointer.
 
 OPENSSL_EXPORT int EVP_PKEY_set1_RSA(EVP_PKEY *pkey, RSA *key);
 OPENSSL_EXPORT int EVP_PKEY_assign_RSA(EVP_PKEY *pkey, RSA *key);
@@ -175,13 +175,13 @@ OPENSSL_EXPORT EVP_PKEY *EVP_PKEY_new_ed25519_private(
 #define EVP_PKEY_ED25519 NID_ED25519
 
 // EVP_PKEY_assign sets the underlying key of |pkey| to |key|, which must be of
-// the given type. The |type| argument should be one of the |EVP_PKEY_*|
+// the given type. It returns one if successful or zero if the |type| argument
-// values.
+// is not one of the |EVP_PKEY_*| values or if |key| is NULL.
 OPENSSL_EXPORT int EVP_PKEY_assign(EVP_PKEY *pkey, int type, void *key);
 
-// EVP_PKEY_set_type sets the type of |pkey| to |type|, which should be one of
+// EVP_PKEY_set_type sets the type of |pkey| to |type|. It returns one if
-// the |EVP_PKEY_*| values. It returns one if successful or zero otherwise. If
+// successful or zero if the |type| argument is not one of the |EVP_PKEY_*|
-// |pkey| is NULL, it simply reports whether the type is known.
+// values. If |pkey| is NULL, it simply reports whether the type is known.
 OPENSSL_EXPORT int EVP_PKEY_set_type(EVP_PKEY *pkey, int type);
 
 // EVP_PKEY_cmp_parameters compares the parameters of |a| and |b|. It returns
@@ -196,7 +196,8 @@ OPENSSL_EXPORT int EVP_PKEY_cmp_parameters(const EVP_PKEY *a,
 
 // EVP_parse_public_key decodes a DER-encoded SubjectPublicKeyInfo structure
 // (RFC 5280) from |cbs| and advances |cbs|. It returns a newly-allocated
-// |EVP_PKEY| or NULL on error.
+// |EVP_PKEY| or NULL on error. If the key is an EC key, the curve is guaranteed
+// to be set.
 //
 // The caller must check the type of the parsed public key to ensure it is
 // suitable and validate other desired key properties such as RSA modulus size

include/openssl/hmac.h

@@ -122,7 +122,7 @@ OPENSSL_EXPORT int HMAC_Update(HMAC_CTX *ctx, const uint8_t *data,
 // |out| and the sets |*out_len| to the length of the result. On entry, |out|
 // must contain at least |HMAC_size| bytes of space. An output size of
 // |EVP_MAX_MD_SIZE| will always be large enough. It returns one on success or
-// zero on error.
+// zero on allocation failure.
 OPENSSL_EXPORT int HMAC_Final(HMAC_CTX *ctx, uint8_t *out,
                               unsigned int *out_len);