Command docs: wrap literal file names with F<>
authorRichard Levitte <levitte@openssl.org>
Tue, 1 Oct 2019 18:19:45 +0000 (20:19 +0200)
committerRichard Levitte <levitte@openssl.org>
Wed, 9 Oct 2019 08:44:32 +0000 (10:44 +0200)
Reviewed-by: Tomas Mraz <tmraz@fedoraproject.org>
(Merged from https://github.com/openssl/openssl/pull/10065)

14 files changed:
doc/man1/CA.pl.pod
doc/man1/openssl-ca.pod
doc/man1/openssl-fipsinstall.pod
doc/man1/openssl-rand.pod
doc/man1/openssl-rehash.pod
doc/man1/openssl-rsa.pod
doc/man1/openssl-rsautl.pod
doc/man1/openssl-s_server.pod
doc/man1/openssl-s_time.pod
doc/man1/openssl-ts.pod
doc/man1/openssl-tsget.pod
doc/man1/openssl-verify.pod
doc/man1/openssl-x509.pod
doc/man1/openssl.pod

index 235e341..129bf35 100644 (file)
@@ -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<newkey.pem> and the request written to the file F<newreq.pem>.
 This argument invokes L<openssl-req(1)> 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<newkey.pem> and the request written to the file F<newreq.pem>.
 Executes L<openssl-req(1)> command below the hood.
 
 =item B<-newreq-nodes>
@@ -67,15 +67,15 @@ Creates a new CA hierarchy for use with the B<ca> 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<demoCA> in the current directory.
 L<openssl-req(1)> and L<openssl-ca(1)> 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<newcert.pem> and the CA certificate to be in the file F<demoCA/cacert.pem>,
+it creates a file F<newcert.p12>. 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<openssl-pkcs12(1)> command.
 =item B<-sign>, B<-signcert>, B<-xsign>
 
 Calls the L<openssl-ca(1)> 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<newreq.pem>. The new certificate is written to the
+file F<newcert.pem> except in the case of the B<-xsign> option when it is
 written to standard output. Leverages L<openssl-ca(1)> command.
 
 =item B<-signCA>
@@ -99,7 +99,7 @@ a root CA.  Extra params are passed on to L<openssl-ca(1)> 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<newreq.pem>.
 Extra params are passed on to L<openssl-x509(1)> and L<openssl-ca(1)> commands.
 
 =item B<-crl>
@@ -116,9 +116,9 @@ Leverages L<openssl-ca(1)> command.
 
 =item B<-verify>
 
-Verifies certificates against the CA certificate for "demoCA". If no
+Verifies certificates against the CA certificate for F<demoCA>. If no
 certificates are specified on the command line it tries to verify the file
-"newcert.pem".  Invokes L<openssl-verify(1)> command.
+F<newcert.pem>.  Invokes L<openssl-verify(1)> command.
 
 =item B<-extra-req> | B<-extra-ca> | B<-extra-pkcs12> | B<-extra-x509> | B<-extra-verify> I<extra-params>
 
@@ -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<cacert.pem>) when prompted for the CA filename.
 
 Create a DSA certificate request and private key (a different set of parameters
 can optionally be created first):
index 8e1ce25..d58bd0e 100644 (file)
@@ -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<openssl-req(1)>, 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<demoCA>,
+F<demoCA/private> and F<demoCA/newcerts> would be created. The CA
+certificate would be copied to F<demoCA/cacert.pem> and its private
+key to F<demoCA/private/cakey.pem>. A file F<demoCA/serial> would be
 created containing for example "01" and the empty index file
-demoCA/index.txt.
+F<demoCA/index.txt>.
 
 
 Sign a certificate request:
index 7237e96..44f6e0e 100644 (file)
@@ -110,14 +110,14 @@ C<openssl list -digest-commands>.
 
 =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<fips.so> and run a FIPS self test
+for the module, and save the F<fips.conf> 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<fips.conf> 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 \
index d8b60c0..6ce3326 100644 (file)
@@ -21,9 +21,9 @@ I<num>
 
 This command outputs I<num> pseudo-random bytes after seeding
 the random number generator once.  As in other B<openssl> 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
