X-Git-Url: https://git.openssl.org/gitweb/?p=openssl.git;a=blobdiff_plain;f=doc%2Fapps%2Fx509.pod;h=7f32eef0009babb68033c8089fd7b290641f2bb6;hp=9ecd3a3c25354f6884a7c1c881cb1942a6d45554;hb=2b40660ec1ee69ff4121937d12a50937d9fb0bfb;hpb=bb075f883356589425b7e57f788c7498a83b0219

diff --git a/doc/apps/x509.pod b/doc/apps/x509.pod
index 9ecd3a3c25..7f32eef000 100644
--- a/doc/apps/x509.pod
+++ b/doc/apps/x509.pod
@@ -19,6 +19,8 @@ B<openssl> B<x509>
 [B<-hash>]
 [B<-subject>]
 [B<-issuer>]
+[B<-nameopt option>]
+[B<-email>]
 [B<-startdate>]
 [B<-enddate>]
 [B<-purpose>]
@@ -137,6 +139,16 @@ 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.
+
 =item B<-startdate>
 
 prints out the start date of the certificate, that is the notBefore date.
@@ -179,7 +191,7 @@ may be trusted for SSL client but not SSL server use.
 See the description of the B<verify> utility for more information on the
 meaning of trust settings.
 
-Future versions of OpenSSL will recognise trust settings on any
+Future versions of OpenSSL will recognize trust settings on any
 certificate: not just root CAs.
 
 
@@ -212,9 +224,10 @@ clears all the prohibited or rejected uses of the certificate.
 
 =item B<-addtrust arg>
 
-adds a trusted certificate use. Currently acceptable values
-are B<all> (any purpose), B<sslclient> (SSL client use), B<sslserver>
-(SSL server use) B<email> (S/MIME email) and B<objsign> (Object signing).
+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) and B<emailProtection> (S/MIME email) are used.
+Other OpenSSL applications may define additional uses.
 
 =item B<-addreject arg>
 
@@ -329,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 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 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<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
@@ -342,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
@@ -361,13 +519,13 @@ Convert a certificate to a certificate request:
 Convert a certificate request into a self signed certificate using
 extensions for a CA:
 
- openssl x509 -req -in careq.pem -config openssl.cnf -extensions v3_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 -config openssl.cnf -extensions v3_usr \
+ openssl x509 -req -in req.pem -extfile openssl.cnf -extensions v3_usr \
 	-CA cacert.pem -CAkey key.pem -CAcreateserial
 
 
@@ -394,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
@@ -401,6 +564,10 @@ two certificates with the same fingerprint can be considered to be the same.
 
 The Netscape fingerprint uses MD5 whereas MSIE uses SHA1.
 
+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
@@ -516,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.