[BACK]Return to openssl.1 CVS log [TXT][DIR] Up to [local] / src / usr.bin / openssl

Diff for /src/usr.bin/openssl/openssl.1 between version 1.79 and 1.80

version 1.79, 2016/09/20 16:45:38 version 1.80, 2016/09/22 13:30:49
Line 1956 
Line 1956 
 or takes a file of certificates  or takes a file of certificates
 and converts it into a Netscape certificate sequence.  and converts it into a Netscape certificate sequence.
 .Pp  .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:  The options are as follows:
 .Bl -tag -width Ds  .Bl -tag -width Ds
 .It Fl in Ar file  .It Fl in Ar file
Line 2452 
Line 2446 
 keys encrypted using PKCS#5 v2.0 algorithms and high iteration counts  keys encrypted using PKCS#5 v2.0 algorithms and high iteration counts
 are more secure.  are more secure.
 .Pp  .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:  The options are as follows:
 .Bl -tag -width Ds  .Bl -tag -width Ds
 .It Fl embed  .It Fl embed
Line 5347 
Line 5328 
 .Nm openssl  .Nm openssl
 version.  version.
 .El  .El
 .\"  
 .\" X509  
 .\"  
 .Sh X509  .Sh X509
 .nr nS 1  .nr nS 1
 .Nm "openssl x509"  .Nm "openssl x509"
 .Bk -words  
 .Op Fl C  .Op Fl C
 .Op Fl addreject Ar arg  .Op Fl addreject Ar arg
 .Op Fl addtrust Ar arg  .Op Fl addtrust Ar arg
 .Op Fl alias  .Op Fl alias
 .Op Fl CA Ar file  .Op Fl CA Ar file
 .Op Fl CAcreateserial  .Op Fl CAcreateserial
 .Op Fl CAform Ar DER | PEM  .Op Fl CAform Cm der | pem
 .Op Fl CAkey Ar file  .Op Fl CAkey Ar file
 .Op Fl CAkeyform Ar DER | PEM  .Op Fl CAkeyform Cm der | pem
 .Op Fl CAserial Ar file  .Op Fl CAserial Ar file
 .Op Fl certopt Ar option  .Op Fl certopt Ar option
 .Op Fl checkend Ar arg  .Op Fl checkend Ar arg
Line 5378 
Line 5355 
 .Op Fl fingerprint  .Op Fl fingerprint
 .Op Fl hash  .Op Fl hash
 .Op Fl in Ar file  .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
 .Op Fl issuer_hash  .Op Fl issuer_hash
 .Op Fl issuer_hash_old  .Op Fl issuer_hash_old
 .Op Fl keyform Ar DER | PEM  .Op Fl keyform Cm der | pem
 .Op Fl md5 | sha1  .Op Fl md5 | sha1
 .Op Fl modulus  .Op Fl modulus
 .Op Fl nameopt Ar option  .Op Fl nameopt Ar option
Line 5390 
Line 5367 
 .Op Fl ocsp_uri  .Op Fl ocsp_uri
 .Op Fl ocspid  .Op Fl ocspid
 .Op Fl out Ar file  .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 passin Ar arg
 .Op Fl pubkey  .Op Fl pubkey
 .Op Fl purpose  .Op Fl purpose
Line 5406 
Line 5383 
 .Op Fl text  .Op Fl text
 .Op Fl trustout  .Op Fl trustout
 .Op Fl x509toreq  .Op Fl x509toreq
 .Ek  
 .nr nS 0  .nr nS 0
 .Pp  .Pp
 The  The
Line 5417 
Line 5393 
 .Qq mini CA ,  .Qq mini CA ,
 or edit certificate trust settings.  or edit certificate trust settings.
 .Pp  .Pp
 Since there are a large number of options, they are split up into  The following are x509 input, output, and general purpose options:
 various sections.  
 .Sh X509 INPUT, OUTPUT, AND GENERAL PURPOSE OPTIONS  
 .Bl -tag -width "XXXX"  .Bl -tag -width "XXXX"
 .It Fl in Ar file  .It Fl in Ar file
 This specifies the input  The input file to read from,
 .Ar file  or standard input if not specified.
 to read a certificate from, or standard input if this option is not specified.  .It Fl inform Cm der | net | pem
 .It Fl inform Ar DER | NET | PEM  The input format.
 This specifies the input format.  
 Normally, the command will expect an X.509 certificate,  Normally, the command will expect an X.509 certificate,
 but this can change if other options such as  but this can change if other options such as
 .Fl req  .Fl req
 are present.  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  .It Fl md5 | sha1
 The digest to use.  The digest to use.
 This affects any signing or display option that uses a message digest,  This affects any signing or display option that uses a message digest,
