diff options
author | Dr. Stephen Henson <steve@openssl.org> | 2000-07-30 01:27:59 +0000 |
---|---|---|
committer | Dr. Stephen Henson <steve@openssl.org> | 2000-07-30 01:27:59 +0000 |
commit | bd4e152791acc2a41441bd5713cbddc4b3645d27 (patch) | |
tree | e1983b3384fbeb19ef792e271dacf49fabeef431 /doc/apps/x509.pod | |
parent | aa826d88e196ec13e1df4aeb2a55b8ea579aba60 (diff) |
Document the new DN printing options.
Change a few names to be more meaningful.
Fix typos in CA.pl docs.
Diffstat (limited to 'doc/apps/x509.pod')
-rw-r--r-- | doc/apps/x509.pod | 161 |
1 files changed, 157 insertions, 4 deletions
diff --git a/doc/apps/x509.pod b/doc/apps/x509.pod index 133c4200ce..f8742f84fc 100644 --- a/doc/apps/x509.pod +++ b/doc/apps/x509.pod @@ -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. |