shorten x509;

1 files changed, 414 insertions, 755 deletions

diff --git a/src/usr.bin/openssl/openssl.1 b/src/usr.bin/openssl/openssl.1
index 6945eadfc1..2fa7a70b69 100644
--- a/src/usr.bin/openssl/openssl.1
+++ b/src/usr.bin/openssl/openssl.1
@@ -1,4 +1,4 @@
-.\" $OpenBSD: openssl.1,v 1.79 2016/09/20 16:45:38 jmc Exp $
+.\" $OpenBSD: openssl.1,v 1.80 2016/09/22 13:30:49 jmc Exp $
 .\" ====================================================================
 .\" Copyright (c) 1998-2002 The OpenSSL Project.  All rights reserved.
 .\"
@@ -112,7 +112,7 @@
 .\"
 .\" OPENSSL
 .\"
-.Dd $Mdocdate: September 20 2016 $
+.Dd $Mdocdate: September 22 2016 $
 .Dt OPENSSL 1
 .Os
 .Sh NAME
@@ -1956,12 +1956,6 @@ and prints out the certificates contained in it,
 or takes a file of certificates
 and converts it into a Netscape certificate sequence.
 .Pp
-The PEM-encoded form uses the same headers and footers as a certificate:
-.Bd -unfilled -offset indent
------BEGIN CERTIFICATE-----
------END CERTIFICATE-----
-.Ed
-.Pp
 The options are as follows:
 .Bl -tag -width Ds
 .It Fl in Ar file
@@ -2452,19 +2446,6 @@ The default encryption is only 56 bits;
 keys encrypted using PKCS#5 v2.0 algorithms and high iteration counts
 are more secure.
 .Pp
-The encrypted form of a PEM-encoded PKCS#8 file uses the following
-headers and footers:
-.Bd -unfilled -offset indent
------BEGIN ENCRYPTED PRIVATE KEY-----
------END ENCRYPTED PRIVATE KEY-----
-.Ed
-.Pp
-The unencrypted form uses:
-.Bd -unfilled -offset indent
------BEGIN PRIVATE KEY-----
------END PRIVATE KEY-----
-.Ed
-.Pp
 The options are as follows:
 .Bl -tag -width Ds
 .It Fl embed
@@ -5347,22 +5328,18 @@ The current
 .Nm openssl
 version.
 .El
-.\"
-.\" X509
-.\"
 .Sh X509
 .nr nS 1
 .Nm "openssl x509"
-.Bk -words
 .Op Fl C
 .Op Fl addreject Ar arg
 .Op Fl addtrust Ar arg
 .Op Fl alias
 .Op Fl CA Ar file
 .Op Fl CAcreateserial
-.Op Fl CAform Ar DER | PEM
+.Op Fl CAform Cm der | pem
 .Op Fl CAkey Ar file
-.Op Fl CAkeyform Ar DER | PEM
+.Op Fl CAkeyform Cm der | pem
 .Op Fl CAserial Ar file
 .Op Fl certopt Ar option
 .Op Fl checkend Ar arg
@@ -5378,11 +5355,11 @@ version.
 .Op Fl fingerprint
 .Op Fl hash
 .Op Fl in Ar file
-.Op Fl inform Ar DER | NET | PEM
+.Op Fl inform Cm der | net | pem
 .Op Fl issuer
 .Op Fl issuer_hash
 .Op Fl issuer_hash_old
-.Op Fl keyform Ar DER | PEM
+.Op Fl keyform Cm der | pem
 .Op Fl md5 | sha1
 .Op Fl modulus
 .Op Fl nameopt Ar option
@@ -5390,7 +5367,7 @@ version.
 .Op Fl ocsp_uri
 .Op Fl ocspid
 .Op Fl out Ar file
-.Op Fl outform Ar DER | NET | PEM
+.Op Fl outform Cm der | net | pem
 .Op Fl passin Ar arg
 .Op Fl pubkey
 .Op Fl purpose
@@ -5406,7 +5383,6 @@ version.
 .Op Fl text
 .Op Fl trustout
 .Op Fl x509toreq
-.Ek
 .nr nS 0
 .Pp
 The
@@ -5417,29 +5393,17 @@ various forms, sign certificate requests like a
 .Qq mini CA ,
 or edit certificate trust settings.
 .Pp
-Since there are a large number of options, they are split up into
-various sections.
-.Sh X509 INPUT, OUTPUT, AND GENERAL PURPOSE OPTIONS
+The following are x509 input, output, and general purpose options:
 .Bl -tag -width "XXXX"
 .It Fl in Ar file
-This specifies the input
-.Ar file
-to read a certificate from, or standard input if this option is not specified.
-.It Fl inform Ar DER | NET | PEM
-This specifies the input format.
+The input file to read from,
+or standard input if not specified.
+.It Fl inform Cm der | net | pem
+The input format.
 Normally, the command will expect an X.509 certificate,
 but this can change if other options such as
 .Fl req
 are present.
-The
-.Ar DER
-format is the DER encoding of the certificate and
-.Ar PEM
-is the base64 encoding of the DER encoding with header and footer lines added.
-The
-.Ar NET
-option is an obscure Netscape server format that is now
-obsolete.
 .It Fl md5 | sha1
 The digest to use.
 This affects any signing or display option that uses a message digest,
@@ -5449,215 +5413,447 @@ and
 .Fl CA
 options.
 If not specified, MD5 is used.
