Refine the documents of several APIs

Reviewed-by: Matt Caswell <matt@openssl.org>
Reviewed-by: Tomas Mraz <tomas@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/19816)

15 files changed, 33 insertions, 20 deletions

diff --git a/crypto/evp/evp_lib.c b/crypto/evp/evp_lib.c
index a8dbfbfada..8a66433512 100644
--- a/crypto/evp/evp_lib.c
+++ b/crypto/evp/evp_lib.c
@@ -602,7 +602,7 @@ int EVP_CIPHER_CTX_get_updated_iv(EVP_CIPHER_CTX *ctx, void *buf, size_t len)
 
     params[0] =
         OSSL_PARAM_construct_octet_string(OSSL_CIPHER_PARAM_UPDATED_IV, buf, len);
-    return evp_do_ciph_ctx_getparams(ctx->cipher, ctx->algctx, params);
+    return evp_do_ciph_ctx_getparams(ctx->cipher, ctx->algctx, params) > 0;
 }
 
 int EVP_CIPHER_CTX_get_original_iv(EVP_CIPHER_CTX *ctx, void *buf, size_t len)
@@ -611,7 +611,7 @@ int EVP_CIPHER_CTX_get_original_iv(EVP_CIPHER_CTX *ctx, void *buf, size_t len)
 
     params[0] =
         OSSL_PARAM_construct_octet_string(OSSL_CIPHER_PARAM_IV, buf, len);
-    return evp_do_ciph_ctx_getparams(ctx->cipher, ctx->algctx, params);
+    return evp_do_ciph_ctx_getparams(ctx->cipher, ctx->algctx, params) > 0;
 }
 
 unsigned char *EVP_CIPHER_CTX_buf_noconst(EVP_CIPHER_CTX *ctx)
