apps/x509.c: Major code, user guidance, and documentation cleanup

This brings the options in help output and doc in reasonable order
and fixes various corner cases of option use combinations

Reviewed-by: Tomas Mraz <tomas@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/13711)

1 files changed, 340 insertions, 316 deletions

diff --git a/doc/man1/openssl-x509.pod.in b/doc/man1/openssl-x509.pod.in
index e708486508..1540162ba6 100644
--- a/doc/man1/openssl-x509.pod.in
+++ b/doc/man1/openssl-x509.pod.in
@@ -9,70 +9,70 @@ openssl-x509 - Certificate display and signing command
 
 B<openssl> B<x509>
 [B<-help>]
+[B<-in> I<filename>|I<uri>]
+[B<-passin> I<arg>]
+[B<-new>]
+[B<-x509toreq>]
+[B<-req>]
 [B<-inform> B<DER>|B<PEM>]
-[B<-outform> B<DER>|B<PEM>]
+[B<-vfyopt> I<nm>:I<v>]
+[B<-signkey> I<filename>|I<uri>]
 [B<-keyform> B<DER>|B<PEM>|B<P12>|B<ENGINE>]
-[B<-CAform> B<DER>|B<PEM>|B<P12>]
-[B<-CAkeyform> B<DER>|B<PEM>|B<P12>|B<ENGINE>]
-[B<-in> I<filename>]
 [B<-out> I<filename>]
+[B<-outform> B<DER>|B<PEM>]
+[B<-nocert>]
+[B<-noout>]
+[B<-text>]
+[B<-certopt> I<option>]
+[B<-fingerprint>]
+[B<-alias>]
 [B<-serial>]
+[B<-startdate>]
+[B<-enddate>]
+[B<-dates>]
+[B<-subject>]
+[B<-issuer>]
+{- $OpenSSL::safe::opt_name_synopsis -}
+[B<-email>]
 [B<-hash>]
 [B<-subject_hash>]
 [B<-subject_hash_old>]
 [B<-issuer_hash>]
 [B<-issuer_hash_old>]
+[B<-ext> I<extensions>]
 [B<-ocspid>]
-[B<-subject>]
-[B<-issuer>]
-[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>|I<uri>]
-[B<-badsig>]
-[B<-passin> I<arg>]
-[B<-x509toreq>]
-[B<-req>]
-[B<-CA> I<filename>]
-[B<-CAkey> I<filename>|I<uri>]
-[B<-CAcreateserial>]
-[B<-CAserial> I<filename>]
-[B<-new>]
-[B<-next_serial>]
-[B<-nocert>]
-[B<-force_pubkey> I<filename>]
-[B<-subj> I<arg>]
-[B<-text>]
-[B<-ext> I<extensions>]
-[B<-certopt> I<option>]
+[B<-modulus>]
+[B<-checkend> I<num>]
 [B<-checkhost> I<host>]
 [B<-checkemail> I<host>]
 [B<-checkip> I<ipaddr>]
-[B<-I<digest>>]
+[B<-set_serial> I<n>]
+[B<-next_serial>]
+[B<-days> I<arg>]
+[B<-preserve_dates>]
+[B<-subj> I<arg>]
+[B<-force_pubkey> I<filename>]
 [B<-clrext>]
 [B<-extfile> I<filename>]
 [B<-extensions> I<section>]
 [B<-sigopt> I<nm>:I<v>]
-[B<-vfyopt> I<nm>:I<v>]
-[B<-preserve_dates>]
-{- $OpenSSL::safe::opt_name_synopsis -}
+[B<-badsig>]
+[B<-I<digest>>]
+[B<-CA> I<filename>|I<uri>]
+[B<-CAform> B<DER>|B<PEM>|B<P12>]
+[B<-CAkey> I<filename>|I<uri>]
+[B<-CAkeyform> B<DER>|B<PEM>|B<P12>|B<ENGINE>]
+[B<-CAserial> I<filename>]
+[B<-CAcreateserial>]
+[B<-trustout>]
+[B<-setalias> I<arg>]
+[B<-clrtrust>]
+[B<-addtrust> I<arg>]
+[B<-clrreject>]
+[B<-addreject> I<arg>]
 {- $OpenSSL::safe::opt_r_synopsis -}
 {- $OpenSSL::safe::opt_engine_synopsis -}{- $OpenSSL::safe::opt_provider_synopsis -}
 
