x509(1ssl)x509(1ssl)NAMEx509 - Certificate display and signing utility
SYNOPSIS
openssl x509 [-inform DER | PEM | NET] [-outform DER | PEM | NET]
[-keyform DER| PEM] [-CAform DER | PEM] [-CAkeyform DER | PEM]
[-infilename] [-outfilename] [-serial] [-hash] [-subject] [-issuer]
[-nameopt option] [-email] [-startdate] [-enddate] [-purpose] [-dates]
[-modulus] [-fingerprint] [-alias] [-noout] [-trustout] [-clrtrust]
[-clrreject] [-addtrust arg] [-addreject arg] [-setalias arg] [-days
arg] [-signkey filename] [-x509toreq] [-req] [-CA filename] [-CAkey
filename] [-CAcreateserial] [-CAserial filename] [-text] [-C] [-md2 |
-md5 | -sha1 | -mdc2] [-clrext] [-extfile filename] [-extensions sec‐
tion]
INPUT, OUTPUT AND GENERAL PURPOSE OPTIONS
Specifies the input format. Normally the command will expect an X509
certificate but this can change if other options such as -req are
present. The DER format is the DER encoding of the certificate, and PEM
is the base64 encoding of the DER encoding with header and footer lines
added. The NET option is an obscure Netscape server format that is
obsolete. Specifies the output format. The options have the same mean‐
ing as the -inform option. Specifies the input filename to read a cer‐
tificate from or standard input if this option is not specified. Spec‐
ifies the output filename to write to or standard output by default.
The digest to use. This affects any signing or display option that uses
a message digest, such as the -fingerprint, -signkey and -CA options.
If not specified then MD5 is used. If the key being used to sign with
is a DSA key then this option has no effect. SHA1 is always used with
DSA keys.
DISPLAY OPTIONS
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.
Prevents output of the encoded version of the request. Prints out the
value of the modulus of the public key contained in the certificate.
Outputs the certificate serial number. Outputs the hash of the cer‐
tificate subject name. This is used in OpenSSL to form an index to
allow certificates in a directory to be looked up by subject name.
Outputs the subject name. Outputs the issuer name. Option which
determines how the subject or issuer names are displayed. This option
may be used more than once to set multiple options. See the Name
Options section for more information. Outputs the email address if
any. Prints the start date of the certificate, that is the notBefore
date. Prints the expiration date of the certificate, that is the
notAfter date. Prints the start and expiration dates of a certificate.
Prints the digest of the DER encoded version of the whole certificate.
Outputs the certificate in the form of a C source file.
The -alias and -purpose options are display options but are described
in the Trust Options section.
TRUST OPTIONS
These options are experimental and may change.
A trusted certificate is an ordinary certificate which has several
additional pieces of information attached to it, such as the permitted
and prohibited uses of the certificate and an alias.
Usually when a certificate is being verified, at least one certificate
must be 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.
Trust settings are only used with a root CA. They allow finer control
over the purposes of the root CA. For example, a CA may be trusted for
SSL client but not SSL server use.
See the description of the verify utility for more information on the
meaning of trust settings.
Future versions of OpenSSL will recognize trust settings on any cer‐
tificate, not just root CAs. Causes x509 to output a trusted certifi‐
cate. An ordinary or trusted certificate can be input, but by default
an ordinary certificate is output and any trust settings are discarded.
With the -trustout option a trusted certificate is output. A trusted
certificate is automatically output if any trust settings are modified.
Sets the alias of the certificate. This will allow the certificate to
be referred to using a nickname, such as Steve's Certificate. Outputs
the certificate alias, if any. Clears all the permitted or trusted
uses of the certificate. Clears all the prohibited or rejected uses of
the certificate. Adds a trusted certificate use. Any object name can
be used here but only clientAuth (SSL client use), serverAuth (SSL
server use) and emailProtection (S/MIME email) are used. Other OpenSSL
applications may define additional uses. Adds a prohibited use. It
accepts the same values as the -addtrust option. Performs tests on the
certificate extensions and outputs the results.
Certificate Extensions
The -purpose option checks the certificate extensions and determines
what the certificate can be used for. The actual checks are complex and
include various hacks and workarounds to handle broken certificates and
software.
The same code is used when verifying untrusted certificates in chains.
The basicConstraints extension CA flag is used to determine whether the
certificate can be used as a CA. If the CA flag is true then it is a
CA. If the CA flag is false then it is not a CA. All CAs should have
the CA flag set to true.
If the 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 not be regarded as a CA. However, it is
allowed to be a CA to work around some broken software.
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
given. This is to work around the problem of Verisign roots which are
V1 self signed certificates.
If the keyUsage extension is present then additional restraints are
made on the uses of the certificate. A CA certificate must have the
keyCertSign bit set if the keyUsage extension is present.
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.
The comments about basicConstraints and keyUsage and V1 certificates
apply to all CA certificates. A complete description of each test fol‐
lows: SSL Client
The extended key usage extension must be absent or include the
web client authentication OID. The keyUsage extension must be
absent or it must have the digitalSignature bit set. Netscape
certificate type must be absent or it must have the SSL client
bit set. SSL Client CA
The extended key usage extension must be absent or include the
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 basicConstraints extension is absent. SSL
Server
The extended key usage extension must be absent or include the
web server authentication and/or one of the SGC OIDs. The
keyUsage extension must be absent or it must have the digi‐
talSignature, the keyEncipherment set or both bits set. Netscape
certificate type must be absent or have the SSL server bit set.
SSL Server CA
The extended key usage extension must be absent or include the
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 basicConstraints extension
is absent. Netscape SSL Server
For Netscape SSL clients to connect to an SSL server it must
have the keyEncipherment bit set if the 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 nor‐
mal SSL server. Common S/MIME Client Tests
The extended key usage extension must be absent or include the
email protection OID. 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 toler‐
ated as an alternative but a warning is shown. This is because
some Verisign certificates don't set the S/MIME bit. S/MIME
Signing
In addition to the common S/MIME client tests the digitalSigna‐
ture bit must be set if the keyUsage extension is present.
S/MIME Encryption
In addition to the common S/MIME tests the keyEncipherment bit
must be set if the keyUsage extension is present. S/MIME CA
The extended key usage extension must be absent or include the
email protection OID. Netscape certificate type must be absent
or must have the S/MIME CA bit set. This is used as a work
around if the basicConstraints extension is absent. CRL Signing
The keyUsage extension must be absent or it must have the CRL
signing bit set. CRL Signing CA
The normal CA tests apply, except in this case the basic‐
Constraints extension must be present.
SIGNING OPTIONS
The x509 command can be used to sign certificates and requests. It can
thus behave like a mini CA. Causes the input file to be self-signed
using the supplied private key. If the input file is a certificate it
sets the issuer name to the subject name (i.e. It 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 a value determined by the -days option. Any certificate
extensions are retained unless the -clrext option is supplied. If the
input is a certificate request, then a self-signed certificate is cre‐
ated using the supplied private key using the subject name in the
request. Deletes any extensions from a certificate. This option is
used when a certificate is being created from another certificate, such
as with the -signkey or the -CA options. Normally all extensions are
retained. Specifies the format (DER or PEM) of the private key file
used in the -signkey option. Specifies the number of days to make a
certificate valid. The default is 30 days. Converts a certificate into
a certificate request. The -signkey option is used to pass the required
private key. By default a certificate is expected on input. With this
option, a certificate request is expected instead. Specifies the CA
certificate to be used for signing. When this option is present x509
behaves like a mini CA. The input file is signed by this CA using this
option, meaning its issuer name is set to the subject name of the CA
and it is digitally signed using the CA's private key.
This option is normally combined with the -req option. Without
the -req option the input is a certificate which must be self-
signed. Sets the CA private key to sign a certificate with. If
this option is not specified then it is assumed that the CA pri‐
vate key is present in the CA certificate file. Sets the CA
serial number file to use.
When the -CA option is used to sign a certificate it uses a
serial number specified in a file. This file 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.
The default filename consists of the CA certificate file base
name with appended. For example, if the CA certificate file is
called mycacert.pem it expects to find a serial number file
called mycacert.srl. Creates a CA serial number file if it
does not exist. It will contain the serial number 02 and the
certificate being signed will have the number 1 as its serial
number. Normally, if the -CA option is specified and the serial
number file does not exist it is an error. File containing cer‐
tificate extensions to use. If not specified then no extensions
are added to the certificate. The section to add certificate
extensions from. If this option is not specified then the exten‐
sions should either be contained in the unnamed (default) sec‐
tion or the default section should contain a variable called
extensions which contains the section to use.
NAME OPTIONS
The nameopt command line option determines how the subject and issuer
names are displayed. If no nameopt option is present the default one‐
line 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 - to turn the option off. Usually, only the first four
are used. Uses the old format. This is equivalent to specifying no
name options. Displays names compatible with RFC2253 equivalent to
esc_2253, esc_ctrl, esc_msb, utf8, dump_nostr, dump_unknown, dump_der,
sep_comma_plus, dn_rev and sname. A oneline format which is more read‐
able than RFC2253. It is equivalent to esc_2253, esc_ctrl, esc_msb,
utf8, dump_nostr, dump_der, use_quote, sep_comma_plus_spc, spc_eq and
sname options. A multiline format. It is equivalent to esc_ctrl,
esc_msb, sep_multiline, spc_eq and lname. Escapes the special charac‐
ters required by RFC2253 in a field. These characters are ,+"<>;. Addi‐
tionally # is escaped at the begining of a string and a space character
at the beginning or end of a string. Escapes control characters.
These characters are 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.
Escapes characters with the MSB set, that is with ASCII values larger
than 127. Escapes some characters by surrounding the whole string with
" characters. Without the option, all escaping is done with the \ char‐
acter. Converts all strings to UTF8 format first. This is required by
RFC2253. If you have a UTF8 compatible terminal then the use of this
option (and not setting esc_msb) may result in the correct display of
multibyte (international) characters. Is this option is not present,
then multibyte characters larger than 0xff will be represented using
the format \UXXXX for 16 bits and \WXXXXXXXX for 32 bits. Also, if this
option is off any UTF8Strings will be converted to their character form
first. Does not attempt to interpret multibyte characters in any way.
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. Shows the type of the ASN1 character
string. The type precedes the field contents. For example, BMPSTRING:
Hello World. When this option is set any fields that need to be hex‐
dumped will be dumped using the DER encoding of the field. Otherwise,
just the content octets will be displayed. Both options use the RFC2253
#XXXX... format. Dumps non-character string types, such as 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.
Dumps all fields. This option when used with dump_der allows the DER
encoding of the structure to be unambiguously determined. Dumps any
field whose OID is not recognized by OpenSSL. Determines the field
separators. The first character is between RDNs and the second between
multiple AVAs. (Multiple AVAs are very rare and their use is discour‐
aged.) The options ending in space additionally place a space after the
separator to make it more readable. The sep_multiline uses a linefeed
character for the RDN separator and a spaced + for the AVA separator.
It also indents the fields by four characters. Reverses the fields of
the DN. This is required by RFC2253. As a side effect this also
reverses the order of multiple AVAs, but this is permissible. Alter
how the field name is displayed. The nofname option does not display
the field at all. The sname option uses the short name form (CN for
commonName, for example), and the lname option uses the long form. The
oid option represents the OID in numerical form and is useful for diag‐
nostic purpose. Places spaces around the = character which follows the
field name.
DESCRIPTION
The x509 command is a multipurpose certificate utility. It can be used
to display certificate information, convert certificates to various
forms, sign certificate requests such as a mini CA, or edit certificate
trust settings. Since there are a large number of options they are
divided into various sections.
NOTES
The PEM format uses the following header and footer lines:
-----BEGIN CERTIFICATE----
-----END CERTIFICATE----
It will also handle files containing:
-----BEGIN X509 CERTIFICATE----
-----END X509 CERTIFICATE----
Trusted certificates have the following 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 incor‐
rect, it is more likely to display the majority of certificates cor‐
rectly.
The -fingerprint option takes the digest of the DER encoded certifi‐
cate. This is commonly called a fingerprint. Because of the nature of
message digests, the fingerprint of a certificate is unique to that
certificate. Two certificates with the same fingerprint can be consid‐
ered to be the same.
The Netscape fingerprint uses MD5 whereas MSIE uses SHA1.
The -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.
RESTRICTIONS
Extensions in certificates are not transferred to certificate requests
and vice versa.
It is possible to produce invalid certificates or requests by specify‐
ing the wrong private key or using inconsistent options in some cases.
These should be checked.
There should be options to explicitly set such things as start and end
dates rather than an offset from the current time.
The code to implement the verify behavior described in the Trust Set‐
tings is under development. It describes the intended behavior rather
than the current behavior.
EXAMPLES
In these examples the \ character means the example should be on one
line.
Display the contents of a certificate:
openssl x509-in cert.pem -noout -text
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 sup‐
porting UTF8:
openssl x509-in cert.pem -noout -subject -nameopt oneline -nameopt
-escmsb
Display the certificate MD5 fingerprint:
openssl x509-in cert.pem -noout -fingerprint
Display the certificate SHA1 fingerprint:
openssl x509-sha1 -in cert.pem -noout -fingerprint
Convert a certificate from PEM to DER format:
openssl x509-in cert.pem -inform PEM -out cert.der -outform DER
Convert a certificate to a certificate request:
openssl x509-x509toreq -in cert.pem -out req.pem -signkey key.pem
Convert a certificate request into a self signed certificate using
extensions for a CA:
openssl x509-req -in careq.pem -extfile openssl.cnf -extensions v3_ca
\ -signkey key.pem -out cacert.pem
Sign a certificate request using the CA certificate above and add user
certificate extensions:
openssl x509-req -in req.pem -extfile openssl.cnf -extensions v3_usr
\ -CA cacert.pem -CAkey key.pem -CAcreateserial
Set a certificate to be trusted for SSL client use and change set its
alias to "Steve's Class 1 CA"
openssl x509-in cert.pem -addtrust sslclient \ -alias "Steve's
Class 1 CA" -out trust.pem
SEE ALSO
Commands: req(1ssl), ca(1ssl), genrsa(1ssl), gendsa(1ssl), verify(1ssl)x509(1ssl)