Line 5449 
Line 5413 
 .Fl CA  .Fl CA
 options.  options.
 If not specified, MD5 is used.  If not specified, MD5 is used.
 If the key being used to sign with is a DSA key,  SHA1 is always used with DSA keys.
 this option has no effect: SHA1 is always used with DSA keys.  
 .It Fl out Ar file  .It Fl out Ar file
 This specifies the output  The output file to write to,
 .Ar file  or standard output if none is specified.
 to write to, or standard output by default.  .It Fl outform Cm der | net | pem
 .It Fl outform Ar DER | NET | PEM  The output format.
 This specifies the output format; the options have the same meaning as the  
 .Fl inform  
 option.  
 .It Fl passin Ar arg  .It Fl passin Ar arg
 The key password source.  The key password source.
 .El  .El
 .Sh X509 DISPLAY OPTIONS  .Pp
 .Sy Note :  The following are x509 display options:
 The  
 .Fl alias  
 and  
 .Fl purpose  
 options are also display options but are described in the  
 .Sx X509 TRUST SETTINGS  
 section.  
 .Bl -tag -width "XXXX"  .Bl -tag -width "XXXX"
 .It Fl C  .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  .It Fl certopt Ar option
 Customise the output format used with  Customise the output format used with
 .Fl text .  .Fl text ,
 The  either using a list of comma-separated options or by specifying
 .Ar option  
 argument can be a single option or multiple options separated by commas.  
 The  
 .Fl certopt  .Fl certopt
 switch may also be used more than once to set multiple options.  multiple times.
 See the  The default behaviour is to print all fields.
 .Sx X509 TEXT OPTIONS  The options are as follows:
 section for more information.  .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  .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  .It Fl email
 Outputs the email address(es), if any.  Output the email addresses, if any.
 .It Fl enddate  .It Fl enddate
 Prints out the expiry date of the certificate; that is, the  Print the expiry date of the certificate; that is, the
 .Em notAfter  .Cm notAfter
 date.  date.
 .It Fl fingerprint  .It Fl fingerprint
 Prints out the digest of the DER-encoded version of the whole certificate  Print the digest of the DER-encoded version of the whole certificate.
 (see  
 .Sx DIGEST OPTIONS ) .  
 .It Fl hash  .It Fl hash
 A synonym for  A synonym for
 .Fl subject_hash ,  .Fl subject_hash .
 for backwards compatibility.  
 .It Fl issuer  .It Fl issuer
 Outputs the issuer name.  Print the issuer name.
 .It Fl issuer_hash  .It Fl issuer_hash
 Outputs the  Print the hash of the certificate issuer name.
 .Qq hash  
 of the certificate issuer name.  
 .It Fl issuer_hash_old  .It Fl issuer_hash_old
 Outputs the  Print the hash of the certificate issuer name
 .Qq hash  using the older algorithm as used by
 of the certificate issuer name using the older algorithm  .Nm openssl
 as used by  
 .Nm OpenSSL  
 versions before 1.0.0.  versions before 1.0.0.
 .It Fl modulus  .It Fl modulus
 This option prints out the value of the modulus of the public key  Print the value of the modulus of the public key contained in the certificate.
 contained in the certificate.  
 .It Fl nameopt Ar option  .It Fl nameopt Ar option
 Option which determines how the subject or issuer names are displayed.  Customise how the subject or issuer names are displayed,
 The  either using a list of comma-separated options or by specifying
 .Ar option  
 argument can be a single option or multiple options separated by commas.  
 Alternatively, the  
 .Fl nameopt  .Fl nameopt
 switch may be used more than once to set multiple options.  multiple times.
 See the  The default behaviour is to use the
 .Sx X509 NAME OPTIONS  .Cm oneline
 section for more information.  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  .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  .It Fl ocsp_uri
 Outputs the OCSP responder addresses, if any.  Print the OCSP responder addresses, if any.
 .It Fl ocspid  .It Fl ocspid
 Print OCSP hash values for the subject name and public key.  Print OCSP hash values for the subject name and public key.
 .It Fl pubkey  .It Fl pubkey
 Output the public key.  Print the public key.
 .It Fl serial  .It Fl serial
 Outputs the certificate serial number.  Print the certificate serial number.
 .It Fl startdate  .It Fl startdate
 Prints out the start date of the certificate; that is, the  Print the start date of the certificate; that is, the
 .Em notBefore  .Cm notBefore
 date.  date.
 .It Fl subject  .It Fl subject
 Outputs the subject name.  Print the subject name.
 .It Fl subject_hash  .It Fl subject_hash
 Outputs the  Print the hash of the certificate subject name.
 .Qq hash  
 of the certificate subject name.  
 This is used in  This is used in
 .Nm OpenSSL  .Nm openssl
 to form an index to allow certificates in a directory to be looked up  to form an index to allow certificates in a directory to be looked up
 by subject name.  by subject name.
 .It Fl subject_hash_old  .It Fl subject_hash_old
 Outputs the  Print the hash of the certificate subject name
 .Qq hash  using the older algorithm as used by
 of the certificate subject name using the older algorithm  .Nm openssl
 as used by  
 .Nm OpenSSL  
 versions before 1.0.0.  versions before 1.0.0.
 .It Fl text  .It Fl text
 Prints out the certificate in text form.  Print the full 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.  
 .El  .El
 .Sh X509 TRUST SETTINGS  
 Please note these options are currently experimental and may well change.  
 .Pp  .Pp
 A  A trusted certificate is a certificate which has several
 .Em trusted certificate  
 is an ordinary certificate which has several  
 additional pieces of information attached to it such as the permitted  additional pieces of information attached to it such as the permitted
 and prohibited uses of the certificate and an  and prohibited uses of the certificate and an alias.
 .Qq alias .  When a certificate is being verified at least one certificate must be trusted.
 .Pp  By default, a trusted certificate must be stored locally and be a root CA.
 Normally, when a certificate is being verified at least one certificate  The following are x509 trust settings options:
 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.  
 .Bl -tag -width "XXXX"  .Bl -tag -width "XXXX"
 .It Fl addreject Ar arg  .It Fl addreject Ar arg
 Adds a prohibited use.  Add a prohibited use.
 It accepts the same values as the  Accepts the same values as the
 .Fl addtrust  .Fl addtrust
 option.  option.
 .It Fl addtrust Ar arg  .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  Any object name can be used here, but currently only
 .Ar clientAuth  .Cm clientAuth
 .Pq SSL client use ,  (SSL client use),
 .Ar serverAuth  .Cm serverAuth
 .Pq SSL server use ,  (SSL server use),
 and  and
 .Ar emailProtection  .Cm emailProtection
 .Pq S/MIME email  (S/MIME email) are used.
 are used.  
 Other  
 .Nm OpenSSL  
 applications may define additional uses.  
 .It Fl alias  .It Fl alias
 Outputs the certificate alias, if any.  Output the certificate alias.
 .It Fl clrreject  .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  .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  .It Fl purpose
 This option performs tests on the certificate extensions and outputs  Perform tests on the certificate extensions.
 the results.  The same code is used when verifying untrusted certificates in chains,
 For a more complete description, see the  so this section is useful if a chain is rejected by the verify code.
 .Sx X.509 CERTIFICATE EXTENSIONS  .Pp
 section.  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  .It Fl setalias Ar arg
 Sets the alias of the certificate.  Set the alias of the certificate,
 This will allow the certificate to be referred to using a nickname,  allowing the certificate to be referred to using a nickname,
 for example  such as
 .Qq Steve's Certificate .  .Qq Steve's Certificate .
 .It Fl trustout  .It Fl trustout
 This causes  Output a trusted certificate
 .Nm x509  (the default if any trust settings are modified).
 to output a  
 .Em trusted certificate .  
 An ordinary or trusted certificate can be input, but by default an ordinary  An ordinary or trusted certificate can be input, but by default an ordinary
 certificate is output and any trust settings are discarded.  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  .El
 .Sh X509 SIGNING OPTIONS  .Pp
 The  The
 .Nm x509  .Nm x509
 utility can be used to sign certificates and requests: it  utility can be used to sign certificates and requests:
 can thus behave like a  it can thus behave like a mini CA.
 .Qq mini CA .  The following are x509 signing options:
 .Bl -tag -width "XXXX"  .Bl -tag -width "XXXX"
 .It Fl CA Ar file  .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,  When this option is present,
 .Nm x509  .Nm x509
 behaves like a  behaves like a mini CA.
 .Qq mini CA .  
 The input file is signed by the CA using this option;  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  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.  digitally signed using the CA's private key.