@@ -80,10 +80,11 @@ B<openssl> B<x509>
 
 =head1 DESCRIPTION
 
-This command is a multi-purposes certificate command. 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.
+This command is a multi-purposes certificate handling command.
+It can be used to print certificate information,
+convert certificates to various forms, edit certificate trust settings,
+generate certificates from scratch or from certificating requests
+and then self-signing them or signing them like a "micro CA".
 
 Since there are a large number of options they will split up into
 various sections.
@@ -98,356 +99,369 @@ various sections.
 
 Print out a usage message.
 
+=item B<-in> I<filename>|I<uri>
+
+If the B<-req> option is not used this specifies the input
+to read a certificate from or standard input if this option is not specified.
+With the B<-req> option this specifies a certificate request file.
+
+=item B<-passin> I<arg>
+
+The key and certificate file password source.
+For more information about the format of I<arg>
+see L<openssl-passphrase-options(1)>.
+
+=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> option needs to be given.
+The public key to include can be given with the B<-force_pubkey> option
+and defaults to the key given with the B<-signkey> option,
+which implies self-signature.
+
+=item B<-x509toreq>
+
+Output a certificate request (rather than a certificate).
+The B<-signkey> option must be used to provide the private key for self-signing;
+the corresponding public key is placed in the subjectPKInfo field.
+
+Any X.509 extensions included in an input file are ignored.
+X.509 extensions to be added can be specified using the B<-extfile> option.
+
+=item B<-req>
+
+By default a certificate is expected on input.
+With this option a certificate request is expected instead,
+which is transformed into a certificate.
+
+Any X.509 extensions included in the request file are ignored.
+X.509 extensions to be added can be specified using the B<-extfile> option.
+
 =item B<-inform> B<DER>|B<PEM>
 
-The CSR input format; the default is B<PEM>.
+The CSR input file format; the default is B<PEM>.
 See L<openssl-format-options(1)> for details.
 
-The input is normally an X.509 certificate file of any format,
-but this can change if other options such as B<-req> are used.
+=item B<-vfyopt> I<nm>:I<v>
 
-B<-outform> B<DER>|B<PEM>
+Pass options to the signature algorithm during verify operations.
+Names and values of these options are algorithm-specific.
 
-The output format; the default is B<PEM>.
-See L<openssl-format-options(1)> for details.
+=item B<-signkey> I<filename>|I<uri>
 
-=item B<-in> I<filename>
+This option causes the new certificate or certificate request
+to be self-signed using the supplied private key.
+This cannot be used in conjunction with the B<-CA> option.
 
-This specifies the input filename to read a certificate from or standard input
-if this option is not specified.
+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>).
+Unless the B<-preserve_dates> option is supplied,
+it sets the validity start date to the current time
+and the end date to a value determined by the B<-days> option.
+Unless the B<-clrext> option is supplied, it retains all certificate extensions
+except for any subject identifier and authority key identifier.
+For those, new values are generated unless prohibited by configuration.
 
-=item B<-out> I<filename>
+=item B<-keyform> B<DER>|B<PEM>|B<P12>|B<ENGINE>
 
-This specifies the output filename to write to or standard output by
-default.
+The key input format; the default is B<PEM>.
+The only value with effect is B<ENGINE>; all others have become obsolete.
+See L<openssl-format-options(1)> for details.
 
-=item B<-I<digest>>
+=item B<-out> I<filename>
 
-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.
+This specifies the output filename to write to or standard output by default.
 
-=item B<-preserve_dates>
+=item B<-outform> B<DER>|B<PEM>
 
-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.
+The output format; the default is B<PEM>.
+See L<openssl-format-options(1)> for details.
 
-{- $OpenSSL::safe::opt_r_synopsis -}
+=item B<-nocert>
 
-{- $OpenSSL::safe::opt_engine_item -}
+Do not output a certificate (except for printing as requested by below options).
 
-{- $OpenSSL::safe::opt_provider_item -}
+=item B<-noout>
+
+This option prevents output except for printing as requested by below options.
 
 =back
 
-=head2 Display Options
+=head2 Certificate Printing Options
 
-Note: the B<-alias> and B<-purpose> options are also display options
+Note: the B<-alias> and B<-purpose> options are also printing 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
+Prints out the certificate in text form. Full details are printed 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<-checkhost> I<host>
+Customise the print 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 Printing Flags> section for more information.
 
-Check that the certificate matches the specified host.
+=item B<-fingerprint>
 