index d29590b..d813faa 100644 (file)
@@ -28,7 +28,7 @@ script B<c_rehash> has to be used instead.  They are functionally
 equivalent, except for minor differences noted below.
 
 B<openssl rehash> 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<SSL_CERT_DIR> environment variable
 is consulted; this should be a colon-separated list of directories,
 like the Unix B<PATH> variable.
 If that is not set then the default directory (installation-specific
-but often B</usr/local/ssl/certs>) is processed.
+but often F</usr/local/ssl/certs>) 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.
index 36f96b7..7c2fd9e 100644 (file)
@@ -186,7 +186,7 @@ Output the public part of a private key in B<RSAPublicKey> 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
index 43f8e84..0774b92 100644 (file)
@@ -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<openssl-asn1parse(1)>. Consider the self signed
-example in certs/pca-cert.pem . Running L<openssl-asn1parse(1)> as follows
+example in F<certs/pca-cert.pem>. Running L<openssl-asn1parse(1)> as follows
 yields:
 
  openssl asn1parse -in pca-cert.pem
index 94f1a5e..a9aa085 100644 (file)
@@ -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<server.pem> 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>.
index fc192b2..4e095c2 100644 (file)
@@ -56,7 +56,7 @@ This specifies the host and optional port to connect to.
 =item B<-www> I<page>
 
 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<index.html> 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.
 
index 6e9087b..d879f49 100644 (file)
@@ -526,11 +526,11 @@ public key certificate identifier. Default is sha256. (Optional)
 
 All the examples below presume that B<OPENSSL_CONF> is set to a proper
 configuration file, e.g. the example configuration file
-openssl/apps/openssl.cnf will do.
+F<openssl/apps/openssl.cnf> will do.
 
 =head2 Timestamp Request
 
-To create a timestamp request for design1.txt with SHA-256 digest,
+To create a timestamp request for F<design1.txt> 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<design2.txt>, 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<req(1)>, L<ca(1)>, and L<x509(1)> 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<cacert.pem> contains the certificate of the CA,
+F<tsacert.pem> is the signing certificate issued by F<cacert.pem> and
+F<tsakey.pem> is the private key of the TSA.
 
 To create a timestamp response for a request:
 
index 10595db..3ebe56b 100644 (file)
@@ -135,37 +135,37 @@ arguments.
 
 =head1 EXAMPLES
 
-The examples below presume that B<file1.tsq> and B<file2.tsq> contain valid
+The examples below presume that F<file1.tsq> and F<file2.tsq> 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<file1.tsq> over HTTP, output is written to
+F<file1.tsr>:
 
   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<file1.tsq> and F<file2.tsq> over HTTP showing
+progress, output is written to F<file1.reply> and F<file2.reply> 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<file3.tsq>, send it to the server and
+write the response to F<file3.tsr>:
 
   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<file1.tsq> 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<file1.tsq> over HTTPS with certificate-based
+client authentication (it will ask for the passphrase if F<client_key.pem> is
 protected):
 
   tsget -h https://tsa.opentsa.org:8443/tsa -C cacerts.pem \
index 0dd27c4..81493a0 100644 (file)
@@ -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<< <openssl/x509_vfy.h> >>.
 Some of the error codes are defined but never returned: these are described
 as "unused".
 
index 5fcff0a..8da1601 100644 (file)
@@ -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<mycacert.pem> it expects to find a serial number file called
+F<mycacert.srl>.
 
 =item B<-CAcreateserial>
 
index fad0e85..8a31f09 100644 (file)
@@ -48,7 +48,7 @@ arguments and have a B<-config> option to specify that file.
 The environment variable B<OPENSSL_CONF> can be used to specify
 the location of the file.
 If the environment variable is not specified, then the file is named
-B<openssl.cnf> in the default certificate storage area, whose value
+F<openssl.cnf> in the default certificate storage area, whose value
 depends on the configuration flags specified when the OpenSSL
 was built.