From bd4e152791acc2a41441bd5713cbddc4b3645d27 Mon Sep 17 00:00:00 2001 From: "Dr. Stephen Henson" Date: Sun, 30 Jul 2000 01:27:59 +0000 Subject: [PATCH] Document the new DN printing options. Change a few names to be more meaningful. Fix typos in CA.pl docs. --- apps/apps.c | 4 +- crypto/asn1/a_strex.c | 10 +-- crypto/asn1/asn1.h | 2 +- crypto/x509/x509.h | 8 +-- doc/apps/CA.pl.pod | 4 +- doc/apps/x509.pod | 161 ++++++++++++++++++++++++++++++++++++++++-- 6 files changed, 171 insertions(+), 18 deletions(-) diff --git a/apps/apps.c b/apps/apps.c index 183a2b1d8a..7ae7c77ca6 100644 --- a/apps/apps.c +++ b/apps/apps.c @@ -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}, diff --git a/crypto/asn1/a_strex.c b/crypto/asn1/a_strex.c index ef225be06a..f94ae2751b 100644 --- a/crypto/asn1/a_strex.c +++ b/crypto/asn1/a_strex.c @@ -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); diff --git a/crypto/asn1/asn1.h b/crypto/asn1/asn1.h index 9cf0fc0d01..9189537f28 100644 --- a/crypto/asn1/asn1.h +++ b/crypto/asn1/asn1.h @@ -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 diff --git a/crypto/x509/x509.h b/crypto/x509/x509.h index ef72135414..ffa6e01251 100644 --- a/crypto/x509/x509.h +++ b/crypto/x509/x509.h @@ -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 '=' */ diff --git a/doc/apps/CA.pl.pod b/doc/apps/CA.pl.pod index 9d287f0c4d..75aa2a1d26 100644 --- a/doc/apps/CA.pl.pod +++ b/doc/apps/CA.pl.pod @@ -69,7 +69,7 @@ list box), otherwise the name "My Certificate" is used. calls the B 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 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 B [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 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 command line switch determines how the subject and issuer +names are displayed. If no B 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 + +use the old format. This is equivalent to specifying no name options at all. + +=item B + +displays names compatible with RFC2253 equivalent to B, B, +B, B, B, B, B, +B, B and B. + +=item B + +a oneline format which is more readable than RFC2253. It is equivalent to +specifying the B, B, B, B, B, +B, B, B, B and B +options. + +=item B + +a multiline format. It is equivalent B, B, B, +B and B. + +=item B + +escape the "special" characters required by RFC2253 in a field That is +B<,+"EE;>. Additionally B<#> is escaped at the beginnging of a string +and a space character at the beginning or end of a string. + +=item B + +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 + +escape characters with the MSB set, that is with ASCII values larger than +127. + +=item B + +escapes some characters by surrounding the whole string with B<"> characters, +without the option all escaping is done with the B<\> character. + +=item B + +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 setting B) 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 + +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 the type of the ASN1 character string. The type precedes the +field contents. For example "BMPSTRING: Hello World". + +=item B + +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 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 fields. This option when used with B allows the +DER encoding of the structure to be unambiguously determined. + +=item B + +dump any field whose OID is not recognised by OpenSSL. + +=item B, B, B, +B + +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 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 + +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, B, B, B + +these options alter how the field name is displayed. B does +not display the field at all. B uses the "short name" form +(CN for commonName for example). B uses the long form. +B represents the OID in numerical form and is useful for +diagnostic purpose. + +=item B + +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. -- 2.25.1