-If the key being used to sign with is a DSA key,
-this option has no effect: SHA1 is always used with DSA keys.
+SHA1 is always used with DSA keys.
 .It Fl out Ar file
-This specifies the output
-.Ar file
-to write to, or standard output by default.
-.It Fl outform Ar DER | NET | PEM
-This specifies the output format; the options have the same meaning as the
-.Fl inform
-option.
+The output file to write to,
+or standard output if none is specified.
+.It Fl outform Cm der | net | pem
+The output format.
 .It Fl passin Ar arg
 The key password source.
 .El
-.Sh X509 DISPLAY OPTIONS
-.Sy Note :
-The
-.Fl alias
-and
-.Fl purpose
-options are also display options but are described in the
-.Sx X509 TRUST SETTINGS
-section.
+.Pp
+The following are x509 display options:
 .Bl -tag -width "XXXX"
 .It Fl C
-This outputs the certificate in the form of a C source file.
+Output the certificate in the form of a C source file.
 .It Fl certopt Ar option
 Customise the output format used with
-.Fl text .
-The
-.Ar option
-argument can be a single option or multiple options separated by commas.
-The
+.Fl text ,
+either using a list of comma-separated options or by specifying
 .Fl certopt
-switch may also be used more than once to set multiple options.
-See the
-.Sx X509 TEXT OPTIONS
-section for more information.
+multiple times.
+The default behaviour is to print all fields.
+The options are as follows:
+.Pp
+.Bl -tag -width "no_extensions" -offset indent -compact
+.It Cm ca_default
+Equivalent to
+.Cm no_issuer , no_pubkey , no_header ,
+.Cm no_version , no_sigdump ,
+and
+.Cm no_signame .
+.It Cm compatible
+Equivalent to no output options at all.
+.It Cm ext_default
+Print unsupported certificate extensions.
+.It Cm ext_dump
+Hex dump unsupported extensions.
+.It Cm ext_error
+Print an error message for unsupported certificate extensions.
+.It Cm ext_parse
+ASN1 parse unsupported extensions.
+.It Cm no_aux
+Do not print certificate trust information.
+.It Cm no_extensions
+Do not print X509V3 extensions.
+.It Cm no_header
+Do not print header (Certificate and Data) information.
+.It Cm no_issuer
+Do not print the issuer name.
+.It Cm no_pubkey
+Do not print the public key.
+.It Cm no_serial
+Do not print the serial number.
+.It Cm no_sigdump
+Do not give a hexadecimal dump of the certificate signature.
+.It Cm no_signame
+Do not print the signature algorithm used.
+.It Cm no_subject
+Do not print the subject name.
+.It Cm no_validity
+Do not print the
+.Cm notBefore
+and
+.Cm notAfter
+(validity) fields.
+.It Cm no_version
+Do not print the version number.
+.El
 .It Fl dates
-Prints out the start and expiry dates of a certificate.
+Print the start and expiry date of a certificate.
 .It Fl email
-Outputs the email address(es), if any.
+Output the email addresses, if any.
 .It Fl enddate
-Prints out the expiry date of the certificate; that is, the
-.Em notAfter
+Print the expiry date of the certificate; that is, the
+.Cm notAfter
 date.
 .It Fl fingerprint
-Prints out the digest of the DER-encoded version of the whole certificate
-(see
-.Sx DIGEST OPTIONS ) .
+Print the digest of the DER-encoded version of the whole certificate.
 .It Fl hash
 A synonym for
-.Fl subject_hash ,
-for backwards compatibility.
+.Fl subject_hash .
 .It Fl issuer
-Outputs the issuer name.
+Print the issuer name.
 .It Fl issuer_hash
-Outputs the
-.Qq hash
-of the certificate issuer name.
+Print the hash of the certificate issuer name.
 .It Fl issuer_hash_old
-Outputs the
-.Qq hash
-of the certificate issuer name using the older algorithm
-as used by
-.Nm OpenSSL
+Print the hash of the certificate issuer name
+using the older algorithm as used by
+.Nm openssl
 versions before 1.0.0.
 .It Fl modulus
-This option prints out the value of the modulus of the public key
-contained in the certificate.
+Print the value of the modulus of the public key contained in the certificate.
 .It Fl nameopt Ar option
-Option which determines how the subject or issuer names are displayed.
-The
-.Ar option
-argument can be a single option or multiple options separated by commas.
-Alternatively, the
+Customise how the subject or issuer names are displayed,
+either using a list of comma-separated options or by specifying
 .Fl nameopt
