The branch master has been updated via bc24e3ee52aacf3afe700617a13995c8ac96c8d5 (commit) from 0d2bfe52bb7e839f7bddcdb1160c335f2994df2f (commit)
- Log ----------------------------------------------------------------- commit bc24e3ee52aacf3afe700617a13995c8ac96c8d5 Author: Rich Salz <rs...@akamai.com> Date: Thu Oct 24 23:02:09 2019 -0400 Move -nameopt to openssl.pod Also clarify the description of the options. Reviewed-by: Paul Yang <kaishen...@antfin.com> Reviewed-by: Dmitry Belyavskiy <beld...@gmail.com> Reviewed-by: Matthias St. Pierre <matthias.st.pie...@ncp-e.com> (Merged from https://github.com/openssl/openssl/pull/10259) ----------------------------------------------------------------------- Summary of changes: doc/man1/openssl-crl.pod.in | 9 +-- doc/man1/openssl-req.pod.in | 11 +-- doc/man1/openssl-s_client.pod.in | 11 +-- doc/man1/openssl-s_server.pod.in | 11 +-- doc/man1/openssl-s_time.pod.in | 13 ++-- doc/man1/openssl-verify.pod.in | 15 ++-- doc/man1/openssl-x509.pod.in | 153 +-------------------------------------- doc/man1/openssl.pod | 150 ++++++++++++++++++++++++++++++++++++++ doc/perlvars.pm | 8 ++ 9 files changed, 184 insertions(+), 197 deletions(-) diff --git a/doc/man1/openssl-crl.pod.in b/doc/man1/openssl-crl.pod.in index 29d2ac25d5..680a11d06c 100644 --- a/doc/man1/openssl-crl.pod.in +++ b/doc/man1/openssl-crl.pod.in @@ -15,12 +15,12 @@ B<openssl> B<crl> [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 @@ -61,11 +61,6 @@ default. 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. @@ -92,6 +87,8 @@ Output the lastUpdate field. Output the nextUpdate field. +{- $OpenSSL::safe::opt_name_item -} + {- $OpenSSL::safe::opt_trust_item -} =back diff --git a/doc/man1/openssl-req.pod.in b/doc/man1/openssl-req.pod.in index 88772cad7c..17ffe9ade6 100644 --- a/doc/man1/openssl-req.pod.in +++ b/doc/man1/openssl-req.pod.in @@ -39,7 +39,6 @@ B<openssl> B<req> [B<-reqexts> I<section>] [B<-precert>] [B<-utf8>] -[B<-nameopt>] [B<-reqopt>] [B<-subject>] [B<-subj> I<arg>] @@ -49,6 +48,7 @@ B<openssl> B<req> [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 @@ -280,13 +280,6 @@ default they are interpreted as ASCII. This means that the field 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 @@ -330,6 +323,8 @@ string is required by the SM2 signature algorithm for signing and verification. 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 diff --git a/doc/man1/openssl-s_client.pod.in b/doc/man1/openssl-s_client.pod.in index b14332dbda..f010e60679 100644 --- a/doc/man1/openssl-s_client.pod.in +++ b/doc/man1/openssl-s_client.pod.in @@ -58,7 +58,6 @@ B<openssl> B<s_client> [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>] @@ -128,6 +127,7 @@ B<openssl> B<s_client> [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 -} @@ -282,13 +282,6 @@ will never fail due to a server certificate verify failure. 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 @@ -706,6 +699,8 @@ be provided as a single positional argument after all options. If neither 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 -} diff --git a/doc/man1/openssl-s_server.pod.in b/doc/man1/openssl-s_server.pod.in index f8913e647c..ed2d049081 100644 --- a/doc/man1/openssl-s_server.pod.in +++ b/doc/man1/openssl-s_server.pod.in @@ -19,7 +19,6 @@ B<openssl> B<s_server> [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>] @@ -174,6 +173,7 @@ B<openssl> B<s_server> [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 -} @@ -263,13 +263,6 @@ B<-cert> option. 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, @@ -721,6 +714,8 @@ data that was sent will be rejected. 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 -} diff --git a/doc/man1/openssl-s_time.pod.in b/doc/man1/openssl-s_time.pod.in index fd7cb02358..01707324db 100644 --- a/doc/man1/openssl-s_time.pod.in +++ b/doc/man1/openssl-s_time.pod.in @@ -16,7 +16,6 @@ B<openssl> B<s_time> [B<-reuse>] [B<-new>] [B<-verify> I<depth>] -[B<-nameopt> I<option>] [B<-time> I<seconds>] [B<-ssl3>] [B<-tls1>] @@ -26,6 +25,7 @@ B<openssl> B<s_time> [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 @@ -76,12 +76,11 @@ Currently the verify operation continues after errors so all the problems 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> @@ -133,6 +132,8 @@ and optionally transfer payload data from a server. Server and client performance and the link speed determine how many connections it can establish. +{- $OpenSSL::safe::opt_name_item -} + {- $OpenSSL::safe::opt_trust_item -} =back diff --git a/doc/man1/openssl-verify.pod.in b/doc/man1/openssl-verify.pod.in index 4f7f587b6d..100cff4a6b 100644 --- a/doc/man1/openssl-verify.pod.in +++ b/doc/man1/openssl-verify.pod.in @@ -22,7 +22,6 @@ B<openssl> B<verify> [B<-ignore_critical>] [B<-inhibit_any>] [B<-inhibit_map>] -[B<-nameopt> I<option>] [B<-no_check_time>] [B<-partial_chain>] [B<-policy> I<arg>] @@ -48,6 +47,7 @@ B<openssl> B<verify> [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> ...] @@ -133,13 +133,6 @@ Set policy variable inhibit-any-policy (see RFC5280). 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 @@ -306,14 +299,16 @@ required by the SM2 signature algorithm for signing and verification. 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, diff --git a/doc/man1/openssl-x509.pod.in b/doc/man1/openssl-x509.pod.in index ae9957117a..5dfb9bb0e6 100644 --- a/doc/man1/openssl-x509.pod.in +++ b/doc/man1/openssl-x509.pod.in @@ -23,7 +23,6 @@ B<openssl> B<x509> [B<-ocspid>] [B<-subject>] [B<-issuer>] -[B<-nameopt> I<option>] [B<-email>] [B<-ocsp_uri>] [B<-startdate>] @@ -66,6 +65,7 @@ B<openssl> B<x509> [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 @@ -213,12 +213,7 @@ Outputs the subject name. 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> @@ -488,150 +483,6 @@ 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 diff --git a/doc/man1/openssl.pod b/doc/man1/openssl.pod index 21e9d97217..2e58b1bb3e 100644 --- a/doc/man1/openssl.pod +++ b/doc/man1/openssl.pod @@ -783,6 +783,156 @@ See L<openssl(1)/Format Options> for details. =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 diff --git a/doc/perlvars.pm b/doc/perlvars.pm index 01234f189b..5425c87e03 100644 --- a/doc/perlvars.pm +++ b/doc/perlvars.pm @@ -67,6 +67,14 @@ $OpenSSL::safe::opt_x_item = "" . "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 = ""