Document the new DN printing options.
authorDr. Stephen Henson <steve@openssl.org>
Sun, 30 Jul 2000 01:27:59 +0000 (01:27 +0000)
committerDr. Stephen Henson <steve@openssl.org>
Sun, 30 Jul 2000 01:27:59 +0000 (01:27 +0000)
Change a few names to be more meaningful.

Fix typos in CA.pl docs.

apps/apps.c
crypto/asn1/a_strex.c
crypto/asn1/asn1.h
crypto/x509/x509.h
doc/apps/CA.pl.pod
doc/apps/x509.pod

index 183a2b1..7ae7c77 100644 (file)
@@ -668,8 +668,8 @@ int set_name_ex(unsigned long *flags, const char *arg)
                { "esc_msb", ASN1_STRFLGS_ESC_MSB, 0},
                { "use_quote", ASN1_STRFLGS_ESC_QUOTE, 0},
                { "utf8", ASN1_STRFLGS_UTF8_CONVERT, 0},
-               { "no_type", ASN1_STRFLGS_IGNORE_TYPE, 0},
-               { "show_name", ASN1_STRFLGS_SHOW_NAME, 0},
+               { "ignore_type", ASN1_STRFLGS_IGNORE_TYPE, 0},
+               { "show_type", ASN1_STRFLGS_SHOW_TYPE, 0},
                { "dump_all", ASN1_STRFLGS_DUMP_ALL, 0},
                { "dump_nostr", ASN1_STRFLGS_DUMP_UNKNOWN, 0},
                { "dump_der", ASN1_STRFLGS_DUMP_DER, 0},
index ef225be..f94ae27 100644 (file)
@@ -311,7 +311,7 @@ static int do_print_ex(char_io *io_ch, void *arg, unsigned long lflags, ASN1_STR
        outlen = 0;
 
 
-       if(lflags & ASN1_STRFLGS_SHOW_NAME) {
+       if(lflags & ASN1_STRFLGS_SHOW_TYPE) {
                const char *tagname;
                tagname = ASN1_tag2str(type);
                outlen += strlen(tagname);
@@ -392,8 +392,8 @@ static int do_name_ex(char_io *io_ch, void *arg, X509_NAME *n,
                case XN_FLAG_SEP_MULTILINE:
                sep_dn = "\n";
                sep_dn_len = 1;
-               sep_mv = "+";
-               sep_mv_len = 1;
+               sep_mv = " + ";
+               sep_mv_len = 3;
                break;
 
                case XN_FLAG_SEP_COMMA_PLUS:
@@ -446,9 +446,9 @@ static int do_name_ex(char_io *io_ch, void *arg, X509_NAME *n,
                        } else {
                                if(!io_ch(arg, sep_dn, sep_dn_len)) return -1;
                                outlen += sep_dn_len;
+                               if(!do_indent(io_ch, arg, indent)) return -1;
+                               outlen += indent;
                        }
-                       if(!do_indent(io_ch, arg, indent)) return -1;
-                       outlen += indent;
                }
                prev = ent->set;
                fn = X509_NAME_ENTRY_get_object(ent);
index 9cf0fc0..9189537 100644 (file)
@@ -306,7 +306,7 @@ typedef int ASN1_NULL;
 #define ASN1_STRFLGS_IGNORE_TYPE       0x20
 
 /* If this is set we include the string type in the output */
-#define ASN1_STRFLGS_SHOW_NAME         0x40
+#define ASN1_STRFLGS_SHOW_TYPE         0x40
 
 /* This determines which strings to display and which to
  * 'dump' (hex dump of content octets or DER encoding). We can
index ef72135..ffa6e01 100644 (file)
@@ -338,10 +338,10 @@ DECLARE_STACK_OF(X509_TRUST)
 
 #define XN_FLAG_FN_MASK                (0x3 << 21)
 
-#define XN_FLAG_FN_NONE                0               /* No field names */
-#define XN_FLAG_FN_SN          (1 << 21)       /* Object short name */
-#define XN_FLAG_FN_LN          (2 << 21)       /* Object long name */
-#define XN_FLAG_FN_OID         (3 << 21)       /* Always use OIDs */
+#define XN_FLAG_FN_SN          0               /* Object short name */
+#define XN_FLAG_FN_LN          (1 << 21)       /* Object long name */
+#define XN_FLAG_FN_OID         (2 << 21)       /* Always use OIDs */
+#define XN_FLAG_FN_NONE                (3 << 21)       /* No field names */
 
 #define XN_FLAG_SPC_EQ         (1 << 23)       /* Put spaces round '=' */
 
index 9d287f0..75aa2a1 100644 (file)
@@ -69,7 +69,7 @@ list box), otherwise the name "My Certificate" is used.
 
 calls the B<ca> program to sign a certificate request. It expects the request
 to be in the file "newreq.pem". The new certificate is written to the file
-"newcert.pem" except in the case of the B<-xcert> option when it is written
+"newcert.pem" except in the case of the B<-xsign> option when it is written
 to standard output.
 
 =item B<-signcert>
@@ -122,7 +122,7 @@ Create the CA directories and files:
 
 enter cacert.pem when prompted for the CA file name.
 
-Create a DSA certificate request and privat key (a different set of parameters
+Create a DSA certificate request and private key (a different set of parameters
 can optionally be created first):
 
  openssl req -out newreq.pem -newkey dsa:dsap.pem 
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.