-switch may be used more than once to set multiple options.
-See the
-.Sx X509 NAME OPTIONS
-section for more information.
+multiple times.
+The default behaviour is to use the
+.Cm oneline
+format.
+The options,
+which can be preceded by a dash to turn them off,
+are as follows:
+.Bl -tag -width "XXXX"
+.It Cm align
+Align field values for a more readable output.
+Only usable with
+.Ar sep_multiline .
+.It Cm compat
+Use the old format,
+equivalent to specifying no options at all.
+.It Cm dn_rev
+Reverse the fields of the DN, as required by RFC 2253.
+As a side effect, this also reverses the order of multiple AVAs.
+.It Cm dump_all
+Dump all fields.
+When used with
+.Ar dump_der ,
+it allows the DER encoding of the structure to be unambiguously determined.
+.It Cm dump_der
+Any fields that need to be hexdumped are
+dumped using the DER encoding of the field.
+Otherwise just the content octets will be displayed.
+Both options use the RFC 2253 #XXXX... format.
+.It Cm dump_nostr
+Dump non-character string types
+(for example OCTET STRING);
+usually, non-character string types are displayed
+as though each content octet represents a single character.
+.It Cm dump_unknown
+Dump any field whose OID is not recognised by
+.Nm openssl .
+.It Cm esc_2253
+Escape the
+.Qq special
+characters required by RFC 2253 in a field that is
+.Dq \& ,+"<>; .
+Additionally,
+.Sq #
+is escaped at the beginning of a string
+and a space character at the beginning or end of a string.
+.It Cm 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 RFC 2253 \eXX notation (where XX are two hex
+digits representing the character value).
+.It Cm esc_msb
+Escape characters with the MSB set; that is, with ASCII values larger than
+127.
+.It Cm multiline
+A multiline format.
+Equivalent to
+.Cm esc_ctrl , esc_msb , sep_multiline ,
+.Cm space_eq , lname ,
+and
+.Cm align .
+.It Cm no_type
+Do not attempt to interpret multibyte characters.
+That is, content octets are merely dumped as though one octet
+represents each character.
+This is useful for diagnostic purposes
+but results in rather odd looking output.
+.It Cm nofname , sname , lname , oid
+Alter how the field name is displayed:
+.Cm nofname
+does not display the field at all;
+.Cm sname
+uses the short name form (CN for
+.Cm commonName ,
+for example);
+.Cm lname
+uses the long form.
+.Cm oid
+represents the OID in numerical form and is useful for diagnostic purpose.
+.It Cm oneline
+A one line format which is more readable than
+.Cm RFC2253 .
+Equivalent to
+.Cm esc_2253 , esc_ctrl , esc_msb , utf8 ,
+.Cm dump_nostr , dump_der , use_quote , sep_comma_plus_spc ,
+.Cm space_eq ,
+and
+.Cm sname .
+.It Cm RFC2253
+Displays names compatible with RFC 2253.
+Equivalent to
+.Cm esc_2253 , esc_ctrl ,
+.Cm esc_msb , utf8 , dump_nostr , dump_unknown ,
+.Cm dump_der , sep_comma_plus , dn_rev ,
+and
+.Cm sname .
+.It Cm sep_comma_plus , sep_comma_plus_space , sep_semi_plus_space , sep_multiline
+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
+.Qq space
+additionally place a space after the separator to make it more readable.
+.Cm sep_multiline
+uses a linefeed character for the RDN separator and a spaced
+.Sq +
+for the AVA separator,
+as well as indenting the fields by four characters.
+.It Cm show_type
+Show the type of the ASN1 character string.
+The type precedes the field contents.
+For example
+.Qq BMPSTRING: Hello World .
+.It Cm space_eq
+Place spaces round the
+.Sq =
+character which follows the field name.
+.It Cm use_quote
+Escape some characters by surrounding the whole string with
+.Sq \&"
+characters.
+Without the option, all escaping is done with the
+.Sq \e
+character.
+.It Cm utf8
+Convert all strings to UTF8 format first, as required by RFC 2253.
+On a UTF8 compatible terminal,
+the use of this option (and not setting
+.Cm esc_msb )
+may result in the correct display of multibyte characters.
+Usually, multibyte characters larger than 0xff
+are represented using the format \eUXXXX for 16 bits and \eWXXXXXXXX
+for 32 bits,
+and any UTF8Strings are converted to their character form first.
+.El
 .It Fl noout
-This option prevents output of the encoded version of the request.
+Do not output the encoded version of the request.
 .It Fl ocsp_uri
-Outputs the OCSP responder addresses, if any.
+Print the OCSP responder addresses, if any.
 .It Fl ocspid
 Print OCSP hash values for the subject name and public key.
 .It Fl pubkey
-Output the public key.
+Print the public key.
 .It Fl serial
-Outputs the certificate serial number.
+Print the certificate serial number.
 .It Fl startdate
-Prints out the start date of the certificate; that is, the
-.Em notBefore
+Print the start date of the certificate; that is, the
+.Cm notBefore
 date.
 .It Fl subject
-Outputs the subject name.
+Print the subject name.
 .It Fl subject_hash
-Outputs the
-.Qq hash
-of the certificate subject name.
+Print the hash of the certificate subject name.
 This is used in
-.Nm OpenSSL
+.Nm openssl
 to form an index to allow certificates in a directory to be looked up
 by subject name.
 .It Fl subject_hash_old
-Outputs the
-.Qq hash
-of the certificate subject name using the older algorithm
-as used by
-.Nm OpenSSL
+Print the hash of the certificate subject name
+using the older algorithm as used by
+.Nm openssl
 versions before 1.0.0.
 .It Fl text
-Prints out the certificate in text form.
-Full details are output including the public key, signature algorithms,
-issuer and subject names, serial number, any extensions present,
-and any trust settings.
+Print the full certificate in text form.
 .El
-.Sh X509 TRUST SETTINGS
-Please note these options are currently experimental and may well change.
 .Pp
-A
-.Em trusted certificate
-is an ordinary certificate which has several
+A trusted certificate is a certificate which has several
 additional pieces of information attached to it such as the permitted
