From: Paul Yang Date: Tue, 26 Feb 2019 05:11:10 +0000 (+0800) Subject: Place return values after examples in doc X-Git-Tag: openssl-3.0.0-alpha1~2456 X-Git-Url: https://git.openssl.org/gitweb/?p=openssl.git;a=commitdiff_plain;h=4564e77ae9dd1866e8a033f03511b6a1792c024e Place return values after examples in doc Reviewed-by: Richard Levitte (Merged from https://github.com/openssl/openssl/pull/8338) --- diff --git a/doc/internal/man3/openssl_ctx_get_data.pod b/doc/internal/man3/openssl_ctx_get_data.pod index ee98dc2733..db066ad9b6 100644 --- a/doc/internal/man3/openssl_ctx_get_data.pod +++ b/doc/internal/man3/openssl_ctx_get_data.pod @@ -39,6 +39,14 @@ context is freed. openssl_ctx_get_data() is used to retrieve a pointer to the data in the library context C associated with the given C. +=head1 RETURN VALUES + +openssl_ctx_new_index() returns -1 on error, otherwise the allocated +index number. + +openssl_ctx_get_data() returns a pointer on success, or C on +failure. + =head1 EXAMPLES =head2 Initialization @@ -88,14 +96,6 @@ To get and use the data stored in the library context, simply do this: */ FOO *data = openssl_ctx_get_data(ctx, foo_index); -=head1 RETURN VALUES - -openssl_ctx_new_index() returns -1 on error, otherwise the allocated -index number. - -openssl_ctx_get_data() returns a pointer on success, or C on -failure. - =head1 SEE ALSO L diff --git a/doc/man3/ASN1_TIME_set.pod b/doc/man3/ASN1_TIME_set.pod index 009e6f64c5..9db9970f5e 100644 --- a/doc/man3/ASN1_TIME_set.pod +++ b/doc/man3/ASN1_TIME_set.pod @@ -173,38 +173,6 @@ certificates complying with RFC5280 et al use GMT anyway. Use the ASN1_TIME_normalize() function to normalize the time value before printing to get GMT results. -=head1 EXAMPLES - -Set a time structure to one hour after the current time and print it out: - - #include - #include - - ASN1_TIME *tm; - time_t t; - BIO *b; - - t = time(NULL); - tm = ASN1_TIME_adj(NULL, t, 0, 60 * 60); - b = BIO_new_fp(stdout, BIO_NOCLOSE); - ASN1_TIME_print(b, tm); - ASN1_STRING_free(tm); - BIO_free(b); - -Determine if one time is later or sooner than the current time: - - int day, sec; - - if (!ASN1_TIME_diff(&day, &sec, NULL, to)) - /* Invalid time format */ - - if (day > 0 || sec > 0) - printf("Later\n"); - else if (day < 0 || sec < 0) - printf("Sooner\n"); - else - printf("Same\n"); - =head1 RETURN VALUES ASN1_TIME_set(), ASN1_UTCTIME_set(), ASN1_GENERALIZEDTIME_set(), ASN1_TIME_adj(), @@ -238,6 +206,38 @@ ASN1_TIME_compare() returns -1 if B is before B, 0 if B equals B, or ASN1_TIME_to_generalizedtime() returns a pointer to the appropriate time structure on success or NULL if an error occurred. +=head1 EXAMPLES + +Set a time structure to one hour after the current time and print it out: + + #include + #include + + ASN1_TIME *tm; + time_t t; + BIO *b; + + t = time(NULL); + tm = ASN1_TIME_adj(NULL, t, 0, 60 * 60); + b = BIO_new_fp(stdout, BIO_NOCLOSE); + ASN1_TIME_print(b, tm); + ASN1_STRING_free(tm); + BIO_free(b); + +Determine if one time is later or sooner than the current time: + + int day, sec; + + if (!ASN1_TIME_diff(&day, &sec, NULL, to)) + /* Invalid time format */ + + if (day > 0 || sec > 0) + printf("Later\n"); + else if (day < 0 || sec < 0) + printf("Sooner\n"); + else + printf("Same\n"); + =head1 HISTORY The ASN1_TIME_to_tm() function was added in OpenSSL 1.1.1. diff --git a/doc/man3/ASN1_generate_nconf.pod b/doc/man3/ASN1_generate_nconf.pod index 1dfe9f7b9b..0ea71d2b3e 100644 --- a/doc/man3/ASN1_generate_nconf.pod +++ b/doc/man3/ASN1_generate_nconf.pod @@ -162,6 +162,13 @@ bits are zero. =back +=head1 RETURN VALUES + +ASN1_generate_nconf() and ASN1_generate_v3() return the encoded +data as an B structure or B if an error occurred. + +The error codes that can be obtained by L. + =head1 EXAMPLES A simple IA5String: @@ -247,13 +254,6 @@ structure: e=INTEGER:0x010001 -=head1 RETURN VALUES - -ASN1_generate_nconf() and ASN1_generate_v3() return the encoded -data as an B structure or B if an error occurred. - -The error codes that can be obtained by L. - =head1 SEE ALSO L diff --git a/doc/man3/BIO_push.pod b/doc/man3/BIO_push.pod index 02b6f18182..c5919f3cfd 100644 --- a/doc/man3/BIO_push.pod +++ b/doc/man3/BIO_push.pod @@ -36,6 +36,13 @@ The process of calling BIO_push() and BIO_pop() on a BIO may have additional consequences (a control call is made to the affected BIOs) any effects will be noted in the descriptions of individual BIOs. +=head1 RETURN VALUES + +BIO_push() returns the end of the chain, B. + +BIO_pop() returns the next BIO in the chain, or NULL if there is no next +BIO. + =head1 EXAMPLES For these examples suppose B and B are digest BIOs, B is @@ -62,13 +69,6 @@ by B and B. If the call: The call will return B and the new chain will be B data can be written to B as before. -=head1 RETURN VALUES - -BIO_push() returns the end of the chain, B. - -BIO_pop() returns the next BIO in the chain, or NULL if there is no next -BIO. - =head1 SEE ALSO L diff --git a/doc/man3/BIO_s_file.pod b/doc/man3/BIO_s_file.pod index 5f0cdbe105..0d6cc98c16 100644 --- a/doc/man3/BIO_s_file.pod +++ b/doc/man3/BIO_s_file.pod @@ -80,6 +80,24 @@ On Windows BIO_new_files reserves for the filename argument to be UTF-8 encoded. In other words if you have to make it work in multi- lingual environment, encode file names in UTF-8. +=head1 RETURN VALUES + +BIO_s_file() returns the file BIO method. + +BIO_new_file() and BIO_new_fp() return a file BIO or NULL if an error +occurred. + +BIO_set_fp() and BIO_get_fp() return 1 for success or 0 for failure +(although the current implementation never return 0). + +BIO_seek() returns the same value as the underlying fseek() function: +0 for success or -1 for failure. + +BIO_tell() returns the current file position. + +BIO_read_filename(), BIO_write_filename(), BIO_append_filename() and +BIO_rw_filename() return 1 for success or 0 for failure. + =head1 EXAMPLES File BIO "hello world": @@ -122,24 +140,6 @@ Alternative technique: BIO_printf(out, "Hello World\n"); BIO_free(out); -=head1 RETURN VALUES - -BIO_s_file() returns the file BIO method. - -BIO_new_file() and BIO_new_fp() return a file BIO or NULL if an error -occurred. - -BIO_set_fp() and BIO_get_fp() return 1 for success or 0 for failure -(although the current implementation never return 0). - -BIO_seek() returns the same value as the underlying fseek() function: -0 for success or -1 for failure. - -BIO_tell() returns the current file position. - -BIO_read_filename(), BIO_write_filename(), BIO_append_filename() and -BIO_rw_filename() return 1 for success or 0 for failure. - =head1 BUGS BIO_reset() and BIO_seek() are implemented using fseek() on the underlying diff --git a/doc/man3/CONF_modules_load_file.pod b/doc/man3/CONF_modules_load_file.pod index 037c7f255c..c0623eb721 100644 --- a/doc/man3/CONF_modules_load_file.pod +++ b/doc/man3/CONF_modules_load_file.pod @@ -67,6 +67,12 @@ Applications can use the CONF_modules_load() function if they wish to load a configuration file themselves and have finer control over how errors are treated. +=head1 RETURN VALUES + +These functions return 1 for success and a zero or negative value for +failure. If module errors are not ignored the return code will reflect the +return value of the failing module (this will always be zero or negative). + =head1 EXAMPLES Load a configuration file and print out any errors and exit (missing file @@ -122,12 +128,6 @@ Load and parse configuration file manually, custom error handling: NCONF_free(cnf); } -=head1 RETURN VALUES - -These functions return 1 for success and a zero or negative value for -failure. If module errors are not ignored the return code will reflect the -return value of the failing module (this will always be zero or negative). - =head1 SEE ALSO L, L diff --git a/doc/man3/EVP_PKEY_set1_RSA.pod b/doc/man3/EVP_PKEY_set1_RSA.pod index 67471c9f56..868e3372c8 100644 --- a/doc/man3/EVP_PKEY_set1_RSA.pod +++ b/doc/man3/EVP_PKEY_set1_RSA.pod @@ -111,13 +111,6 @@ is no longer possible: the equivalent is EVP_PKEY_base_id(pkey). EVP_PKEY_set1_engine() is typically used by an ENGINE returning an HSM key as part of its routine to load a private key. -=head1 EXAMPLES - -After loading an ECC key, it is possible to convert it to using SM2 -algorithms with EVP_PKEY_set_alias_type: - - EVP_PKEY_set_alias_type(pkey, EVP_PKEY_SM2); - =head1 RETURN VALUES EVP_PKEY_set1_RSA(), EVP_PKEY_set1_DSA(), EVP_PKEY_set1_DH() and @@ -138,6 +131,13 @@ EVP_PKEY_set1_engine() returns 1 for success and 0 for failure. EVP_PKEY_set_alias_type() returns 1 for success and 0 for error. +=head1 EXAMPLES + +After loading an ECC key, it is possible to convert it to using SM2 +algorithms with EVP_PKEY_set_alias_type: + + EVP_PKEY_set_alias_type(pkey, EVP_PKEY_SM2); + =head1 SEE ALSO L diff --git a/doc/man3/OBJ_nid2obj.pod b/doc/man3/OBJ_nid2obj.pod index 0345062d9f..79923d1ce8 100644 --- a/doc/man3/OBJ_nid2obj.pod +++ b/doc/man3/OBJ_nid2obj.pod @@ -130,6 +130,17 @@ These functions cannot return B because an B can represent both an internal, constant, OID and a dynamically-created one. The latter cannot be constant because it needs to be freed after use. +=head1 RETURN VALUES + +OBJ_nid2obj() returns an B structure or B is an +error occurred. + +OBJ_nid2ln() and OBJ_nid2sn() returns a valid string or B +on error. + +OBJ_obj2nid(), OBJ_ln2nid(), OBJ_sn2nid() and OBJ_txt2nid() return +a NID or B on error. + =head1 EXAMPLES Create an object for B: @@ -159,17 +170,6 @@ Instead B must point to a valid buffer and B should be set to a positive value. A buffer length of 80 should be more than enough to handle any OID encountered in practice. -=head1 RETURN VALUES - -OBJ_nid2obj() returns an B structure or B is an -error occurred. - -OBJ_nid2ln() and OBJ_nid2sn() returns a valid string or B -on error. - -OBJ_obj2nid(), OBJ_ln2nid(), OBJ_sn2nid() and OBJ_txt2nid() return -a NID or B on error. - =head1 SEE ALSO L diff --git a/doc/man3/OPENSSL_s390xcap.pod b/doc/man3/OPENSSL_s390xcap.pod index cf5cf8e467..34c029a40c 100644 --- a/doc/man3/OPENSSL_s390xcap.pod +++ b/doc/man3/OPENSSL_s390xcap.pod @@ -139,6 +139,10 @@ the numbering is continuous across 64-bit mask boundaries. # 20 1<<43 KMA-GCM-AES-256 : +=head1 RETURN VALUES + +Not available. + =head1 EXAMPLES Disables all instruction set extensions which the z196 processor does not implement: @@ -153,10 +157,6 @@ Disables the KM-XTS-AES and and the KIMD-SHAKE function codes: OPENSSL_s390xcap="km:~0x2800:~0;kimd:~0xc000000:~0" -=head1 RETURN VALUES - -Not available. - =head1 SEE ALSO [1] z/Architecture Principles of Operation, SA22-7832-11 diff --git a/doc/man3/PEM_read_bio_PrivateKey.pod b/doc/man3/PEM_read_bio_PrivateKey.pod index 1f538155fd..54dc27e184 100644 --- a/doc/man3/PEM_read_bio_PrivateKey.pod +++ b/doc/man3/PEM_read_bio_PrivateKey.pod @@ -298,71 +298,6 @@ arbitrary data to be passed to the callback by the application B return the number of characters in the passphrase or -1 if an error occurred. -=head1 EXAMPLES - -Although the PEM routines take several arguments in almost all applications -most of them are set to 0 or NULL. - -Read a certificate in PEM format from a BIO: - - X509 *x; - - x = PEM_read_bio_X509(bp, NULL, 0, NULL); - if (x == NULL) - /* Error */ - -Alternative method: - - X509 *x = NULL; - - if (!PEM_read_bio_X509(bp, &x, 0, NULL)) - /* Error */ - -Write a certificate to a BIO: - - if (!PEM_write_bio_X509(bp, x)) - /* Error */ - -Write a private key (using traditional format) to a BIO using -triple DES encryption, the pass phrase is prompted for: - - if (!PEM_write_bio_PrivateKey(bp, key, EVP_des_ede3_cbc(), NULL, 0, 0, NULL)) - /* Error */ - -Write a private key (using PKCS#8 format) to a BIO using triple -DES encryption, using the pass phrase "hello": - - if (!PEM_write_bio_PKCS8PrivateKey(bp, key, EVP_des_ede3_cbc(), - NULL, 0, 0, "hello")) - /* Error */ - -Read a private key from a BIO using a pass phrase callback: - - key = PEM_read_bio_PrivateKey(bp, NULL, pass_cb, "My Private Key"); - if (key == NULL) - /* Error */ - -Skeleton pass phrase callback: - - int pass_cb(char *buf, int size, int rwflag, void *u) - { - - /* We'd probably do something else if 'rwflag' is 1 */ - printf("Enter pass phrase for \"%s\"\n", (char *)u); - - /* get pass phrase, length 'len' into 'tmp' */ - char *tmp = "hello"; - if (tmp == NULL) /* An error occurred */ - return -1; - - size_t len = strlen(tmp); - - if (len > size) - len = size; - memcpy(buf, tmp, len); - return len; - } - =head1 NOTES The old B write routines are retained for compatibility. @@ -460,6 +395,71 @@ if an error occurred. The write routines return 1 for success or 0 for failure. +=head1 EXAMPLES + +Although the PEM routines take several arguments in almost all applications +most of them are set to 0 or NULL. + +Read a certificate in PEM format from a BIO: + + X509 *x; + + x = PEM_read_bio_X509(bp, NULL, 0, NULL); + if (x == NULL) + /* Error */ + +Alternative method: + + X509 *x = NULL; + + if (!PEM_read_bio_X509(bp, &x, 0, NULL)) + /* Error */ + +Write a certificate to a BIO: + + if (!PEM_write_bio_X509(bp, x)) + /* Error */ + +Write a private key (using traditional format) to a BIO using +triple DES encryption, the pass phrase is prompted for: + + if (!PEM_write_bio_PrivateKey(bp, key, EVP_des_ede3_cbc(), NULL, 0, 0, NULL)) + /* Error */ + +Write a private key (using PKCS#8 format) to a BIO using triple +DES encryption, using the pass phrase "hello": + + if (!PEM_write_bio_PKCS8PrivateKey(bp, key, EVP_des_ede3_cbc(), + NULL, 0, 0, "hello")) + /* Error */ + +Read a private key from a BIO using a pass phrase callback: + + key = PEM_read_bio_PrivateKey(bp, NULL, pass_cb, "My Private Key"); + if (key == NULL) + /* Error */ + +Skeleton pass phrase callback: + + int pass_cb(char *buf, int size, int rwflag, void *u) + { + + /* We'd probably do something else if 'rwflag' is 1 */ + printf("Enter pass phrase for \"%s\"\n", (char *)u); + + /* get pass phrase, length 'len' into 'tmp' */ + char *tmp = "hello"; + if (tmp == NULL) /* An error occurred */ + return -1; + + size_t len = strlen(tmp); + + if (len > size) + len = size; + memcpy(buf, tmp, len); + return len; + } + =head1 HISTORY The old Netscape certificate sequences were no longer documented diff --git a/doc/man3/SSL_CONF_cmd.pod b/doc/man3/SSL_CONF_cmd.pod index 5759c7f125..5c58268f49 100644 --- a/doc/man3/SSL_CONF_cmd.pod +++ b/doc/man3/SSL_CONF_cmd.pod @@ -598,6 +598,23 @@ checking or translation of the command value. For example if the return value is B an application could translate a relative pathname to an absolute pathname. +=head1 RETURN VALUES + +SSL_CONF_cmd() returns 1 if the value of B is recognised and B is +B used and 2 if both B and B are used. In other words it +returns the number of arguments processed. This is useful when processing +command lines. + +A return value of -2 means B is not recognised. + +A return value of -3 means B is recognised and the command requires a +value but B is NULL. + +A return code of 0 indicates that both B and B are valid but an +error occurred attempting to perform the operation: for example due to an +error in the syntax of B in this case the error queue may provide +additional information. + =head1 EXAMPLES Set supported signature algorithms: @@ -644,23 +661,6 @@ Set supported curves to P-256, P-384: SSL_CONF_cmd(ctx, "Curves", "P-256:P-384"); -=head1 RETURN VALUES - -SSL_CONF_cmd() returns 1 if the value of B is recognised and B is -B used and 2 if both B and B are used. In other words it -returns the number of arguments processed. This is useful when processing -command lines. - -A return value of -2 means B is not recognised. - -A return value of -3 means B is recognised and the command requires a -value but B is NULL. - -A return code of 0 indicates that both B and B are valid but an -error occurred attempting to perform the operation: for example due to an -error in the syntax of B in this case the error queue may provide -additional information. - =head1 SEE ALSO L, diff --git a/doc/man3/SSL_CTX_load_verify_locations.pod b/doc/man3/SSL_CTX_load_verify_locations.pod index 03dec15606..b955c60eed 100644 --- a/doc/man3/SSL_CTX_load_verify_locations.pod +++ b/doc/man3/SSL_CTX_load_verify_locations.pod @@ -100,23 +100,6 @@ with different expiration dates. If a "certificate expired" verification error occurs, no other certificate will be searched. Make sure to not have expired certificates mixed with valid ones. -=head1 EXAMPLES - -Generate a CA certificate file with descriptive text from the CA certificates -ca1.pem ca2.pem ca3.pem: - - #!/bin/sh - rm CAfile.pem - for i in ca1.pem ca2.pem ca3.pem ; do - openssl x509 -in $i -text >> CAfile.pem - done - -Prepare the directory /some/where/certs containing several CA certificates -for use as B: - - cd /some/where/certs - c_rehash . - =head1 RETURN VALUES For SSL_CTX_load_verify_locations the following return values can occur: @@ -139,6 +122,23 @@ SSL_CTX_set_default_verify_paths(), SSL_CTX_set_default_verify_dir() and SSL_CTX_set_default_verify_file() all return 1 on success or 0 on failure. A missing default location is still treated as a success. +=head1 EXAMPLES + +Generate a CA certificate file with descriptive text from the CA certificates +ca1.pem ca2.pem ca3.pem: + + #!/bin/sh + rm CAfile.pem + for i in ca1.pem ca2.pem ca3.pem ; do + openssl x509 -in $i -text >> CAfile.pem + done + +Prepare the directory /some/where/certs containing several CA certificates +for use as B: + + cd /some/where/certs + c_rehash . + =head1 SEE ALSO L, diff --git a/doc/man3/SSL_CTX_set1_sigalgs.pod b/doc/man3/SSL_CTX_set1_sigalgs.pod index 642f71a75c..eb31006346 100644 --- a/doc/man3/SSL_CTX_set1_sigalgs.pod +++ b/doc/man3/SSL_CTX_set1_sigalgs.pod @@ -83,6 +83,10 @@ be used with the B<_list> forms of the API. The use of MD5 as a digest is strongly discouraged due to security weaknesses. +=head1 RETURN VALUES + +All these functions return 1 for success and 0 for failure. + =head1 EXAMPLES Set supported signature algorithms to SHA256 with ECDSA and SHA256 with RSA @@ -97,10 +101,6 @@ using a string: SSL_CTX_set1_sigalgs_list(ctx, "ECDSA+SHA256:RSA+SHA256"); -=head1 RETURN VALUES - -All these functions return 1 for success and 0 for failure. - =head1 SEE ALSO L, L, diff --git a/doc/man3/SSL_CTX_set_generate_session_id.pod b/doc/man3/SSL_CTX_set_generate_session_id.pod index 37ecd02684..8bf8e152d5 100644 --- a/doc/man3/SSL_CTX_set_generate_session_id.pod +++ b/doc/man3/SSL_CTX_set_generate_session_id.pod @@ -82,6 +82,14 @@ and the same race condition applies. The callback must return 0 if it cannot generate a session id for whatever reason and return 1 on success. +=head1 RETURN VALUES + +SSL_CTX_set_generate_session_id() and SSL_set_generate_session_id() +always return 1. + +SSL_has_matching_session_id() returns 1 if another session with the +same id is already in the cache. + =head1 EXAMPLES The callback function listed will generate a session id with the @@ -114,14 +122,6 @@ server id given, and will fill the rest with pseudo random bytes: } -=head1 RETURN VALUES - -SSL_CTX_set_generate_session_id() and SSL_set_generate_session_id() -always return 1. - -SSL_has_matching_session_id() returns 1 if another session with the -same id is already in the cache. - =head1 SEE ALSO L, L diff --git a/doc/man3/SSL_CTX_set_tlsext_ticket_key_cb.pod b/doc/man3/SSL_CTX_set_tlsext_ticket_key_cb.pod index 9013abc2a2..88e70c5fa2 100644 --- a/doc/man3/SSL_CTX_set_tlsext_ticket_key_cb.pod +++ b/doc/man3/SSL_CTX_set_tlsext_ticket_key_cb.pod @@ -121,6 +121,10 @@ For example if a cipher suite uses 256 bit ciphers but only a 128 bit ticket key the overall security is only 128 bits because breaking the ticket key will enable an attacker to obtain the session keys. +=head1 RETURN VALUES + +returns 0 to indicate the callback function was set. + =head1 EXAMPLES Reference Implementation: @@ -175,10 +179,6 @@ Reference Implementation: } } -=head1 RETURN VALUES - -returns 0 to indicate the callback function was set. - =head1 SEE ALSO L, L, diff --git a/doc/man3/SSL_CTX_set_tmp_dh_callback.pod b/doc/man3/SSL_CTX_set_tmp_dh_callback.pod index f69c37cd22..bc1dafa53b 100644 --- a/doc/man3/SSL_CTX_set_tmp_dh_callback.pod +++ b/doc/man3/SSL_CTX_set_tmp_dh_callback.pod @@ -81,6 +81,14 @@ are advised to either use SSL_CTX_set_tmp_dh() or alternatively, use the callback but ignore B and B and simply supply at least 2048-bit parameters in the callback. +=head1 RETURN VALUES + +SSL_CTX_set_tmp_dh_callback() and SSL_set_tmp_dh_callback() do not return +diagnostic output. + +SSL_CTX_set_tmp_dh() and SSL_set_tmp_dh() do return 1 on success and 0 +on failure. Check the error queue to find out the reason of failure. + =head1 EXAMPLES Setup DH parameters with a key length of 2048 bits. (Error handling @@ -109,14 +117,6 @@ Code for setting up parameters during server initialization: /* Error. */ ... -=head1 RETURN VALUES - -SSL_CTX_set_tmp_dh_callback() and SSL_set_tmp_dh_callback() do not return -diagnostic output. - -SSL_CTX_set_tmp_dh() and SSL_set_tmp_dh() do return 1 on success and 0 -on failure. Check the error queue to find out the reason of failure. - =head1 SEE ALSO L, L, diff --git a/doc/man3/SSL_load_client_CA_file.pod b/doc/man3/SSL_load_client_CA_file.pod index e1922d5fb4..23449dd3c3 100644 --- a/doc/man3/SSL_load_client_CA_file.pod +++ b/doc/man3/SSL_load_client_CA_file.pod @@ -23,21 +23,6 @@ the specific usage as support function for L, it is not limited to CA certificates. -=head1 EXAMPLES - -Load names of CAs from file and use it as a client CA list: - - SSL_CTX *ctx; - STACK_OF(X509_NAME) *cert_names; - - ... - cert_names = SSL_load_client_CA_file("/path/to/CAfile.pem"); - if (cert_names != NULL) - SSL_CTX_set_client_CA_list(ctx, cert_names); - else - /* error */ - ... - =head1 RETURN VALUES The following return values can occur: @@ -54,6 +39,21 @@ Pointer to the subject names of the successfully read certificates. =back +=head1 EXAMPLES + +Load names of CAs from file and use it as a client CA list: + + SSL_CTX *ctx; + STACK_OF(X509_NAME) *cert_names; + + ... + cert_names = SSL_load_client_CA_file("/path/to/CAfile.pem"); + if (cert_names != NULL) + SSL_CTX_set_client_CA_list(ctx, cert_names); + else + /* error */ + ... + =head1 SEE ALSO L, diff --git a/doc/man3/X509_NAME_add_entry_by_txt.pod b/doc/man3/X509_NAME_add_entry_by_txt.pod index a7b123573f..7f52966121 100644 --- a/doc/man3/X509_NAME_add_entry_by_txt.pod +++ b/doc/man3/X509_NAME_add_entry_by_txt.pod @@ -74,6 +74,15 @@ structure respectively. This will then be a multivalued RDN: since multivalues RDNs are very seldom used B is almost always set to zero. +=head1 RETURN VALUES + +X509_NAME_add_entry_by_txt(), X509_NAME_add_entry_by_OBJ(), +X509_NAME_add_entry_by_NID() and X509_NAME_add_entry() return 1 for +success of 0 if an error occurred. + +X509_NAME_delete_entry() returns either the deleted B +structure of B if an error occurred. + =head1 EXAMPLES Create an B structure: @@ -95,15 +104,6 @@ Create an B structure: "Joe Bloggs", -1, -1, 0)) /* Error */ -=head1 RETURN VALUES - -X509_NAME_add_entry_by_txt(), X509_NAME_add_entry_by_OBJ(), -X509_NAME_add_entry_by_NID() and X509_NAME_add_entry() return 1 for -success of 0 if an error occurred. - -X509_NAME_delete_entry() returns either the deleted B -structure of B if an error occurred. - =head1 BUGS B can still be set to B to use a diff --git a/doc/man3/X509_NAME_get_index_by_NID.pod b/doc/man3/X509_NAME_get_index_by_NID.pod index 12843736fa..f287849c0e 100644 --- a/doc/man3/X509_NAME_get_index_by_NID.pod +++ b/doc/man3/X509_NAME_get_index_by_NID.pod @@ -69,6 +69,18 @@ Applications which could pass invalid NIDs to X509_NAME_get_index_by_NID() should check for the return value of -2. Alternatively the NID validity can be determined first by checking OBJ_nid2obj(nid) is not NULL. +=head1 RETURN VALUES + +X509_NAME_get_index_by_NID() and X509_NAME_get_index_by_OBJ() +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_get_entry() returns an B pointer to the +requested entry or B if the index is invalid. + =head1 EXAMPLES Process all entries: @@ -94,18 +106,6 @@ Process all commonName entries: /* Do something with e */ } -=head1 RETURN VALUES - -X509_NAME_get_index_by_NID() and X509_NAME_get_index_by_OBJ() -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_get_entry() returns an B pointer to the -requested entry or B if the index is invalid. - =head1 SEE ALSO L, L diff --git a/doc/man3/d2i_X509.pod b/doc/man3/d2i_X509.pod index c11da95178..23dc73c336 100644 --- a/doc/man3/d2i_X509.pod +++ b/doc/man3/d2i_X509.pod @@ -496,6 +496,19 @@ Represents the B structure defined in PKCS#1 and PKCS#7. =back +=head1 RETURN VALUES + +d2i_TYPE(), d2i_TYPE_bio() and d2i_TYPE_fp() return a valid B structure +or B if an error occurs. If the "reuse" capability has been used with +a valid structure being passed in via B, then the object is not freed in +the event of error but may be in a potentially invalid or inconsistent state. + +i2d_TYPE() returns the number of bytes successfully encoded or a negative +value if an error occurs. + +i2d_TYPE_bio() and i2d_TYPE_fp() return 1 for success and 0 if an error +occurs. + =head1 EXAMPLES Allocate and encode the DER encoding of an X509 structure: @@ -586,19 +599,6 @@ structure has been modified after deserialization or previous serialization. This is because some objects cache the encoding for efficiency reasons. -=head1 RETURN VALUES - -d2i_TYPE(), d2i_TYPE_bio() and d2i_TYPE_fp() return a valid B structure -or B if an error occurs. If the "reuse" capability has been used with -a valid structure being passed in via B, then the object is not freed in -the event of error but may be in a potentially invalid or inconsistent state. - -i2d_TYPE() returns the number of bytes successfully encoded or a negative -value if an error occurs. - -i2d_TYPE_bio() and i2d_TYPE_fp() return 1 for success and 0 if an error -occurs. - =head1 COPYRIGHT Copyright 1998-2018 The OpenSSL Project Authors. All Rights Reserved.