[openssl] OpenSSL_1_1_1-stable update
matthias.st.pierre at ncp-e.com
matthias.st.pierre at ncp-e.com
Mon Apr 15 10:32:46 UTC 2019
The branch OpenSSL_1_1_1-stable has been updated
via 1ced49fbb7428994b137248d52f108d4045bb4a3 (commit)
via 18bad53564e10b92832475dfce0c56665b5d3bed (commit)
via 3b01f353b8533f2d66f7411c3513d9444ba68329 (commit)
via 32a775df9b720781220556549d7e52c45ebb562d (commit)
via a345fa370e6acd1293e7370a85266e87dc7ebc38 (commit)
via d090fc0019b8ef04bcae8c7eafe98950a9694fc8 (commit)
from e861d659c0b2ddccc5eff577b322d2fd4a8f9616 (commit)
- Log -----------------------------------------------------------------
commit 1ced49fbb7428994b137248d52f108d4045bb4a3
Author: Joshua Lock <jlock at vmware.com>
Date: Thu Apr 11 15:38:56 2019 +0100
Further harmonisation of manual page HISTORY sections
A couple of minor tweaks to match the style introduced in #7854:
- BIO_connect: remove line break to make more grep friendly
- SSL_CTX_new: harmoise the format of the HISTORY section
Reviewed-by: Matthias St. Pierre <Matthias.St.Pierre at ncp-e.com>
Reviewed-by: Richard Levitte <levitte at openssl.org>
(cherry picked from commit 938e82f622eb04ebbfe534c79d234d0f6a0df035)
Reviewed-by: Matt Caswell <matt at openssl.org>
(Merged from https://github.com/openssl/openssl/pull/8736)
commit 18bad53564e10b92832475dfce0c56665b5d3bed
Author: Joshua Lock <jlock at vmware.com>
Date: Tue Apr 9 15:13:55 2019 +0100
Update various man pages to place HISTORY section after SEE ALSO
SEE ALSO before HISTORY is the more common pattern in OpenSSL manual
pages and seems to be the prevalent order based on sampling my system
manual pages.
Fixes #8631
Reviewed-by: Matthias St. Pierre <Matthias.St.Pierre at ncp-e.com>
Reviewed-by: Richard Levitte <levitte at openssl.org>
(cherry picked from commit b5c4bbbe54e112b976155004b3d702e47ce7d9d9)
Conflicts:
doc/man3/RAND_DRBG_generate.pod
doc/man3/RAND_DRBG_reseed.pod
Reviewed-by: Matt Caswell <matt at openssl.org>
(Merged from https://github.com/openssl/openssl/pull/8736)
commit 3b01f353b8533f2d66f7411c3513d9444ba68329
Author: Joshua Lock <jlock at vmware.com>
Date: Tue Apr 9 15:10:08 2019 +0100
Add a check for history section location to find-doc-nits
Check that the HISTORY section is located after the SEE ALSO section,
this is a much more frequent order in OpenSSL manual pages (and UNIX
manual pages in general).
Also check that SEE ALSO comes after EXAMPLES, so that the tool can
ensure the correct manual section sequence.
Reviewed-by: Matthias St. Pierre <Matthias.St.Pierre at ncp-e.com>
Reviewed-by: Richard Levitte <levitte at openssl.org>
(cherry picked from commit 573ac8f2228241771f727ecd8ff10f54073536d3)
Reviewed-by: Matt Caswell <matt at openssl.org>
(Merged from https://github.com/openssl/openssl/pull/8736)
commit 32a775df9b720781220556549d7e52c45ebb562d
Author: Joshua Lock <jlock at vmware.com>
Date: Tue Apr 9 14:53:58 2019 +0100
Make check_example_location() in find-doc-nits generic
Change to check_section_location(), a generic function to ensure that
section SECTION appears before section BEFORE in the man pages.
Reviewed-by: Matthias St. Pierre <Matthias.St.Pierre at ncp-e.com>
Reviewed-by: Richard Levitte <levitte at openssl.org>
(cherry picked from commit 95f92d57755a9bfc83135a585da69d497f7293d9)
Reviewed-by: Matt Caswell <matt at openssl.org>
(Merged from https://github.com/openssl/openssl/pull/8736)
commit a345fa370e6acd1293e7370a85266e87dc7ebc38
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>
(cherry picked from commit cc838ee2d66f7295bf7a7e6695aab1080d6791e9)
Reviewed-by: Matt Caswell <matt at openssl.org>
Reviewed-by: Matthias St. Pierre <Matthias.St.Pierre at ncp-e.com>
(Merged from https://github.com/openssl/openssl/pull/8736)
commit d090fc0019b8ef04bcae8c7eafe98950a9694fc8
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>
(cherry picked from commit 4564e77ae9dd1866e8a033f03511b6a1792c024e)
Conflicts:
doc/internal/man3/openssl_ctx_get_data.pod (non-existant)
doc/man3/OPENSSL_s390xcap.pod (non-existant)
Reviewed-by: Matt Caswell <matt at openssl.org>
Reviewed-by: Matthias St. Pierre <Matthias.St.Pierre at ncp-e.com>
(Merged from https://github.com/openssl/openssl/pull/8736)
-----------------------------------------------------------------------
Summary of changes:
doc/man3/ASN1_TIME_set.pod | 64 ++++++------
doc/man3/ASN1_generate_nconf.pod | 14 +--
doc/man3/BIO_connect.pod | 14 +--
doc/man3/BIO_push.pod | 14 +--
doc/man3/BIO_s_file.pod | 36 +++----
doc/man3/BN_rand.pod | 20 ++--
doc/man3/BN_security_bits.pod | 10 +-
doc/man3/CONF_modules_load_file.pod | 12 +--
doc/man3/DES_random_key.pod | 12 +--
doc/man3/EVP_PKEY_set1_RSA.pod | 14 +--
doc/man3/OBJ_nid2obj.pod | 22 ++--
doc/man3/PEM_read_bio_PrivateKey.pod | 140 +++++++++++++-------------
doc/man3/RAND_DRBG_generate.pod | 10 +-
doc/man3/RAND_DRBG_get0_master.pod | 11 +-
doc/man3/RAND_DRBG_new.pod | 10 +-
doc/man3/RAND_DRBG_reseed.pod | 10 +-
doc/man3/RAND_DRBG_set_callbacks.pod | 11 +-
doc/man3/RAND_add.pod | 12 +--
doc/man3/RAND_bytes.pod | 20 ++--
doc/man3/RAND_cleanup.pod | 10 +-
doc/man3/SSL_CIPHER_get_name.pod | 12 +--
doc/man3/SSL_CONF_cmd.pod | 34 +++----
doc/man3/SSL_CTX_load_verify_locations.pod | 34 +++----
doc/man3/SSL_CTX_new.pod | 14 +--
doc/man3/SSL_CTX_set1_sigalgs.pod | 8 +-
doc/man3/SSL_CTX_set_default_passwd_cb.pod | 12 +--
doc/man3/SSL_CTX_set_generate_session_id.pod | 16 +--
doc/man3/SSL_CTX_set_min_proto_version.pod | 10 +-
doc/man3/SSL_CTX_set_split_send_fragment.pod | 10 +-
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/SSL_read.pod | 10 +-
doc/man3/SSL_write.pod | 10 +-
doc/man3/X509_NAME_add_entry_by_txt.pod | 18 ++--
doc/man3/X509_NAME_get_index_by_NID.pod | 24 ++---
doc/man3/X509_get_subject_name.pod | 18 ++--
doc/man3/d2i_X509.pod | 26 ++---
util/find-doc-nits | 23 ++++-
39 files changed, 409 insertions(+), 390 deletions(-)
diff --git a/doc/man3/ASN1_TIME_set.pod b/doc/man3/ASN1_TIME_set.pod
index a083ebf..66525f9 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 bf29af6..df37167 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_connect.pod b/doc/man3/BIO_connect.pod
index 454832e..2766c3d 100644
--- a/doc/man3/BIO_connect.pod
+++ b/doc/man3/BIO_connect.pod
@@ -95,19 +95,19 @@ B<INVALID_SOCKET> (-1) on error. When an error has occurred, the
OpenSSL error stack will hold the error data and errno has the system
error.
-=head1 HISTORY
-
-BIO_gethostname(), BIO_get_port(), BIO_get_host_ip(),
-BIO_get_accept_socket() and BIO_accept() were deprecated in
-OpenSSL 1.1.0. Use the functions described above instead.
-
=head1 SEE ALSO
L<BIO_ADDR(3)>
+=head1 HISTORY
+
+BIO_gethostname(), BIO_get_port(), BIO_get_host_ip(),
+BIO_get_accept_socket() and BIO_accept() were deprecated in OpenSSL 1.1.0.
+Use the functions described above instead.
+
=head1 COPYRIGHT
-Copyright 2016-2018 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2016-2019 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
diff --git a/doc/man3/BIO_push.pod b/doc/man3/BIO_push.pod
index ce56db9..480b73c 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 23cdc9b..5419315 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/BN_rand.pod b/doc/man3/BN_rand.pod
index 90b50ff..d57348e 100644
--- a/doc/man3/BN_rand.pod
+++ b/doc/man3/BN_rand.pod
@@ -59,6 +59,15 @@ seeded with enough randomness to ensure an unpredictable byte sequence.
The functions return 1 on success, 0 on error.
The error codes can be obtained by L<ERR_get_error(3)>.
+=head1 SEE ALSO
+
+L<ERR_get_error(3)>,
+L<RAND_add(3)>,
+L<RAND_bytes(3)>,
+L<RAND_priv_bytes(3)>,
+L<RAND(7)>,
+L<RAND_DRBG(7)>
+
=head1 HISTORY
=over 2
@@ -78,18 +87,9 @@ BN_priv_rand() and BN_priv_rand_range() functions were added in OpenSSL 1.1.1.
=back
-=head1 SEE ALSO
-
-L<ERR_get_error(3)>,
-L<RAND_add(3)>,
-L<RAND_bytes(3)>,
-L<RAND_priv_bytes(3)>,
-L<RAND(7)>,
-L<RAND_DRBG(7)>
-
=head1 COPYRIGHT
-Copyright 2000-2018 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2000-2019 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
diff --git a/doc/man3/BN_security_bits.pod b/doc/man3/BN_security_bits.pod
index f6e5857..acf5902 100644
--- a/doc/man3/BN_security_bits.pod
+++ b/doc/man3/BN_security_bits.pod
@@ -31,17 +31,17 @@ Number of security bits.
ECC (Elliptic Curve Cryptography) is not covered by the BN_security_bits()
function. The symmetric algorithms are not covered neither.
-=head1 HISTORY
-
-The BN_security_bits() function was added in OpenSSL 1.1.0.
-
=head1 SEE ALSO
L<DH_security_bits(3)>, L<DSA_security_bits(3)>, L<RSA_security_bits(3)>
+=head1 HISTORY
+
+The BN_security_bits() function was added in OpenSSL 1.1.0.
+
=head1 COPYRIGHT
-Copyright 2017 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2017-2019 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
diff --git a/doc/man3/CONF_modules_load_file.pod b/doc/man3/CONF_modules_load_file.pod
index 485cf79..04fbd60 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/DES_random_key.pod b/doc/man3/DES_random_key.pod
index 6e0394d..bd4bd97 100644
--- a/doc/man3/DES_random_key.pod
+++ b/doc/man3/DES_random_key.pod
@@ -296,6 +296,11 @@ last 4 bytes of the checksum of the input.
DES_fcrypt() returns a pointer to the caller-provided buffer and DES_crypt() -
to a static buffer on success; otherwise they return NULL.
+=head1 SEE ALSO
+
+L<des_modes(7)>,
+L<EVP_EncryptInit(3)>
+
=head1 HISTORY
The requirement that the B<salt> parameter to DES_crypt() and DES_fcrypt()
@@ -304,14 +309,9 @@ OpenSSL 1.1.0. Previous versions tried to use the letter uppercase B<A>
if both character were not present, and could crash when given non-ASCII
on some platforms.
-=head1 SEE ALSO
-
-L<des_modes(7)>,
-L<EVP_EncryptInit(3)>
-
=head1 COPYRIGHT
-Copyright 2000-2018 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2000-2019 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
diff --git a/doc/man3/EVP_PKEY_set1_RSA.pod b/doc/man3/EVP_PKEY_set1_RSA.pod
index 352e068..a4d6721 100644
--- a/doc/man3/EVP_PKEY_set1_RSA.pod
+++ b/doc/man3/EVP_PKEY_set1_RSA.pod
@@ -114,13 +114,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
@@ -141,6 +134,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 cbf889f..2c2e42f 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/PEM_read_bio_PrivateKey.pod b/doc/man3/PEM_read_bio_PrivateKey.pod
index 744a46f..7c381e8 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,20 +395,85 @@ if an error occurred.
The write routines return 1 for success or 0 for failure.
-=head1 HISTORY
+=head1 EXAMPLES
-The old Netscape certificate sequences were no longer documented
-in OpenSSL 1.1.0; applications should use the PKCS7 standard instead
-as they will be formally deprecated in a future releases.
+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 SEE ALSO
L<EVP_EncryptInit(3)>, L<EVP_BytesToKey(3)>,
L<passphrase-encoding(7)>
+=head1 HISTORY
+
+The old Netscape certificate sequences were no longer documented
+in OpenSSL 1.1.0; applications should use the PKCS7 standard instead
+as they will be formally deprecated in a future releases.
+
=head1 COPYRIGHT
-Copyright 2001-2018 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2001-2019 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
diff --git a/doc/man3/RAND_DRBG_generate.pod b/doc/man3/RAND_DRBG_generate.pod
index b39ee93..bee2d6c 100644
--- a/doc/man3/RAND_DRBG_generate.pod
+++ b/doc/man3/RAND_DRBG_generate.pod
@@ -65,10 +65,6 @@ Since the default DRBG implementation does not have access to such an approved
entropy source, a request for prediction resistance will always fail.
In other words, prediction resistance is currently not supported yet by the DRBG.
-=head1 HISTORY
-
-The RAND_DRBG functions were added in OpenSSL 1.1.1.
-
=head1 SEE ALSO
L<RAND_bytes(3)>,
@@ -76,9 +72,13 @@ L<RAND_DRBG_set_reseed_interval(3)>,
L<RAND_DRBG_set_reseed_time_interval(3)>,
L<RAND_DRBG(7)>
+=head1 HISTORY
+
+The RAND_DRBG functions were added in OpenSSL 1.1.1.
+
=head1 COPYRIGHT
-Copyright 2017-2018 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2017-2019 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
diff --git a/doc/man3/RAND_DRBG_get0_master.pod b/doc/man3/RAND_DRBG_get0_master.pod
index c958bf2..55d1eab 100644
--- a/doc/man3/RAND_DRBG_get0_master.pod
+++ b/doc/man3/RAND_DRBG_get0_master.pod
@@ -53,11 +53,6 @@ During initialization, it is possible to change the reseed interval
and reseed time interval.
It is also possible to exchange the reseeding callbacks entirely.
-
-=head1 HISTORY
-
-The RAND_DRBG functions were added in OpenSSL 1.1.1.
-
=head1 SEE ALSO
L<RAND_DRBG_set_callbacks(3)>,
@@ -68,9 +63,13 @@ L<RAND_DRBG_set_callbacks(3)>,
L<RAND_DRBG_generate(3)>,
L<RAND_DRBG(7)>
+=head1 HISTORY
+
+The RAND_DRBG functions were added in OpenSSL 1.1.1.
+
=head1 COPYRIGHT
-Copyright 2017-2018 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2017-2019 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
diff --git a/doc/man3/RAND_DRBG_new.pod b/doc/man3/RAND_DRBG_new.pod
index dcd7a94..5da91be 100644
--- a/doc/man3/RAND_DRBG_new.pod
+++ b/doc/man3/RAND_DRBG_new.pod
@@ -104,10 +104,6 @@ To ensure that they are applied to the global and thread-local DRBG instances
RAND_DRBG_set_defaults() before creating any thread and before calling any
cryptographic routines that obtain random data directly or indirectly.
-=head1 HISTORY
-
-The RAND_DRBG functions were added in OpenSSL 1.1.1.
-
=head1 SEE ALSO
L<OPENSSL_zalloc(3)>,
@@ -115,9 +111,13 @@ L<OPENSSL_secure_zalloc(3)>,
L<RAND_DRBG_generate(3)>,
L<RAND_DRBG(7)>
+=head1 HISTORY
+
+The RAND_DRBG functions were added in OpenSSL 1.1.1.
+
=head1 COPYRIGHT
-Copyright 2017-2018 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2017-2019 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
diff --git a/doc/man3/RAND_DRBG_reseed.pod b/doc/man3/RAND_DRBG_reseed.pod
index a0a4e56..3610c13 100644
--- a/doc/man3/RAND_DRBG_reseed.pod
+++ b/doc/man3/RAND_DRBG_reseed.pod
@@ -93,10 +93,6 @@ To ensure that they are applied to the global and thread-local DRBG instances
RAND_DRBG_set_reseed_defaults() before creating any thread and before calling any
cryptographic routines that obtain random data directly or indirectly.
-=head1 HISTORY
-
-The RAND_DRBG functions were added in OpenSSL 1.1.1.
-
=head1 SEE ALSO
L<RAND_DRBG_generate(3)>,
@@ -104,9 +100,13 @@ L<RAND_DRBG_bytes(3)>,
L<RAND_DRBG_set_callbacks(3)>.
L<RAND_DRBG(7)>
+=head1 HISTORY
+
+The RAND_DRBG functions were added in OpenSSL 1.1.1.
+
=head1 COPYRIGHT
-Copyright 2017-2018 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2017-2019 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
diff --git a/doc/man3/RAND_DRBG_set_callbacks.pod b/doc/man3/RAND_DRBG_set_callbacks.pod
index a927d6a..3da051e 100644
--- a/doc/man3/RAND_DRBG_set_callbacks.pod
+++ b/doc/man3/RAND_DRBG_set_callbacks.pod
@@ -124,20 +124,19 @@ In this case the DRBG will automatically request an extra amount of entropy
utilize for the nonce, following the recommendations of [NIST SP 800-90A Rev. 1],
section 8.6.7.
-
-=head1 HISTORY
-
-The RAND_DRBG functions were added in OpenSSL 1.1.1.
-
=head1 SEE ALSO
L<RAND_DRBG_new(3)>,
L<RAND_DRBG_reseed(3)>,
L<RAND_DRBG(7)>
+=head1 HISTORY
+
+The RAND_DRBG functions were added in OpenSSL 1.1.1.
+
=head1 COPYRIGHT
-Copyright 2017-2018 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2017-2019 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
diff --git a/doc/man3/RAND_add.pod b/doc/man3/RAND_add.pod
index b6753fd..4ba6ff9 100644
--- a/doc/man3/RAND_add.pod
+++ b/doc/man3/RAND_add.pod
@@ -80,11 +80,6 @@ RAND_event() returns RAND_status().
The other functions do not return values.
-=head1 HISTORY
-
-RAND_event() and RAND_screen() were deprecated in OpenSSL 1.1.0 and should
-not be used.
-
=head1 SEE ALSO
L<RAND_bytes(3)>,
@@ -92,9 +87,14 @@ L<RAND_egd(3)>,
L<RAND_load_file(3)>,
L<RAND(7)>
+=head1 HISTORY
+
+RAND_event() and RAND_screen() were deprecated in OpenSSL 1.1.0 and should
+not be used.
+
=head1 COPYRIGHT
-Copyright 2000-2018 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2000-2019 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
diff --git a/doc/man3/RAND_bytes.pod b/doc/man3/RAND_bytes.pod
index f257e05..e2265d1 100644
--- a/doc/man3/RAND_bytes.pod
+++ b/doc/man3/RAND_bytes.pod
@@ -43,6 +43,15 @@ return 1 on success, -1 if not supported by the current
RAND method, or 0 on other failure. The error code can be
obtained by L<ERR_get_error(3)>.
+=head1 SEE ALSO
+
+L<RAND_add(3)>,
+L<RAND_bytes(3)>,
+L<RAND_priv_bytes(3)>,
+L<ERR_get_error(3)>,
+L<RAND(7)>,
+L<RAND_DRBG(7)>
+
=head1 HISTORY
=over 2
@@ -57,18 +66,9 @@ The RAND_priv_bytes() function was added in OpenSSL 1.1.1.
=back
-=head1 SEE ALSO
-
-L<RAND_add(3)>,
-L<RAND_bytes(3)>,
-L<RAND_priv_bytes(3)>,
-L<ERR_get_error(3)>,
-L<RAND(7)>,
-L<RAND_DRBG(7)>
-
=head1 COPYRIGHT
-Copyright 2000-2018 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2000-2019 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
diff --git a/doc/man3/RAND_cleanup.pod b/doc/man3/RAND_cleanup.pod
index 3859ce3..e518753 100644
--- a/doc/man3/RAND_cleanup.pod
+++ b/doc/man3/RAND_cleanup.pod
@@ -23,18 +23,18 @@ L<OPENSSL_init_crypto(3)>.
RAND_cleanup() returns no value.
+=head1 SEE ALSO
+
+L<RAND(7)>
+
=head1 HISTORY
RAND_cleanup() was deprecated in OpenSSL 1.1.0; do not use it.
See L<OPENSSL_init_crypto(3)>
-=head1 SEE ALSO
-
-L<RAND(7)>
-
=head1 COPYRIGHT
-Copyright 2000-2018 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2000-2019 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
diff --git a/doc/man3/SSL_CIPHER_get_name.pod b/doc/man3/SSL_CIPHER_get_name.pod
index 8800bbd..26edae3 100644
--- a/doc/man3/SSL_CIPHER_get_name.pod
+++ b/doc/man3/SSL_CIPHER_get_name.pod
@@ -180,6 +180,11 @@ SSL_CIPHER_get_id() returns a 4-byte integer representing the OpenSSL-specific I
SSL_CIPHER_get_protocol_id() returns a 2-byte integer representing the TLS
protocol-specific ID.
+=head1 SEE ALSO
+
+L<ssl(7)>, L<SSL_get_current_cipher(3)>,
+L<SSL_get_ciphers(3)>, L<ciphers(1)>
+
=head1 HISTORY
The SSL_CIPHER_get_version() function was updated to always return the
@@ -196,14 +201,9 @@ required to enable this function.
The OPENSSL_cipher_name() function was added in OpenSSL 1.1.1.
-=head1 SEE ALSO
-
-L<ssl(7)>, L<SSL_get_current_cipher(3)>,
-L<SSL_get_ciphers(3)>, L<ciphers(1)>
-
=head1 COPYRIGHT
-Copyright 2000-2018 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2000-2019 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
diff --git a/doc/man3/SSL_CONF_cmd.pod b/doc/man3/SSL_CONF_cmd.pod
index a74e728..7f2449e 100644
--- a/doc/man3/SSL_CONF_cmd.pod
+++ b/doc/man3/SSL_CONF_cmd.pod
@@ -594,6 +594,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:
@@ -640,23 +657,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 a96aafe..e2637d2 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_new.pod b/doc/man3/SSL_CTX_new.pod
index d078341..df25a6f 100644
--- a/doc/man3/SSL_CTX_new.pod
+++ b/doc/man3/SSL_CTX_new.pod
@@ -190,6 +190,11 @@ SSL_CTX_up_ref() returns 1 for success and 0 for failure.
=back
+=head1 SEE ALSO
+
+L<SSL_CTX_set_options(3)>, L<SSL_CTX_free(3)>, L<SSL_accept(3)>,
+L<SSL_CTX_set_min_proto_version(3)>, L<ssl(7)>, L<SSL_set_connect_state(3)>
+
=head1 HISTORY
Support for SSLv2 and the corresponding SSLv2_method(),
@@ -198,18 +203,13 @@ removed in OpenSSL 1.1.0.
SSLv23_method(), SSLv23_server_method() and SSLv23_client_method()
were deprecated and the preferred TLS_method(), TLS_server_method()
-and TLS_client_method() functions were introduced in OpenSSL 1.1.0.
+and TLS_client_method() functions were added in OpenSSL 1.1.0.
All version-specific methods were deprecated in OpenSSL 1.1.0.
-=head1 SEE ALSO
-
-L<SSL_CTX_set_options(3)>, L<SSL_CTX_free(3)>, L<SSL_accept(3)>,
-L<SSL_CTX_set_min_proto_version(3)>, L<ssl(7)>, L<SSL_set_connect_state(3)>
-
=head1 COPYRIGHT
-Copyright 2000-2018 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2000-2019 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
diff --git a/doc/man3/SSL_CTX_set1_sigalgs.pod b/doc/man3/SSL_CTX_set1_sigalgs.pod
index 93d5320..335ad33 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_default_passwd_cb.pod b/doc/man3/SSL_CTX_set_default_passwd_cb.pod
index 999a70c..991ce7a 100644
--- a/doc/man3/SSL_CTX_set_default_passwd_cb.pod
+++ b/doc/man3/SSL_CTX_set_default_passwd_cb.pod
@@ -90,20 +90,20 @@ truncated.
return strlen(buf);
}
+=head1 SEE ALSO
+
+L<ssl(7)>,
+L<SSL_CTX_use_certificate(3)>
+
=head1 HISTORY
SSL_CTX_get_default_passwd_cb(), SSL_CTX_get_default_passwd_cb_userdata(),
SSL_set_default_passwd_cb() and SSL_set_default_passwd_cb_userdata() were
added in OpenSSL 1.1.0.
-=head1 SEE ALSO
-
-L<ssl(7)>,
-L<SSL_CTX_use_certificate(3)>
-
=head1 COPYRIGHT
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2000-2019 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
diff --git a/doc/man3/SSL_CTX_set_generate_session_id.pod b/doc/man3/SSL_CTX_set_generate_session_id.pod
index 2bee351..9242af6 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_min_proto_version.pod b/doc/man3/SSL_CTX_set_min_proto_version.pod
index 4586658..7dfbfec 100644
--- a/doc/man3/SSL_CTX_set_min_proto_version.pod
+++ b/doc/man3/SSL_CTX_set_min_proto_version.pod
@@ -52,18 +52,18 @@ lowest or highest protocol, respectively.
All these functions are implemented using macros.
+=head1 SEE ALSO
+
+L<SSL_CTX_set_options(3)>, L<SSL_CONF_cmd(3)>
+
=head1 HISTORY
The setter functions were added in OpenSSL 1.1.0. The getter functions
were added in OpenSSL 1.1.1.
-=head1 SEE ALSO
-
-L<SSL_CTX_set_options(3)>, L<SSL_CONF_cmd(3)>
-
=head1 COPYRIGHT
-Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2016-2019 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
diff --git a/doc/man3/SSL_CTX_set_split_send_fragment.pod b/doc/man3/SSL_CTX_set_split_send_fragment.pod
index 877b4ae..d63ca41 100644
--- a/doc/man3/SSL_CTX_set_split_send_fragment.pod
+++ b/doc/man3/SSL_CTX_set_split_send_fragment.pod
@@ -162,6 +162,10 @@ SSL_set_default_read_buffer_len(), SSL_CTX_set_tlsext_max_fragment_length(),
SSL_set_tlsext_max_fragment_length() and SSL_SESSION_get_max_fragment_length()
all these functions are implemented using macros.
+=head1 SEE ALSO
+
+L<SSL_CTX_set_read_ahead(3)>, L<SSL_pending(3)>
+
=head1 HISTORY
The SSL_CTX_set_max_pipelines(), SSL_set_max_pipelines(),
@@ -172,13 +176,9 @@ functions were added in OpenSSL 1.1.0.
The SSL_CTX_set_tlsext_max_fragment_length(), SSL_set_tlsext_max_fragment_length()
and SSL_SESSION_get_max_fragment_length() functions were added in OpenSSL 1.1.1.
-=head1 SEE ALSO
-
-L<SSL_CTX_set_read_ahead(3)>, L<SSL_pending(3)>
-
=head1 COPYRIGHT
-Copyright 2016-2017 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2016-2019 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
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 7a4bb34..9ef0bff 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 a2ac1c0..521d8b4 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 412b1a0..4372f9f 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/SSL_read.pod b/doc/man3/SSL_read.pod
index 1410a02..4da7ad1 100644
--- a/doc/man3/SSL_read.pod
+++ b/doc/man3/SSL_read.pod
@@ -126,10 +126,6 @@ You should instead call SSL_get_error() to find out if it's retryable.
=back
-=head1 HISTORY
-
-The SSL_read_ex() and SSL_peek_ex() functions were added in OpenSSL 1.1.1.
-
=head1 SEE ALSO
L<SSL_get_error(3)>, L<SSL_write_ex(3)>,
@@ -140,9 +136,13 @@ L<SSL_pending(3)>,
L<SSL_shutdown(3)>, L<SSL_set_shutdown(3)>,
L<ssl(7)>, L<bio(7)>
+=head1 HISTORY
+
+The SSL_read_ex() and SSL_peek_ex() functions were added in OpenSSL 1.1.1.
+
=head1 COPYRIGHT
-Copyright 2000-2018 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2000-2019 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
diff --git a/doc/man3/SSL_write.pod b/doc/man3/SSL_write.pod
index 3956f1d..84eb948 100644
--- a/doc/man3/SSL_write.pod
+++ b/doc/man3/SSL_write.pod
@@ -104,10 +104,6 @@ You should instead call SSL_get_error() to find out if it's retryable.
=back
-=head1 HISTORY
-
-The SSL_write_ex() function was added in OpenSSL 1.1.1.
-
=head1 SEE ALSO
L<SSL_get_error(3)>, L<SSL_read_ex(3)>, L<SSL_read(3)>
@@ -116,9 +112,13 @@ L<SSL_connect(3)>, L<SSL_accept(3)>
L<SSL_set_connect_state(3)>,
L<ssl(7)>, L<bio(7)>
+=head1 HISTORY
+
+The SSL_write_ex() function was added in OpenSSL 1.1.1.
+
=head1 COPYRIGHT
-Copyright 2000-2018 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2000-2019 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
diff --git a/doc/man3/X509_NAME_add_entry_by_txt.pod b/doc/man3/X509_NAME_add_entry_by_txt.pod
index b48f090..f6f61aa 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 5621806..0012276 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/X509_get_subject_name.pod b/doc/man3/X509_get_subject_name.pod
index 7c4a499..807f9d3 100644
--- a/doc/man3/X509_get_subject_name.pod
+++ b/doc/man3/X509_get_subject_name.pod
@@ -48,14 +48,6 @@ and X509_CRL_get_issuer() return an B<X509_NAME> pointer.
X509_set_subject_name(), X509_set_issuer_name(), X509_REQ_set_subject_name()
and X509_CRL_set_issuer_name() return 1 for success and 0 for failure.
-=head1 HISTORY
-
-X509_REQ_get_subject_name() is a function in OpenSSL 1.1.0 and a macro in
-earlier versions.
-
-X509_CRL_get_issuer() is a function in OpenSSL 1.1.0. It was previously
-added in OpenSSL 1.0.0 as a macro.
-
=head1 SEE ALSO
L<d2i_X509(3)>,
@@ -74,9 +66,17 @@ L<X509_sign(3)>,
L<X509V3_get_d2i(3)>,
L<X509_verify_cert(3)>
+=head1 HISTORY
+
+X509_REQ_get_subject_name() is a function in OpenSSL 1.1.0 and a macro in
+earlier versions.
+
+X509_CRL_get_issuer() is a function in OpenSSL 1.1.0. It was previously
+added in OpenSSL 1.0.0 as a macro.
+
=head1 COPYRIGHT
-Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2015-2019 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
diff --git a/doc/man3/d2i_X509.pod b/doc/man3/d2i_X509.pod
index 71985a4..04688a1 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 860bb99..7340782 100755
--- a/util/find-doc-nits
+++ b/util/find-doc-nits
@@ -1,5 +1,5 @@
#! /usr/bin/env perl
-# Copyright 2002-2018 The OpenSSL Project Authors. All Rights Reserved.
+# Copyright 2002-2019 The OpenSSL Project Authors. All Rights Reserved.
#
# Licensed under the OpenSSL license (the "License"). You may not use
# this file except in compliance with the License. You can obtain a copy
@@ -137,6 +137,20 @@ sub name_synopsis()
}
}
+# Check if SECTION is located before BEFORE
+sub check_section_location()
+{
+ my $filename = shift;
+ my $contents = shift;
+ my $section = shift;
+ my $before = shift;
+
+ return unless $contents =~ /=head1 $section/
+ and $contents =~ /=head1 $before/;
+ print "$filename: $section should be placed before $before section\n"
+ if $contents =~ /=head1 $before.*=head1 $section/ms;
+}
+
sub check()
{
my $filename = shift;
@@ -150,6 +164,13 @@ sub check()
close POD;
}
+ # Check if EXAMPLES is located after RETURN VALUES section.
+ &check_section_location($filename, $contents, "RETURN VALUES", "EXAMPLES") if $filename =~ m|man3/|;
+ # Check if HISTORY is located after SEE ALSO
+ &check_section_location($filename, $contents, "SEE ALSO", "HISTORY") if $filename =~ m|man3/|;
+ # Check if SEE ALSO is located after EXAMPLES
+ &check_section_location($filename, $contents, "EXAMPLES", "SEE ALSO") if $filename =~ m|man3/|;
+
my $id = "${filename}:1:";
&name_synopsis($id, $filename, $contents)
More information about the openssl-commits
mailing list