Line 5669 
Line 5865 
 .Fl req  .Fl req
 option, the input is a certificate which must be self-signed.  option, the input is a certificate which must be self-signed.
 .It Fl CAcreateserial  .It Fl CAcreateserial
 With this option the CA serial number file is created if it does not exist:  Create the CA serial number file if it does not exist
 it will contain the serial number  instead of generating an error.
   The file will contain the serial number
 .Sq 02  .Sq 02
 and the certificate being signed will have  and the certificate being signed will have
 .Sq 1  .Sq 1
 as its serial number.  as its serial number.
 Normally, if the  .It Fl CAform Cm der | pem
 .Fl CA  
 option is specified and the serial number file does not exist, it is an error.  
 .It Fl CAform Ar DER | PEM  
 The format of the CA certificate file.  The format of the CA certificate file.
 The default is  The default is
 .Ar PEM .  .Cm pem .
 .It Fl CAkey Ar file  .It Fl CAkey Ar file
 Sets the CA private key to sign a certificate with.  Set the CA private key to sign a certificate with.
 If this option is not specified, it is assumed that the CA private key  Otherwise it is assumed that the CA private key is present
 is present in the CA certificate file.  in the CA certificate file.
 .It Fl CAkeyform Ar DER | PEM  .It Fl CAkeyform Cm der | pem
 The format of the CA private key.  The format of the CA private key.
 The default is  The default is
 .Ar PEM .  .Cm pem .
 .It Fl CAserial Ar file  .It Fl CAserial Ar file
 Sets the CA serial number file to use.  Use the serial number in
 .Pp  .Ar file
 When the  to sign a certificate.
 .Fl CA  The file should consist of one line containing an even number of hex digits
 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  
 with the serial number to use.  with the serial number to use.
 After each use the serial number is incremented and written out  After each use the serial number is incremented and written out
 to the file again.  to the file again.
