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);
