Document the new DN printing options.
[openssl.git] / doc / apps / x509.pod
index 133c420..f8742f8 100644 (file)
@@ -19,6 +19,7 @@ B<openssl> B<x509>
 [B<-hash>]
 [B<-subject>]
 [B<-issuer>]
+[B<-nameopt option>]
 [B<-email>]
 [B<-startdate>]
 [B<-enddate>]
@@ -138,6 +139,12 @@ outputs the subject name.
 
 outputs the issuer name.
 
+=item B<-nameopt option>
+
+option which determine how the subject or issuer names are displayed. This
+option may be used more than once to set multiple options. See the B<NAME
+OPTIONS> section for more information.
+
 =item B<-email>
 
 outputs the email address(es) if any.
@@ -335,6 +342,138 @@ specified then the extensions should either be contained in the unnamed
 
 =back
 
+=head1 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. This is equivalent to specifying no name options at all.
+
+=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_spc>, B<spc_eq> and B<sname>
+options.
+
+=item B<multiline>
+
+a multiline format. It is equivalent B<esc_ctrl>, B<esc_msb>, B<sep_multiline>,
+B<spc_eq> and B<lname>.
+
+=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 beginnging of a string
+and a space character at the beginning or end of a string.
+
+=item B<esc_ctrl>
+
+escape and 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<no_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 repesents 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 RDNs and the second between multiple 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.
+
+=item B<dn_rev>
+
+reverse the fields of the DN. This is required by RFC2253. As a side
+effect this also reveress 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<spc_eq>
+
+places spaces round the B<=> character which follows the field
+name.
+
+=back
+
 =head1 EXAMPLES
 
 Note: in these examples the '\' means the example should be all on one
@@ -348,6 +487,19 @@ 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 -nameopt -escmsb
+
 Display the certificate MD5 fingerprint:
 
  openssl x509 -in cert.pem -noout -fingerprint
@@ -400,6 +552,11 @@ Trusted certificates have the lines
  -----BEGIN TRUSTED CERTIFICATE----
  -----END TRUSTED CERTIFICATE----
 
+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<-fingerprint> option takes the digest of the DER encoded certificate.
 This is commonly called a "fingerprint". Because of the nature of message
 digests the fingerprint of a certificate is unique to that certificate and
@@ -526,10 +683,6 @@ must be present.
 
 =head1 BUGS
 
-The way DNs are printed is in a "historical SSLeay" format which doesn't
-follow any published standard. It should follow some standard like RFC2253
-or RFC1779 with options to make the stuff more readable.
-
 Extensions in certificates are not transferred to certificate requests and
 vice versa.