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>
diff --git a/include/openssl/ec.h b/include/openssl/ec.h index 989cf56..dbb72ab 100644 --- a/include/openssl/ec.h +++ b/include/openssl/ec.h
@@ -102,7 +102,7 @@ // 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),
diff --git a/include/openssl/ec_key.h b/include/openssl/ec_key.h index cc075e5..a94116c 100644 --- a/include/openssl/ec_key.h +++ b/include/openssl/ec_key.h
@@ -113,8 +113,8 @@ 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 is an error to change to a different one. +// It returns one on success and zero if |key| is already configured with a +// 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|.
diff --git a/include/openssl/ecdsa.h b/include/openssl/ecdsa.h index 42da1c6..ff326ab 100644 --- a/include/openssl/ecdsa.h +++ b/include/openssl/ecdsa.h
@@ -86,7 +86,7 @@ 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);
diff --git a/include/openssl/evp.h b/include/openssl/evp.h index 7994b84..eb4c727 100644 --- a/include/openssl/evp.h +++ b/include/openssl/evp.h
@@ -136,11 +136,11 @@ // // 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| -// functions adopt the caller's reference. The |get1| functions return a fresh -// reference to the underlying object or NULL if |pkey| is not of the correct -// type. The |get0| functions behave the same but return a non-owning -// pointer. +// underlying key and return one on success or zero if |key| is NULL. The +// |assign| functions adopt the caller's reference and return one on success or +// zero if |key| is NULL. The |get1| functions return a fresh reference to the +// underlying object or NULL if |pkey| is not of the correct type. The |get0| +// 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 @@ #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_*| -// values. +// the given type. It returns one if successful or zero if the |type| argument +// 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 -// the |EVP_PKEY_*| values. It returns one if successful or zero otherwise. If -// |pkey| is NULL, it simply reports whether the type is known. +// EVP_PKEY_set_type sets the type of |pkey| to |type|. It returns one if +// successful or zero if the |type| argument is not one of the |EVP_PKEY_*| +// 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 @@ // 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
diff --git a/include/openssl/hmac.h b/include/openssl/hmac.h index 20f3e4d..977dea6 100644 --- a/include/openssl/hmac.h +++ b/include/openssl/hmac.h
@@ -122,7 +122,7 @@ // |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);