From a7aadf8b878501b512127200443041bba8361bbf Mon Sep 17 00:00:00 2001 From: Rich Salz Date: Mon, 12 Dec 2016 11:14:40 -0500 Subject: [PATCH] Fix various doc nits. Don't use regexps for section names, just strings: More consistency. Rename "COMMAND OPTIONS" to OPTIONS. Fix a couple of other nit-level things. Reviewed-by: Richard Levitte (Merged from https://github.com/openssl/openssl/pull/2076) (cherry picked from commit 3dfda1a6363c0cf4efee94754a36c2d86be190c3) --- doc/apps/CA.pl.pod | 62 +++++++++++++------ doc/apps/ca.pod | 2 +- doc/apps/ciphers.pod | 10 ++- doc/apps/cms.pod | 2 +- doc/apps/crl.pod | 2 +- doc/apps/crl2pkcs7.pod | 2 +- doc/apps/dsa.pod | 2 +- doc/apps/ec.pod | 2 +- doc/apps/errstr.pod | 6 +- doc/apps/nseq.pod | 2 +- doc/apps/ocsp.pod | 2 +- doc/apps/openssl.pod | 4 +- doc/apps/pkcs12.pod | 2 +- doc/apps/pkcs7.pod | 2 +- doc/apps/pkcs8.pod | 2 +- doc/apps/pkey.pod | 2 +- doc/apps/pkeyparam.pod | 2 +- doc/apps/pkeyutl.pod | 7 ++- doc/apps/req.pod | 2 +- doc/apps/rsa.pod | 2 +- doc/apps/rsautl.pod | 2 +- doc/apps/sess_id.pod | 2 +- doc/apps/smime.pod | 2 +- doc/apps/spkac.pod | 2 +- doc/apps/verify.pod | 2 +- doc/crypto/ERR_GET_LIB.pod | 4 +- doc/crypto/EVP_EncryptInit.pod | 6 +- doc/crypto/SSL_set_bio.pod | 108 +++++++++++++++++++++++++++++++++ util/find-doc-nits.pl | 6 +- 29 files changed, 193 insertions(+), 60 deletions(-) create mode 100644 doc/crypto/SSL_set_bio.pod diff --git a/doc/apps/CA.pl.pod b/doc/apps/CA.pl.pod index ed30d6a2d1..727cce12c7 100644 --- a/doc/apps/CA.pl.pod +++ b/doc/apps/CA.pl.pod @@ -7,19 +7,27 @@ CA.pl - friendlier interface for OpenSSL certificate programs =head1 SYNOPSIS B -[B<-?>] -[B<-h>] -[B<-help>] -[B<-newcert>] -[B<-newreq>] -[B<-newreq-nodes>] -[B<-newca>] -[B<-xsign>] -[B<-sign>] -[B<-signreq>] -[B<-signcert>] -[B<-verify>] -[B] +B<-?> | +B<-h> | +B<-help> + +B +B<-newcert> | +B<-newreq> | +B<-newreq-nodes> | +B<-xsign> | +B<-sign> | +B<-signCA> | +B<-signcert> | +B<-crl> | +B<-newca> +[B<-extra-cmd> extra-params] + +B B<-pkcs12> [B<-extra-pkcs12> extra-params] [B] + +B B<-verify> [B<-extra-verify> extra-params] B... + +B B<-revoke> [B<-extra-ca> extra-params] B [B] =head1 DESCRIPTION @@ -28,7 +36,7 @@ arguments to the B command for some common certificate operations. It is intended to simplify the process of certificate creation and management by the use of some simple options. -=head1 COMMAND OPTIONS +=head1 OPTIONS =over 4 @@ -40,15 +48,18 @@ prints a usage message. creates a new self signed certificate. The private key is written to the file "newkey.pem" and the request written to the file "newreq.pem". +This argument invokes B command. =item B<-newreq> creates a new certificate request. The private key is written to the file "newkey.pem" and the request written to the file "newreq.pem". +Executes B command below the hood. =item B<-newreq-nodes> is like B<-newreq> except that the private key will not be encrypted. +Uses B command. =item B<-newca> @@ -57,6 +68,7 @@ and B<-xsign> options). The user is prompted to enter the filename of the CA certificates (which should also contain the private key) or by hitting ENTER details of the CA will be prompted for. The relevant files and directories are created in a directory called "demoCA" in the current directory. +B and B commands are get invoked. =item B<-pkcs12> @@ -68,29 +80,31 @@ B<-sign> option. The PKCS#12 file can be imported directly into a browser. If there is an additional argument on the command line it will be used as the "friendly name" for the certificate (which is typically displayed in the browser list box), otherwise the name "My Certificate" is used. +Delegates work to B command. -=item B<-sign>, B<-signreq>, B<-xsign> +=item B<-sign>, B<-signcert>, B<-xsign> calls the B program to sign a certificate request. It expects the request to be in the file "newreq.pem". The new certificate is written to the file "newcert.pem" except in the case of the B<-xsign> option when it is written -to standard output. - +to standard output. Leverages B command. =item B<-signCA> this option is the same as the B<-signreq> option except it uses the configuration file section B and so makes the signed request a valid CA certificate. This is useful when creating intermediate CA from a root CA. +Extra params are passed on to B command. =item B<-signcert> this option is the same as B<-sign> except it expects a self signed certificate to be present in the file "newreq.pem". +Extra params are passed on to B and B commands. =item B<-crl> -generate a CRL +generate a CRL. Executes B command. =item B<-revoke certfile [reason]> @@ -98,15 +112,23 @@ revoke the certificate contained in the specified B. An optional reason may be specified, and must be one of: B, B, B, B, B, B, B, or B. +Leverages B command. =item B<-verify> verifies certificates against the CA certificate for "demoCA". If no certificates are specified on the command line it tries to verify the file "newcert.pem". +Invokes B command. -=item B +=item B<-extra-req> | B<-extra-ca> | B<-extra-pkcs12> | B<-extra-x509> | B<-extra-verify> -one or more optional certificate file names for use with the B<-verify> command. +The purpose of these parameters is to allow optional parameters to be supplied +to B that this command executes. The B<-extra-cmd> are specific to the +option being used and the B command getting invoked. For example +when this command invokes B extra parameters can be passed on +with the B<-extra-req> parameter. The +B commands being invoked per option are documented below. +Users should consult B command documentation for more information. =back diff --git a/doc/apps/ca.pod b/doc/apps/ca.pod index 3be6979588..5d4cfda125 100644 --- a/doc/apps/ca.pod +++ b/doc/apps/ca.pod @@ -62,7 +62,7 @@ and their status. The options descriptions will be divided into each purpose. -=head1 COMMAND OPTIONS +=head1 OPTIONS =over 4 diff --git a/doc/apps/ciphers.pod b/doc/apps/ciphers.pod index c392077653..c1d1cb25a0 100644 --- a/doc/apps/ciphers.pod +++ b/doc/apps/ciphers.pod @@ -15,6 +15,7 @@ B B [B<-tls1>] [B<-tls1_1>] [B<-tls1_2>] +[B<-tls1_3>] [B<-s>] [B<-psk>] [B<-srp>] @@ -27,7 +28,7 @@ The B command converts textual OpenSSL cipher lists into ordered SSL cipher preference lists. It can be used as a test tool to determine the appropriate cipherlist. -=head1 COMMAND OPTIONS +=head1 OPTIONS =over 4 @@ -69,6 +70,11 @@ L. Like B<-v>, but include the official cipher suite values in hex. +=item B<-tls1_3> + +In combination with the B<-s> option, list the ciphers which would be used if +TLSv1.3 were negotiated. + =item B<-tls1_2> In combination with the B<-s> option, list the ciphers which would be used if @@ -711,7 +717,7 @@ Set security level to 2 and display all ciphers consistent with level 2: =head1 SEE ALSO -L, L, L +L, L, L =head1 HISTORY diff --git a/doc/apps/cms.pod b/doc/apps/cms.pod index d5529bea6b..b97120a0e4 100644 --- a/doc/apps/cms.pod +++ b/doc/apps/cms.pod @@ -104,7 +104,7 @@ B B The B command handles S/MIME v3.1 mail. It can encrypt, decrypt, sign and verify, compress and uncompress S/MIME messages. -=head1 COMMAND OPTIONS +=head1 OPTIONS There are fourteen operation options that set the type of operation to be performed. The meaning of the other options varies according to the operation diff --git a/doc/apps/crl.pod b/doc/apps/crl.pod index 0edff8d0f2..2fad2101ee 100644 --- a/doc/apps/crl.pod +++ b/doc/apps/crl.pod @@ -26,7 +26,7 @@ B B The B command processes CRL files in DER or PEM format. -=head1 COMMAND OPTIONS +=head1 OPTIONS =over 4 diff --git a/doc/apps/crl2pkcs7.pod b/doc/apps/crl2pkcs7.pod index 4056543cf6..8c679ea8fd 100644 --- a/doc/apps/crl2pkcs7.pod +++ b/doc/apps/crl2pkcs7.pod @@ -21,7 +21,7 @@ The B command takes an optional CRL and one or more certificates and converts them into a PKCS#7 degenerate "certificates only" structure. -=head1 COMMAND OPTIONS +=head1 OPTIONS =over 4 diff --git a/doc/apps/dsa.pod b/doc/apps/dsa.pod index caa06966e5..0e4f508fab 100644 --- a/doc/apps/dsa.pod +++ b/doc/apps/dsa.pod @@ -37,7 +37,7 @@ forms and their components printed out. B This command uses the traditional SSLeay compatible format for private key encryption: newer applications should use the more secure PKCS#8 format using the B -=head1 COMMAND OPTIONS +=head1 OPTIONS =over 4 diff --git a/doc/apps/ec.pod b/doc/apps/ec.pod index 758709f081..a5f920e841 100644 --- a/doc/apps/ec.pod +++ b/doc/apps/ec.pod @@ -36,7 +36,7 @@ private key format specified in 'SEC 1: Elliptic Curve Cryptography' (http://www.secg.org/). To convert an OpenSSL EC private key into the PKCS#8 private key format use the B command. -=head1 COMMAND OPTIONS +=head1 OPTIONS =over 4 diff --git a/doc/apps/errstr.pod b/doc/apps/errstr.pod index 5ec7b2e395..8dfe49a5e4 100644 --- a/doc/apps/errstr.pod +++ b/doc/apps/errstr.pod @@ -15,7 +15,7 @@ numerical forms will be available. The B utility can be used to display the meaning of the hex code. The hex code is the hex digits after the second colon. -=head1 COMMAND OPTIONS +=head1 OPTIONS None. @@ -33,10 +33,6 @@ to produce the error message: error:2006D080:BIO routines:BIO_new_file:no such file -=head1 SEE ALSO - -L - =head1 COPYRIGHT Copyright 2004-2016 The OpenSSL Project Authors. All Rights Reserved. diff --git a/doc/apps/nseq.pod b/doc/apps/nseq.pod index 4765aecea8..a90f8a0026 100644 --- a/doc/apps/nseq.pod +++ b/doc/apps/nseq.pod @@ -19,7 +19,7 @@ sequence and prints out the certificates contained in it or takes a file of certificates and converts it into a Netscape certificate sequence. -=head1 COMMAND OPTIONS +=head1 OPTIONS =over 4 diff --git a/doc/apps/ocsp.pod b/doc/apps/ocsp.pod index 75273a9b25..ec82088fae 100644 --- a/doc/apps/ocsp.pod +++ b/doc/apps/ocsp.pod @@ -95,7 +95,7 @@ The B command performs many common OCSP tasks. It can be used to print out requests and responses, create requests and send queries to an OCSP responder and behave like a mini OCSP server itself. -=head1 COMMAND OPTIONS +=head1 OPTIONS This command operates as either a client or a server. The options are described below, divided into those two modes. diff --git a/doc/apps/openssl.pod b/doc/apps/openssl.pod index 3014bb31c7..a7e65ff70d 100644 --- a/doc/apps/openssl.pod +++ b/doc/apps/openssl.pod @@ -350,7 +350,7 @@ RC5 Cipher =back -=head1 COMMAND OPTIONS +=head1 OPTIONS Details of which options are available depend on the specific command. This section describes some common options with common behavior. @@ -422,7 +422,7 @@ L, L, L, L, L, L, L, L, L, -L, L, L +L, L, L =head1 HISTORY diff --git a/doc/apps/pkcs12.pod b/doc/apps/pkcs12.pod index e851018cfd..3dea46cdcf 100644 --- a/doc/apps/pkcs12.pod +++ b/doc/apps/pkcs12.pod @@ -49,7 +49,7 @@ The B command allows PKCS#12 files (sometimes referred to as PFX files) to be created and parsed. PKCS#12 files are used by several programs including Netscape, MSIE and MS Outlook. -=head1 COMMAND OPTIONS +=head1 OPTIONS There are a lot of options the meaning of some depends of whether a PKCS#12 file is being created or parsed. By default a PKCS#12 file is parsed. A PKCS#12 diff --git a/doc/apps/pkcs7.pod b/doc/apps/pkcs7.pod index 8c3c11f88b..d238946b34 100644 --- a/doc/apps/pkcs7.pod +++ b/doc/apps/pkcs7.pod @@ -21,7 +21,7 @@ B B The B command processes PKCS#7 files in DER or PEM format. -=head1 COMMAND OPTIONS +=head1 OPTIONS =over 4 diff --git a/doc/apps/pkcs8.pod b/doc/apps/pkcs8.pod index cd6db02a59..dee64a0019 100644 --- a/doc/apps/pkcs8.pod +++ b/doc/apps/pkcs8.pod @@ -34,7 +34,7 @@ The B command processes private keys in PKCS#8 format. It can handle both unencrypted PKCS#8 PrivateKeyInfo format and EncryptedPrivateKeyInfo format with a variety of PKCS#5 (v1.5 and v2.0) and PKCS#12 algorithms. -=head1 COMMAND OPTIONS +=head1 OPTIONS =over 4 diff --git a/doc/apps/pkey.pod b/doc/apps/pkey.pod index dc736a3370..2119c70c7a 100644 --- a/doc/apps/pkey.pod +++ b/doc/apps/pkey.pod @@ -28,7 +28,7 @@ B B The B command processes public or private keys. They can be converted between various forms and their components printed out. -=head1 COMMAND OPTIONS +=head1 OPTIONS =over 4 diff --git a/doc/apps/pkeyparam.pod b/doc/apps/pkeyparam.pod index 6a8c4a806b..755915ff9b 100644 --- a/doc/apps/pkeyparam.pod +++ b/doc/apps/pkeyparam.pod @@ -19,7 +19,7 @@ B B The B command processes public or private keys. They can be converted between various forms and their components printed out. -=head1 COMMAND OPTIONS +=head1 OPTIONS =over 4 diff --git a/doc/apps/pkeyutl.pod b/doc/apps/pkeyutl.pod index 8a455b8187..ceb9de34b4 100644 --- a/doc/apps/pkeyutl.pod +++ b/doc/apps/pkeyutl.pod @@ -38,7 +38,7 @@ B B The B command can be used to perform public key operations using any supported algorithm. -=head1 COMMAND OPTIONS +=head1 OPTIONS =over 4 @@ -126,7 +126,8 @@ derive a shared secret using the peer key. Use key derivation function B. The supported algorithms are at present B and B. Note: additional parameters and the KDF output length will normally have to be -set for this to work. See L and L +set for this to work. +See L and L for the supported string parameters of each algorithm. =item B<-kdflen length> @@ -277,7 +278,7 @@ seed consisting of the single byte 0xFF: L, L, L L, L, L, -L, L +L, L =head1 COPYRIGHT diff --git a/doc/apps/req.pod b/doc/apps/req.pod index 299d092799..8362f53d8c 100644 --- a/doc/apps/req.pod +++ b/doc/apps/req.pod @@ -52,7 +52,7 @@ The B command primarily creates and processes certificate requests in PKCS#10 format. It can additionally create self signed certificates for use as root CAs for example. -=head1 COMMAND OPTIONS +=head1 OPTIONS =over 4 diff --git a/doc/apps/rsa.pod b/doc/apps/rsa.pod index c3178ab398..8e9943fe58 100644 --- a/doc/apps/rsa.pod +++ b/doc/apps/rsa.pod @@ -41,7 +41,7 @@ traditional SSLeay compatible format for private key encryption: newer applications should use the more secure PKCS#8 format using the B utility. -=head1 COMMAND OPTIONS +=head1 OPTIONS =over 4 diff --git a/doc/apps/rsautl.pod b/doc/apps/rsautl.pod index 325c6911d6..038f00be44 100644 --- a/doc/apps/rsautl.pod +++ b/doc/apps/rsautl.pod @@ -29,7 +29,7 @@ B B The B command can be used to sign, verify, encrypt and decrypt data using the RSA algorithm. -=head1 COMMAND OPTIONS +=head1 OPTIONS =over 4 diff --git a/doc/apps/sess_id.pod b/doc/apps/sess_id.pod index 3694f7d838..19ac9a75b1 100644 --- a/doc/apps/sess_id.pod +++ b/doc/apps/sess_id.pod @@ -24,7 +24,7 @@ master key) in human readable format. Since this is a diagnostic tool that needs some knowledge of the SSL protocol to use properly, most users will not need to use it. -=head1 COMMAND OPTIONS +=head1 OPTIONS =over 4 diff --git a/doc/apps/smime.pod b/doc/apps/smime.pod index ba59eda26f..7980e35e77 100644 --- a/doc/apps/smime.pod +++ b/doc/apps/smime.pod @@ -74,7 +74,7 @@ B B The B command handles S/MIME mail. It can encrypt, decrypt, sign and verify S/MIME messages. -=head1 COMMAND OPTIONS +=head1 OPTIONS There are six operation options that set the type of operation to be performed. The meaning of the other options varies according to the operation type. diff --git a/doc/apps/spkac.pod b/doc/apps/spkac.pod index 35c6a128d8..8955bc445d 100644 --- a/doc/apps/spkac.pod +++ b/doc/apps/spkac.pod @@ -26,7 +26,7 @@ The B command processes Netscape signed public key and challenge (SPKAC) files. It can print out their contents, verify the signature and produce its own SPKACs from a supplied private key. -=head1 COMMAND OPTIONS +=head1 OPTIONS =over 4 diff --git a/doc/apps/verify.pod b/doc/apps/verify.pod index 0fd1799af2..8ba5ff67e4 100644 --- a/doc/apps/verify.pod +++ b/doc/apps/verify.pod @@ -55,7 +55,7 @@ B B The B command verifies certificate chains. -=head1 COMMAND OPTIONS +=head1 OPTIONS =over 4 diff --git a/doc/crypto/ERR_GET_LIB.pod b/doc/crypto/ERR_GET_LIB.pod index d809d7a54e..7368a401fc 100644 --- a/doc/crypto/ERR_GET_LIB.pod +++ b/doc/crypto/ERR_GET_LIB.pod @@ -2,8 +2,8 @@ =head1 NAME -ERR_GET_LIB, ERR_GET_FUNC, ERR_GET_REASON - get library, function and -reason code +ERR_GET_LIB, ERR_GET_FUNC, ERR_GET_REASON, ERR_FATAL_ERROR +- get information from error codes =head1 SYNOPSIS diff --git a/doc/crypto/EVP_EncryptInit.pod b/doc/crypto/EVP_EncryptInit.pod index 040bc17fff..db578e506a 100644 --- a/doc/crypto/EVP_EncryptInit.pod +++ b/doc/crypto/EVP_EncryptInit.pod @@ -409,8 +409,8 @@ The ChaCha20 stream cipher. The key length is 256 bits, the IV is 96 bits long. Authenticated encryption with ChaCha20-Poly1305. Like EVP_chacha20() the key is 256 bits and the IV is 96 bits. This supports additional authenticated -data (AAD) and produces a 128 bit authentication tag. The L -section below applies. +data (AAD) and produces a 128 bit authentication tag. See the +L section for more information. =back @@ -639,7 +639,7 @@ with a 128-bit key: =head1 SEE ALSO -L +L =head1 HISTORY diff --git a/doc/crypto/SSL_set_bio.pod b/doc/crypto/SSL_set_bio.pod new file mode 100644 index 0000000000..58d22b63d7 --- /dev/null +++ b/doc/crypto/SSL_set_bio.pod @@ -0,0 +1,108 @@ +=pod + +=head1 NAME + +SSL_set_bio, SSL_set0_rbio, SSL_set0_wbio - connect the SSL object with a BIO + +=head1 SYNOPSIS + + #include + + void SSL_set_bio(SSL *ssl, BIO *rbio, BIO *wbio); + void SSL_set0_rbio(SSL *s, BIO *rbio); + void SSL_set0_wbio(SSL *s, BIO *wbio); + +=head1 DESCRIPTION + +SSL_set0_rbio() connects the BIO B for the read operations of the B +object. The SSL engine inherits the behaviour of B. If the BIO is +non-blocking then the B object will also have non-blocking behaviour. This +function transfers ownership of B to B. It will be automatically +freed using L when the B is freed. On calling this +function, any existing B that was previously set will also be freed via a +call to L (this includes the case where the B is set to +the same value as previously). + +SSL_set0_wbio() works in the same as SSL_set0_rbio() except that it connects +the BIO B for the write operations of the B object. Note that if the +rbio and wbio are the same then SSL_set0_rbio() and SSL_set0_wbio() each take +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: + +=over 4 + +=item * + +If neither the rbio or 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 +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. + +=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. + +=item * + +If the rbio and wbio parameters are different and the rbio is the same as the +previously set value then one reference is consumbed for the wbio and no +references are consumed for the 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. + +=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. + +=back + +=head1 RETURN VALUES + +SSL_set_bio(), SSL_set_rbio() and SSL_set_wbio() cannot fail. + +=head1 SEE ALSO + +L, +L, L, +L, L, L + +=head1 HISTORY + +SSL_set0_rbio() and SSL_set0_wbio() were added in OpenSSL 1.1.0. + +=head1 COPYRIGHT + +Copyright 2000-2016 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 +in the file LICENSE in the source distribution or at +L. + +=cut diff --git a/util/find-doc-nits.pl b/util/find-doc-nits.pl index d9d16d698e..e7f9a47736 100755 --- a/util/find-doc-nits.pl +++ b/util/find-doc-nits.pl @@ -22,8 +22,8 @@ my $OUT; my %mandatory_sections = ( '*' => [ 'NAME', 'DESCRIPTION', 'COPYRIGHT' ], - 1 => [ 'SYNOPSIS', '(COMMAND\s+)?OPTIONS' ], - 3 => [ 'SYNOPSIS', 'RETURN\s+VALUES' ], + 1 => [ 'SYNOPSIS', 'OPTIONS' ], + 3 => [ 'SYNOPSIS', 'RETURN VALUES' ], 5 => [ ], 7 => [ ] ); my %default_sections = @@ -162,7 +162,7 @@ sub check() } foreach ((@{$mandatory_sections{'*'}}, @{$mandatory_sections{$section}})) { - print "$id doesn't have a head1 section matching $_\n" + print "$id: missing $_ head1 section\n" if $contents !~ /^=head1\s+${_}\s*$/m; } -- 2.25.1