Refine the documents of several APIs
authorPeiwei Hu <jlu.hpw@foxmail.com>
Fri, 2 Dec 2022 07:43:01 +0000 (15:43 +0800)
committerTomas Mraz <tomas@openssl.org>
Fri, 16 Dec 2022 17:59:28 +0000 (18:59 +0100)
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:
crypto/evp/evp_lib.c
crypto/rsa/rsa_sign.c
crypto/x509/x509_v3.c
crypto/x509/x509name.c
doc/man3/DES_random_key.pod
doc/man3/EVP_DigestInit.pod
doc/man3/EVP_EncryptInit.pod
doc/man3/EVP_PKEY_set1_encoded_public_key.pod
doc/man3/EVP_VerifyInit.pod
doc/man3/OCSP_REQUEST_new.pod
doc/man3/RSA_sign.pod
doc/man3/SSL_CTX_set_generate_session_id.pod
doc/man3/X509_NAME_get_index_by_NID.pod
doc/man3/X509v3_get_ext_by_NID.pod
doc/man3/i2d_re_X509_tbs.pod

index a8dbfbfada04f64eb4db23561c106e992440060b..8a664335128b16dc8437ac1b48fe4892601be2b7 100644 (file)
@@ -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)
index cec4d639e318cfbd45c808685cc995fb1981db3b..b14b134080684ae106bb0a082936ca3767ee9d10 100644 (file)
@@ -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. */
index e9f256cee2267ad1a072f46b203b6d408b8047bc..c29856e5b155115828d22117fb8bcfc605e2112d 100644 (file)
 
 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,
index de29f9713ad65ce8b3a1279bdf992b8793f8333e..75ff07d899da3dc78894bd4ea6ac0424d35ac4a5 100644 (file)
@@ -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)
index 1f0020eae6448f8b472e8b804092e2819b1fb10b..48fd3d0231561cb2c21fc607cfef390c77b06ef2 100644 (file)
@@ -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.
 
index 183f2e09bd82edbd03b8e3bca3dc3080b24025b5..b8a0cb91f8d70d13e72a15be25220fc471cbd2dd 100644 (file)
@@ -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()
 
index 1d5cb6c7595d50d715a9785d1e6d24663790b8fe..3a6755e27a615735ab15bc359a870d35c2ea62fe 100644 (file)
@@ -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.
index 5ed6b20a06b4f0303d105561e0368923a38da77c..2b9f27aaa0095b14192d77f357eaa95d46788cec 100644 (file)
@@ -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
 
index 0cb67d7dc1e0394e803d214e3fe5835dd49491cc..a6d5772c3b83cf3058f7f411bf3ce7c5331d7816 100644 (file)
@@ -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)>.
 
index e9d260fec1d02b36c94a8bffade8f8717e151219..e34e591fe01becc46ac18b57271e2acaff58ff8f 100644 (file)
@@ -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.
index ed5885d48b575a38f4818b0cd859a7cca27405cf..a85a2575376b6ecf652f3863346c1eab5cae1f0e 100644 (file)
@@ -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)>.
 
index 7fb8a7662923b6965486595198638d49de9d6884..14fb12cfd0f3c9b97f30bd437310d1cbf1c1ce17 100644 (file)
@@ -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
 
index 5049e50c48d16b8ee8875d68c63223a65b0debbd..805c5fc519fa9445ab8011cb9042379a5344d358 100644 (file)
@@ -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.
index 9d26bfe19a7c5ead74ecb849e5ef0d7962ac16c3..4010a71c4371a8a7ee155c21f9ac223809ba56c1 100644 (file)
@@ -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.
index 76d46eab7a4ae6050d5542b5d7fc6576618fd6c6..bdb9bff6d681a64b89bed31d16c563e72b43dc27 100644 (file)
@@ -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