[openssl-commits] [openssl] master update
Rich Salz
rsalz at openssl.org
Mon Jul 3 14:40:37 UTC 2017
The branch master has been updated
via a95d7574dbcd91c734c1542a423e1cac34dc18b5 (commit)
from b43c37658600300de485100185eebec8bfa3dbcf (commit)
- Log -----------------------------------------------------------------
commit a95d7574dbcd91c734c1542a423e1cac34dc18b5
Author: Rich Salz <rsalz at openssl.org>
Date: Sun Jul 2 12:16:38 2017 -0400
Various doc fixes
Fix a =head1 section name
Fix a typo in POD label
Remove a spurious =back
Add a missing blank line
Avoid 'legacy' -- use 'deprecated' if still needed if we cannot just reword.
Always do strict checking
Do not warn about missing "RETURN VALUES" unless -s is set.
Change OpenSSL version 1.1 -> 1.1.0
Reviewed-by: Matt Caswell <matt at openssl.org>
(Merged from https://github.com/openssl/openssl/pull/3830)
-----------------------------------------------------------------------
Summary of changes:
doc/man1/ca.pod | 5 ++-
doc/man1/enc.pod | 2 +-
doc/man1/storeutl.pod | 2 +-
doc/man3/ASN1_STRING_print_ex.pod | 3 +-
doc/man3/BIO_connect.pod | 4 +--
doc/man3/CRYPTO_get_ex_new_index.pod | 3 +-
doc/man3/EVP_CIPHER_meth_new.pod | 4 +--
doc/man3/EVP_DigestInit.pod | 10 +++---
doc/man3/OPENSSL_LH_stats.pod | 4 +--
doc/man3/PEM_read_bio_PrivateKey.pod | 7 +++--
doc/man3/RAND_bytes.pod | 2 +-
doc/man3/SSL_CTX_set0_CA_list.pod | 2 --
doc/man3/SSL_set_bio.pod | 54 ++++++++++++++++++--------------
doc/man3/X509_NAME_get_index_by_NID.pod | 5 +--
doc/man3/X509_NAME_print_ex.pod | 7 +++--
doc/man3/X509_VERIFY_PARAM_set_flags.pod | 7 +++--
doc/man7/ossl_store.pod | 1 +
util/find-doc-nits | 32 +++++++++----------
18 files changed, 76 insertions(+), 78 deletions(-)
diff --git a/doc/man1/ca.pod b/doc/man1/ca.pod
index f2c003b..26d648e 100644
--- a/doc/man1/ca.pod
+++ b/doc/man1/ca.pod
@@ -188,11 +188,10 @@ for more information.
=item B<-msie_hack>
-This is a legacy option to make B<ca> work with very old versions of
+This is a deprecated option to make B<ca> work with very old versions of
the IE certificate enrollment control "certenr3". It used UniversalStrings
for almost everything. Since the old control has various security bugs
-its use is strongly discouraged. The newer control "Xenroll" does not
-need this option.
+its use is strongly discouraged.
=item B<-preserveDN>
diff --git a/doc/man1/enc.pod b/doc/man1/enc.pod
index 5691785..13f1272 100644
--- a/doc/man1/enc.pod
+++ b/doc/man1/enc.pod
@@ -349,7 +349,7 @@ certain parameters. So if, for example, you want to use RC2 with a
=head1 HISTORY
-The default digest was changed from MD5 to SHA256 in Openssl 1.1.
+The default digest was changed from MD5 to SHA256 in Openssl 1.1.0.
=head1 COPYRIGHT
diff --git a/doc/man1/storeutl.pod b/doc/man1/storeutl.pod
index 8874f34..2792a55 100644
--- a/doc/man1/storeutl.pod
+++ b/doc/man1/storeutl.pod
@@ -20,7 +20,7 @@ B<uri> ...
The B<storeutl> command can be used to display the contents (after decryption
as the case may be) fetched from the given URIs.
-=head1 COMMAND OPTIONS
+=head1 OPTIONS
=over 4
diff --git a/doc/man3/ASN1_STRING_print_ex.pod b/doc/man3/ASN1_STRING_print_ex.pod
index a521f78..401de9b 100644
--- a/doc/man3/ASN1_STRING_print_ex.pod
+++ b/doc/man3/ASN1_STRING_print_ex.pod
@@ -32,7 +32,8 @@ ASN1_tag2str() returns a human-readable name of the specified ASN.1 B<tag>.
=head1 NOTES
-ASN1_STRING_print() is a legacy function which should be avoided in new applications.
+ASN1_STRING_print() is a deprecated function which should be avoided; use
+ASN1_STRING_print_ex() instead.
Although there are a large number of options frequently B<ASN1_STRFLGS_RFC2253> is
suitable, or on UTF8 terminals B<ASN1_STRFLGS_RFC2253 & ~ASN1_STRFLGS_ESC_MSB>.
diff --git a/doc/man3/BIO_connect.pod b/doc/man3/BIO_connect.pod
index bb1047a..91dcab1 100644
--- a/doc/man3/BIO_connect.pod
+++ b/doc/man3/BIO_connect.pod
@@ -93,8 +93,8 @@ error.
=head1 HISTORY
BIO_gethostname(), BIO_get_port(), BIO_get_host_ip(),
-BIO_get_accept_socket() and BIO_accept() are deprecated since OpenSSL
-1.1. Use the functions described above instead.
+BIO_get_accept_socket() and BIO_accept() were deprecated in
+OpenSSL 1.1.0. Use the functions described above instead.
=head1 SEE ALSO
diff --git a/doc/man3/CRYPTO_get_ex_new_index.pod b/doc/man3/CRYPTO_get_ex_new_index.pod
index 8251dda..1a4ad52 100644
--- a/doc/man3/CRYPTO_get_ex_new_index.pod
+++ b/doc/man3/CRYPTO_get_ex_new_index.pod
@@ -143,8 +143,7 @@ will fail.
=head1 RETURN VALUES
-CRYPTO_get_ex_new_index() returns a new index or -1 on failure; the
-value B<0> is reserved for the legacy "app_data" API's.
+CRYPTO_get_ex_new_index() returns a new index or -1 on failure.
CRYPTO_free_ex_index() and
CRYPTO_set_ex_data() return 1 on success or 0 on failure.
diff --git a/doc/man3/EVP_CIPHER_meth_new.pod b/doc/man3/EVP_CIPHER_meth_new.pod
index f8478e3..e1583c5 100644
--- a/doc/man3/EVP_CIPHER_meth_new.pod
+++ b/doc/man3/EVP_CIPHER_meth_new.pod
@@ -222,9 +222,7 @@ L<EVP_EncryptInit>
=head1 HISTORY
-The B<EVP_CIPHER> structure was openly available in OpenSSL before version
-1.1.
-The functions described here were added in OpenSSL version 1.1.
+The functions described here were added in OpenSSL version 1.1.0.
=head1 COPYRIGHT
diff --git a/doc/man3/EVP_DigestInit.pod b/doc/man3/EVP_DigestInit.pod
index d0bb337..933ffb2 100644
--- a/doc/man3/EVP_DigestInit.pod
+++ b/doc/man3/EVP_DigestInit.pod
@@ -241,15 +241,13 @@ L<evp(7)>
=head1 HISTORY
-B<EVP_MD_CTX> became opaque in OpenSSL 1.1. Consequently, stack
-allocated B<EVP_MD_CTX>s are no longer supported.
-
EVP_MD_CTX_create() and EVP_MD_CTX_destroy() were renamed to
-EVP_MD_CTX_new() and EVP_MD_CTX_free() in OpenSSL 1.1.
+EVP_MD_CTX_new() and EVP_MD_CTX_free() in OpenSSL 1.1.0.
The link between digests and signing algorithms was fixed in OpenSSL 1.0 and
-later, so now EVP_sha1() can be used with RSA and DSA. The legacy EVP_dss1()
-was removed in OpenSSL 1.1.0
+later, so now EVP_sha1() can be used with RSA and DSA.
+
+EVP_dss1() was removed in OpenSSL 1.1.0
=head1 COPYRIGHT
diff --git a/doc/man3/OPENSSL_LH_stats.pod b/doc/man3/OPENSSL_LH_stats.pod
index f7118ff..49351f4 100644
--- a/doc/man3/OPENSSL_LH_stats.pod
+++ b/doc/man3/OPENSSL_LH_stats.pod
@@ -21,9 +21,7 @@ OPENSSL_LH_node_stats_bio, OPENSSL_LH_node_usage_stats_bio - LHASH statistics
=head1 DESCRIPTION
The B<LHASH> structure records statistics about most aspects of
-accessing the hash table. This is mostly a legacy of Eric Young
-writing this library for the reasons of implementing what looked like
-a nice algorithm rather than for a particular software product.
+accessing the hash table.
OPENSSL_LH_stats() prints out statistics on the size of the hash table, how
many entries are in it, and the number and result of calls to the
diff --git a/doc/man3/PEM_read_bio_PrivateKey.pod b/doc/man3/PEM_read_bio_PrivateKey.pod
index 5fb14e9..b2130c8 100644
--- a/doc/man3/PEM_read_bio_PrivateKey.pod
+++ b/doc/man3/PEM_read_bio_PrivateKey.pod
@@ -170,8 +170,9 @@ EVP_PKEY structure. The write routines use PKCS#8 private key format and are
equivalent to PEM_write_bio_PKCS8PrivateKey().The read functions transparently
handle traditional and PKCS#8 format encrypted and unencrypted keys.
-PEM_write_bio_PrivateKey_traditional() writes out a private key in legacy
-"traditional" format.
+PEM_write_bio_PrivateKey_traditional() writes out a private key in the
+"traditional" format with a simple private key marker and should only
+be used for compatibility with legacy programs.
PEM_write_bio_PKCS8PrivateKey() and PEM_write_PKCS8PrivateKey() write a private
key in an EVP_PKEY structure in PKCS#8 EncryptedPrivateKeyInfo format using
@@ -459,7 +460,7 @@ The write routines return 1 for success or 0 for failure.
=head1 HISTORY
The old Netscape certificate sequences were no longer documented
-in OpenSSL 1.1; applications should use the PKCS7 standard instead
+in OpenSSL 1.1.0; applications should use the PKCS7 standard instead
as they will be formally deprecated in a future releases.
=head1 SEE ALSO
diff --git a/doc/man3/RAND_bytes.pod b/doc/man3/RAND_bytes.pod
index 9c2f9e1..ffddf81 100644
--- a/doc/man3/RAND_bytes.pod
+++ b/doc/man3/RAND_bytes.pod
@@ -30,7 +30,7 @@ RAND_bytes() returns 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)>.
-=head HISTORY
+=head1 HISTORY
RAND_pseudo_bytes() was deprecated in OpenSSL 1.1.0.
diff --git a/doc/man3/SSL_CTX_set0_CA_list.pod b/doc/man3/SSL_CTX_set0_CA_list.pod
index 5e94f5c..0f8b7da 100644
--- a/doc/man3/SSL_CTX_set0_CA_list.pod
+++ b/doc/man3/SSL_CTX_set0_CA_list.pod
@@ -72,8 +72,6 @@ for failure.
SSL_get0_peer_CA_list() returns a stack of CA names sent by the peer or
B<NULL> or an empty stack if no list was sent.
-=back
-
=head1 SEE ALSO
L<ssl(7)>,
diff --git a/doc/man3/SSL_set_bio.pod b/doc/man3/SSL_set_bio.pod
index 4230940..0161752 100644
--- a/doc/man3/SSL_set_bio.pod
+++ b/doc/man3/SSL_set_bio.pod
@@ -30,58 +30,64 @@ ownership of one reference. Therefore it may be necessary to increment the
number of references available using L<BIO_up_ref(3)> before calling the set0
functions.
-SSL_set_bio() does a similar job as SSL_set0_rbio() and SSL_set0_wbio() except
-that it connects both the B<rbio> and the B<wbio> at the same time. This
-function transfers the ownership of B<rbio> and B<wbio> to B<ssl> except that
-the rules for this are much more complex. For this reason this function is
-considered a legacy function and SSL_set0_rbio() and SSL_set0_wbio() should be
-used in preference. The ownership rules are as follows:
+SSL_set_bio() is similar to SSL_set0_rbio() and SSL_set0_wbio() except
+that it connects both the B<rbio> and the B<wbio> at the same time, and
+transfers the ownership of B<rbio> and B<wbio> to B<ssl> according to
+the following set of rules:
=over 2
=item *
-If neither the rbio or wbio have changed from their previous values then nothing
-is done.
+If neither the B<rbio> or B<wbio> have changed from their previous values
+then nothing is done.
=item *
-If the rbio and wbio parameters are different and both are different to their
+If the B<rbio> and B<wbio> parameters are different and both are different
+to their
previously set values then one reference is consumed for the rbio and one
reference is consumed for the wbio.
=item *
-If the rbio and wbio parameters are the same and the rbio is not the same as the
-previously set value then one reference is consumed.
+If the B<rbio> and B<wbio> parameters are the same and the B<rbio> is not
+the same as the previously set value then one reference is consumed.
=item *
-If the rbio and wbio parameters are the same and the rbio is the same as the
-previously set value, then no additional references are consumed.
+If the B<rbio> and B<wbio> parameters are the same and the B<rbio> is the
+same as the previously set value, then no additional references are consumed.
=item *
-If the rbio and wbio parameters are different and the rbio is the same as the
-previously set value then one reference is consumed for the wbio and no
-references are consumed for the rbio.
+If the B<rbio> and B<wbio> parameters are different and the B<rbio> is the
+same as the
+previously set value then one reference is consumed for the B<wbio> and no
+references are consumed for the B<rbio>.
=item *
-If the rbio and wbio parameters are different and the wbio is the same as the
-previously set value and the old rbio and wbio values were the same as each
-other then one reference is consumed for the rbio and no references are consumed
-for the wbio.
+If the B<rbio> and B<wbio> parameters are different and the B<wbio> is the
+same as the previously set value and the old B<rbio> and B<wbio> values
+were the same as each other then one reference is consumed for the B<rbio>
+and no references are consumed for the B<wbio>.
=item *
-If the rbio and wbio parameters are different and the wbio is the same as the
-previously set value and the old rbio and wbio values were different to each
-other then one reference is consumed for the rbio and one reference is consumed
-for the wbio.
+If the B<rbio> and B<wbio> parameters are different and the B<wbio>
+is the same as the
+previously set value and the old B<rbio> and B<wbio> values were different
+to each
+other then one reference is consumed for the B<rbio> and one reference
+is consumed
+for the B<wbio>.
=back
+Because of this complexity, this function should be avoided;
+use SSL_set0_rbio() and SSL_set0_wbio() instead.
+
=head1 RETURN VALUES
SSL_set_bio(), SSL_set_rbio() and SSL_set_wbio() cannot fail.
diff --git a/doc/man3/X509_NAME_get_index_by_NID.pod b/doc/man3/X509_NAME_get_index_by_NID.pod
index be68b26..5579dab 100644
--- a/doc/man3/X509_NAME_get_index_by_NID.pod
+++ b/doc/man3/X509_NAME_get_index_by_NID.pod
@@ -48,8 +48,9 @@ of space needed in B<buf> (excluding the final null) is returned.
=head1 NOTES
-X509_NAME_get_text_by_NID() and X509_NAME_get_text_by_OBJ() are
-legacy functions which have various limitations which make them
+X509_NAME_get_text_by_NID() and X509_NAME_get_text_by_OBJ() should be
+considered deprecaated because they
+have various limitations which make them
of minimal use in practice. They can only find the first matching
entry and will copy the contents of the field verbatim: this can
be highly confusing if the target is a multicharacter string type
diff --git a/doc/man3/X509_NAME_print_ex.pod b/doc/man3/X509_NAME_print_ex.pod
index e59512d..ad5009e 100644
--- a/doc/man3/X509_NAME_print_ex.pod
+++ b/doc/man3/X509_NAME_print_ex.pod
@@ -35,10 +35,11 @@ characters. Multiple lines are used if the output (including indent) exceeds
=head1 NOTES
-The functions X509_NAME_oneline() and X509_NAME_print() are legacy functions which
+The functions X509_NAME_oneline() and X509_NAME_print()
produce a non standard output form, they don't handle multi character fields and
-have various quirks and inconsistencies. Their use is strongly discouraged in new
-applications.
+have various quirks and inconsistencies.
+Their use is strongly discouraged in new applications and they could
+be deprecated in a future release.
Although there are a large number of possible flags for most purposes
B<XN_FLAG_ONELINE>, B<XN_FLAG_MULTILINE> or B<XN_FLAG_RFC2253> will suffice.
diff --git a/doc/man3/X509_VERIFY_PARAM_set_flags.pod b/doc/man3/X509_VERIFY_PARAM_set_flags.pod
index e8428e1..a4e3061 100644
--- a/doc/man3/X509_VERIFY_PARAM_set_flags.pod
+++ b/doc/man3/X509_VERIFY_PARAM_set_flags.pod
@@ -292,8 +292,9 @@ of ORed.
=head1 NOTES
The above functions should be used to manipulate verification parameters
-instead of legacy functions which work in specific structures such as
-X509_STORE_CTX_set_flags().
+instead of functions which work in specific structures such as
+X509_STORE_CTX_set_flags() which are likely to be deprecated in a future
+release.
=head1 BUGS
@@ -327,7 +328,7 @@ L<X509_check_ip(3)>
=head1 HISTORY
The B<X509_V_FLAG_NO_ALT_CHAINS> flag was added in OpenSSL 1.1.0
-The legacy B<X509_V_FLAG_CB_ISSUER_CHECK> flag is deprecated as of
+The flag B<X509_V_FLAG_CB_ISSUER_CHECK> was deprecated in
OpenSSL 1.1.0, and has no effect.
=head1 COPYRIGHT
diff --git a/doc/man7/ossl_store.pod b/doc/man7/ossl_store.pod
index b4b76dd..59cfc7c 100644
--- a/doc/man7/ossl_store.pod
+++ b/doc/man7/ossl_store.pod
@@ -89,6 +89,7 @@ only).
OSSL_STORE_close(ctx);
=head1 SEE ALSO
+
L<OSSL_STORE_open(3)>, L<OSSL_STORE_INFO(3)>, L<OSSL_STORE_LOADER(3)>
=head1 COPYRIGHT
diff --git a/util/find-doc-nits b/util/find-doc-nits
index 8f6d482..bdc1ba2 100755
--- a/util/find-doc-nits
+++ b/util/find-doc-nits
@@ -174,17 +174,14 @@ sub check()
print "$id Bad =over $1\n"
if $contents =~ /=over([^ ][^24])/;
- # Look for multiple consecutive openssl #include lines.
- # Consecutive because of files like md5.pod. Sometimes it's okay
- # or necessary, as in ssl/SSL_set1_host.pod
if ( $contents !~ /=for comment multiple includes/ ) {
+ # Look for multiple consecutive openssl #include lines
+ # (non-consecutive lines are okay; see man3/MD5.pod).
if ( $contents =~ /=head1 SYNOPSIS(.*)=head1 DESCRIPTION/ms ) {
my $count = 0;
foreach my $line ( split /\n+/, $1 ) {
if ( $line =~ m at include <openssl/@ ) {
- if ( ++$count == 2 ) {
- print "$id has multiple includes\n";
- }
+ print "$id has multiple includes\n" if ++$count == 2;
} else {
$count = 0;
}
@@ -192,18 +189,6 @@ sub check()
}
}
- return unless $opt_s;
-
- # Find what section this page is in. If run from "." assume
- # section 3.
- my $section = 3;
- $section = $1 if $dirname =~ /man([1-9])/;
-
- foreach ((@{$mandatory_sections{'*'}}, @{$mandatory_sections{$section}})) {
- print "$id: missing $_ head1 section\n"
- if $contents !~ /^=head1\s+${_}\s*$/m;
- }
-
open my $OUT, '>', $temp
or die "Can't open $temp, $!";
podchecker($filename, $OUT);
@@ -216,6 +201,17 @@ sub check()
}
close $OUT;
unlink $temp || warn "Can't remove $temp, $!";
+
+ # Find what section this page is in; assume 3.
+ my $section = 3;
+ $section = $1 if $dirname =~ /man([1-9])/;
+
+ foreach ((@{$mandatory_sections{'*'}}, @{$mandatory_sections{$section}})) {
+ # Skip "return values" if not -s
+ next if $_ eq 'RETURN VALUES' and not $opt_s;
+ print "$id: missing $_ head1 section\n"
+ if $contents !~ /^=head1\s+${_}\s*$/m;
+ }
}
my %dups;
More information about the openssl-commits
mailing list