Line 5725 
Line 5916 
 options).  options).
 Normally, all extensions are retained.  Normally, all extensions are retained.
 .It Fl days Ar arg  .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.  The default is 30 days.
 .It Fl extensions Ar section  .It Fl extensions Ar section
 The section to add certificate extensions from.  The section to add certificate extensions from.
 If this option is not specified, the extensions should either be  If this option is not specified, the extensions should either be
 contained in the unnamed  contained in the unnamed (default) section
 .Pq default  or the default section should contain a variable called
 section or the default section should contain a variable called  
 .Qq extensions  .Qq extensions
 which contains the section to use.  which contains the section to use.
 .It Fl extfile Ar file  .It Fl extfile Ar file
 File containing certificate extensions to use.  File containing certificate extensions to use.
 If not specified, no extensions are added to the certificate.  If not specified, no extensions are added to the certificate.
 .It Fl keyform Ar DER | PEM  .It Fl keyform Cm der | pem
 Specifies the format  The format of the private key file used in the
 .Pq DER or PEM  
 of the private key file used in the  
 .Fl signkey  .Fl signkey
 option.  option.
 .It Fl req  .It Fl req
 By default, a certificate is expected on input.  Expect a certificate request on input instead of a certificate.
 With this option a certificate request is expected instead.  
 .It Fl set_serial Ar n  .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  This option can be used with either the
 .Fl signkey  .Fl signkey
 or  or
Line 5766 
Line 5953 
 .Sq 0x ) .  .Sq 0x ) .
 Negative serial numbers can also be specified but their use is not recommended.  Negative serial numbers can also be specified but their use is not recommended.
 .It Fl signkey Ar file  .It Fl signkey Ar file
 This option causes the input file to be self-signed using the supplied  Self-sign
 private key.  .Ar file
   using the supplied private key.
 .Pp  .Pp
 If the input file is a certificate, it sets the issuer name to the  If the input file is a certificate, it sets the issuer name to the
 subject name  subject name (i.e. makes it self-signed),
 .Pq i.e. makes it self-signed ,  
 changes the public key to the supplied value,  changes the public key to the supplied value,
 and changes the start and end dates.  and changes the start and end dates.
 The start date is set to the current time and the end date is set to  The start date is set to the current time and the end date is set to
Line 5786 
Line 5973 
 is created using the supplied private key using the subject name in  is created using the supplied private key using the subject name in
 the request.  the request.
 .It Fl x509toreq  .It Fl x509toreq
 Converts a certificate into a certificate request.  Convert a certificate into a certificate request.
 The  The
 .Fl signkey  .Fl signkey
 option is used to pass the required private key.  option is used to pass the required private key.
 .El  .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  .Sh COMMON NOTATION
 Several commands share a common syntax,  Several commands share a common syntax,
 as detailed below.  as detailed below.
Legend:
Removed from v.1.79  
changed lines
  Added in v.1.80