diff --git a/crypto/rsa/rsa_sign.c b/crypto/rsa/rsa_sign.c
index cec4d639e3..b14b134080 100644
--- a/crypto/rsa/rsa_sign.c
+++ b/crypto/rsa/rsa_sign.c
@@ -278,7 +278,7 @@ int RSA_sign(int type, const unsigned char *m, unsigned int m_len,
 
 #ifndef FIPS_MODULE
     if (rsa->meth->rsa_sign != NULL)
-        return rsa->meth->rsa_sign(type, m, m_len, sigret, siglen, rsa);
+        return rsa->meth->rsa_sign(type, m, m_len, sigret, siglen, rsa) > 0;
 #endif /* FIPS_MODULE */
 
     /* Compute the encoded digest. */
diff --git a/crypto/x509/x509_v3.c b/crypto/x509/x509_v3.c
index e9f256cee2..c29856e5b1 100644
--- a/crypto/x509/x509_v3.c
+++ b/crypto/x509/x509_v3.c
@@ -19,9 +19,12 @@
 
 int X509v3_get_ext_count(const STACK_OF(X509_EXTENSION) *x)
 {
+    int ret;
+
     if (x == NULL)
         return 0;
-    return sk_X509_EXTENSION_num(x);
+    ret = sk_X509_EXTENSION_num(x);
+    return ret > 0 ? ret : 0;
 }
 
 int X509v3_get_ext_by_NID(const STACK_OF(X509_EXTENSION) *x, int nid,
diff --git a/crypto/x509/x509name.c b/crypto/x509/x509name.c
index de29f9713a..75ff07d899 100644
--- a/crypto/x509/x509name.c
+++ b/crypto/x509/x509name.c
@@ -49,9 +49,12 @@ int X509_NAME_get_text_by_OBJ(const X509_NAME *name, const ASN1_OBJECT *obj,
 
 int X509_NAME_entry_count(const X509_NAME *name)
 {
+    int ret;
+
     if (name == NULL)
         return 0;
-    return sk_X509_NAME_ENTRY_num(name->entries);
+    ret = sk_X509_NAME_ENTRY_num(name->entries);
+    return ret > 0 ? ret : 0;
 }
 
 int X509_NAME_get_index_by_NID(const X509_NAME *name, int nid, int lastpos)
diff --git a/doc/man3/DES_random_key.pod b/doc/man3/DES_random_key.pod
index 1f0020eae6..48fd3d0231 100644
--- a/doc/man3/DES_random_key.pod
+++ b/doc/man3/DES_random_key.pod
@@ -294,9 +294,12 @@ not suitable for most applications; see L<des_modes(7)>.
 
 =head1 RETURN VALUES
 
-DES_set_key(), DES_key_sched(), DES_set_key_checked() and DES_is_weak_key()
+DES_set_key(), DES_key_sched(), and DES_set_key_checked()
 return 0 on success or negative values on error.
 
+DES_is_weak_key() returns 1 if the passed key is a weak key, 0 if it
+is ok.
+
 DES_cbc_cksum() and DES_quad_cksum() return 4-byte integer representing the
 last 4 bytes of the checksum of the input.
 
diff --git a/doc/man3/EVP_DigestInit.pod b/doc/man3/EVP_DigestInit.pod
index 183f2e09bd..b8a0cb91f8 100644
--- a/doc/man3/EVP_DigestInit.pod
+++ b/doc/man3/EVP_DigestInit.pod
@@ -615,7 +615,7 @@ EVP_MD_get_block_size(),
 EVP_MD_CTX_get_size(),
 EVP_MD_CTX_get_block_size()
 
-Returns the digest or block size in bytes.
+Returns the digest or block size in bytes or -1 for failure.
 
 =item EVP_md_null()
 
diff --git a/doc/man3/EVP_EncryptInit.pod b/doc/man3/EVP_EncryptInit.pod
index 1d5cb6c759..3a6755e27a 100644
--- a/doc/man3/EVP_EncryptInit.pod
+++ b/doc/man3/EVP_EncryptInit.pod
@@ -1289,7 +1289,8 @@ EVP_CIPHER_CTX_is_encrypting() returns 1 if the I<ctx> is set up for encryption
 EVP_CIPHER_param_to_asn1() and EVP_CIPHER_asn1_to_param() return greater
 than zero for success and zero or a negative number on failure.
 
-EVP_CIPHER_CTX_rand_key() returns 1 for success.
+EVP_CIPHER_CTX_rand_key() returns 1 for success and zero or a negative number
+for failure.
 
 EVP_CIPHER_names_do_all() returns 1 if the callback was called for all names.
 A return value of 0 means that the callback was not called for any names.
diff --git a/doc/man3/EVP_PKEY_set1_encoded_public_key.pod b/doc/man3/EVP_PKEY_set1_encoded_public_key.pod
index 5ed6b20a06..2b9f27aaa0 100644
--- a/doc/man3/EVP_PKEY_set1_encoded_public_key.pod
+++ b/doc/man3/EVP_PKEY_set1_encoded_public_key.pod
@@ -64,7 +64,7 @@ should use EVP_PKEY_get1_encoded_public_key() instead.
 EVP_PKEY_set1_encoded_public_key() returns 1 for success and 0 or a negative
 value for failure.
 
-EVP_PKEY_get1_encoded_public_key() return 1
+EVP_PKEY_get1_encoded_public_key() returns the length of the encoded key or 0 for failure.
 
 =head1 EXAMPLES
 
diff --git a/doc/man3/EVP_VerifyInit.pod b/doc/man3/EVP_VerifyInit.pod
index 0cb67d7dc1..a6d5772c3b 100644
--- a/doc/man3/EVP_VerifyInit.pod
+++ b/doc/man3/EVP_VerifyInit.pod
@@ -50,7 +50,7 @@ EVP_VerifyInit_ex() and EVP_VerifyUpdate() return 1 for success and 0 for
 failure.
 
 EVP_VerifyFinal_ex() and EVP_VerifyFinal() return 1 for a correct
-signature, 0 for failure and -1 if some other error occurred.
+signature, 0 for failure and a negative value if some other error occurred.
 
 The error codes can be obtained by L<ERR_get_error(3)>.
 
diff --git a/doc/man3/OCSP_REQUEST_new.pod b/doc/man3/OCSP_REQUEST_new.pod
index e9d260fec1..e34e591fe0 100644
--- a/doc/man3/OCSP_REQUEST_new.pod
+++ b/doc/man3/OCSP_REQUEST_new.pod
@@ -62,7 +62,7 @@ OCSP_request_sign() and OCSP_request_add1_cert() return 1 for success and 0
 for failure.
 
 OCSP_request_onereq_count() returns the total number of B<OCSP_ONEREQ>
-structures in B<req>.
+structures in B<req> and -1 on error.
 
 OCSP_request_onereq_get0() returns a pointer to an B<OCSP_ONEREQ> structure
 or B<NULL> if the index value is out or range.
diff --git a/doc/man3/RSA_sign.pod b/doc/man3/RSA_sign.pod
index ed5885d48b..a85a257537 100644
--- a/doc/man3/RSA_sign.pod
+++ b/doc/man3/RSA_sign.pod
@@ -46,8 +46,8 @@ B<rsa> is the signer's public key.
 
 =head1 RETURN VALUES
 
-RSA_sign() returns 1 on success.
-RSA_verify() returns 1 on successful verification.
+RSA_sign() returns 1 on success and 0 for failure.
+RSA_verify() returns 1 on successful verification and 0 for failure.
 
 The error codes can be obtained by L<ERR_get_error(3)>.
 
diff --git a/doc/man3/SSL_CTX_set_generate_session_id.pod b/doc/man3/SSL_CTX_set_generate_session_id.pod
index 7fb8a76629..14fb12cfd0 100644
--- a/doc/man3/SSL_CTX_set_generate_session_id.pod
+++ b/doc/man3/SSL_CTX_set_generate_session_id.pod
@@ -85,10 +85,10 @@ reason and return 1 on success.
 =head1 RETURN VALUES
 
 SSL_CTX_set_generate_session_id() and SSL_set_generate_session_id()
-always return 1.
+return 1 on success and 0 for failure.
 
 SSL_has_matching_session_id() returns 1 if another session with the
-same id is already in the cache.
+same id is already in the cache, or 0 otherwise.
 
 =head1 EXAMPLES
 
diff --git a/doc/man3/X509_NAME_get_index_by_NID.pod b/doc/man3/X509_NAME_get_index_by_NID.pod
index 5049e50c48..805c5fc519 100644
--- a/doc/man3/X509_NAME_get_index_by_NID.pod
+++ b/doc/man3/X509_NAME_get_index_by_NID.pod
@@ -79,7 +79,8 @@ return the index of the next matching entry or -1 if not found.
 X509_NAME_get_index_by_NID() can also return -2 if the supplied
 NID is invalid.
 
-X509_NAME_entry_count() returns the total number of entries.
+X509_NAME_entry_count() returns the total number of entries, and 0
+for failure.
 
 X509_NAME_get_entry() returns an B<X509_NAME> pointer to the
 requested entry or B<NULL> if the index is invalid.
diff --git a/doc/man3/X509v3_get_ext_by_NID.pod b/doc/man3/X509v3_get_ext_by_NID.pod
index 9d26bfe19a..4010a71c43 100644
--- a/doc/man3/X509v3_get_ext_by_NID.pod
+++ b/doc/man3/X509v3_get_ext_by_NID.pod
@@ -121,13 +121,15 @@ using X509_EXTENSION_free().
 
 =head1 RETURN VALUES
 
-X509v3_get_ext_count() returns the extension count.
+X509v3_get_ext_count() returns the extension count or 0 for failure.
 
 X509v3_get_ext(), X509v3_delete_ext() and X509_delete_ext() return an
 B<X509_EXTENSION> structure or NULL if an error occurs.
 
-X509v3_get_ext_by_NID(), X509v3_get_ext_by_OBJ() and
-X509v3_get_ext_by_critical() return the extension index or -1 if an
+X509v3_get_ext_by_OBJ() and X509v3_get_ext_by_critical() return
+the extension index or -1 if an error occurs.
+
+X509v3_get_ext_by_NID() returns the extension index or negative values if an
 error occurs.
 
 X509v3_add_ext() returns a STACK of extensions or NULL on error.
diff --git a/doc/man3/i2d_re_X509_tbs.pod b/doc/man3/i2d_re_X509_tbs.pod
index 76d46eab7a..bdb9bff6d6 100644
--- a/doc/man3/i2d_re_X509_tbs.pod
+++ b/doc/man3/i2d_re_X509_tbs.pod
@@ -55,7 +55,7 @@ d2i_X509_AUX() returns a valid B<X509> structure or NULL if an error occurred.
 i2d_X509_AUX() returns the length of encoded data or -1 on error.
 
 i2d_re_X509_tbs(), i2d_re_X509_CRL_tbs() and i2d_re_X509_REQ_tbs() return the
-length of encoded data or 0 on error.
+length of encoded data or <=0 on error.
 
 =head1 SEE ALSO