-=item B<-checkemail> I<email>
+Calculates and prints 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.
 
-Check that the certificate matches the specified email address.
+=item B<-alias>
 
-=item B<-checkip> I<ipaddr>
+Prints the certificate "alias" (nickname), if any.
 
-Check that the certificate matches the specified IP address.
+=item B<-serial>
 
-=item B<-noout>
+Prints the certificate serial number.
 
-This option prevents output of the encoded version of the certificate.
+=item B<-startdate>
 
-=item B<-pubkey>
+Prints out the start date of the certificate, that is the notBefore date.
 
-Outputs the certificate's SubjectPublicKeyInfo block in PEM format.
+=item B<-enddate>
 
-=item B<-modulus>
+Prints out the expiry date of the certificate, that is the notAfter date.
 
-This option prints out the value of the modulus of the public key
-contained in the certificate.
+=item B<-dates>
 
-=item B<-serial>
+Prints out the start and expiry dates of a certificate.
 
-Outputs the certificate serial number.
+=item B<-subject>
 
-=item B<-subject_hash>
+Prints the subject name.
 
-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>
 
-=item B<-issuer_hash>
+Prints the issuer name.
 
-Outputs the "hash" of the certificate issuer name.
+{- $OpenSSL::safe::opt_name_item -}
 
-=item B<-ocspid>
+=item B<-email>
 
-Outputs the OCSP hash values for the subject name and public key.
+Prints the email address(es) if any.
 
 =item B<-hash>
 
 Synonym for "-subject_hash" for backward compatibility reasons.
 
+=item B<-subject_hash>
+
+Prints 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<-subject_hash_old>
 
-Outputs the "hash" of the certificate subject name using the older algorithm
+Prints the "hash" of the certificate subject name using the older algorithm
 as used by OpenSSL before version 1.0.0.
 
+=item B<-issuer_hash>
+
+Prints the "hash" of the certificate issuer name.
+
 =item B<-issuer_hash_old>
 
-Outputs the "hash" of the certificate issuer name using the older algorithm
+Prints the "hash" of the certificate issuer name using the older algorithm
 as used by OpenSSL before version 1.0.0.
 
-=item B<-subject>
+=item B<-ext> I<extensions>
 
-Outputs the subject name.
+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<-issuer>
+=item B<-ocspid>
 
-Outputs the issuer name.
+Prints the OCSP hash values for the subject name and public key.
 
-{- $OpenSSL::safe::opt_name_item -}
+=item B<-ocsp_uri>
 
-=item B<-email>
+Prints the OCSP responder address(es) if any.
 
-Outputs the email address(es) if any.
+=item B<-purpose>
 
-=item B<-ocsp_uri>
+This option performs tests on the certificate extensions and prints
+the results. For a more complete description see the
+L</CERTIFICATE EXTENSIONS> section.
 
-Outputs the OCSP responder address(es) if any.
+=item B<-pubkey>
 
-=item B<-startdate>
+Prints the certificate's SubjectPublicKeyInfo block in PEM format.
 
-Prints out the start date of the certificate, that is the notBefore date.
+=item B<-modulus>
 
-=item B<-enddate>
+This option prints out the value of the modulus of the public key
+contained in the certificate.
 
-Prints out the expiry date of the certificate, that is the notAfter date.
+=back
 
-=item B<-dates>
+=head2 Certificate Checking Options
 
-Prints out the start and expiry dates of a certificate.
+=over 4
 
 =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>
+=item B<-checkhost> I<host>
 
-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.
+Check that the certificate matches the specified host.
 
-=back
+=item B<-checkemail> I<email>
 
-=head2 Trust Settings
+Check that the certificate matches the specified email address.
 
-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".
+=item B<-checkip> I<ipaddr>
 
-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.
+Check that the certificate matches the specified IP address.
 
-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.
+=back
 
-See the description in L<openssl-verify(1)> for more information
-on the meaning of trust settings.
+=head2 Certificate Output Options
 
-Future versions of OpenSSL will recognize trust settings on any
-certificate: not just root CAs.
+=over 4
 
+=item B<-set_serial> I<n>
 
-=over 4
+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> option) is not used.
 
-=item B<-trustout>
+The serial number can be decimal or hex (if preceded by C<0x>).
 
-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<-next_serial>
 
-=item B<-setalias> I<arg>
+Set the serial to be one more than the number in the certificate.
 
-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<-days> I<arg>
 