-and prohibited uses of the certificate and an
-.Qq alias .
-.Pp
-Normally, when a certificate is being verified at least one certificate
-must be
-.Qq trusted .
-By default, a trusted certificate must be stored
-locally and must be a root CA: any certificate chain ending in this CA
-is then usable for any purpose.
-.Pp
-Trust settings currently are only used with a root CA.
-They allow a finer control over the purposes the root CA can be used for.
-For example, a CA may be trusted for an SSL client but not for
-SSL server use.
-.Pp
-See the description of the
-.Nm verify
-utility for more information on the meaning of trust settings.
-.Pp
-Future versions of
-.Nm OpenSSL
-will recognize trust settings on any certificate: not just root CAs.
+and prohibited uses of the certificate and an alias.
+When a certificate is being verified at least one certificate must be trusted.
+By default, a trusted certificate must be stored locally and be a root CA.
+The following are x509 trust settings options:
 .Bl -tag -width "XXXX"
 .It Fl addreject Ar arg
-Adds a prohibited use.
-It accepts the same values as the
+Add a prohibited use.
+Accepts the same values as the
 .Fl addtrust
 option.
 .It Fl addtrust Ar arg
-Adds a trusted certificate use.
+Add a trusted certificate use.
 Any object name can be used here, but currently only
-.Ar clientAuth
-.Pq SSL client use ,
-.Ar serverAuth
-.Pq SSL server use ,
+.Cm clientAuth
+(SSL client use),
+.Cm serverAuth
+(SSL server use),
 and
-.Ar emailProtection
-.Pq S/MIME email
-are used.
-Other
-.Nm OpenSSL
-applications may define additional uses.
+.Cm emailProtection
+(S/MIME email) are used.
 .It Fl alias
-Outputs the certificate alias, if any.
+Output the certificate alias.
 .It Fl clrreject
-Clears all the prohibited or rejected uses of the certificate.
+Clear all the prohibited or rejected uses of the certificate.
 .It Fl clrtrust
-Clears all the permitted or trusted uses of the certificate.
+Clear all the permitted or trusted uses of the certificate.
 .It Fl purpose
-This option performs tests on the certificate extensions and outputs
-the results.
-For a more complete description, see the
-.Sx X.509 CERTIFICATE EXTENSIONS
-section.
+Perform tests on the certificate extensions.
+The same code is used when verifying untrusted certificates in chains,
+so this section is useful if a chain is rejected by the verify code.
+.Pp
+The
+.Cm basicConstraints
+extension CA flag is used to determine whether the
+certificate can be used as a CA.
+If the CA flag is true, it is a CA;
+if the CA flag is false, it is not a CA.
+All CAs should have the CA flag set to true.
+.Pp
+If the
+.Cm basicConstraints
+extension is absent, then the certificate is
+considered to be a possible CA;
+other extensions are checked according to the intended use of the certificate.
+A warning is given in this case because the certificate should really not
+be regarded as a CA.
+However it is allowed to be a CA to work around some broken software.
+.Pp
+If the certificate is a V1 certificate
+(and thus has no extensions) and it is self-signed,
+it is also assumed to be a CA but a warning is again given.
+This is to work around the problem of Verisign roots
+which are V1 self-signed certificates.
+.Pp
+If the
+.Cm keyUsage
+extension is present, then additional restraints are
+made on the uses of the certificate.
+A CA certificate must have the
+.Cm keyCertSign
+bit set if the
+.Cm keyUsage
+extension is present.
+.Pp
+The extended key usage extension places additional restrictions on the
+certificate uses.
+If this extension is present, whether critical or not,
+the key can only be used for the purposes specified.
+.Pp
+A complete description of each test is given below.
+The comments about
+.Cm basicConstraints
+and
+.Cm keyUsage
+and V1 certificates above apply to all CA certificates.
+.Bl -tag -width "XXXX"
+.It SSL Client
+The extended key usage extension must be absent or include the
+web client authentication OID.
+.Cm keyUsage
+must be absent or it must have the
+.Cm digitalSignature
+bit set.
+The Netscape certificate type must be absent
+or it must have the SSL client bit set.
+.It SSL Client CA
+The extended key usage extension must be absent or include the
+web client authentication OID.
+The Netscape certificate type must be absent
+or it must have the SSL CA bit set:
+this is used as a workaround if the
+.Cm basicConstraints
+extension is absent.
+.It SSL Server
+The extended key usage extension must be absent or include the
+web server authentication and/or one of the SGC OIDs.
+.Cm keyUsage
+must be absent or it must have the
+.Cm digitalSignature
+set, the
+.Cm keyEncipherment
+set, or both bits set.
+The Netscape certificate type must be absent or have the SSL server bit set.
+.It SSL Server CA
+The extended key usage extension must be absent or include the
+web server authentication and/or one of the SGC OIDs.
+The Netscape certificate type must be absent or the SSL CA bit must be set:
+this is used as a workaround if the
+.Cm basicConstraints
+extension is absent.
+.It Netscape SSL Server
+For Netscape SSL clients to connect to an SSL server; it must have the
+.Cm keyEncipherment
+bit set if the
+.Cm keyUsage
+extension is present.
+This isn't always valid because some cipher suites use the key for
+digital signing.
+Otherwise it is the same as a normal SSL server.
+.It Common S/MIME Client Tests
+The extended key usage extension must be absent or include the
+email protection OID.
+The Netscape certificate type must be absent or should have the S/MIME bit set.
+If the S/MIME bit is not set in Netscape certificate type, then the SSL
+client bit is tolerated as an alternative but a warning is shown:
+this is because some Verisign certificates don't set the S/MIME bit.
+.It S/MIME Signing
+In addition to the common S/MIME client tests, the
+.Cm digitalSignature
+bit must be set if the
+.Cm keyUsage
+extension is present.
+.It S/MIME Encryption
+In addition to the common S/MIME tests, the
+.Cm keyEncipherment
+bit must be set if the
+.Cm keyUsage
+extension is present.
+.It S/MIME CA
+The extended key usage extension must be absent or include the
+email protection OID.
+The Netscape certificate type must be absent
+or must have the S/MIME CA bit set:
+this is used as a workaround if the
+.Cm basicConstraints
+extension is absent.
+.It CRL Signing
+The
+.Cm keyUsage
+extension must be absent or it must have the CRL signing bit set.
+.It CRL Signing CA
+The normal CA tests apply, except the
+.Cm basicConstraints
+extension must be present.
+.El
 .It Fl setalias Ar arg
