From 1948394d0e8a8dbffa62c3125fc0aaf9ef187b70 Mon Sep 17 00:00:00 2001 From: Richard Levitte Date: Tue, 1 Oct 2019 20:19:45 +0200 Subject: [PATCH] Command docs: wrap literal file names with F<> Reviewed-by: Tomas Mraz (Merged from https://github.com/openssl/openssl/pull/10065) --- doc/man1/CA.pl.pod | 22 +++++++++++----------- doc/man1/openssl-ca.pod | 12 ++++++------ doc/man1/openssl-fipsinstall.pod | 6 +++--- doc/man1/openssl-rand.pod | 4 ++-- doc/man1/openssl-rehash.pod | 4 ++-- doc/man1/openssl-rsa.pod | 2 +- doc/man1/openssl-rsautl.pod | 2 +- doc/man1/openssl-s_server.pod | 6 +++--- doc/man1/openssl-s_time.pod | 2 +- doc/man1/openssl-ts.pod | 12 ++++++------ doc/man1/openssl-tsget.pod | 20 ++++++++++---------- doc/man1/openssl-verify.pod | 3 ++- doc/man1/openssl-x509.pod | 5 +++-- doc/man1/openssl.pod | 2 +- 14 files changed, 52 insertions(+), 50 deletions(-) diff --git a/doc/man1/CA.pl.pod b/doc/man1/CA.pl.pod index 235e341886..129bf35407 100644 --- a/doc/man1/CA.pl.pod +++ b/doc/man1/CA.pl.pod @@ -47,13 +47,13 @@ Prints a usage message. =item B<-newcert> 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". +F and the request written to the file F. This argument invokes L 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". +F and the request written to the file F. Executes L command below the hood. =item B<-newreq-nodes> @@ -67,15 +67,15 @@ Creates a new CA hierarchy for use with the B program (or the B<-signcert> 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. +are created in a directory called F in the current directory. L and L commands are get invoked. =item B<-pkcs12> Create a PKCS#12 file containing the user certificate, private key and CA certificate. It expects the user certificate and private key to be in the -file "newcert.pem" and the CA certificate to be in the file demoCA/cacert.pem, -it creates a file "newcert.p12". This command can thus be called after the +file F and the CA certificate to be in the file F, +it creates a file F. This command can thus be called after the 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 @@ -85,8 +85,8 @@ Delegates work to L command. =item B<-sign>, B<-signcert>, B<-xsign> Calls the L command 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 +request to be in the file F. The new certificate is written to the +file F except in the case of the B<-xsign> option when it is written to standard output. Leverages L command. =item B<-signCA> @@ -99,7 +99,7 @@ a root CA. Extra params are passed on to L 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". +to be present in the file F. Extra params are passed on to L and L commands. =item B<-crl> @@ -116,9 +116,9 @@ Leverages L command. =item B<-verify> -Verifies certificates against the CA certificate for "demoCA". If no +Verifies certificates against the CA certificate for F. If no certificates are specified on the command line it tries to verify the file -"newcert.pem". Invokes L command. +F. Invokes L command. =item B<-extra-req> | B<-extra-ca> | B<-extra-pkcs12> | B<-extra-x509> | B<-extra-verify> I @@ -164,7 +164,7 @@ Create the CA directories and files: CA.pl -newca -enter cacert.pem when prompted for the CA filename. +enter a filename (for example F) when prompted for the CA filename. Create a DSA certificate request and private key (a different set of parameters can optionally be created first): diff --git a/doc/man1/openssl-ca.pod b/doc/man1/openssl-ca.pod index 8e1ce25aa2..d58bd0ed66 100644 --- a/doc/man1/openssl-ca.pod +++ b/doc/man1/openssl-ca.pod @@ -123,7 +123,7 @@ file in PEM format (except that B<-spkac> outputs DER format). The directory to output certificates to. The certificate will be written to a filename consisting of the serial number in hex with -".pem" appended. +F<.pem> appended. =item B<-cert> @@ -600,12 +600,12 @@ usually involves creating a CA certificate and private key with L, a serial number file and an empty index file and placing them in the relevant directories. -To use the sample configuration file below the directories demoCA, -demoCA/private and demoCA/newcerts would be created. The CA -certificate would be copied to demoCA/cacert.pem and its private -key to demoCA/private/cakey.pem. A file demoCA/serial would be +To use the sample configuration file below the directories F, +F and F would be created. The CA +certificate would be copied to F and its private +key to F. A file F would be created containing for example "01" and the empty index file -demoCA/index.txt. +F. Sign a certificate request: diff --git a/doc/man1/openssl-fipsinstall.pod b/doc/man1/openssl-fipsinstall.pod index 7237e967fd..44f6e0e410 100644 --- a/doc/man1/openssl-fipsinstall.pod +++ b/doc/man1/openssl-fipsinstall.pod @@ -110,14 +110,14 @@ C. =head1 EXAMPLES -Calculate the mac of a FIPS module 'fips.so' and run a FIPS self test -for the module, and save the fips.conf configuration file: +Calculate the mac of a FIPS module F and run a FIPS self test +for the module, and save the F configuration file: openssl fipsinstall -module ./fips.so -out fips.conf -provider_name fips \ -section_name fipsinstall -mac_name HMAC -macopt digest:SHA256 \ -macopt hexkey:000102030405060708090A0B0C0D0E0F10111213 -Verify that the configuration file 'fips.conf' contains the correct info: +Verify that the configuration file F contains the correct info: openssl fipsinstall -module ./fips.so -in fips.conf -provider_name fips \ -section_name fips_install -mac_name HMAC -macopt digest:SHA256 \ diff --git a/doc/man1/openssl-rand.pod b/doc/man1/openssl-rand.pod index d8b60c0f8a..6ce3326efd 100644 --- a/doc/man1/openssl-rand.pod +++ b/doc/man1/openssl-rand.pod @@ -21,9 +21,9 @@ I This command outputs I pseudo-random bytes after seeding the random number generator once. As in other B command -line tools, PRNG seeding uses the file I<$HOME/>B<.rnd> or B<.rnd> +line tools, PRNG seeding uses the file F<$HOME/.rnd> or F<.rnd> in addition to the files given in the B<-rand> option. A new -I<$HOME>/B<.rnd> or B<.rnd> file will be written back if enough +F<$HOME/.rnd> or F<.rnd> file will be written back if enough seeding was obtained from these sources. =head1 OPTIONS diff --git a/doc/man1/openssl-rehash.pod b/doc/man1/openssl-rehash.pod index d29590bf99..d813faacb9 100644 --- a/doc/man1/openssl-rehash.pod +++ b/doc/man1/openssl-rehash.pod @@ -28,7 +28,7 @@ script B has to be used instead. They are functionally equivalent, except for minor differences noted below. B scans directories and calculates a hash value of -each C<.pem>, C<.crt>, C<.cer>, or C<.crl> +each F<.pem>, F<.crt>, F<.cer>, or F<.crl> file in the specified directory list and creates symbolic links for each file, where the name of the link is the hash value. (If the platform does not support symbolic links, a copy is made.) @@ -40,7 +40,7 @@ processed in turn. If not, then the B environment variable is consulted; this should be a colon-separated list of directories, like the Unix B variable. If that is not set then the default directory (installation-specific -but often B) is processed. +but often F) is processed. In order for a directory to be processed, the user must have write permissions on that directory, otherwise an error will be generated. diff --git a/doc/man1/openssl-rsa.pod b/doc/man1/openssl-rsa.pod index 36f96b7b11..7c2fd9effa 100644 --- a/doc/man1/openssl-rsa.pod +++ b/doc/man1/openssl-rsa.pod @@ -186,7 +186,7 @@ Output the public part of a private key in B format: =head1 BUGS -There should be an option that automatically handles .key files, +There should be an option that automatically handles F<.key> files, without having to manually edit them. =head1 SEE ALSO diff --git a/doc/man1/openssl-rsautl.pod b/doc/man1/openssl-rsautl.pod index 43f8e845b3..0774b92797 100644 --- a/doc/man1/openssl-rsautl.pod +++ b/doc/man1/openssl-rsautl.pod @@ -148,7 +148,7 @@ and random padding data visible instead of the 0xff bytes. It is possible to analyse the signature of certificates using this utility in conjunction with L. Consider the self signed -example in certs/pca-cert.pem . Running L as follows +example in F. Running L as follows yields: openssl asn1parse -in pca-cert.pem diff --git a/doc/man1/openssl-s_server.pod b/doc/man1/openssl-s_server.pod index 94f1a5ee1f..a9aa08505f 100644 --- a/doc/man1/openssl-s_server.pod +++ b/doc/man1/openssl-s_server.pod @@ -257,7 +257,7 @@ anonymous cipher suite or PSK) this option has no effect. The certificate to use, most servers cipher suites require the use of a certificate and some require a certificate with a certain public key type: for example the DSS cipher suites require a certificate containing a DSS -(DSA) key. If not specified then the filename "server.pem" will be used. +(DSA) key. If not specified then the filename F will be used. =item B<-cert_chain> @@ -422,7 +422,7 @@ web browser. Cannot be used in conjunction with B<-early_data>. Emulates a simple web server. Pages will be resolved relative to the current directory, for example if the URL https://myhost/page.html is -requested the file ./page.html will be loaded. Cannot be used in conjunction +requested the file F<./page.html> will be loaded. Cannot be used in conjunction with B<-early_data>. =item B<-tlsextdebug> @@ -433,7 +433,7 @@ Print a hex dump of any TLS extensions received from the server. Emulates a simple web server. Pages will be resolved relative to the current directory, for example if the URL https://myhost/page.html is -requested the file ./page.html will be loaded. The files loaded are +requested the file F<./page.html> will be loaded. The files loaded are assumed to contain a complete and correct HTTP response (lines that are part of the HTTP response line and headers must end with CRLF). Cannot be used in conjunction with B<-early_data>. diff --git a/doc/man1/openssl-s_time.pod b/doc/man1/openssl-s_time.pod index fc192b2518..4e095c29e0 100644 --- a/doc/man1/openssl-s_time.pod +++ b/doc/man1/openssl-s_time.pod @@ -56,7 +56,7 @@ This specifies the host and optional port to connect to. =item B<-www> I This specifies the page to GET from the server. A value of '/' gets the -index.htm[l] page. If this parameter is not specified, then this command +F page. If this parameter is not specified, then this command will only perform the handshake to establish SSL connections but not transfer any payload data. diff --git a/doc/man1/openssl-ts.pod b/doc/man1/openssl-ts.pod index 6e9087bd18..d879f49579 100644 --- a/doc/man1/openssl-ts.pod +++ b/doc/man1/openssl-ts.pod @@ -526,11 +526,11 @@ public key certificate identifier. Default is sha256. (Optional) All the examples below presume that B is set to a proper configuration file, e.g. the example configuration file -openssl/apps/openssl.cnf will do. +F will do. =head2 Timestamp Request -To create a timestamp request for design1.txt with SHA-256 digest, +To create a timestamp request for F with SHA-256 digest, without nonce and policy, and without requirement for a certificate in the response: @@ -548,7 +548,7 @@ To print the content of the previous request in human readable format: openssl ts -query -in design1.tsq -text To create a timestamp request which includes the SHA-512 digest -of design2.txt, requests the signer certificate and nonce, and +of F, requests the signer certificate and nonce, and specifies a policy id (assuming the tsa_policy1 name is defined in the OID section of the config file): @@ -565,9 +565,9 @@ user certificate section of the config file to generate a proper certificate; extendedKeyUsage = critical,timeStamping See L, L, and L for instructions. The examples -below assume that cacert.pem contains the certificate of the CA, -tsacert.pem is the signing certificate issued by cacert.pem and -tsakey.pem is the private key of the TSA. +below assume that F contains the certificate of the CA, +F is the signing certificate issued by F and +F is the private key of the TSA. To create a timestamp response for a request: diff --git a/doc/man1/openssl-tsget.pod b/doc/man1/openssl-tsget.pod index 10595db07c..3ebe56b8a4 100644 --- a/doc/man1/openssl-tsget.pod +++ b/doc/man1/openssl-tsget.pod @@ -135,37 +135,37 @@ arguments. =head1 EXAMPLES -The examples below presume that B and B contain valid +The examples below presume that F and F contain valid timestamp requests, tsa.opentsa.org listens at port 8080 for HTTP requests and at port 8443 for HTTPS requests, the TSA service is available at the /tsa absolute path. -Get a timestamp response for file1.tsq over HTTP, output is written to -file1.tsr: +Get a timestamp response for F over HTTP, output is written to +F: tsget -h http://tsa.opentsa.org:8080/tsa file1.tsq -Get a timestamp response for file1.tsq and file2.tsq over HTTP showing -progress, output is written to file1.reply and file2.reply respectively: +Get a timestamp response for F and F over HTTP showing +progress, output is written to F and F respectively: tsget -h http://tsa.opentsa.org:8080/tsa -v -e .reply \ file1.tsq file2.tsq -Create a timestamp request, write it to file3.tsq, send it to the server and -write the response to file3.tsr: +Create a timestamp request, write it to F, send it to the server and +write the response to F: openssl ts -query -data file3.txt -cert | tee file3.tsq \ | tsget -h http://tsa.opentsa.org:8080/tsa \ -o file3.tsr -Get a timestamp response for file1.tsq over HTTPS without client +Get a timestamp response for F over HTTPS without client authentication: tsget -h https://tsa.opentsa.org:8443/tsa \ -C cacerts.pem file1.tsq -Get a timestamp response for file1.tsq over HTTPS with certificate-based -client authentication (it will ask for the passphrase if client_key.pem is +Get a timestamp response for F over HTTPS with certificate-based +client authentication (it will ask for the passphrase if F is protected): tsget -h https://tsa.opentsa.org:8443/tsa -C cacerts.pem \ diff --git a/doc/man1/openssl-verify.pod b/doc/man1/openssl-verify.pod index 0dd27c4200..81493a0fb4 100644 --- a/doc/man1/openssl-verify.pod +++ b/doc/man1/openssl-verify.pod @@ -416,7 +416,8 @@ then 1 for the CA that signed the certificate and so on. Finally a text version of the error number is presented. A partial list of the error codes and messages is shown below, this also -includes the name of the error code as defined in the header file x509_vfy.h +includes the name of the error code as defined in the header file +F<< >>. Some of the error codes are defined but never returned: these are described as "unused". diff --git a/doc/man1/openssl-x509.pod b/doc/man1/openssl-x509.pod index 5fcff0aed4..8da1601a7e 100644 --- a/doc/man1/openssl-x509.pod +++ b/doc/man1/openssl-x509.pod @@ -437,8 +437,9 @@ an even number of hex digits with the serial number to use. After each use the serial number is incremented and written out to the file again. The default filename consists of the CA certificate file base name with -".srl" appended. For example if the CA certificate file is called -"mycacert.pem" it expects to find a serial number file called "mycacert.srl". +F<.srl> appended. For example if the CA certificate file is called +F it expects to find a serial number file called +F. =item B<-CAcreateserial> diff --git a/doc/man1/openssl.pod b/doc/man1/openssl.pod index fad0e85b0d..8a31f09ceb 100644 --- a/doc/man1/openssl.pod +++ b/doc/man1/openssl.pod @@ -48,7 +48,7 @@ arguments and have a B<-config> option to specify that file. The environment variable B can be used to specify the location of the file. If the environment variable is not specified, then the file is named -B in the default certificate storage area, whose value +F in the default certificate storage area, whose value depends on the configuration flags specified when the OpenSSL was built. -- 2.25.1