From a95d7574dbcd91c734c1542a423e1cac34dc18b5 Mon Sep 17 00:00:00 2001 From: Rich Salz Date: Sun, 2 Jul 2017 12:16:38 -0400 Subject: [PATCH] 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 (Merged from https://github.com/openssl/openssl/pull/3830) --- 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 f2c003b880..26d648e924 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 work with very old versions of +This is a deprecated option to make B 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 5691785cd5..13f1272d81 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 8874f34967..2792a554fa 100644 --- a/doc/man1/storeutl.pod +++ b/doc/man1/storeutl.pod @@ -20,7 +20,7 @@ B ... The B 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 a521f78ea9..401de9b5d6 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. =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 is suitable, or on UTF8 terminals B. diff --git a/doc/man3/BIO_connect.pod b/doc/man3/BIO_connect.pod index bb1047a347..91dcab1178 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 8251dda94f..1a4ad52de0 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 f8478e38d4..e1583c5c55 100644 --- a/doc/man3/EVP_CIPHER_meth_new.pod +++ b/doc/man3/EVP_CIPHER_meth_new.pod @@ -222,9 +222,7 @@ L =head1 HISTORY -The B 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 d0bb33713a..933ffb2122 100644 --- a/doc/man3/EVP_DigestInit.pod +++ b/doc/man3/EVP_DigestInit.pod @@ -241,15 +241,13 @@ L =head1 HISTORY -B became opaque in OpenSSL 1.1. Consequently, stack -allocated Bs 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 f7118ff4fc..49351f4dce 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 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 5fb14e9cef..b2130c8646 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 9c2f9e19a6..ffddf81a59 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. -=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 5e94f5c954..0f8b7da7e1 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 or an empty stack if no list was sent. -=back - =head1 SEE ALSO L, diff --git a/doc/man3/SSL_set_bio.pod b/doc/man3/SSL_set_bio.pod index 4230940bdb..01617521bf 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 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 and the B at the same time. This -function transfers the ownership of B and B to B 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 and the B at the same time, and +transfers the ownership of B and B to B 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 or B 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 and B 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 and B parameters are the same and the B 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 and B parameters are the same and the B 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 and B parameters are different and the B is the +same as the +previously set value then one reference is consumed for the B and no +references are consumed for the B. =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 and B parameters are different and the B is the +same as the previously set value and the old B and B values +were the same as each other then one reference is consumed for the B +and no references are consumed for the B. =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 and B parameters are different and the B +is the same as the +previously set value and the old B and B values were different +to each +other then one reference is consumed for the B and one reference +is consumed +for the B. =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 be68b265eb..5579dabb77 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 (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 e59512dc58..ad5009e715 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, B or B will suffice. diff --git a/doc/man3/X509_VERIFY_PARAM_set_flags.pod b/doc/man3/X509_VERIFY_PARAM_set_flags.pod index e8428e1c57..a4e30614cd 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 =head1 HISTORY The B flag was added in OpenSSL 1.1.0 -The legacy B flag is deprecated as of +The flag B 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 b4b76dd503..59cfc7cea7 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, L, L =head1 COPYRIGHT diff --git a/util/find-doc-nits b/util/find-doc-nits index 8f6d482278..bdc1ba225b 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@include ', $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; -- 2.34.1