From 485d336137f2afa62e378bc39dcfa37dcfb222da Mon Sep 17 00:00:00 2001 From: Rich Salz Date: Fri, 16 Aug 2019 08:34:16 -0400 Subject: [PATCH] Do not have duplicate section heads Change find-doc-nits to complain if a section header is repeated, within a parent header (i.e., duplicate =head2 within a =head1). In almost all cases, we just remove the duplicate header, as it was a "continuation" of the =head1 that was already in affect. In some cases, just remove "=head1 NOTES", possibly moving text around, because the "NOTES" were really important parts of the DESCRIPTION section. No =headX sections should end with a period. All =head1 labels should be in all uppercase. No sub-head (=head2, etc) should be in all uppercase. Update find-doc-nits to reject the above. Fixup an internal POD link Reviewed-by: Richard Levitte Reviewed-by: Paul Yang Reviewed-by: Paul Dale (Merged from https://github.com/openssl/openssl/pull/9631) --- doc/man1/openssl-ciphers.pod | 2 +- doc/man1/openssl-cms.pod | 4 +- doc/man1/openssl-ocsp.pod | 2 +- doc/man1/openssl-pkcs8.pod | 2 +- doc/man1/openssl-pkeyutl.pod | 4 +- doc/man3/CMS_compress.pod | 4 -- doc/man3/CMS_encrypt.pod | 4 -- doc/man3/CRYPTO_THREAD_run_once.pod | 20 ++++---- doc/man3/EVP_EncryptInit.pod | 4 +- doc/man3/OSSL_trace_set_channel.pod | 2 +- doc/man3/PKCS12_newpass.pod | 22 ++++----- doc/man3/PKCS7_encrypt.pod | 4 -- doc/man3/PKCS7_sign.pod | 4 -- doc/man3/SSL_CTX_set_options.pod | 2 +- doc/man3/SSL_CTX_use_psk_identity_hint.pod | 2 - doc/man3/SSL_shutdown.pod | 56 ++++++++++------------ doc/man5/x509v3_config.pod | 20 ++++---- doc/man7/RAND_DRBG.pod | 2 +- doc/man7/provider.pod | 2 +- util/find-doc-nits | 39 +++++++++++++-- 20 files changed, 103 insertions(+), 98 deletions(-) diff --git a/doc/man1/openssl-ciphers.pod b/doc/man1/openssl-ciphers.pod index eabf312262..7e498333c6 100644 --- a/doc/man1/openssl-ciphers.pod +++ b/doc/man1/openssl-ciphers.pod @@ -508,7 +508,7 @@ Note: these ciphers can also be used in SSL v3. TLS_DHE_DSS_WITH_RC4_128_SHA DHE-DSS-RC4-SHA -=head2 Elliptic curve cipher suites. +=head2 Elliptic curve cipher suites TLS_ECDHE_RSA_WITH_NULL_SHA ECDHE-RSA-NULL-SHA TLS_ECDHE_RSA_WITH_RC4_128_SHA ECDHE-RSA-RC4-SHA diff --git a/doc/man1/openssl-cms.pod b/doc/man1/openssl-cms.pod index b0e3a29d09..54e757ff11 100644 --- a/doc/man1/openssl-cms.pod +++ b/doc/man1/openssl-cms.pod @@ -559,7 +559,7 @@ The B<-debug_decrypt> option can be used to disable the MMA attack protection and return an error if no recipient can be found: this option should be used with caution. For a fuller description see L). -=head1 CAdES Basic Electronic Signature (CAdES-BES) +=head1 CADES BASIC ELECTRONIC SIGNATURE (CADES-BES) A CAdES Basic Electronic Signature (CAdES-BES), as defined in the European Standard ETSI EN 319 122-1 V1.1.1, contains: @@ -625,7 +625,7 @@ the signers certificates. =back -=head1 COMPATIBILITY WITH PKCS#7 format. +=head1 COMPATIBILITY WITH PKCS#7 FORMAT The B utility can only process the older B format. The B utility supports Cryptographic Message Syntax format. Use of some features diff --git a/doc/man1/openssl-ocsp.pod b/doc/man1/openssl-ocsp.pod index df6b9af1f4..d5bc2f75da 100644 --- a/doc/man1/openssl-ocsp.pod +++ b/doc/man1/openssl-ocsp.pod @@ -392,7 +392,7 @@ immediately available. =back -=head1 OCSP Response verification. +=head1 OCSP RESPONSE VERIFICATION OCSP Response follows the rules specified in RFC2560. diff --git a/doc/man1/openssl-pkcs8.pod b/doc/man1/openssl-pkcs8.pod index a9ca581cdc..9b63694907 100644 --- a/doc/man1/openssl-pkcs8.pod +++ b/doc/man1/openssl-pkcs8.pod @@ -209,7 +209,7 @@ It is possible to write out DER encoded encrypted private keys in PKCS#8 format because the encryption details are included at an ASN1 level whereas the traditional format includes them at a PEM level. -=head1 PKCS#5 v1.5 and PKCS#12 algorithms. +=head1 PKCS#5 V1.5 AND PKCS#12 ALGORITHMS Various algorithms can be used with the B<-v1> command line option, including PKCS#5 v1.5 and PKCS#12. These are described in more detail diff --git a/doc/man1/openssl-pkeyutl.pod b/doc/man1/openssl-pkeyutl.pod index 7a7e2c023f..e4a0d2c11f 100644 --- a/doc/man1/openssl-pkeyutl.pod +++ b/doc/man1/openssl-pkeyutl.pod @@ -309,12 +309,12 @@ The EC algorithm supports sign, verify and derive operations. The sign and verify operations use ECDSA and derive uses ECDH. SHA1 is assumed by default for the B<-pkeyopt> B option. -=head1 X25519 and X448 ALGORITHMS +=head1 X25519 AND X448 ALGORITHMS The X25519 and X448 algorithms support key derivation only. Currently there are no additional options. -=head1 Ed25519 and Ed448 ALGORITHMS +=head1 ED25519 AND ED448 ALGORITHMS These algorithms only support signing and verifying. OpenSSL only implements the "pure" variants of these algorithms so raw data can be passed directly to them diff --git a/doc/man3/CMS_compress.pod b/doc/man3/CMS_compress.pod index 56cf26cd57..312484610e 100644 --- a/doc/man3/CMS_compress.pod +++ b/doc/man3/CMS_compress.pod @@ -17,8 +17,6 @@ is the compression algorithm to use or B to use the default algorithm (zlib compression). B is the content to be compressed. B is an optional set of flags. -=head1 NOTES - The only currently supported compression algorithm is zlib using the NID NID_zlib_compression. @@ -41,8 +39,6 @@ The compressed data is included in the CMS_ContentInfo structure, unless B is set in which case it is omitted. This is rarely used in practice and is not supported by SMIME_write_CMS(). -=head1 NOTES - If the flag B is set the returned B structure is B complete and outputting its contents via a function that does not properly finalize the B structure will give unpredictable diff --git a/doc/man3/CMS_encrypt.pod b/doc/man3/CMS_encrypt.pod index ff2cf8d2d6..1bc9fd041d 100644 --- a/doc/man3/CMS_encrypt.pod +++ b/doc/man3/CMS_encrypt.pod @@ -17,8 +17,6 @@ CMS_encrypt() creates and returns a CMS EnvelopedData structure. B is a list of recipient certificates. B is the content to be encrypted. B is the symmetric cipher to use. B is an optional set of flags. -=head1 NOTES - Only certificates carrying RSA, Diffie-Hellman or EC keys are supported by this function. @@ -60,8 +58,6 @@ The data being encrypted is included in the CMS_ContentInfo structure, unless B is set in which case it is omitted. This is rarely used in practice and is not supported by SMIME_write_CMS(). -=head1 NOTES - If the flag B is set the returned B structure is B complete and outputting its contents via a function that does not properly finalize the B structure will give unpredictable diff --git a/doc/man3/CRYPTO_THREAD_run_once.pod b/doc/man3/CRYPTO_THREAD_run_once.pod index ee413e7672..ab7ff878be 100644 --- a/doc/man3/CRYPTO_THREAD_run_once.pod +++ b/doc/man3/CRYPTO_THREAD_run_once.pod @@ -99,6 +99,15 @@ crypto.h where use of CRYPTO_THREAD_* types and functions is required. =head1 EXAMPLES +You can find out if OpenSSL was configured with thread support: + + #include + #if defined(OPENSSL_THREADS) + /* thread support enabled */ + #else + /* no thread support */ + #endif + This example safely initializes and uses a lock. #ifdef _WIN32 @@ -144,17 +153,6 @@ no longer in use and is unloaded. The simplest solution is to just "leak" the lock in applications and not repeatedly load/unload shared libraries that allocate locks. -=head1 NOTES - -You can find out if OpenSSL was configured with thread support: - - #include - #if defined(OPENSSL_THREADS) - /* thread support enabled */ - #else - /* no thread support */ - #endif - =head1 SEE ALSO L diff --git a/doc/man3/EVP_EncryptInit.pod b/doc/man3/EVP_EncryptInit.pod index 011b6e6c3a..7f69a23dd7 100644 --- a/doc/man3/EVP_EncryptInit.pod +++ b/doc/man3/EVP_EncryptInit.pod @@ -406,7 +406,7 @@ Null cipher: does nothing. =back -=head1 AEAD Interface +=head1 AEAD INTERFACE The EVP interface for Authenticated Encryption with Associated Data (AEAD) modes are subtly altered and several additional I operations are supported @@ -485,7 +485,7 @@ the length of the tag (with the C parameter set to NULL) when encrypting. The tag length is often referred to as B. If not set a default value is used (12 for AES). When decrypting, the tag needs to be set before passing in data to be decrypted, but as in GCM and OCB mode, it can be set after -passing additional authenticated data (see L). +passing additional authenticated data (see L). =item EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_CCM_SET_L, ivlen, NULL) diff --git a/doc/man3/OSSL_trace_set_channel.pod b/doc/man3/OSSL_trace_set_channel.pod index 6a88fe7f24..f214abdb40 100644 --- a/doc/man3/OSSL_trace_set_channel.pod +++ b/doc/man3/OSSL_trace_set_channel.pod @@ -214,7 +214,7 @@ the following: BIO_dump(trc_out, bar, sizeof(bar)); } OSSL_TRACE_END(TLS); -=head1 Simple example +=head2 Simple example An example with just a channel and constant prefix / suffix. diff --git a/doc/man3/PKCS12_newpass.pod b/doc/man3/PKCS12_newpass.pod index 491fbcbbee..52d349e76c 100644 --- a/doc/man3/PKCS12_newpass.pod +++ b/doc/man3/PKCS12_newpass.pod @@ -17,8 +17,6 @@ PKCS12_newpass() changes the password of a PKCS12 structure. B is a pointer to a PKCS12 structure. B is the existing password and B is the new password. -=head1 NOTES - Each of B and B is independently interpreted as a string in the UTF-8 encoding. If it is not valid UTF-8, it is assumed to be ISO8859-1 instead. @@ -29,6 +27,15 @@ use. This may include passwords from local text files, or input from the terminal or command line. Refer to the documentation of L, for example. +If the PKCS#12 structure does not have a password, then you must use the empty +string "" for B. Using NULL for B will result in a +PKCS12_newpass() failure. + +If the wrong password is used for B then the function will fail, +with a MAC verification error. In rare cases the PKCS12 structure does not +contain a MAC: in this case it will usually fail with a decryption padding +error. + =head1 RETURN VALUES PKCS12_newpass() returns 1 on success or 0 on failure. Applications can @@ -83,17 +90,6 @@ the result to a new file. } -=head1 NOTES - -If the PKCS#12 structure does not have a password, then you must use the empty -string "" for B. Using NULL for B will result in a -PKCS12_newpass() failure. - -If the wrong password is used for B then the function will fail, -with a MAC verification error. In rare cases the PKCS12 structure does not -contain a MAC: in this case it will usually fail with a decryption padding -error. - =head1 BUGS The password format is a NULL terminated ASCII string which is converted to diff --git a/doc/man3/PKCS7_encrypt.pod b/doc/man3/PKCS7_encrypt.pod index 44b985e7be..b2d07e8e15 100644 --- a/doc/man3/PKCS7_encrypt.pod +++ b/doc/man3/PKCS7_encrypt.pod @@ -17,8 +17,6 @@ PKCS7_encrypt() creates and returns a PKCS#7 envelopedData structure. B is a list of recipient certificates. B is the content to be encrypted. B is the symmetric cipher to use. B is an optional set of flags. -=head1 NOTES - Only RSA keys are supported in PKCS#7 and envelopedData so the recipient certificates supplied to this function must all contain RSA public keys, though they do not have to be signed using the RSA algorithm. @@ -52,8 +50,6 @@ B is ignored. If the B flag is set a partial B structure is output suitable for streaming I/O: no data is read from the BIO B. -=head1 NOTES - If the flag B is set the returned B structure is B complete and outputting its contents via a function that does not properly finalize the B structure will give unpredictable diff --git a/doc/man3/PKCS7_sign.pod b/doc/man3/PKCS7_sign.pod index 4a14aac77a..f53e7b4c17 100644 --- a/doc/man3/PKCS7_sign.pod +++ b/doc/man3/PKCS7_sign.pod @@ -22,8 +22,6 @@ The data to be signed is read from BIO B. B is an optional set of flags. -=head1 NOTES - Any of the following flags (ored together) can be passed in the B parameter. @@ -66,8 +64,6 @@ way data can be signed in a single pass. If the B flag is set a partial B structure is output to which additional signers and capabilities can be added before finalization. -=head1 NOTES - If the flag B is set the returned B structure is B complete and outputting its contents via a function that does not properly finalize the B structure will give unpredictable results. diff --git a/doc/man3/SSL_CTX_set_options.pod b/doc/man3/SSL_CTX_set_options.pod index 32abd2fc01..82dd64fe0f 100644 --- a/doc/man3/SSL_CTX_set_options.pod +++ b/doc/man3/SSL_CTX_set_options.pod @@ -313,7 +313,7 @@ unaware of the unpatched nature of the client. If the option B is set then renegotiation B succeeds. -=head2 Patched OpenSSL client and unpatched server. +=head2 Patched OpenSSL client and unpatched server If the option B or B is set then initial connections diff --git a/doc/man3/SSL_CTX_use_psk_identity_hint.pod b/doc/man3/SSL_CTX_use_psk_identity_hint.pod index ac8636b40b..2335dc4061 100644 --- a/doc/man3/SSL_CTX_use_psk_identity_hint.pod +++ b/doc/man3/SSL_CTX_use_psk_identity_hint.pod @@ -85,8 +85,6 @@ check to see if a callback has been set via SSL_CTX_set_psk_server_callback() or SSL_set_psk_server_callback() and use that. In this case the handshake digest will default to SHA-256 for any returned PSK. -=head1 NOTES - A connection established via a TLSv1.3 PSK will appear as if session resumption has occurred so that L will return true. diff --git a/doc/man3/SSL_shutdown.pod b/doc/man3/SSL_shutdown.pod index 6e470a1ab0..608cd7195e 100644 --- a/doc/man3/SSL_shutdown.pod +++ b/doc/man3/SSL_shutdown.pod @@ -15,8 +15,6 @@ SSL_shutdown - shut down a TLS/SSL connection SSL_shutdown() shuts down an active TLS/SSL connection. It sends the close_notify shutdown alert to the peer. -=head1 NOTES - SSL_shutdown() tries to send the close_notify shutdown alert to the peer. Whether the operation succeeds or not, the SSL_SENT_SHUTDOWN flag is set and a currently open session is considered closed and good and will be kept in the @@ -52,6 +50,32 @@ SSL_shutdown() only closes the write direction. It is not possible to call SSL_write() after calling SSL_shutdown(). The read direction is closed by the peer. +The behaviour of SSL_shutdown() additionally depends on the underlying BIO. +If the underlying BIO is B, SSL_shutdown() will only return once the +handshake step has been finished or an error occurred. + +If the underlying BIO is B, SSL_shutdown() will also return +when the underlying BIO could not satisfy the needs of SSL_shutdown() +to continue the handshake. In this case a call to SSL_get_error() with the +return value of SSL_shutdown() will yield B or +B. The calling process then must repeat the call after +taking appropriate action to satisfy the needs of SSL_shutdown(). +The action depends on the underlying BIO. When using a non-blocking socket, +nothing is to be done, but select() can be used to check for the required +condition. When using a buffering BIO, like a BIO pair, data must be written +into or retrieved out of the BIO before being able to continue. + +After SSL_shutdown() returned 0, it is possible to call SSL_shutdown() again +to wait for the peer's close_notify alert. +SSL_shutdown() will return 1 in that case. +However, it is recommended to wait for it using SSL_read() instead. + +SSL_shutdown() can be modified to only set the connection to "shutdown" +state but not actually send the close_notify alert messages, +see L. +When "quiet shutdown" is enabled, SSL_shutdown() will always succeed +and return 1. + =head2 First to close the connection When the application is the first party to send the close_notify @@ -89,34 +113,6 @@ If successful, SSL_shutdown() will return 1. Whether SSL_RECEIVED_SHUTDOWN is already set can be checked using the SSL_get_shutdown() (see also L call. -=head1 NOTES - -The behaviour of SSL_shutdown() additionally depends on the underlying BIO. -If the underlying BIO is B, SSL_shutdown() will only return once the -handshake step has been finished or an error occurred. - -If the underlying BIO is B, SSL_shutdown() will also return -when the underlying BIO could not satisfy the needs of SSL_shutdown() -to continue the handshake. In this case a call to SSL_get_error() with the -return value of SSL_shutdown() will yield B or -B. The calling process then must repeat the call after -taking appropriate action to satisfy the needs of SSL_shutdown(). -The action depends on the underlying BIO. When using a non-blocking socket, -nothing is to be done, but select() can be used to check for the required -condition. When using a buffering BIO, like a BIO pair, data must be written -into or retrieved out of the BIO before being able to continue. - -After SSL_shutdown() returned 0, it is possible to call SSL_shutdown() again -to wait for the peer's close_notify alert. -SSL_shutdown() will return 1 in that case. -However, it is recommended to wait for it using SSL_read() instead. - -SSL_shutdown() can be modified to only set the connection to "shutdown" -state but not actually send the close_notify alert messages, -see L. -When "quiet shutdown" is enabled, SSL_shutdown() will always succeed -and return 1. - =head1 RETURN VALUES The following return values can occur: diff --git a/doc/man5/x509v3_config.pod b/doc/man5/x509v3_config.pod index f9e4b1f7aa..5a84be53c2 100644 --- a/doc/man5/x509v3_config.pod +++ b/doc/man5/x509v3_config.pod @@ -56,7 +56,7 @@ must be used, see the L section fo The following sections describe each supported extension in detail. -=head2 Basic Constraints. +=head2 Basic Constraints This is a multi valued extension which indicates whether a certificate is a CA certificate. The first (mandatory) name is B followed by B or @@ -81,7 +81,7 @@ below this one in a chain. So if you have a CA with a pathlen of zero it can only be used to sign end user certificates and not further CAs. -=head2 Key Usage. +=head2 Key Usage Key usage is a multi valued extension consisting of a list of names of the permitted key usages. @@ -97,7 +97,7 @@ Examples: keyUsage=critical, keyCertSign -=head2 Extended Key Usage. +=head2 Extended Key Usage This extensions consists of a list of usages indicating purposes for which the certificate public key can be used for, @@ -126,7 +126,7 @@ Examples: extendedKeyUsage=serverAuth,clientAuth -=head2 Subject Key Identifier. +=head2 Subject Key Identifier This is really a string extension and can take two possible values. Either the word B which will automatically follow the guidelines in RFC3280 @@ -138,7 +138,7 @@ Example: subjectKeyIdentifier=hash -=head2 Authority Key Identifier. +=head2 Authority Key Identifier The authority key identifier extension permits two options. keyid and issuer: both can take the optional value "always". @@ -156,7 +156,7 @@ Example: authorityKeyIdentifier=keyid,issuer -=head2 Subject Alternative Name. +=head2 Subject Alternative Name The subject alternative name extension allows various literal values to be included in the configuration file. These include B (an email address) @@ -195,7 +195,7 @@ Examples: CN=My Name -=head2 Issuer Alternative Name. +=head2 Issuer Alternative Name The issuer alternative name option supports all the literal options of subject alternative name. It does B support the email:copy option because @@ -208,7 +208,7 @@ Example: issuerAltName = issuer:copy -=head2 Authority Info Access. +=head2 Authority Info Access The authority information access extension gives details about how to access certain information relating to the CA. Its syntax is accessOID;location @@ -300,7 +300,7 @@ Example: CN=Some Name -=head2 Certificate Policies. +=head2 Certificate Policies This is a I extension. All the fields of this extension can be set by using the appropriate syntax. @@ -424,7 +424,7 @@ Example: The following extensions are non standard, Netscape specific and largely obsolete. Their use in new applications is discouraged. -=head2 Netscape String extensions. +=head2 Netscape String extensions Netscape Comment (B) is a string extension containing a comment which will be displayed when the certificate is viewed in some browsers. diff --git a/doc/man7/RAND_DRBG.pod b/doc/man7/RAND_DRBG.pod index c51b8cb238..467a544db3 100644 --- a/doc/man7/RAND_DRBG.pod +++ b/doc/man7/RAND_DRBG.pod @@ -209,7 +209,7 @@ The last feature has been added to support the common practice used with previous OpenSSL versions to call RAND_add() before calling RAND_bytes(). -=head2 Entropy Input vs. Additional Data +=head2 Entropy Input and Additional Data The DRBG distinguishes two different types of random input: I, which comes from a trusted source, and I', diff --git a/doc/man7/provider.pod b/doc/man7/provider.pod index d9010dc9f5..f92d111e95 100644 --- a/doc/man7/provider.pod +++ b/doc/man7/provider.pod @@ -204,7 +204,7 @@ an implementation. The method object that is fetched can then be used with diverse other functions that use them, for example L. -=head2 Implicit fetch +=head3 Implicit fetch I diff --git a/util/find-doc-nits b/util/find-doc-nits index 1b9a2333a3..9126e73586 100755 --- a/util/find-doc-nits +++ b/util/find-doc-nits @@ -159,12 +159,44 @@ sub check_section_location() my $section = shift; my $before = shift; - return - unless $contents =~ /=head1 $section/ and $contents =~ /=head1 $before/; - print "$id $section should be placed before $before section\n" + return unless $contents =~ /=head1 $section/ + and $contents =~ /=head1 $before/; + print "$id $section should appear before $before section\n" if $contents =~ /=head1 $before.*=head1 $section/ms; } +# Check if a =head1 is duplicated, or a =headX is duplicated within a +# =head1. Treats =head2 =head3 as equivalent -- it doesn't reset the head3 +# sets if it finds a =head2 -- but that is good enough for now. Also check +# for proper capitalization, trailing periods, etc. +sub check_head_style() +{ + my $id = shift; + my $contents = shift; + my %head1; + my %subheads; + + foreach my $line ( split /\n+/, $contents ) { + next unless $line =~ /^=head/; + if ( $line =~ /head1/ ) { + print "$id duplicate section $line\n" + if defined $head1{$line}; + $head1{$line} = 1; + %subheads = (); + } else { + print "$id duplicate subsection $line\n" + if defined $subheads{$line}; + $subheads{$line} = 1; + } + print "$id period in =head\n" + if $line =~ /\.[^\w]/ or $line =~ /\.$/; + print "$id not all uppercase in =head1\n" + if $line =~ /head1.*[a-z]/; + print "$id all uppercase in subhead\n" + if $line =~ /head[234][ A-Z0-9]+$/; + } +} + sub check() { my $filename = shift; @@ -179,6 +211,7 @@ sub check() } my $id = "${filename}:1:"; + &check_head_style($id, $contents); # Check ordering of some sections in man3 if ( $filename =~ m|man3/| ) {