-Sets the alias of the certificate.
-This will allow the certificate to be referred to using a nickname,
-for example
+Set the alias of the certificate,
+allowing the certificate to be referred to using a nickname,
+such as
 .Qq Steve's Certificate .
 .It Fl trustout
-This causes
-.Nm x509
-to output a
-.Em trusted certificate .
+Output a trusted certificate
+(the default if any trust settings are modified).
 An ordinary or trusted certificate can be input, but by default an ordinary
 certificate is output and any trust settings are discarded.
-With the
-.Fl trustout
-option a trusted certificate is output.
-A trusted certificate is automatically output if any trust settings
-are modified.
 .El
-.Sh X509 SIGNING OPTIONS
+.Pp
 The
 .Nm x509
-utility can be used to sign certificates and requests: it
-can thus behave like a
-.Qq mini CA .
+utility can be used to sign certificates and requests:
+it can thus behave like a mini CA.
+The following are x509 signing options:
 .Bl -tag -width "XXXX"
 .It Fl CA Ar file
-Specifies the CA certificate to be used for signing.
+The CA certificate to be used for signing.
 When this option is present,
 .Nm x509
-behaves like a
-.Qq mini CA .
+behaves like a mini CA.
 The input file is signed by the CA using this option;
 that is, its issuer name is set to the subject name of the CA and it is
 digitally signed using the CA's private key.
@@ -5669,35 +5865,30 @@ Without the
 .Fl req
 option, the input is a certificate which must be self-signed.
 .It Fl CAcreateserial
-With this option the CA serial number file is created if it does not exist:
-it will contain the serial number
+Create the CA serial number file if it does not exist
+instead of generating an error.
+The file will contain the serial number
 .Sq 02
 and the certificate being signed will have
 .Sq 1
 as its serial number.
-Normally, if the
-.Fl CA
-option is specified and the serial number file does not exist, it is an error.
-.It Fl CAform Ar DER | PEM
+.It Fl CAform Cm der | pem
 The format of the CA certificate file.
 The default is
-.Ar PEM .
+.Cm pem .
 .It Fl CAkey Ar file
-Sets the CA private key to sign a certificate with.
-If this option is not specified, it is assumed that the CA private key
-is present in the CA certificate file.
-.It Fl CAkeyform Ar DER | PEM
+Set the CA private key to sign a certificate with.
+Otherwise it is assumed that the CA private key is present
+in the CA certificate file.
+.It Fl CAkeyform Cm der | pem
 The format of the CA private key.
 The default is
-.Ar PEM .
+.Cm pem .
 .It Fl CAserial Ar file
-Sets the CA serial number file to use.
-.Pp
-When the
-.Fl CA
-option is used to sign a certificate,
-it uses a serial number specified in a file.
-This file consists of one line containing an even number of hex digits
+Use the serial number in
+.Ar file
+to sign a certificate.
+The file should consist of one line containing an even number of hex digits
 with the serial number to use.
 After each use the serial number is incremented and written out
 to the file again.
@@ -5725,30 +5916,26 @@ or the
 options).
 Normally, all extensions are retained.
 .It Fl days Ar arg
-Specifies the number of days to make a certificate valid for.
+The number of days to make a certificate valid for.
 The default is 30 days.
 .It Fl extensions Ar section
 The section to add certificate extensions from.
 If this option is not specified, the extensions should either be
-contained in the unnamed
-.Pq default
-section or the default section should contain a variable called
+contained in the unnamed (default) section
+or the default section should contain a variable called
 .Qq extensions
 which contains the section to use.
 .It Fl extfile Ar file
 File containing certificate extensions to use.
 If not specified, no extensions are added to the certificate.
-.It Fl keyform Ar DER | PEM
-Specifies the format
-.Pq DER or PEM
-of the private key file used in the
+.It Fl keyform Cm der | pem
+The format of the private key file used in the
 .Fl signkey
 option.
 .It Fl req
-By default, a certificate is expected on input.
-With this option a certificate request is expected instead.
+Expect a certificate request on input instead of a certificate.
 .It Fl set_serial Ar n
-Specifies the serial number to use.
+The serial number to use.
 This option can be used with either the
 .Fl signkey
 or
@@ -5766,12 +5953,12 @@ The serial number can be decimal or hex (if preceded by
 .Sq 0x ) .
 Negative serial numbers can also be specified but their use is not recommended.
 .It Fl signkey Ar file
-This option causes the input file to be self-signed using the supplied
-private key.
+Self-sign
+.Ar file
+using the supplied private key.
 .Pp
 If the input file is a certificate, it sets the issuer name to the
-subject name
-.Pq i.e. makes it self-signed ,
+subject name (i.e. makes it self-signed),
 changes the public key to the supplied value,
 and changes the start and end dates.
 The start date is set to the current time and the end date is set to
