Also clarify the description of the options.
Reviewed-by: Paul Yang <kaishen.yy@antfin.com>
Reviewed-by: Dmitry Belyavskiy <beldmit@gmail.com>
Reviewed-by: Matthias St. Pierre <Matthias.St.Pierre@ncp-e.com>
(Merged from https://github.com/openssl/openssl/pull/10259)
[B<-text>]
[B<-in> I<filename>]
[B<-out> I<filename>]
-[B<-nameopt> I<option>]
[B<-noout>]
[B<-hash>]
[B<-issuer>]
[B<-lastupdate>]
[B<-nextupdate>]
+{- $OpenSSL::safe::opt_name_synopsis -}
{- $OpenSSL::safe::opt_trust_synopsis -}
=for openssl ifdef hash_old
Print out the CRL in text form.
-=item B<-nameopt> I<option>
-
-Option which determines how the subject or issuer names are displayed. See
-the description of B<-nameopt> in L<openssl-x509(1)>.
-
=item B<-noout>
Don't output the encoded version of the CRL.
Output the nextUpdate field.
+{- $OpenSSL::safe::opt_name_item -}
+
{- $OpenSSL::safe::opt_trust_item -}
=back
[B<-reqexts> I<section>]
[B<-precert>]
[B<-utf8>]
-[B<-nameopt>]
[B<-reqopt>]
[B<-subject>]
[B<-subj> I<arg>]
[B<-engine> I<id>]
[B<-sm2-id> I<string>]
[B<-sm2-hex-id> I<hex-string>]
+{- $OpenSSL::safe::opt_name_synopsis -}
{- $OpenSSL::safe::opt_r_synopsis -}
=for openssl ifdef engine keygen_engine sm2-id sm2-hex-id
values, whether prompted from a terminal or obtained from a
configuration file, must be valid UTF8 strings.
-=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<openssl-x509(1)> manual page for details.
-
=item B<-reqopt> I<option>
Customise the output format used with B<-text>. The I<option> argument can be
Specify a binary ID string to use when verifying an SM2 certificate request. The
argument for this option is string of hexadecimal digits.
+{- $OpenSSL::safe::opt_name_item -}
+
{- $OpenSSL::safe::opt_r_item -}
=back
[B<-no_alt_chains>]
[B<-use_deltas>]
[B<-auth_level> I<num>]
-[B<-nameopt> I<option>]
[B<-verify_depth> I<num>]
[B<-verify_email> I<email>]
[B<-verify_hostname> I<hostname>]
[B<-keylogfile> I<file>]
[B<-early_data> I<file>]
[B<-enable_pha>]
+{- $OpenSSL::safe::opt_name_synopsis -}
{- $OpenSSL::safe::opt_x_synopsis -}
{- $OpenSSL::safe::opt_trust_synopsis -}
{- $OpenSSL::safe::opt_r_synopsis -}
Return verification errors instead of continuing. This will typically
abort the handshake with a fatal error.
-=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<openssl-x509(1)> manual page for details.
-
=item B<-chainCApath> I<directory>
The directory to use for building the chain provided to the server. This
nor B<-connect> are provided, falls back to attempting to connect to
I<localhost> on port I<4433>.
+{- $OpenSSL::safe::opt_name_item -}
+
{- $OpenSSL::safe::opt_x_item -}
{- $OpenSSL::safe::opt_trust_item -}
[B<-verify> I<int>]
[B<-Verify> I<int>]
[B<-cert> I<infile>]
-[B<-nameopt> I<val>]
[B<-naccept> I<+int>]
[B<-serverinfo> I<val>]
[B<-certform> B<DER>|B<PEM>]
[B<-anti_replay>]
[B<-no_anti_replay>]
[B<-http_server_binmode>]
+{- $OpenSSL::safe::opt_name_synopsis -}
{- $OpenSSL::safe::opt_x_synopsis -}
{- $OpenSSL::safe::opt_trust_synopsis -}
{- $OpenSSL::safe::opt_r_synopsis -}
Specify whether the application should build the certificate chain to be
provided to the client.
-=item B<-nameopt> I<val>
-
-Option which determines how the subject or issuer names are displayed. The
-I<val> 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<openssl-x509(1)> manual page for details.
-
=item B<-naccept> I<+int>
The server will exit after receiving the specified number of connections,
When acting as web-server (using option B<-WWW> or B<-HTTP>) open files requested
by the client in binary mode.
+{- $OpenSSL::safe::opt_name_item -}
+
{- $OpenSSL::safe::opt_x_item -}
{- $OpenSSL::safe::opt_trust_item -}
[B<-reuse>]
[B<-new>]
[B<-verify> I<depth>]
-[B<-nameopt> I<option>]
[B<-time> I<seconds>]
[B<-ssl3>]
[B<-tls1>]
[B<-bugs>]
[B<-cipher> I<cipherlist>]
[B<-ciphersuites> I<val>]
+{- $OpenSSL::safe::opt_name_synopsis -}
{- $OpenSSL::safe::opt_trust_synopsis -}
=for openssl ifdef ssl3 tls1 tls1_1 tls1_2 tls1_3
with a certificate chain can be seen. As a side effect the connection
will never fail due to a server certificate verify failure.
-=item B<-nameopt> I<option>
+=item B<-CApath> I<directory>
-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<openssl-x509(1)> manual page for details.
+The directory to use for server certificate verification. This directory
+must be in "hash format", see L<openssl-verify(1)> for more information.
+These are also used when building the client certificate chain.
=item B<-new>
performance and the link speed determine how many connections it
can establish.
+{- $OpenSSL::safe::opt_name_item -}
+
{- $OpenSSL::safe::opt_trust_item -}
=back
[B<-ignore_critical>]
[B<-inhibit_any>]
[B<-inhibit_map>]
-[B<-nameopt> I<option>]
[B<-no_check_time>]
[B<-partial_chain>]
[B<-policy> I<arg>]
[B<-show_chain>]
[B<-sm2-id> I<string>]
[B<-sm2-hex-id> I<hex-string>]
+{- $OpenSSL::safe::opt_name_synopsis -}
{- $OpenSSL::safe::opt_trust_synopsis -}
[B<-->]
[I<certificate> ...]
Set policy variable inhibit-policy-mapping (see RFC5280).
-=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<openssl-x509(1)> manual page for details.
-
=item B<-no_check_time>
This option suppresses checking the validity period of certificates and CRLs
Specify a binary ID string to use when signing or verifying using an SM2
certificate. The argument for this option is string of hexadecimal digits.
+{- $OpenSSL::safe::opt_name_item -}
+
+{- $OpenSSL::safe::opt_trust_item -}
+
=item B<-->
Indicates the last option. All arguments following this are assumed to be
certificate files. This is useful if the first certificate filename begins
with a B<-->.
-{- $OpenSSL::safe::opt_trust_item -}
-
=item I<certificate> ...
One or more certificates to verify. If no certificates are given,
[B<-ocspid>]
[B<-subject>]
[B<-issuer>]
-[B<-nameopt> I<option>]
[B<-email>]
[B<-ocsp_uri>]
[B<-startdate>]
[B<-sigopt> I<nm>:I<v>]
[B<-engine> I<id>]
[B<-preserve_dates>]
+{- $OpenSSL::safe::opt_name_synopsis -}
{- $OpenSSL::safe::opt_r_synopsis -}
=for openssl ifdef engine subject_hash_old issuer_hash_old
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.
+{- $OpenSSL::safe::opt_name_item -}
=item B<-email>
=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
=back
+=head2 Name Format Options
+
+OpenSSL provides fine-grain control over how the subject and issuer DN's are
+displayed.
+This is specified by using the B<-nameopt> option, which takes a
+comma-separated list of options from the following set.
+An option may be preceeded by a minus sign, C<->, to turn it off.
+The default value is C<oneline>.
+The first four are the most commonly used.
+
+=over 4
+
+=item B<compat>
+
+Display the name using an old format from previous OpenSSL versions.
+
+=item B<RFC2253>
+
+Display the name using the format defined in RFC 2253.
+It is 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>
+
+Display the name in one line, using a format that is more readable
+RFC 2253.
+It is equivalent to 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.
+
+=item B<multiline>
+
+Display the name using multiple lines.
+It is equivalent to 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 in a field, as required by RFC 2253.
+That is, any of the characters C<,+"E<lt>E<gt>;>, C<#> at the beginning of
+a string and leading or trailing spaces.
+
+=item B<esc_2254>
+
+Escape the "special" characters in a field as required by RFC 2254 in a field.
+That is, the B<NUL> character and and of C<()*>.
+
+=item B<esc_ctrl>
+
+Escape non-printable ASCII characters, codes less than 0x20 (space)
+or greater than 0x7F (DELETE). They are displayed using RFC 2253 C<\XX>
+notation where B<XX> are the two hex digits representing the character value.
+
+=item B<esc_msb>
+
+Escape any characters with the most significant bit set, that is with
+values larger than 127, as described in B<esc_ctrl>.
+
+=item B<use_quote>
+
+Escapes some characters by surrounding the entire string with quotation
+marks, C<">.
+Without this option, individual special characters are preceeded with
+a backslash character, C<\>.
+
+=item B<utf8>
+
+Convert all strings to UTF-8 format first as required by RFC 2253.
+If the output device is UTF-8 compatible, then using this option (and
+not setting B<esc_msb>) may give the correct display of multibyte
+characters.
+If this option is not set, then multibyte characters larger than 0xFF
+will be output as C<\UXXXX> for 16 bits or C<\WXXXXXXXX> for 32 bits.
+In addition, 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, the 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>
+
+Display the type of the ASN1 character string before the value,
+such as C<BMPSTRING: Hello World>.
+
+=item B<dump_der>
+
+Any fields that would be output in hex format are displayed using
+the DER encoding of the field.
+If not set, just the content octets are displayed.
+Either way, the B<#XXXX...> format of RFC 2253 is used.
+
+=item B<dump_nostr>
+
+Dump non-character strings, such as ASN.1 B<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. When this used with B<dump_der>, this 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>
+
+Specify the field separators. The first word is used between the
+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> starts each field on its own line, and uses "plus space"
+for the AVA separator.
+It also indents the fields by four characters.
+The default value is B<sep_comma_plus_space>.
+
+=item B<dn_rev>
+
+Reverse the fields of the DN as required by RFC 2253.
+This also reverses the order of multiple AVAs in a field, but this is
+permissible as there is no ordering on values.
+
+=item B<nofname>, B<sname>, B<lname>, B<oid>
+
+Specify 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 equal sign, C<=>, character which follows the field
+name.
+
+=back
+
=head1 ENVIRONMENT
The OpenSSL library can be take some configuration parameters from the
. "Set extended certificate verification options.\n"
. "See L<openssl(1)/Extended Verification Options> for details.";
+# Name output options
+$OpenSSL::safe::opt_name_synopsis = ""
+. "[B<-nameopt> I<option>]";
+$OpenSSL::safe::opt_name_item = ""
+. "=item B<-nameopt> I<option>\n"
+. "\n"
+. "This specifies how the subject or issuer names are displayed.\n"
+. "See L<openssl(1)/Name Format Options> for details.";
# Random State Options
$OpenSSL::safe::opt_r_synopsis = ""
projects / oweals / openssl.git / commitdiff