[openssl] master update
yang.yang at baishancloud.com
yang.yang at baishancloud.com
Fri Mar 1 06:16:23 UTC 2019
The branch master has been updated
via cc838ee2d66f7295bf7a7e6695aab1080d6791e9 (commit)
via 4564e77ae9dd1866e8a033f03511b6a1792c024e (commit)
from 69f6b3ceaba493e70e1296880ea6c93e40714f0f (commit)
- Log -----------------------------------------------------------------
commit cc838ee2d66f7295bf7a7e6695aab1080d6791e9
Author: Paul Yang <yang.yang at baishancloud.com>
Date: Tue Feb 26 13:51:02 2019 +0800
Add section order check in util/find-doc-nits
This patch checks if the EXAMPLES section in a pod file is placed
before the RETURN VALUES section.
Reviewed-by: Richard Levitte <levitte at openssl.org>
(Merged from https://github.com/openssl/openssl/pull/8338)
commit 4564e77ae9dd1866e8a033f03511b6a1792c024e
Author: Paul Yang <yang.yang at baishancloud.com>
Date: Tue Feb 26 13:11:10 2019 +0800
Place return values after examples in doc
Reviewed-by: Richard Levitte <levitte at openssl.org>
(Merged from https://github.com/openssl/openssl/pull/8338)
-----------------------------------------------------------------------
Summary of changes:
doc/internal/man3/openssl_ctx_get_data.pod | 16 ++--
doc/man3/ASN1_TIME_set.pod | 64 ++++++-------
doc/man3/ASN1_generate_nconf.pod | 14 +--
doc/man3/BIO_push.pod | 14 +--
doc/man3/BIO_s_file.pod | 36 +++----
doc/man3/CONF_modules_load_file.pod | 12 +--
doc/man3/EVP_PKEY_set1_RSA.pod | 14 +--
doc/man3/OBJ_nid2obj.pod | 22 ++---
doc/man3/OPENSSL_s390xcap.pod | 8 +-
doc/man3/PEM_read_bio_PrivateKey.pod | 130 +++++++++++++-------------
doc/man3/SSL_CONF_cmd.pod | 34 +++----
doc/man3/SSL_CTX_load_verify_locations.pod | 34 +++----
doc/man3/SSL_CTX_set1_sigalgs.pod | 8 +-
doc/man3/SSL_CTX_set_generate_session_id.pod | 16 ++--
doc/man3/SSL_CTX_set_tlsext_ticket_key_cb.pod | 8 +-
doc/man3/SSL_CTX_set_tmp_dh_callback.pod | 16 ++--
doc/man3/SSL_load_client_CA_file.pod | 30 +++---
doc/man3/X509_NAME_add_entry_by_txt.pod | 18 ++--
doc/man3/X509_NAME_get_index_by_NID.pod | 24 ++---
doc/man3/d2i_X509.pod | 26 +++---
util/find-doc-nits | 14 +++
21 files changed, 286 insertions(+), 272 deletions(-)
diff --git a/doc/internal/man3/openssl_ctx_get_data.pod b/doc/internal/man3/openssl_ctx_get_data.pod
index ee98dc2..db066ad 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<ctx> associated with the given C<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<NULL> 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<NULL> on
-failure.
-
=head1 SEE ALSO
L<OPENSSL_CTX(3)>
diff --git a/doc/man3/ASN1_TIME_set.pod b/doc/man3/ASN1_TIME_set.pod
index 009e6f6..9db9970 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 <time.h>
- #include <openssl/asn1.h>
-
- 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<a> is before B<b>, 0 if B<a> equals B<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 <time.h>
+ #include <openssl/asn1.h>
+
+ 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 1dfe9f7..0ea71d2 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<ASN1_TYPE> structure or B<NULL> if an error occurred.
+
+The error codes that can be obtained by L<ERR_get_error(3)>.
+
=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<ASN1_TYPE> structure or B<NULL> if an error occurred.
-
-The error codes that can be obtained by L<ERR_get_error(3)>.
-
=head1 SEE ALSO
L<ERR_get_error(3)>
diff --git a/doc/man3/BIO_push.pod b/doc/man3/BIO_push.pod
index 02b6f18..c5919f3 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<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<md1> and B<md2> are digest BIOs, B<b64> is
@@ -62,13 +69,6 @@ by B<md1> and B<md2>. If the call:
The call will return B<b64> and the new chain will be B<md1-b64-f> data can
be written to B<md1> as before.
-=head1 RETURN VALUES
-
-BIO_push() returns the end of the chain, B<b>.
-
-BIO_pop() returns the next BIO in the chain, or NULL if there is no next
-BIO.
-
=head1 SEE ALSO
L<bio>
diff --git a/doc/man3/BIO_s_file.pod b/doc/man3/BIO_s_file.pod
index 5f0cdbe..0d6cc98 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 037c7f2..c0623eb 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<config(5)>, L<OPENSSL_config(3)>
diff --git a/doc/man3/EVP_PKEY_set1_RSA.pod b/doc/man3/EVP_PKEY_set1_RSA.pod
index 67471c9..868e337 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<EVP_PKEY_new(3)>
diff --git a/doc/man3/OBJ_nid2obj.pod b/doc/man3/OBJ_nid2obj.pod
index 0345062..79923d1 100644
--- a/doc/man3/OBJ_nid2obj.pod
+++ b/doc/man3/OBJ_nid2obj.pod
@@ -130,6 +130,17 @@ These functions cannot return B<const> because an B<ASN1_OBJECT> 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<ASN1_OBJECT> structure or B<NULL> is an
+error occurred.
+
+OBJ_nid2ln() and OBJ_nid2sn() returns a valid string or B<NULL>
+on error.
+
+OBJ_obj2nid(), OBJ_ln2nid(), OBJ_sn2nid() and OBJ_txt2nid() return
+a NID or B<NID_undef> on error.
+
=head1 EXAMPLES
Create an object for B<commonName>:
@@ -159,17 +170,6 @@ Instead B<buf> must point to a valid buffer and B<buf_len> 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<ASN1_OBJECT> structure or B<NULL> is an
-error occurred.
-
-OBJ_nid2ln() and OBJ_nid2sn() returns a valid string or B<NULL>
-on error.
-
-OBJ_obj2nid(), OBJ_ln2nid(), OBJ_sn2nid() and OBJ_txt2nid() return
-a NID or B<NID_undef> on error.
-
=head1 SEE ALSO
L<ERR_get_error(3)>
diff --git a/doc/man3/OPENSSL_s390xcap.pod b/doc/man3/OPENSSL_s390xcap.pod
index cf5cf8e..34c029a 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 1f53815..54dc27e 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<must> 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<PrivateKey> 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 5759c7f..5c58268 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<SSL_CONF_TYPE_FILE> an application could translate a relative
pathname to an absolute pathname.
+=head1 RETURN VALUES
+
+SSL_CONF_cmd() returns 1 if the value of B<cmd> is recognised and B<value> is
+B<NOT> used and 2 if both B<cmd> and B<value> 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<cmd> is not recognised.
+
+A return value of -3 means B<cmd> is recognised and the command requires a
+value but B<value> is NULL.
+
+A return code of 0 indicates that both B<cmd> and B<value> are valid but an
+error occurred attempting to perform the operation: for example due to an
+error in the syntax of B<value> 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<cmd> is recognised and B<value> is
-B<NOT> used and 2 if both B<cmd> and B<value> 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<cmd> is not recognised.
-
-A return value of -3 means B<cmd> is recognised and the command requires a
-value but B<value> is NULL.
-
-A return code of 0 indicates that both B<cmd> and B<value> are valid but an
-error occurred attempting to perform the operation: for example due to an
-error in the syntax of B<value> in this case the error queue may provide
-additional information.
-
=head1 SEE ALSO
L<SSL_CONF_CTX_new(3)>,
diff --git a/doc/man3/SSL_CTX_load_verify_locations.pod b/doc/man3/SSL_CTX_load_verify_locations.pod
index 03dec15..b955c60 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<CApath>:
-
- 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<CApath>:
+
+ cd /some/where/certs
+ c_rehash .
+
=head1 SEE ALSO
L<ssl(7)>,
diff --git a/doc/man3/SSL_CTX_set1_sigalgs.pod b/doc/man3/SSL_CTX_set1_sigalgs.pod
index 642f71a..eb31006 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<ssl(7)>, L<SSL_get_shared_sigalgs(3)>,
diff --git a/doc/man3/SSL_CTX_set_generate_session_id.pod b/doc/man3/SSL_CTX_set_generate_session_id.pod
index 37ecd02..8bf8e15 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<ssl(7)>, L<SSL_get_version(3)>
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 9013abc..88e70c5 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<ssl(7)>, L<SSL_set_session(3)>,
diff --git a/doc/man3/SSL_CTX_set_tmp_dh_callback.pod b/doc/man3/SSL_CTX_set_tmp_dh_callback.pod
index f69c37c..bc1dafa 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<keylength> and B<is_export> 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<ssl(7)>, L<SSL_CTX_set_cipher_list(3)>,
diff --git a/doc/man3/SSL_load_client_CA_file.pod b/doc/man3/SSL_load_client_CA_file.pod
index e1922d5..23449dd 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<SSL_CTX_set_client_CA_list(3)>,
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<ssl(7)>,
diff --git a/doc/man3/X509_NAME_add_entry_by_txt.pod b/doc/man3/X509_NAME_add_entry_by_txt.pod
index a7b1235..7f52966 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<set> 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<X509_NAME_ENTRY>
+structure of B<NULL> if an error occurred.
+
=head1 EXAMPLES
Create an B<X509_NAME> structure:
@@ -95,15 +104,6 @@ Create an B<X509_NAME> 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<X509_NAME_ENTRY>
-structure of B<NULL> if an error occurred.
-
=head1 BUGS
B<type> can still be set to B<V_ASN1_APP_CHOOSE> 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 1284373..f287849 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<X509_NAME> pointer to the
+requested entry or B<NULL> 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<X509_NAME> pointer to the
-requested entry or B<NULL> if the index is invalid.
-
=head1 SEE ALSO
L<ERR_get_error(3)>, L<d2i_X509_NAME(3)>
diff --git a/doc/man3/d2i_X509.pod b/doc/man3/d2i_X509.pod
index c11da95..23dc73c 100644
--- a/doc/man3/d2i_X509.pod
+++ b/doc/man3/d2i_X509.pod
@@ -496,6 +496,19 @@ Represents the B<DigestInfo> 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<TYPE> structure
+or B<NULL> if an error occurs. If the "reuse" capability has been used with
+a valid structure being passed in via B<a>, 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<TYPE> structure
-or B<NULL> if an error occurs. If the "reuse" capability has been used with
-a valid structure being passed in via B<a>, 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.
diff --git a/util/find-doc-nits b/util/find-doc-nits
index a8cea9c..5d5c2d0 100755
--- a/util/find-doc-nits
+++ b/util/find-doc-nits
@@ -142,6 +142,18 @@ sub name_synopsis()
}
}
+# Check if EXAMPLES is located after RETURN VALUES section.
+sub check_example_location()
+{
+ my $filename = shift;
+ my $contents = shift;
+
+ return unless $contents =~ /=head1 RETURN VALUES/
+ and $contents =~ /=head1 EXAMPLES/;
+ print "$filename: RETURN VAULES should be placed before EXAMPLES section\n"
+ if $contents =~ /=head1 EXAMPLES.*=head1 RETURN VALUES/ms;
+}
+
sub check()
{
my $filename = shift;
@@ -155,6 +167,8 @@ sub check()
close POD;
}
+ &check_example_location($filename, $contents) if $filename =~ m|man3/|;
+
my $id = "${filename}:1:";
&name_synopsis($id, $filename, $contents)
More information about the openssl-commits
mailing list