-=item B<-alias>
+Specifies the number of days until a newly generated certificate expires.
+The default is 30.
+Cannot be used together with the B<-preserve_dates> option.
 
-Outputs the certificate alias, if any.
+=item B<-preserve_dates>
 
-=item B<-clrtrust>
+When signing a certificate, preserve "notBefore" and "notAfter" dates of any
+input certificate instead of adjusting them to current time and duration.
+Cannot be used together with the B<-days> option.
 
-Clears all the permitted or trusted uses of the certificate.
+=item B<-subj> I<arg>
 
-=item B<-clrreject>
+When a certificate is created set its subject name to the given value.
+When the certificate is self-signed the issuer name is set to the same value.
 
-Clears all the prohibited or rejected uses of the certificate.
+The arg must be formatted as C</type0=value0/type1=value1/type2=...>.
+Special characters may be escaped by C<\> (backslash), 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-DN).
+Multi-valued RDNs can be formed by placing a C<+> character instead of a C</>
+between the AttributeValueAssertions (AVAs) that specify the members of the set.
+Example:
 
-=item B<-addtrust> I<arg>
+C</DC=org/DC=OpenSSL/DC=users/UID=123456+CN=John Doe>
 
-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.
+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.
 
-=item B<-addreject> I<arg>
+=item B<-force_pubkey> I<filename>
 
-Adds a prohibited use. It accepts the same values as the B<-addtrust>
-option.
+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.
 
-=item B<-purpose>
+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.
 
-This option performs tests on the certificate extensions and outputs
-the results. For a more complete description see the
-L</CERTIFICATE EXTENSIONS> section.
+=item B<-clrext>
 
-=back
+Delete any extensions from a certificate. This option is used when a
+certificate is being created from another certificate (for example with
+either the B<-signkey> or the B<-CA> option).
+Normally all extensions are retained.
 
-=head2 Signing Options
+=item B<-extfile> I<filename>
 
-This command can be used to sign certificates and requests: it
-can thus behave like a "mini CA".
+Configuration file containing certificate extensions to add.
 
-=over 4
+=item B<-extensions> I<section>
 
-=item B<-signkey> I<filename>|I<uri>
+The section in the extfile 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.
 
-This option causes the input file to be self signed using the supplied
-private key.
+=item B<-sigopt> I<nm>:I<v>
 
-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.
+Pass options to the signature algorithm during sign operations.
+Names and values of these options are algorithm-specific.
 
 =item B<-badsig>
 
 Corrupt the signature before writing it; this can be useful
 for testing.
 
-=item B<-sigopt> I<nm>:I<v>
-
-Pass options to the signature algorithm during sign operations.
-Names and values of these options are algorithm-specific.
-
-=item B<-vfyopt> I<nm>:I<v>
+=item B<-I<digest>>
 
-Pass options to the signature algorithm during verify operations.
-Names and values of these options are algorithm-specific.
+The digest to use.
+This affects any signing or printing 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<-passin> I<arg>
+=back
 
-The key and certificate file password source.
-For more information about the format of I<arg>
-see L<openssl-passphrase-options(1)>.
+=head2 Micro-CA Options
 
-=item B<-clrext>
+=over 4
 
-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<-CA> I<filename>|I<uri>
 
-=item B<-keyform> B<DER>|B<PEM>|B<P12>|B<ENGINE>
+Specifies the "CA" certificate to be used for signing.
+When present, this behaves like a "micro CA" as follows:
+The subject name of the "CA" certificate is placed as issuer name in the new
+certificate, which is then signed using the "CA" key given as detailed below.
 
-The key format; the default is B<PEM>.
-The only value with effect is B<ENGINE>; all others have become obsolete.
-See L<openssl-format-options(1)> for details.
+This option cannot be used in conjunction with the B<-signkey> option.
+This option is normally combined with the B<-req> option referencing a CSR.
+Without the B<-req> option the input must be a self-signed certificate
+unless the B<-new> option is given, which generates a certificate from scratch.
 
 =item B<-CAform> B<DER>|B<PEM>|B<P12>,
 
 The format for the CA certificate.
 This option has no effect and is retained for backward compatibility.
 
+=item B<-CAkey> I<filename>|I<uri>
+
+Sets the CA private key to sign a certificate with.
+The private key must match the public key of the certificate given with B<-CA>.
+If this option is not provided then the key must be present in the B<-CA> input.
+
 =item B<-CAkeyform> B<DER>|B<PEM>|B<P12>|B<ENGINE>
 
 The format for the CA key; the default is B<PEM>.
 The only value with effect is B<ENGINE>; all others have become obsolete.
 See L<openssl-format-options(1)> 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>|I<uri>
