From dd1f28427b375931fda45180619c8f5971cd6bca Mon Sep 17 00:00:00 2001 From: Peiwei Hu Date: Fri, 2 Dec 2022 15:43:01 +0800 Subject: [PATCH] Refine the documents of several APIs Reviewed-by: Matt Caswell Reviewed-by: Tomas Mraz (Merged from https://github.com/openssl/openssl/pull/19816) --- crypto/evp/evp_lib.c | 4 ++-- crypto/rsa/rsa_sign.c | 2 +- crypto/x509/x509_v3.c | 5 ++++- crypto/x509/x509name.c | 5 ++++- doc/man3/DES_random_key.pod | 5 ++++- doc/man3/EVP_DigestInit.pod | 2 +- doc/man3/EVP_EncryptInit.pod | 3 ++- doc/man3/EVP_PKEY_set1_encoded_public_key.pod | 2 +- doc/man3/EVP_VerifyInit.pod | 2 +- doc/man3/OCSP_REQUEST_new.pod | 2 +- doc/man3/RSA_sign.pod | 4 ++-- doc/man3/SSL_CTX_set_generate_session_id.pod | 4 ++-- doc/man3/X509_NAME_get_index_by_NID.pod | 3 ++- doc/man3/X509v3_get_ext_by_NID.pod | 8 +++++--- doc/man3/i2d_re_X509_tbs.pod | 2 +- 15 files changed, 33 insertions(+), 20 deletions(-) diff --git a/crypto/evp/evp_lib.c b/crypto/evp/evp_lib.c index a8dbfbfada04f..8a664335128b1 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 cec4d639e318c..b14b134080684 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 e9f256cee2267..c29856e5b1551 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 de29f9713ad65..75ff07d899da3 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 1f0020eae6448..48fd3d0231561 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. =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 183f2e09bd82e..b8a0cb91f8d70 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 1d5cb6c7595d5..3a6755e27a615 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 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 5ed6b20a06b4f..2b9f27aaa0095 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 0cb67d7dc1e03..a6d5772c3b83c 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. diff --git a/doc/man3/OCSP_REQUEST_new.pod b/doc/man3/OCSP_REQUEST_new.pod index e9d260fec1d02..e34e591fe01be 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 -structures in B. +structures in B and -1 on error. OCSP_request_onereq_get0() returns a pointer to an B structure or B if the index value is out or range. diff --git a/doc/man3/RSA_sign.pod b/doc/man3/RSA_sign.pod index ed5885d48b575..a85a2575376b6 100644 --- a/doc/man3/RSA_sign.pod +++ b/doc/man3/RSA_sign.pod @@ -46,8 +46,8 @@ B 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. diff --git a/doc/man3/SSL_CTX_set_generate_session_id.pod b/doc/man3/SSL_CTX_set_generate_session_id.pod index 7fb8a7662923b..14fb12cfd0f3c 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 5049e50c48d16..805c5fc519fa9 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 pointer to the requested entry or B 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 9d26bfe19a7c5..4010a71c4371a 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 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 76d46eab7a4ae..bdb9bff6d681a 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 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