Infrastructure for templated doc in POD files

Use new doc-build capabilities
Add -i flag to dofile.
Add doc/man1 to SUBDIRS for the new templated doc files
Rewrite commit a397aca (merged from PR 10118) to use the doc-template stuff.
Put template references in common place
Template options and text come at the end of command-specific options:
opt_x, opt_trust, opt_r (in that order).
Refactor xchain options.
Do doc-nits after building generated sources.

Reviewed-by: Tomas Mraz <tmraz@fedoraproject.org>
Reviewed-by: Richard Levitte <levitte@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/10159)

1 files changed, 948 insertions, 0 deletions

diff --git a/doc/man1/openssl-x509.pod.in b/doc/man1/openssl-x509.pod.in
new file mode 100644
index 0000000000..c99a5b23f0
--- /dev/null
+++ b/doc/man1/openssl-x509.pod.in
@@ -0,0 +1,948 @@
+=pod
+
+=begin comment
+{- join("\n", @autowarntext) -}
+
+=end comment
+
+=head1 NAME
+
+openssl-x509 - Certificate display and signing utility
+
+=head1 SYNOPSIS
+
+B<openssl> B<x509>
+[B<-help>]
+[B<-inform> B<DER>|B<PEM>]
+[B<-outform> B<DER>|B<PEM>]
+[B<-keyform> B<DER>|B<PEM>]
+[B<-CAform> B<DER>|B<PEM>]
+[B<-CAkeyform> B<DER>|B<PEM>]
+[B<-in> I<filename>]
+[B<-out> I<filename>]
+[B<-serial>]
+[B<-hash>]
+[B<-subject_hash>]
+[B<-issuer_hash>]
+[B<-ocspid>]
+[B<-subject>]
+[B<-issuer>]
+[B<-nameopt> I<option>]
+[B<-email>]
+[B<-ocsp_uri>]
+[B<-startdate>]
+[B<-enddate>]
+[B<-purpose>]
+[B<-dates>]
+[B<-checkend> I<num>]
+[B<-modulus>]
+[B<-pubkey>]
+[B<-fingerprint>]
+[B<-alias>]
+[B<-noout>]
+[B<-trustout>]
+[B<-clrtrust>]
+[B<-clrreject>]
+[B<-addtrust> I<arg>]
+[B<-addreject> I<arg>]
+[B<-setalias> I<arg>]
+[B<-days> I<arg>]
+[B<-set_serial> I<n>]
+[B<-signkey> I<filename>]
+[B<-passin> I<arg>]
+[B<-x509toreq>]
+[B<-req>]
+[B<-CA> I<filename>]
+[B<-CAkey> I<filename>]
+[B<-CAcreateserial>]
+[B<-CAserial> I<filename>]
+[B<-new>]
+[B<-force_pubkey> I<filename>]
+[B<-subj> I<arg>]
+[B<-text>]
+[B<-ext> I<extensions>]
+[B<-certopt> I<option>]
+[B<-C>]
+[B<-I<digest>>]
+[B<-clrext>]
+[B<-extfile> I<filename>]
+[B<-extensions> I<section>]
+[B<-sigopt> I<nm>:I<v>]
+[B<-engine> I<id>]
+[B<-preserve_dates>]
+{- $OpenSSL::safe::opt_r_synopsis -}
+
+=for openssl ifdef engine subject_hash_old issuer_hash_old
+
+=head1 DESCRIPTION
+
+This command is a multi purpose certificate utility. It can
+be used to display certificate information, convert certificates to
+various forms, sign certificate requests like a "mini CA" or edit
+certificate trust settings.
+
+Since there are a large number of options they will split up into
+various sections.
+
+=head1 OPTIONS
+
+=head2 Input, Output, and General Purpose Options
+
+=over 4
+
+=item B<-help>
+
+Print out a usage message.
+
+=item B<-inform> B<DER>|B<PEM>, B<-outform> B<DER>|B<PEM>
+
+The input and formats; the default is B<PEM>.
+See L<openssl(1)/Format Options> for details.
+
+The input is normally an X.509 certificate, but this can change if other
+options such as B<-req> are used.
+
+=item B<-in> I<filename>
+
+This specifies the input filename to read a certificate from or standard input
+if this option is not specified.
+
+=item B<-out> I<filename>
+
+This specifies the output filename to write to or standard output by
+default.
+
+=item B<-I<digest>>
+
+The digest to use.
+This affects any signing or display option that uses a message
+digest, such as the B<-fingerprint>, B<-signkey> and B<-CA> options.
+Any digest supported by the L<openssl-dgst(1)> command can be used.
+If not specified then SHA1 is used with B<-fingerprint> or
+the default digest for the signing algorithm is used, typically SHA256.
+
+=item B<-engine> I<id>
+
+Specifying an engine (by its unique I<id> string) will cause this command
+to attempt to obtain a functional reference to the specified engine,
+thus initialising it if needed. The engine will then be set as the default
+for all available algorithms.
+
+=item B<-preserve_dates>
+
+When signing a certificate, preserve the "notBefore" and "notAfter" dates
+instead of adjusting them to current time and duration.
+Cannot be used with the B<-days> option.
+
+{- $OpenSSL::safe::opt_r_synopsis -}
+
+=back
+
+=head2 Display Options
+
+Note: the B<-alias> and B<-purpose> options are also display options
+but are described in the L</Trust Settings> section.
+
+=over 4
+
+=item B<-text>
+
+Prints out the certificate in text form. Full details are output including the
+public key, signature algorithms, issuer and subject names, serial number
+any extensions present and any trust settings.
+
+=item B<-ext> I<extensions>
+
+Prints out the certificate extensions in text form. Extensions are specified
+with a comma separated string, e.g., "subjectAltName,subjectKeyIdentifier".
+See the L<x509v3_config(5)> manual page for the extension names.
+
+=item B<-certopt> I<option>
+
+Customise the output format used with B<-text>. The I<option> argument
+can be a single option or multiple options separated by commas. The
+B<-certopt> switch may be also be used more than once to set multiple
+options. See the L</Text Options> section for more information.
+
+=item B<-noout>
+
+This option prevents output of the encoded version of the certificate.
+
+=item B<-pubkey>
+
+Outputs the certificate's SubjectPublicKeyInfo block in PEM format.
+
+=item B<-modulus>
+
+This option prints out the value of the modulus of the public key
+contained in the certificate.
+
+=item B<-serial>
+
+Outputs the certificate serial number.
+
+=item B<-subject_hash>
+
+Outputs the "hash" of the certificate subject name. This is used in OpenSSL to
+form an index to allow certificates in a directory to be looked up by subject
+name.
+
+=item B<-issuer_hash>
+
+Outputs the "hash" of the certificate issuer name.
+
+=item B<-ocspid>
+
+Outputs the OCSP hash values for the subject name and public key.
+
+=item B<-hash>
+
+Synonym for "-subject_hash" for backward compatibility reasons.
+
+=item B<-subject_hash_old>
+
+Outputs the "hash" of the certificate subject name using the older algorithm
+as used by OpenSSL before version 1.0.0.
+
+=item B<-issuer_hash_old>
+
+Outputs the "hash" of the certificate issuer name using the older algorithm
+as used by OpenSSL before version 1.0.0.
+
+=item B<-subject>
+
+Outputs the subject name.
+
+=item B<-issuer>
+
+Outputs the issuer name.
+
+=item B<-nameopt> I<option>
+
+Option which determines how the subject or issuer names are displayed. The
+I<option> argument can be a single option or multiple options separated by
+commas.  Alternatively the B<-nameopt> switch may be used more than once to
+set multiple options. See the L</Name Options> section for more information.
+
+=item B<-email>
+
+Outputs the email address(es) if any.
+
+=item B<-ocsp_uri>
+
+Outputs the OCSP responder address(es) if any.
+
+=item B<-startdate>
+
+Prints out the start date of the certificate, that is the notBefore date.
+
+=item B<-enddate>
+
+Prints out the expiry date of the certificate, that is the notAfter date.
+
+=item B<-dates>
+
+Prints out the start and expiry dates of a certificate.
+
+=item B<-checkend> I<arg>
+
+Checks if the certificate expires within the next I<arg> seconds and exits
+nonzero if yes it will expire or zero if not.
+
+=item B<-fingerprint>
+
+Calculates and outputs the digest of the DER encoded version of the entire
+certificate (see digest options).
+This is commonly called a "fingerprint". Because of the nature of message
+digests, the fingerprint of a certificate is unique to that certificate and
+two certificates with the same fingerprint can be considered to be the same.
+
+=item B<-C>
+
+This outputs the certificate in the form of a C source file.
+
+=back
+
+=head2 Trust Settings
+
+A B<trusted certificate> is an ordinary certificate which has several
+additional pieces of information attached to it such as the permitted
+and prohibited uses of the certificate and an "alias".
+
+Normally when a certificate is being verified at least one certificate
+must be "trusted". By default a trusted certificate must be stored
+locally and must be a root CA: any certificate chain ending in this CA
+is then usable for any purpose.
+
+Trust settings currently are only used with a root CA. They allow a finer
+control over the purposes the root CA can be used for. For example a CA
+may be trusted for SSL client but not SSL server use.
+
+See the description in L<openssl-verify(1)> for more information
+on the meaning of trust settings.
+
+Future versions of OpenSSL will recognize trust settings on any
+certificate: not just root CAs.
+
+
+=over 4
+
+=item B<-trustout>
+
+Output a B<trusted> certificate rather than an ordinary. An ordinary
+or trusted certificate can be input but by default an ordinary
+certificate is output and any trust settings are discarded. With the
+B<-trustout> option a trusted certificate is output. A trusted
+certificate is automatically output if any trust settings are modified.
+
+=item B<-setalias> I<arg>
+
+Sets the alias of the certificate. This will allow the certificate
+to be referred to using a nickname for example "Steve's Certificate".
+
+=item B<-alias>
+
+Outputs the certificate alias, if any.
+
+=item B<-clrtrust>
+
+Clears all the permitted or trusted uses of the certificate.
+
+=item B<-clrreject>
+
+Clears all the prohibited or rejected uses of the certificate.
+
+=item B<-addtrust> I<arg>
+
+Adds a trusted certificate use.
+Any object name can be used here but currently only B<clientAuth> (SSL client
+use), B<serverAuth> (SSL server use), B<emailProtection> (S/MIME email) and
+B<anyExtendedKeyUsage> are used.
+As of OpenSSL 1.1.0, the last of these blocks all purposes when rejected or
+enables all purposes when trusted.
+Other OpenSSL applications may define additional uses.
+
+=item B<-addreject> I<arg>
+
+Adds a prohibited use. It accepts the same values as the B<-addtrust>
+option.
+
+=item B<-purpose>
+
+This option performs tests on the certificate extensions and outputs
+the results. For a more complete description see the
+L</CERTIFICATE EXTENSIONS> section.
+
+=back
+
+=head2 Signing Options
+
+This command can be used to sign certificates and requests: it
+can thus behave like a "mini CA".
+
+=over 4
+
+=item B<-signkey> I<filename>
+
+This option causes the input file to be self signed using the supplied
+private key.
+
+It sets the issuer name to the subject name (i.e., makes it self-issued)
+and changes the public key to the supplied value (unless overridden by
+B<-force_pubkey>). It sets the validity start date to the current time
+and the end date to a value determined by the B<-days> option.
+It retains any certificate extensions unless the B<-clrext> option is supplied;
+this includes, for example, any existing key identifier extensions.
+
+=item B<-sigopt> I<nm>:I<v>
+
+Pass options to the signature algorithm during sign or verify operations.
+Names and values of these options are algorithm-specific.
+
+=item B<-passin> I<arg>
+
+The key password source. For more information about the format of I<arg>
+see L<openssl(1)/Pass Phrase Options>.
+
+=item B<-clrext>
+
+Delete any extensions from a certificate. This option is used when a
+certificate is being created from another certificate (for example with
+the B<-signkey> or the B<-CA> options). Normally all extensions are
+retained.
+
+=item B<-keyform> B<DER>|B<PEM>
+
+The key format; the default is B<PEM>.
+See L<openssl(1)/Format Options> for details.
+
+=item B<-CAform> B<DER>|B<PEM>, B<-CAkeyform> B<DER>|B<PEM>
+
+The format for the CA certificate and key; the default is B<PEM>.
+See L<openssl(1)/Format Options> for details.
+
+=item B<-days> I<arg>
+
+Specifies the number of days to make a certificate valid for. The default
+is 30 days. Cannot be used with the B<-preserve_dates> option.
+
+=item B<-x509toreq>
+
+Converts a certificate into a certificate request. The B<-signkey> option
+is used to pass the required private key.
+
+=item B<-req>
+
+By default a certificate is expected on input. With this option a
+certificate request is expected instead.
+
+=item B<-set_serial> I<n>
+
+Specifies the serial number to use. This option can be used with either
+the B<-signkey> or B<-CA> options. If used in conjunction with the B<-CA>
+option the serial number file (as specified by the B<-CAserial> or
+B<-CAcreateserial> options) is not used.
+
+The serial number can be decimal or hex (if preceded by C<0x>).
+
+=item B<-CA> I<filename>
+
+Specifies the CA certificate to be used for signing. When this option is
+present, this command behaves like a "mini CA". The input file is signed by
+this CA using this option: that is its issuer name is set to the subject name
+of the CA and it is digitally signed using the CAs private key.
+
+This option is normally combined with the B<-req> option. Without the
+B<-req> option the input is a certificate which must be self signed.
+
+=item B<-CAkey> I<filename>
+
+Sets the CA private key to sign a certificate with. If this option is
+not specified then it is assumed that the CA private key is present in
+the CA certificate file.
+
+=item B<-CAserial> I<filename>
+
+Sets the CA serial number file to use.
+
+When the B<-CA> option is used to sign a certificate it uses a serial
+number specified in a file. This file consists of one line containing
+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
+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>
+
+With this option the CA serial number file is created if it does not exist:
+it will contain the serial number "02" and the certificate being signed will
+have the 1 as its serial number. If the B<-CA> option is specified
+and the serial number file does not exist a random number is generated;
+this is the recommended practice.
+
+=item B<-extfile> I<filename>
+
+File containing certificate extensions to use. If not specified then
+no extensions are added to the certificate.
+
+=item B<-extensions> I<section>
+
+The section to add certificate extensions from. If this option is not
+specified then the extensions should either be contained in the unnamed
+(default) section or the default section should contain a variable called
+"extensions" which contains the section to use. See the
+L<x509v3_config(5)> manual page for details of the
+extension section format.
+
+=item B<-new>
+
+Generate a certificate from scratch, not using an input certificate
+or certificate request. So the B<-in> option must not be used in this case.
+Instead, the B<-subj> and <-force_pubkey> options need to be given.
+
+=item B<-force_pubkey> I<filename>
+
+When a certificate is created set its public key to the key in I<filename>
+instead of the key contained in the input or given with the B<-signkey> option.
+
+This option is useful for creating self-issued certificates that are not
+self-signed, for instance when the key cannot be used for signing, such as DH.
+It can also be used in conjunction with b<-new> and B<-subj> to directly
+generate a certificate containing any desired public key.
+
+The format of the key file can be specified using the B<-keyform> option.
+
+=item B<-subj> I<arg>
+
+When a certificate is created set its subject name to the given value.
+The arg must be formatted as C</type0=value0/type1=value1/type2=...>.
+Keyword characters may be escaped by \ (backslash), and whitespace is retained.
+Empty values are permitted, but the corresponding type will not be included
+in the certificate. Giving a single C</> will lead to an empty sequence of RDNs
+(a NULL subject DN).
+
+Unless the B<-CA> option is given the issuer is set to the same value.
+
+This option can be used in conjunction with the B<-force_pubkey> option
+to create a certificate even without providing an input certificate
+or certificate request.
+
+=back
+
+=head2 Name Options
+
+The B<-nameopt> command line switch determines how the subject and issuer
+names are displayed. If no B<-nameopt> switch is present the default "oneline"
+format is used which is compatible with previous versions of OpenSSL.
+Each option is described in detail below, all options can be preceded by
+a B<-> to turn the option off. Only the first four will normally be used.
+
+=over 4
+
+=item B<compat>
+
+Use the old format.
+
+=item B<RFC2253>
+
+Displays names compatible with RFC2253 equivalent to B<esc_2253>, B<esc_ctrl>,
+B<esc_msb>, B<utf8>, B<dump_nostr>, B<dump_unknown>, B<dump_der>,
+B<sep_comma_plus>, B<dn_rev> and B<sname>.
+
+=item B<oneline>
+
+A oneline format which is more readable than RFC2253. It is equivalent to
+specifying the  B<esc_2253>, B<esc_ctrl>, B<esc_msb>, B<utf8>, B<dump_nostr>,
+B<dump_der>, B<use_quote>, B<sep_comma_plus_space>, B<space_eq> and B<sname>
+options.  This is the I<default> of no name options are given explicitly.
+
+=item B<multiline>
+
+A multiline format. It is equivalent B<esc_ctrl>, B<esc_msb>, B<sep_multiline>,
+B<space_eq>, B<lname> and B<align>.
+
+=item B<esc_2253>
+
+Escape the "special" characters required by RFC2253 in a field. That is
+B<,+"E<lt>E<gt>;>. Additionally B<#> is escaped at the beginning of a string
+and a space character at the beginning or end of a string.
+
+=item B<esc_2254>
+
+Escape the "special" characters required by RFC2254 in a field. That is
+the B<NUL> character as well as and B<()*>.
+
+=item B<esc_ctrl>
+
+Escape control characters. That is those with ASCII values less than
+0x20 (space) and the delete (0x7f) character. They are escaped using the
+RFC2253 \XX notation (where XX are two hex digits representing the
+character value).
+
+=item B<esc_msb>
+
+Escape characters with the MSB set, that is with ASCII values larger than
+127.
+
+=item B<use_quote>
+
+Escapes some characters by surrounding the whole string with B<"> characters,
+without the option all escaping is done with the B<\> character.
+
+=item B<utf8>
+
+Convert all strings to UTF8 format first. This is required by RFC2253. If
+you are lucky enough to have a UTF8 compatible terminal then the use
+of this option (and B<not> setting B<esc_msb>) may result in the correct
+display of multibyte (international) characters. Is this option is not
+present then multibyte characters larger than 0xff will be represented
+using the format \UXXXX for 16 bits and \WXXXXXXXX for 32 bits.
+Also if this option is off any UTF8Strings will be converted to their
+character form first.
+
+=item B<ignore_type>
+
+This option does not attempt to interpret multibyte characters in any
+way. That is their content octets are merely dumped as though one octet
+represents each character. This is useful for diagnostic purposes but
+will result in rather odd looking output.
+
+=item B<show_type>
+
+Show the type of the ASN1 character string. The type precedes the
+field contents. For example "BMPSTRING: Hello World".
+
+=item B<dump_der>
+
+When this option is set any fields that need to be hexdumped will
+be dumped using the DER encoding of the field. Otherwise just the
+content octets will be displayed. Both options use the RFC2253
+B<#XXXX...> format.
+
+=item B<dump_nostr>
+
+Dump non character string types (for example OCTET STRING) if this
+option is not set then non character string types will be displayed
+as though each content octet represents a single character.
+
+=item B<dump_all>
+
+Dump all fields. This option when used with B<dump_der> allows the
+DER encoding of the structure to be unambiguously determined.
+
+=item B<dump_unknown>
+
+Dump any field whose OID is not recognised by OpenSSL.
+
+=item B<sep_comma_plus>, B<sep_comma_plus_space>, B<sep_semi_plus_space>,
+B<sep_multiline>
+
+These options determine the field separators. The first character is
+between Relative Distinguished Names (RDNs) and the second is between
+multiple Attribute Value Assertions (AVAs, multiple AVAs are
+very rare and their use is discouraged). The options ending in
+"space" additionally place a space after the separator to make it
+more readable. The B<sep_multiline> uses a linefeed character for
+the RDN separator and a spaced B<+> for the AVA separator. It also
+indents the fields by four characters. If no field separator is specified
+then B<sep_comma_plus_space> is used by default.
+
+=item B<dn_rev>
+
+Reverse the fields of the DN. This is required by RFC2253. As a side
+effect this also reverses the order of multiple AVAs but this is
+permissible.
+
+=item B<nofname>, B<sname>, B<lname>, B<oid>
+
+These options alter how the field name is displayed. B<nofname> does
+not display the field at all. B<sname> uses the "short name" form
+(CN for commonName for example). B<lname> uses the long form.
+B<oid> represents the OID in numerical form and is useful for
+diagnostic purpose.
+
+=item B<align>
+
+Align field values for a more readable output. Only usable with
+B<sep_multiline>.
+
+=item B<space_eq>
+
+Places spaces round the B<=> character which follows the field
+name.
+
+=back
+
+=head2 Text Options
+
+As well as customising the name output format, it is also possible to
+customise the actual fields printed using the B<certopt> options when
+the B<text> option is present. The default behaviour is to print all fields.
+
+=over 4
+
+=item B<compatible>
+
+Use the old format. This is equivalent to specifying no output options at all.
+
+=item B<no_header>
+
+Don't print header information: that is the lines saying "Certificate"
+and "Data".
+
+=item B<no_version>
+
+Don't print out the version number.
+
+=item B<no_serial>
+
+Don't print out the serial number.
+
+=item B<no_signame>
+
+Don't print out the signature algorithm used.
+
+=item B<no_validity>
+
+Don't print the validity, that is the B<notBefore> and B<notAfter> fields.
+
+=item B<no_subject>
+
+Don't print out the subject name.
+
+=item B<no_issuer>
+
+Don't print out the issuer name.
+
+=item B<no_pubkey>
+
+Don't print out the public key.
+
+=item B<no_sigdump>
+
+Don't give a hexadecimal dump of the certificate signature.
+
+=item B<no_aux>
+
+Don't print out certificate trust information.
+
+=item B<no_extensions>
+
+Don't print out any X509V3 extensions.
+
+=item B<ext_default>
+
+Retain default extension behaviour: attempt to print out unsupported
+certificate extensions.
+
+=item B<ext_error>
+
+Print an error message for unsupported certificate extensions.
+
+=item B<ext_parse>
+
+ASN1 parse unsupported extensions.
+
+=item B<ext_dump>
+
+Hex dump unsupported extensions.
+
+=item B<ca_default>
+
+The value used by L<openssl-ca(1)>, equivalent to B<no_issuer>, B<no_pubkey>,
+B<no_header>, and B<no_version>.
+
+=back
+
+=head1 EXAMPLES
+
+Note: in these examples the '\' means the example should be all on one
+line.
+
+Display the contents of a certificate:
+
+ openssl x509 -in cert.pem -noout -text
+
+Display the "Subject Alternative Name" extension of a certificate:
+
+ openssl x509 -in cert.pem -noout -ext subjectAltName
+
+Display more extensions of a certificate:
+
+ openssl x509 -in cert.pem -noout -ext subjectAltName,nsCertType
+
+Display the certificate serial number:
+
+ openssl x509 -in cert.pem -noout -serial
+
+Display the certificate subject name:
+
+ openssl x509 -in cert.pem -noout -subject
+
+Display the certificate subject name in RFC2253 form:
+
+ openssl x509 -in cert.pem -noout -subject -nameopt RFC2253
+
+Display the certificate subject name in oneline form on a terminal
+supporting UTF8:
+
+ openssl x509 -in cert.pem -noout -subject -nameopt oneline,-esc_msb
+
+Display the certificate SHA1 fingerprint:
+
+ openssl x509 -sha1 -in cert.pem -noout -fingerprint
+
+Convert a certificate from PEM to DER format:
+
+ openssl x509 -in cert.pem -inform PEM -out cert.der -outform DER
+
+Convert a certificate to a certificate request:
+
+ openssl x509 -x509toreq -in cert.pem -out req.pem -signkey key.pem
+
+Convert a certificate request into a self signed certificate using
+extensions for a CA:
+
+ openssl x509 -req -in careq.pem -extfile openssl.cnf -extensions v3_ca \
+        -signkey key.pem -out cacert.pem
+
+Sign a certificate request using the CA certificate above and add user
+certificate extensions:
+
+ openssl x509 -req -in req.pem -extfile openssl.cnf -extensions v3_usr \
+        -CA cacert.pem -CAkey key.pem -CAcreateserial
+
+
+Set a certificate to be trusted for SSL client use and change set its alias to
+"Steve's Class 1 CA"
+
+ openssl x509 -in cert.pem -addtrust clientAuth \
+        -setalias "Steve's Class 1 CA" -out trust.pem
+
+=head1 NOTES
+
+The conversion to UTF8 format used with the name options assumes that
+T61Strings use the ISO8859-1 character set. This is wrong but Netscape
+and MSIE do this as do many certificates. So although this is incorrect
+it is more likely to display the majority of certificates correctly.
+
+The B<-email> option searches the subject name and the subject alternative
+name extension. Only unique email addresses will be printed out: it will
+not print the same address more than once.
+
+=head1 CERTIFICATE EXTENSIONS
+
+The B<-purpose> option checks the certificate extensions and determines
+what the certificate can be used for. The actual checks done are rather
+complex and include various hacks and workarounds to handle broken
+certificates and software.
+
+The same code is used when verifying untrusted certificates in chains
+so this section is useful if a chain is rejected by the verify code.
+
+The basicConstraints extension CA flag is used to determine whether the
+certificate can be used as a CA. If the CA flag is true then it is a CA,
+if the CA flag is false then it is not a CA. B<All> CAs should have the
+CA flag set to true.
+
+If the basicConstraints extension is absent then the certificate is
+considered to be a "possible CA" other extensions are checked according
+to the intended use of the certificate. A warning is given in this case
+because the certificate should really not be regarded as a CA: however
+it is allowed to be a CA to work around some broken software.
+
+If the certificate is a V1 certificate (and thus has no extensions) and
+it is self signed it is also assumed to be a CA but a warning is again
+given: this is to work around the problem of Verisign roots which are V1
+self signed certificates.
+
+If the keyUsage extension is present then additional restraints are
+made on the uses of the certificate. A CA certificate B<must> have the
+keyCertSign bit set if the keyUsage extension is present.
+
+The extended key usage extension places additional restrictions on the
+certificate uses. If this extension is present (whether critical or not)
+the key can only be used for the purposes specified.
+
+A complete description of each test is given below. The comments about
+basicConstraints and keyUsage and V1 certificates above apply to B<all>
+CA certificates.
+
+
+=over 4
+
+=item B<SSL Client>
+
+The extended key usage extension must be absent or include the "web client
+authentication" OID.  keyUsage must be absent or it must have the
+digitalSignature bit set. Netscape certificate type must be absent or it must
+have the SSL client bit set.
+
+=item B<SSL Client CA>
+
+The extended key usage extension must be absent or include the "web client
+authentication" OID. Netscape certificate type must be absent or it must have
+the SSL CA bit set: this is used as a work around if the basicConstraints
+extension is absent.
+
+=item B<SSL Server>
+
+The extended key usage extension must be absent or include the "web server
+authentication" and/or one of the SGC OIDs.  keyUsage must be absent or it
+must have the digitalSignature, the keyEncipherment set or both bits set.
+Netscape certificate type must be absent or have the SSL server bit set.
+
+=item B<SSL Server CA>
+
+The extended key usage extension must be absent or include the "web server
+authentication" and/or one of the SGC OIDs.  Netscape certificate type must
+be absent or the SSL CA bit must be set: this is used as a work around if the
+basicConstraints extension is absent.
+
+=item B<Netscape SSL Server>
+
+For Netscape SSL clients to connect to an SSL server it must have the
+keyEncipherment bit set if the keyUsage extension is present. This isn't
+always valid because some cipher suites use the key for digital signing.
+Otherwise it is the same as a normal SSL server.
+
+=item B<Common S/MIME Client Tests>
+
+The extended key usage extension must be absent or include the "email
+protection" OID. Netscape certificate type must be absent or should have the
+S/MIME bit set. If the S/MIME bit is not set in Netscape certificate type
+then the SSL client bit is tolerated as an alternative but a warning is shown:
+this is because some Verisign certificates don't set the S/MIME bit.
+
+=item B<S/MIME Signing>
+
+In addition to the common S/MIME client tests the digitalSignature bit or
+the nonRepudiation bit must be set if the keyUsage extension is present.
+
+=item B<S/MIME Encryption>
+
+In addition to the common S/MIME tests the keyEncipherment bit must be set
+if the keyUsage extension is present.
+
+=item B<S/MIME CA>
+
+The extended key usage extension must be absent or include the "email
+protection" OID. Netscape certificate type must be absent or must have the
+S/MIME CA bit set: this is used as a work around if the basicConstraints
+extension is absent.
+
+=item B<CRL Signing>
+
+The keyUsage extension must be absent or it must have the CRL signing bit
+set.
+
+=item B<CRL Signing CA>
+
+The normal CA tests apply. Except in this case the basicConstraints extension
+must be present.
+
+=back
+
+=head1 BUGS
+
+Extensions in certificates are not transferred to certificate requests and
+vice versa.
+
+It is possible to produce invalid certificates or requests by specifying the
+wrong private key or using inconsistent options in some cases: these should
+be checked.
+
+There should be options to explicitly set such things as start and end
+dates rather than an offset from the current time.
+
+=head1 SEE ALSO
+
+L<openssl(1)>,
+L<openssl-req(1)>,
+L<openssl-ca(1)>,
+L<openssl-genrsa(1)>,
+L<openssl-gendsa(1)>,
+L<openssl-verify(1)>,
+L<x509v3_config(5)>
+
+=head1 HISTORY
+
+The hash algorithm used in the B<-subject_hash> and B<-issuer_hash> options
+before OpenSSL 1.0.0 was based on the deprecated MD5 algorithm and the encoding
+of the distinguished name. In OpenSSL 1.0.0 and later it is based on a canonical
+version of the DN using SHA1. This means that any directories using the old
+form must have their links rebuilt using L<openssl-rehash(1)> or similar.
+
+=head1 COPYRIGHT
+
+Copyright 2000-2019 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the Apache License 2.0 (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<https://www.openssl.org/source/license.html>.
+
+=cut