-
-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.
@@ -470,81 +484,92 @@ 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>
+=back
 
-File containing certificate extensions to use. If not specified then
-no extensions are added to the certificate.
+=head2 Trust Settings
 
-=item B<-extensions> I<section>
+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 possibly an "alias" (nickname).
 
-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.
+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.
 
-=item B<-new>
+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.
 
-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> option needs to be given.
-The public key to include defaults to the key given with the B<-signkey> option,
-which implies self-signature.
-It may also be given explicity using the B<-force_pubkey> option.
+See the description in L<openssl-verify(1)> for more information
+on the meaning of trust settings.
 
-=item B<-next_serial>
+Future versions of OpenSSL will recognize trust settings on any
+certificate: not just root CAs.
 
-Set the serial to be one more than the number in the certificate.
+=over 4
 
-=item B<-nocert>
+=item B<-trustout>
 
-Do not generate or output a certificate.
+Mark any certificate PEM output as <trusted> certificate rather than 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<-force_pubkey> I<filename>
+=item B<-setalias> I<arg>
 
-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.
+Sets the "alias" of the certificate. This will allow the certificate
+to be referred to using a nickname for example "Steve's Certificate".
 
-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.
+=item B<-clrtrust>
 
-=item B<-subj> I<arg>
+Clears all the permitted or trusted uses of the certificate.
 
-When a certificate is created set its subject name to the given value.
+=item B<-addtrust> I<arg>
 
-The arg must be formatted as C</type0=value0/type1=value1/type2=...>.
-Special characters may be escaped by C<\> (backslash), 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-DN).
-Multi-valued RDNs can be formed by placing a C<+> character instead of a C</>
-between the AttributeValueAssertions (AVAs) that specify the members of the set.
-Example:
+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.
 
-C</DC=org/DC=OpenSSL/DC=users/UID=123456+CN=John Doe>
+=item B<-clrreject>
 
-Unless the B<-CA> option is given the issuer is set to the same value.
+Clears all the prohibited or rejected uses of the certificate.
 
-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.
+=item B<-addreject> I<arg>
+
+Adds a prohibited use.
+It accepts the same values as the B<-addtrust> option.
 
 =back
 
-=head2 Text Options
+=head2 Generic options
+
+=over 4
+
+{- $OpenSSL::safe::opt_r_item -}
+
+{- $OpenSSL::safe::opt_engine_item -}
 
-As well as customising the name output format, it is also possible to
-customise the actual fields printed using the B<certopt> options when
+{- $OpenSSL::safe::opt_provider_item -}
+
+=back
+
+=head2 Text Printing Flags
+
+As well as customising the name printing format, it is also possible to
+customise the actual fields printed using the B<certopt> option 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.
+Use the old format. This is equivalent to specifying no printing options at all.
 
 =item B<no_header>
 
@@ -620,36 +645,36 @@ B<no_header>, and B<no_version>.
 Note: in these examples the '\' means the example should be all on one
 line.
 
-Display the contents of a certificate:
+Print the contents of a certificate:
 
  openssl x509 -in cert.pem -noout -text
 
-Display the "Subject Alternative Name" extension of a certificate:
+Print the "Subject Alternative Name" extension of a certificate:
 
  openssl x509 -in cert.pem -noout -ext subjectAltName
 
-Display more extensions of a certificate:
+Print more extensions of a certificate:
 
  openssl x509 -in cert.pem -noout -ext subjectAltName,nsCertType
 
-Display the certificate serial number:
+Print the certificate serial number:
 
  openssl x509 -in cert.pem -noout -serial
 
-Display the certificate subject name:
+Print the certificate subject name:
 
  openssl x509 -in cert.pem -noout -subject
 
-Display the certificate subject name in RFC2253 form:
+Print 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
+Print 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:
+Print the certificate SHA1 fingerprint:
 
  openssl x509 -sha1 -in cert.pem -noout -fingerprint
 
@@ -661,7 +686,7 @@ 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
+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 \
@@ -673,7 +698,6 @@ 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"
 
@@ -685,7 +709,7 @@ Set a certificate to be trusted for SSL client use and change set its alias to
 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.
+it is more likely to print 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
@@ -713,9 +737,9 @@ 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