@@ -5786,539 +5973,11 @@ If the input is a certificate request, a self-signed certificate
 is created using the supplied private key using the subject name in
 the request.
 .It Fl x509toreq
-Converts a certificate into a certificate request.
+Convert a certificate into a certificate request.
 The
 .Fl signkey
 option is used to pass the required private key.
 .El
-.Sh X509 NAME OPTIONS
-The
-.Fl nameopt
-command line switch determines how the subject and issuer
-names are displayed.
-If no
-.Fl nameopt
-switch is present, the default
-.Qq oneline
-format is used which is compatible with previous versions of
-.Nm OpenSSL .
-Each option is described in detail below; all options can be preceded by a
-.Sq -
-to turn the option off.
-Only
-.Ar compat ,
-.Ar RFC2253 ,
-.Ar oneline ,
-and
-.Ar multiline
-will normally be used.
-.Bl -tag -width "XXXX"
-.It Ar align
-Align field values for a more readable output.
-Only usable with
-.Ar sep_multiline .
-.It Ar compat
-Use the old format.
-This is equivalent to specifying no name options at all.
-.It Ar dn_rev
-Reverse the fields of the DN.
-This is required by RFC 2253.
-As a side effect, this also reverses the order of multiple AVAs but this is
-permissible.
-.It Ar dump_all
-Dump all fields.
-This option, when used with
-.Ar dump_der ,
-allows the DER encoding of the structure to be unambiguously determined.
-.It Ar 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 RFC 2253 #XXXX... format.
-.It Ar dump_nostr
-Dump non-character string types
-.Pq for example OCTET STRING ;
-if this option is not set, non-character string types will be displayed
-as though each content octet represents a single character.
-.It Ar dump_unknown
-Dump any field whose OID is not recognised by
-.Nm OpenSSL .
-.It Ar esc_2253
-Escape the
-.Qq special
-characters required by RFC 2253 in a field that is
-.Dq \& ,+"\*(Lt\*(Gt; .
-Additionally,
-.Sq #
-is escaped at the beginning of a string
-and a space character at the beginning or end of a string.
-.It Ar esc_ctrl
-Escape control characters.
-That is, those with ASCII values less than 0x20
-.Pq space
-and the delete
-.Pq 0x7f
-character.
-They are escaped using the RFC 2253 \eXX notation (where XX are two hex
-digits representing the character value).
-.It Ar esc_msb
-Escape characters with the MSB set; that is, with ASCII values larger than
-127.
-.It Ar multiline
-A multiline format.
-It is equivalent to
-.Ar esc_ctrl , esc_msb , sep_multiline ,
-.Ar space_eq , lname ,
-and
-.Ar align .
-.It Ar 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.
-.It Ar nofname , sname , lname , oid
-These options alter how the field name is displayed.
-.Ar nofname
-does not display the field at all.
-.Ar sname
-uses the
-.Qq short name
-form (CN for
-.Ar commonName ,
-for example).
-.Ar lname
-uses the long form.
-.Ar oid
-represents the OID in numerical form and is useful for diagnostic purpose.
-.It Ar oneline
-A oneline format which is more readable than
-.Ar RFC2253 .
-It is equivalent to specifying the
-.Ar esc_2253 , esc_ctrl , esc_msb , utf8 ,
-.Ar dump_nostr , dump_der , use_quote , sep_comma_plus_spc ,
-.Ar space_eq ,
-and
-.Ar sname
-options.
-.It Ar RFC2253
-Displays names compatible with RFC 2253; equivalent to
-.Ar esc_2253 , esc_ctrl ,
-.Ar esc_msb , utf8 , dump_nostr , dump_unknown ,
-.Ar dump_der , sep_comma_plus , dn_rev ,
-and
-.Ar sname .
-.It Ar sep_comma_plus , sep_comma_plus_space , sep_semi_plus_space , 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
-.Qq space
-additionally place a space after the separator to make it more readable.
-The
-.Ar sep_multiline
-uses a linefeed character for the RDN separator and a spaced
-.Sq +
-for the AVA separator.
-It also indents the fields by four characters.
-.It Ar show_type
-Show the type of the ASN1 character string.
-The type precedes the field contents.
-For example
-.Qq BMPSTRING: Hello World .
-.It Ar space_eq
-Places spaces round the
-.Sq =
-character which follows the field name.
-.It Ar use_quote
-Escapes some characters by surrounding the whole string with
-.Sq \&"
-characters.
-Without the option, all escaping is done with the
-.Sq \e
-character.
-.It Ar utf8
-Convert all strings to UTF8 format first.
-This is required by RFC 2253.
-If you are lucky enough to have a UTF8 compatible terminal,
-the use of this option (and
-.Em not
-setting
-.Ar esc_msb )
-may result in the correct display of multibyte
-.Pq international
-characters.
-If this option is not present, multibyte characters larger than 0xff
-will be represented using the format \eUXXXX for 16 bits and \eWXXXXXXXX
-for 32 bits.
-Also, if this option is off, any UTF8Strings will be converted to their
-character form first.
-.El
-.Sh X509 TEXT OPTIONS
-As well as customising the name output format, it is also possible to
-customise the actual fields printed using the
-.Fl certopt
-options when the
-.Fl text
-option is present.
-The default behaviour is to print all fields.
-.Bl -tag -width "XXXX"
-.It Ar ca_default
-The value used by the
-.Nm ca
-utility; equivalent to
-.Ar no_issuer , no_pubkey , no_header ,
-.Ar no_version , no_sigdump ,
-and
-.Ar no_signame .
-.It Ar compatible
-Use the old format.
-This is equivalent to specifying no output options at all.
-.It Ar ext_default
-Retain default extension behaviour: attempt to print out unsupported
-certificate extensions.
-.It Ar ext_dump
-Hex dump unsupported extensions.
-.It Ar ext_error
-Print an error message for unsupported certificate extensions.
-.It Ar ext_parse
-ASN1 parse unsupported extensions.
-.It Ar no_aux
-Don't print out certificate trust information.
-.It Ar no_extensions
-Don't print out any X509V3 extensions.
-.It Ar no_header
-Don't print header information: that is, the lines saying
-.Qq Certificate
-and
-.Qq Data .
-.It Ar no_issuer
-Don't print out the issuer name.
-.It Ar no_pubkey
-Don't print out the public key.
-.It Ar no_serial
-Don't print out the serial number.
-.It Ar no_sigdump
-Don't give a hexadecimal dump of the certificate signature.
-.It Ar no_signame
-Don't print out the signature algorithm used.
-.It Ar no_subject
-Don't print out the subject name.
-.It Ar no_validity
-Don't print the validity; that is, the
-.Em notBefore
-and
-.Em notAfter
-fields.
-.It Ar no_version
-Don't print out the version number.
-.El
-.Sh X509 EXAMPLES
-Display the contents of a certificate:
-.Pp
-.Dl $ openssl x509 -in cert.pem -noout -text
-.Pp
-Display the certificate serial number:
-.Pp
-.Dl $ openssl x509 -in cert.pem -noout -serial
-.Pp
-Display the certificate subject name:
-.Pp
-.Dl $ openssl x509 -in cert.pem -noout -subject
-.Pp
-Display the certificate subject name in RFC 2253 form:
-.Pp
-.Dl $ openssl x509 -in cert.pem -noout -subject -nameopt RFC2253
-.Pp
-Display the certificate subject name in oneline form on a terminal
-supporting UTF8:
-.Bd -literal -offset indent
-$ openssl x509 -in cert.pem -noout -subject \e
-        -nameopt oneline,-esc_msb
-.Ed
-.Pp
-Display the certificate MD5 fingerprint:
-.Pp
-.Dl $ openssl x509 -in cert.pem -noout -fingerprint
-.Pp
-Display the certificate SHA1 fingerprint:
-.Pp
-.Dl $ openssl x509 -sha1 -in cert.pem -noout -fingerprint
-.Pp
-Convert a certificate from PEM to DER format:
-.Pp
-.Dl "$ openssl x509 -in cert.pem -inform PEM -out cert.der -outform DER"
-.Pp
-Convert a certificate to a certificate request:
-.Bd -literal -offset indent
-$ openssl x509 -x509toreq -in cert.pem -out req.pem \e
-        -signkey key.pem
-.Ed
-.Pp
-Convert a certificate request into a self-signed certificate using
-extensions for a CA:
-.Bd -literal -offset indent
-$ openssl x509 -req -in careq.pem -extfile openssl.cnf -extensions \e
-        v3_ca -signkey key.pem -out cacert.pem
-.Ed
-.Pp
-Sign a certificate request using the CA certificate above and add user
-certificate extensions:
-.Bd -literal -offset indent
-$ openssl x509 -req -in req.pem -extfile openssl.cnf -extensions \e
-        v3_usr -CA cacert.pem -CAkey key.pem -CAcreateserial
-.Ed
-.Pp
-Set a certificate to be trusted for SSL
-client use and set its alias to
-.Qq Steve's Class 1 CA :
-.Bd -literal -offset indent
-$ openssl x509 -in cert.pem -addtrust clientAuth \e
-        -setalias "Steve's Class 1 CA" -out trust.pem
-.Ed
-.Sh X509 NOTES
-The PEM format uses the header and footer lines:
-.Bd -unfilled -offset indent
------BEGIN CERTIFICATE-----
------END CERTIFICATE-----
-.Ed
-.Pp
-It will also handle files containing:
-.Bd -unfilled -offset indent
------BEGIN X509 CERTIFICATE-----
------END X509 CERTIFICATE-----
-.Ed
-.Pp
-Trusted certificates have the lines:
-.Bd -unfilled -offset indent
------BEGIN TRUSTED CERTIFICATE-----
------END TRUSTED CERTIFICATE-----
-.Ed
-.Pp
-The conversion to UTF8 format used with the name options assumes that
-T61Strings use the ISO 8859-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.
-.Pp
-The
-.Fl fingerprint
-option takes the digest of the DER-encoded certificate.
-This is commonly called a
-.Qq fingerprint .
-Because of the nature of message digests, the fingerprint of a certificate
-is unique to that certificate and two certificates with the same fingerprint
-can be considered to be the same.
-.Pp
-The Netscape fingerprint uses MD5, whereas MSIE uses SHA1.
-.Pp
-The
-.Fl 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.
-.Sh X.509 CERTIFICATE EXTENSIONS
-The
-.Fl purpose
-option checks the certificate extensions and determines
-what the certificate can be used for.
-The actual checks done are rather
-complex and include various hacks and workarounds to handle broken
-certificates and software.
-.Pp
-The same code is used when verifying untrusted certificates in chains,
-so this section is useful if a chain is rejected by the verify code.
-.Pp
-The
-.Em basicConstraints
-extension CA flag is used to determine whether the
-certificate can be used as a CA.
-If the CA flag is true, it is a CA;
-if the CA flag is false, it is not a CA.
-.Em All
-CAs should have the CA flag set to true.
-.Pp
-If the
-.Em basicConstraints
-extension is absent, then the certificate is
-considered to be a
-.Qq possible CA ;
-other extensions are checked according to the intended use of the certificate.
-A warning is given in this case because the certificate should really not
-be regarded as a CA: however,
-it is allowed to be a CA to work around some broken software.
-.Pp
-If the certificate is a V1 certificate
-.Pq and thus has no extensions
-and it is self-signed, it is also assumed to be a CA but a warning is again
-given: this is to work around the problem of Verisign roots which are V1
-self-signed certificates.
-.Pp
-If the
-.Em keyUsage
-extension is present, then additional restraints are
-made on the uses of the certificate.
-A CA certificate
-.Em must
-have the
-.Em keyCertSign
-bit set if the
-.Em keyUsage
-extension is present.
-.Pp
-The extended key usage extension places additional restrictions on the
-certificate uses.
-If this extension is present
-.Pq whether critical or not ,
-the key can only be used for the purposes specified.
-.Pp
-A complete description of each test is given below.
-The comments about
-.Em basicConstraints
-and
-.Em keyUsage
-and V1 certificates above apply to
-.Em all
-CA certificates.
-.Bl -tag -width "XXXX"
-.It Ar SSL Client
-The extended key usage extension must be absent or include the
-.Qq web client authentication
-OID.
-.Ar keyUsage
-must be absent or it must have the
-.Em digitalSignature
-bit set.
-Netscape certificate type must be absent or it must have the SSL
-client bit set.
-.It Ar SSL Client CA
-The extended key usage extension must be absent or include the
-.Qq web client authentication
-OID.
-Netscape certificate type must be absent or it must have the SSL CA
-bit set: this is used as a work around if the
-.Em basicConstraints
-extension is absent.
-.It Ar SSL Server
-The extended key usage extension must be absent or include the
-.Qq web server authentication
-and/or one of the SGC OIDs.
-.Em keyUsage
-must be absent or it must have the
-.Em digitalSignature
-set, the
-.Em keyEncipherment
-set, or both bits set.
-Netscape certificate type must be absent or have the SSL server bit set.
-.It Ar SSL Server CA
-The extended key usage extension must be absent or include the
-.Qq web server authentication
-and/or one of the SGC OIDs.
-Netscape certificate type must be absent or the SSL CA
-bit must be set: this is used as a work around if the
-.Em basicConstraints
-extension is absent.
-.It Ar Netscape SSL Server
-For Netscape SSL clients to connect to an SSL server; it must have the
-.Em keyEncipherment
-bit set if the
-.Em keyUsage
-extension is present.
-This isn't always valid because some cipher suites use the key for
-digital signing.
-Otherwise it is the same as a normal SSL server.
-.It Ar Common S/MIME Client Tests
-The extended key usage extension must be absent or include the
-.Qq email protection
-OID.
-Netscape certificate type must be absent or should have the
-.Em S/MIME
-bit set.
-If the
-.Em S/MIME
-bit is not set in Netscape certificate type, then the SSL
-client bit is tolerated as an alternative but a warning is shown:
-this is because some Verisign certificates don't set the
-.Em S/MIME
-bit.
-.It Ar S/MIME Signing
-In addition to the common
-.Em S/MIME
-client tests, the
-.Em digitalSignature
-bit must be set if the
-.Em keyUsage
-extension is present.
-.It Ar S/MIME Encryption
-In addition to the common
-.Em S/MIME
-tests, the
-.Em keyEncipherment
-bit must be set if the
-.Em keyUsage
-extension is present.
-.It Ar S/MIME CA
-The extended key usage extension must be absent or include the
-.Qq email protection
-OID.
-Netscape certificate type must be absent or must have the
-.Em S/MIME CA
-bit set: this is used as a work around if the
-.Em basicConstraints
-extension is absent.
-.It Ar CRL Signing
-The
-.Em keyUsage
-extension must be absent or it must have the
-.Em CRL
-signing bit set.
-.It Ar CRL Signing CA
-The normal CA tests apply.
-Except in this case the
-.Em basicConstraints
-extension must be present.
-.El
-.Sh X509 BUGS
-Extensions in certificates are not transferred to certificate requests and
-vice versa.
-.Pp
-It is possible to produce invalid certificates or requests by specifying the
-wrong private key or using inconsistent options in some cases: these should
-be checked.
-.Pp
-There should be options to explicitly set such things as start and end dates,
-rather than an offset from the current time.
-.Pp
-The code to implement the verify behaviour described in the
-.Sx X509 TRUST SETTINGS
-is currently being developed.
-It thus describes the intended behaviour rather than the current behaviour.
-It is hoped that it will represent reality in
-.Nm OpenSSL
-0.9.5 and later.
-.Sh X509 HISTORY
-Before
-.Nm OpenSSL
-0.9.8,
-the default digest for RSA keys was MD5.
-.Pp
-The hash algorithm used in the
-.Fl subject_hash
-and
-.Fl issuer_hash
-options before
-.Nm OpenSSL
-1.0.0 was based on the deprecated MD5 algorithm and the encoding
-of the distinguished name.
-In
-.Nm OpenSSL
-1.0.0 and later it is based on a canonical version of the DN using SHA1.
-This means that any directories using the old form
-must have their links rebuilt using
-.Ar c_rehash
-or similar.
 .Sh COMMON NOTATION
 Several commands share a common syntax,
 as detailed below.