841 lines
33 KiB
Groff
841 lines
33 KiB
Groff
.\" $NetBSD: openssl_x509.1,v 1.12 2003/07/24 14:16:53 itojun Exp $
|
|
.\"
|
|
.\" Automatically generated by Pod::Man version 1.02
|
|
.\" Thu Jul 24 13:07:46 2003
|
|
.\"
|
|
.\" Standard preamble:
|
|
.\" ======================================================================
|
|
.de Sh \" Subsection heading
|
|
.br
|
|
.if t .Sp
|
|
.ne 5
|
|
.PP
|
|
\fB\\$1\fR
|
|
.PP
|
|
..
|
|
.de Sp \" Vertical space (when we can't use .PP)
|
|
.if t .sp .5v
|
|
.if n .sp
|
|
..
|
|
.de Ip \" List item
|
|
.br
|
|
.ie \\n(.$>=3 .ne \\$3
|
|
.el .ne 3
|
|
.IP "\\$1" \\$2
|
|
..
|
|
.de Vb \" Begin verbatim text
|
|
.ft CW
|
|
.nf
|
|
.ne \\$1
|
|
..
|
|
.de Ve \" End verbatim text
|
|
.ft R
|
|
|
|
.fi
|
|
..
|
|
.\" Set up some character translations and predefined strings. \*(-- will
|
|
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
|
|
.\" double quote, and \*(R" will give a right double quote. | will give a
|
|
.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used
|
|
.\" to do unbreakable dashes and therefore won't be available. \*(C` and
|
|
.\" \*(C' expand to `' in nroff, nothing in troff, for use with C<>
|
|
.tr \(*W-|\(bv\*(Tr
|
|
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
|
|
.ie n \{\
|
|
. ds -- \(*W-
|
|
. ds PI pi
|
|
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
|
|
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
|
|
. ds L" ""
|
|
. ds R" ""
|
|
. ds C` `
|
|
. ds C' '
|
|
'br\}
|
|
.el\{\
|
|
. ds -- \|\(em\|
|
|
. ds PI \(*p
|
|
. ds L" ``
|
|
. ds R" ''
|
|
'br\}
|
|
.\"
|
|
.\" If the F register is turned on, we'll generate index entries on stderr
|
|
.\" for titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and
|
|
.\" index entries marked with X<> in POD. Of course, you'll have to process
|
|
.\" the output yourself in some meaningful fashion.
|
|
.if \nF \{\
|
|
. de IX
|
|
. tm Index:\\$1\t\\n%\t"\\$2"
|
|
. .
|
|
. nr % 0
|
|
. rr F
|
|
.\}
|
|
.\"
|
|
.\" For nroff, turn off justification. Always turn off hyphenation; it
|
|
.\" makes way too many mistakes in technical documents.
|
|
.hy 0
|
|
.if n .na
|
|
.\"
|
|
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
|
|
.\" Fear. Run. Save yourself. No user-serviceable parts.
|
|
.bd B 3
|
|
. \" fudge factors for nroff and troff
|
|
.if n \{\
|
|
. ds #H 0
|
|
. ds #V .8m
|
|
. ds #F .3m
|
|
. ds #[ \f1
|
|
. ds #] \fP
|
|
.\}
|
|
.if t \{\
|
|
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
|
|
. ds #V .6m
|
|
. ds #F 0
|
|
. ds #[ \&
|
|
. ds #] \&
|
|
.\}
|
|
. \" simple accents for nroff and troff
|
|
.if n \{\
|
|
. ds ' \&
|
|
. ds ` \&
|
|
. ds ^ \&
|
|
. ds , \&
|
|
. ds ~ ~
|
|
. ds /
|
|
.\}
|
|
.if t \{\
|
|
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
|
|
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
|
|
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
|
|
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
|
|
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
|
|
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
|
|
.\}
|
|
. \" troff and (daisy-wheel) nroff accents
|
|
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
|
|
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
|
|
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
|
|
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
|
|
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
|
|
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
|
|
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
|
|
.ds ae a\h'-(\w'a'u*4/10)'e
|
|
.ds Ae A\h'-(\w'A'u*4/10)'E
|
|
. \" corrections for vroff
|
|
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
|
|
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
|
|
. \" for low resolution devices (crt and lpr)
|
|
.if \n(.H>23 .if \n(.V>19 \
|
|
\{\
|
|
. ds : e
|
|
. ds 8 ss
|
|
. ds o a
|
|
. ds d- d\h'-1'\(ga
|
|
. ds D- D\h'-1'\(hy
|
|
. ds th \o'bp'
|
|
. ds Th \o'LP'
|
|
. ds ae ae
|
|
. ds Ae AE
|
|
.\}
|
|
.rm #[ #] #H #V #F C
|
|
.\" ======================================================================
|
|
.\"
|
|
.IX Title "X509 1"
|
|
.TH X509 1 "0.9.7b" "2003-01-31" "OpenSSL"
|
|
.UC
|
|
.SH "NAME"
|
|
x509 \- Certificate display and signing utility
|
|
.SH "LIBRARY"
|
|
libcrypto, -lcrypto
|
|
.SH "SYNOPSIS"
|
|
.IX Header "SYNOPSIS"
|
|
\&\fBopenssl\fR \fBx509\fR
|
|
[\fB\-inform DER|PEM|NET\fR]
|
|
[\fB\-outform DER|PEM|NET\fR]
|
|
[\fB\-keyform DER|PEM\fR]
|
|
[\fB\-CAform DER|PEM\fR]
|
|
[\fB\-CAkeyform DER|PEM\fR]
|
|
[\fB\-in filename\fR]
|
|
[\fB\-out filename\fR]
|
|
[\fB\-serial\fR]
|
|
[\fB\-hash\fR]
|
|
[\fB\-subject\fR]
|
|
[\fB\-issuer\fR]
|
|
[\fB\-nameopt option\fR]
|
|
[\fB\-email\fR]
|
|
[\fB\-startdate\fR]
|
|
[\fB\-enddate\fR]
|
|
[\fB\-purpose\fR]
|
|
[\fB\-dates\fR]
|
|
[\fB\-modulus\fR]
|
|
[\fB\-fingerprint\fR]
|
|
[\fB\-alias\fR]
|
|
[\fB\-noout\fR]
|
|
[\fB\-trustout\fR]
|
|
[\fB\-clrtrust\fR]
|
|
[\fB\-clrreject\fR]
|
|
[\fB\-addtrust arg\fR]
|
|
[\fB\-addreject arg\fR]
|
|
[\fB\-setalias arg\fR]
|
|
[\fB\-days arg\fR]
|
|
[\fB\-set_serial n\fR]
|
|
[\fB\-signkey filename\fR]
|
|
[\fB\-x509toreq\fR]
|
|
[\fB\-req\fR]
|
|
[\fB\-CA filename\fR]
|
|
[\fB\-CAkey filename\fR]
|
|
[\fB\-CAcreateserial\fR]
|
|
[\fB\-CAserial filename\fR]
|
|
[\fB\-text\fR]
|
|
[\fB\-C\fR]
|
|
[\fB\-md2|\-md5|\-sha1|\-mdc2\fR]
|
|
[\fB\-clrext\fR]
|
|
[\fB\-extfile filename\fR]
|
|
[\fB\-extensions section\fR]
|
|
[\fB\-engine id\fR]
|
|
.SH "DESCRIPTION"
|
|
.IX Header "DESCRIPTION"
|
|
The \fBx509\fR command is a multi purpose certificate utility. It can be
|
|
used to display certificate information, convert certificates to
|
|
various forms, sign certificate requests like a \*(L"mini \s-1CA\s0\*(R" or edit
|
|
certificate trust settings.
|
|
.PP
|
|
Since there are a large number of options they will split up into
|
|
various sections.
|
|
.SH "OPTIONS"
|
|
.IX Header "OPTIONS"
|
|
.Sh "\s-1INPUT\s0, \s-1OUTPUT\s0 \s-1AND\s0 \s-1GENERAL\s0 \s-1PURPOSE\s0 \s-1OPTIONS\s0"
|
|
.IX Subsection "INPUT, OUTPUT AND GENERAL PURPOSE OPTIONS"
|
|
.Ip "\fB\-inform DER|PEM|NET\fR" 4
|
|
.IX Item "-inform DER|PEM|NET"
|
|
This specifies the input format normally the command will expect an X509
|
|
certificate but this can change if other options such as \fB\-req\fR are
|
|
present. The \s-1DER\s0 format is the \s-1DER\s0 encoding of the certificate and \s-1PEM\s0
|
|
is the base64 encoding of the \s-1DER\s0 encoding with header and footer lines
|
|
added. The \s-1NET\s0 option is an obscure Netscape server format that is now
|
|
obsolete.
|
|
.Ip "\fB\-outform DER|PEM|NET\fR" 4
|
|
.IX Item "-outform DER|PEM|NET"
|
|
This specifies the output format, the options have the same meaning as the
|
|
\&\fB\-inform\fR option.
|
|
.Ip "\fB\-in filename\fR" 4
|
|
.IX Item "-in filename"
|
|
This specifies the input filename to read a certificate from or standard input
|
|
if this option is not specified.
|
|
.Ip "\fB\-out filename\fR" 4
|
|
.IX Item "-out filename"
|
|
This specifies the output filename to write to or standard output by
|
|
default.
|
|
.Ip "\fB\-md2|\-md5|\-sha1|\-mdc2\fR" 4
|
|
.IX Item "-md2|-md5|-sha1|-mdc2"
|
|
the digest to use. This affects any signing or display option that uses a message
|
|
digest, such as the \fB\-fingerprint\fR, \fB\-signkey\fR and \fB\-CA\fR options. If not
|
|
specified then \s-1MD5\s0 is used. If the key being used to sign with is a \s-1DSA\s0 key then
|
|
this option has no effect: \s-1SHA1\s0 is always used with \s-1DSA\s0 keys.
|
|
.Ip "\fB\-engine id\fR" 4
|
|
.IX Item "-engine id"
|
|
specifying an engine (by it's unique \fBid\fR string) will cause \fBreq\fR
|
|
to attempt to obtain a functional reference to the specified engine,
|
|
thus initialising it if needed. The engine will then be set as the default
|
|
for all available algorithms.
|
|
.Sh "\s-1DISPLAY\s0 \s-1OPTIONS\s0"
|
|
.IX Subsection "DISPLAY OPTIONS"
|
|
Note: the \fB\-alias\fR and \fB\-purpose\fR options are also display options
|
|
but are described in the \fB\s-1TRUST\s0 \s-1SETTINGS\s0\fR section.
|
|
.Ip "\fB\-text\fR" 4
|
|
.IX Item "-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.
|
|
.Ip "\fB\-certopt option\fR" 4
|
|
.IX Item "-certopt option"
|
|
customise the output format used with \fB\-text\fR. The \fBoption\fR argument can be
|
|
a single option or multiple options separated by commas. The \fB\-certopt\fR switch
|
|
may be also be used more than once to set multiple options. See the \fB\s-1TEXT\s0 \s-1OPTIONS\s0\fR
|
|
section for more information.
|
|
.Ip "\fB\-noout\fR" 4
|
|
.IX Item "-noout"
|
|
this option prevents output of the encoded version of the request.
|
|
.Ip "\fB\-modulus\fR" 4
|
|
.IX Item "-modulus"
|
|
this option prints out the value of the modulus of the public key
|
|
contained in the certificate.
|
|
.Ip "\fB\-serial\fR" 4
|
|
.IX Item "-serial"
|
|
outputs the certificate serial number.
|
|
.Ip "\fB\-hash\fR" 4
|
|
.IX Item "-hash"
|
|
outputs the \*(L"hash\*(R" of the certificate subject name. This is used in OpenSSL to
|
|
form an index to allow certificates in a directory to be looked up by subject
|
|
name.
|
|
.Ip "\fB\-subject\fR" 4
|
|
.IX Item "-subject"
|
|
outputs the subject name.
|
|
.Ip "\fB\-issuer\fR" 4
|
|
.IX Item "-issuer"
|
|
outputs the issuer name.
|
|
.Ip "\fB\-nameopt option\fR" 4
|
|
.IX Item "-nameopt option"
|
|
option which determines how the subject or issuer names are displayed. The
|
|
\&\fBoption\fR argument can be a single option or multiple options separated by
|
|
commas. Alternatively the \fB\-nameopt\fR switch may be used more than once to
|
|
set multiple options. See the \fB\s-1NAME\s0 \s-1OPTIONS\s0\fR section for more information.
|
|
.Ip "\fB\-email\fR" 4
|
|
.IX Item "-email"
|
|
outputs the email address(es) if any.
|
|
.Ip "\fB\-startdate\fR" 4
|
|
.IX Item "-startdate"
|
|
prints out the start date of the certificate, that is the notBefore date.
|
|
.Ip "\fB\-enddate\fR" 4
|
|
.IX Item "-enddate"
|
|
prints out the expiry date of the certificate, that is the notAfter date.
|
|
.Ip "\fB\-dates\fR" 4
|
|
.IX Item "-dates"
|
|
prints out the start and expiry dates of a certificate.
|
|
.Ip "\fB\-fingerprint\fR" 4
|
|
.IX Item "-fingerprint"
|
|
prints out the digest of the \s-1DER\s0 encoded version of the whole certificate
|
|
(see digest options).
|
|
.Ip "\fB\-C\fR" 4
|
|
.IX Item "-C"
|
|
this outputs the certificate in the form of a C source file.
|
|
.Sh "\s-1TRUST\s0 \s-1SETTINGS\s0"
|
|
.IX Subsection "TRUST SETTINGS"
|
|
Please note these options are currently experimental and may well change.
|
|
.PP
|
|
A \fBtrusted certificate\fR 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 \*(L"alias\*(R".
|
|
.PP
|
|
Normally when a certificate is being verified at least one certificate
|
|
must be \*(L"trusted\*(R". By default a trusted certificate must be stored
|
|
locally and must be a root \s-1CA:\s0 any certificate chain ending in this \s-1CA\s0
|
|
is then usable for any purpose.
|
|
.PP
|
|
Trust settings currently are only used with a root \s-1CA\s0. They allow a finer
|
|
control over the purposes the root \s-1CA\s0 can be used for. For example a \s-1CA\s0
|
|
may be trusted for \s-1SSL\s0 client but not \s-1SSL\s0 server use.
|
|
.PP
|
|
See the description of the \fBverify\fR utility for more information on the
|
|
meaning of trust settings.
|
|
.PP
|
|
Future versions of OpenSSL will recognize trust settings on any
|
|
certificate: not just root CAs.
|
|
.Ip "\fB\-trustout\fR" 4
|
|
.IX Item "-trustout"
|
|
this causes \fBx509\fR to output a \fBtrusted\fR certificate. An ordinary
|
|
or trusted certificate can be input but by default an ordinary
|
|
certificate is output and any trust settings are discarded. With the
|
|
\&\fB\-trustout\fR option a trusted certificate is output. A trusted
|
|
certificate is automatically output if any trust settings are modified.
|
|
.Ip "\fB\-setalias arg\fR" 4
|
|
.IX Item "-setalias arg"
|
|
sets the alias of the certificate. This will allow the certificate
|
|
to be referred to using a nickname for example \*(L"Steve's Certificate\*(R".
|
|
.Ip "\fB\-alias\fR" 4
|
|
.IX Item "-alias"
|
|
outputs the certificate alias, if any.
|
|
.Ip "\fB\-clrtrust\fR" 4
|
|
.IX Item "-clrtrust"
|
|
clears all the permitted or trusted uses of the certificate.
|
|
.Ip "\fB\-clrreject\fR" 4
|
|
.IX Item "-clrreject"
|
|
clears all the prohibited or rejected uses of the certificate.
|
|
.Ip "\fB\-addtrust arg\fR" 4
|
|
.IX Item "-addtrust arg"
|
|
adds a trusted certificate use. Any object name can be used here
|
|
but currently only \fBclientAuth\fR (\s-1SSL\s0 client use), \fBserverAuth\fR
|
|
(\s-1SSL\s0 server use) and \fBemailProtection\fR (S/MIME email) are used.
|
|
Other OpenSSL applications may define additional uses.
|
|
.Ip "\fB\-addreject arg\fR" 4
|
|
.IX Item "-addreject arg"
|
|
adds a prohibited use. It accepts the same values as the \fB\-addtrust\fR
|
|
option.
|
|
.Ip "\fB\-purpose\fR" 4
|
|
.IX Item "-purpose"
|
|
this option performs tests on the certificate extensions and outputs
|
|
the results. For a more complete description see the \fB\s-1CERTIFICATE\s0
|
|
\&\s-1EXTENSIONS\s0\fR section.
|
|
.Sh "\s-1SIGNING\s0 \s-1OPTIONS\s0"
|
|
.IX Subsection "SIGNING OPTIONS"
|
|
The \fBx509\fR utility can be used to sign certificates and requests: it
|
|
can thus behave like a \*(L"mini \s-1CA\s0\*(R".
|
|
.Ip "\fB\-signkey filename\fR" 4
|
|
.IX Item "-signkey filename"
|
|
this option causes the input file to be self signed using the supplied
|
|
private key.
|
|
.Sp
|
|
If the input file is a certificate it sets the issuer name to the
|
|
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 a value determined
|
|
by the \fB\-days\fR option. Any certificate extensions are retained unless
|
|
the \fB\-clrext\fR option is supplied.
|
|
.Sp
|
|
If the input is a certificate request then a self signed certificate
|
|
is created using the supplied private key using the subject name in
|
|
the request.
|
|
.Ip "\fB\-clrext\fR" 4
|
|
.IX Item "-clrext"
|
|
delete any extensions from a certificate. This option is used when a
|
|
certificate is being created from another certificate (for example with
|
|
the \fB\-signkey\fR or the \fB\-CA\fR options). Normally all extensions are
|
|
retained.
|
|
.Ip "\fB\-keyform PEM|DER\fR" 4
|
|
.IX Item "-keyform PEM|DER"
|
|
specifies the format (\s-1DER\s0 or \s-1PEM\s0) of the private key file used in the
|
|
\&\fB\-signkey\fR option.
|
|
.Ip "\fB\-days arg\fR" 4
|
|
.IX Item "-days arg"
|
|
specifies the number of days to make a certificate valid for. The default
|
|
is 30 days.
|
|
.Ip "\fB\-x509toreq\fR" 4
|
|
.IX Item "-x509toreq"
|
|
converts a certificate into a certificate request. The \fB\-signkey\fR option
|
|
is used to pass the required private key.
|
|
.Ip "\fB\-req\fR" 4
|
|
.IX Item "-req"
|
|
by default a certificate is expected on input. With this option a
|
|
certificate request is expected instead.
|
|
.Ip "\fB\-set_serial n\fR" 4
|
|
.IX Item "-set_serial n"
|
|
specifies the serial number to use. This option can be used with either
|
|
the \fB\-signkey\fR or \fB\-CA\fR options. If used in conjunction with the \fB\-CA\fR
|
|
option the serial number file (as specified by the \fB\-CAserial\fR or
|
|
\&\fB\-CAcreateserial\fR options) is not used.
|
|
.Sp
|
|
The serial number can be decimal or hex (if preceded by \fB0x\fR). Negative
|
|
serial numbers can also be specified but their use is not recommended.
|
|
.Ip "\fB\-CA filename\fR" 4
|
|
.IX Item "-CA filename"
|
|
specifies the \s-1CA\s0 certificate to be used for signing. When this option is
|
|
present \fBx509\fR behaves like a \*(L"mini \s-1CA\s0\*(R". The input file is signed by this
|
|
\&\s-1CA\s0 using this option: that is its issuer name is set to the subject name
|
|
of the \s-1CA\s0 and it is digitally signed using the CAs private key.
|
|
.Sp
|
|
This option is normally combined with the \fB\-req\fR option. Without the
|
|
\&\fB\-req\fR option the input is a certificate which must be self signed.
|
|
.Ip "\fB\-CAkey filename\fR" 4
|
|
.IX Item "-CAkey filename"
|
|
sets the \s-1CA\s0 private key to sign a certificate with. If this option is
|
|
not specified then it is assumed that the \s-1CA\s0 private key is present in
|
|
the \s-1CA\s0 certificate file.
|
|
.Ip "\fB\-CAserial filename\fR" 4
|
|
.IX Item "-CAserial filename"
|
|
sets the \s-1CA\s0 serial number file to use.
|
|
.Sp
|
|
When the \fB\-CA\fR 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.
|
|
.Sp
|
|
The default filename consists of the \s-1CA\s0 certificate file base name with
|
|
\&\*(L".srl\*(R" appended. For example if the \s-1CA\s0 certificate file is called
|
|
\&\*(L"mycacert.pem\*(R" it expects to find a serial number file called \*(L"mycacert.srl\*(R".
|
|
.Ip "\fB\-CAcreateserial\fR" 4
|
|
.IX Item "-CAcreateserial"
|
|
with this option the \s-1CA\s0 serial number file is created if it does not exist:
|
|
it will contain the serial number \*(L"02\*(R" and the certificate being signed will
|
|
have the 1 as its serial number. Normally if the \fB\-CA\fR option is specified
|
|
and the serial number file does not exist it is an error.
|
|
.Ip "\fB\-extfile filename\fR" 4
|
|
.IX Item "-extfile filename"
|
|
file containing certificate extensions to use. If not specified then
|
|
no extensions are added to the certificate.
|
|
.Ip "\fB\-extensions section\fR" 4
|
|
.IX Item "-extensions section"
|
|
the section to add certificate extensions from. If this option is not
|
|
specified then the extensions should either be contained in the unnamed
|
|
(default) section or the default section should contain a variable called
|
|
\&\*(L"extensions\*(R" which contains the section to use.
|
|
.Sh "\s-1NAME\s0 \s-1OPTIONS\s0"
|
|
.IX Subsection "NAME OPTIONS"
|
|
The \fBnameopt\fR command line switch determines how the subject and issuer
|
|
names are displayed. If no \fBnameopt\fR switch is present the default \*(L"oneline\*(R"
|
|
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 \fB-\fR to turn the option off. Only the first four will normally be used.
|
|
.Ip "\fBcompat\fR" 4
|
|
.IX Item "compat"
|
|
use the old format. This is equivalent to specifying no name options at all.
|
|
.Ip "\fB\s-1RFC2253\s0\fR" 4
|
|
.IX Item "RFC2253"
|
|
displays names compatible with \s-1RFC2253\s0 equivalent to \fBesc_2253\fR, \fBesc_ctrl\fR,
|
|
\&\fBesc_msb\fR, \fButf8\fR, \fBdump_nostr\fR, \fBdump_unknown\fR, \fBdump_der\fR,
|
|
\&\fBsep_comma_plus\fR, \fBdn_rev\fR and \fBsname\fR.
|
|
.Ip "\fBoneline\fR" 4
|
|
.IX Item "oneline"
|
|
a oneline format which is more readable than \s-1RFC2253\s0. It is equivalent to
|
|
specifying the \fBesc_2253\fR, \fBesc_ctrl\fR, \fBesc_msb\fR, \fButf8\fR, \fBdump_nostr\fR,
|
|
\&\fBdump_der\fR, \fBuse_quote\fR, \fBsep_comma_plus_spc\fR, \fBspc_eq\fR and \fBsname\fR
|
|
options.
|
|
.Ip "\fBmultiline\fR" 4
|
|
.IX Item "multiline"
|
|
a multiline format. It is equivalent \fBesc_ctrl\fR, \fBesc_msb\fR, \fBsep_multiline\fR,
|
|
\&\fBspc_eq\fR, \fBlname\fR and \fBalign\fR.
|
|
.Ip "\fBesc_2253\fR" 4
|
|
.IX Item "esc_2253"
|
|
escape the \*(L"special\*(R" characters required by \s-1RFC2253\s0 in a field That is
|
|
\&\fB,+"<>;\fR. Additionally \fB#\fR is escaped at the beginning of a string
|
|
and a space character at the beginning or end of a string.
|
|
.Ip "\fBesc_ctrl\fR" 4
|
|
.IX Item "esc_ctrl"
|
|
escape control characters. That is those with \s-1ASCII\s0 values less than
|
|
0x20 (space) and the delete (0x7f) character. They are escaped using the
|
|
\&\s-1RFC2253\s0 \eXX notation (where \s-1XX\s0 are two hex digits representing the
|
|
character value).
|
|
.Ip "\fBesc_msb\fR" 4
|
|
.IX Item "esc_msb"
|
|
escape characters with the \s-1MSB\s0 set, that is with \s-1ASCII\s0 values larger than
|
|
127.
|
|
.Ip "\fBuse_quote\fR" 4
|
|
.IX Item "use_quote"
|
|
escapes some characters by surrounding the whole string with \fB"\fR characters,
|
|
without the option all escaping is done with the \fB\e\fR character.
|
|
.Ip "\fButf8\fR" 4
|
|
.IX Item "utf8"
|
|
convert all strings to \s-1UTF8\s0 format first. This is required by \s-1RFC2253\s0. If
|
|
you are lucky enough to have a \s-1UTF8\s0 compatible terminal then the use
|
|
of this option (and \fBnot\fR setting \fBesc_msb\fR) 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 \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.
|
|
.Ip "\fBno_type\fR" 4
|
|
.IX Item "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.
|
|
.Ip "\fBshow_type\fR" 4
|
|
.IX Item "show_type"
|
|
show the type of the \s-1ASN1\s0 character string. The type precedes the
|
|
field contents. For example \*(L"\s-1BMPSTRING:\s0 Hello World\*(R".
|
|
.Ip "\fBdump_der\fR" 4
|
|
.IX Item "dump_der"
|
|
when this option is set any fields that need to be hexdumped will
|
|
be dumped using the \s-1DER\s0 encoding of the field. Otherwise just the
|
|
content octets will be displayed. Both options use the \s-1RFC2253\s0
|
|
\&\fB#XXXX...\fR format.
|
|
.Ip "\fBdump_nostr\fR" 4
|
|
.IX Item "dump_nostr"
|
|
dump non character string types (for example \s-1OCTET\s0 \s-1STRING\s0) if this
|
|
option is not set then non character string types will be displayed
|
|
as though each content octet represents a single character.
|
|
.Ip "\fBdump_all\fR" 4
|
|
.IX Item "dump_all"
|
|
dump all fields. This option when used with \fBdump_der\fR allows the
|
|
\&\s-1DER\s0 encoding of the structure to be unambiguously determined.
|
|
.Ip "\fBdump_unknown\fR" 4
|
|
.IX Item "dump_unknown"
|
|
dump any field whose \s-1OID\s0 is not recognised by OpenSSL.
|
|
.Ip "\fBsep_comma_plus\fR, \fBsep_comma_plus_space\fR, \fBsep_semi_plus_space\fR, \fBsep_multiline\fR" 4
|
|
.IX Item "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
|
|
\&\*(L"space\*(R" additionally place a space after the separator to make it
|
|
more readable. The \fBsep_multiline\fR uses a linefeed character for
|
|
the \s-1RDN\s0 separator and a spaced \fB+\fR for the \s-1AVA\s0 separator. It also
|
|
indents the fields by four characters.
|
|
.Ip "\fBdn_rev\fR" 4
|
|
.IX Item "dn_rev"
|
|
reverse the fields of the \s-1DN\s0. This is required by \s-1RFC2253\s0. As a side
|
|
effect this also reverses the order of multiple AVAs but this is
|
|
permissible.
|
|
.Ip "\fBnofname\fR, \fBsname\fR, \fBlname\fR, \fBoid\fR" 4
|
|
.IX Item "nofname, sname, lname, oid"
|
|
these options alter how the field name is displayed. \fBnofname\fR does
|
|
not display the field at all. \fBsname\fR uses the \*(L"short name\*(R" form
|
|
(\s-1CN\s0 for commonName for example). \fBlname\fR uses the long form.
|
|
\&\fBoid\fR represents the \s-1OID\s0 in numerical form and is useful for
|
|
diagnostic purpose.
|
|
.Ip "\fBalign\fR" 4
|
|
.IX Item "align"
|
|
align field values for a more readable output. Only usable with
|
|
\&\fBsep_multiline\fR.
|
|
.Ip "\fBspc_eq\fR" 4
|
|
.IX Item "spc_eq"
|
|
places spaces round the \fB=\fR character which follows the field
|
|
name.
|
|
.Sh "\s-1TEXT\s0 \s-1OPTIONS\s0"
|
|
.IX Subsection "TEXT OPTIONS"
|
|
As well as customising the name output format, it is also possible to
|
|
customise the actual fields printed using the \fBcertopt\fR options when
|
|
the \fBtext\fR option is present. The default behaviour is to print all fields.
|
|
.Ip "\fBcompatible\fR" 4
|
|
.IX Item "compatible"
|
|
use the old format. This is equivalent to specifying no output options at all.
|
|
.Ip "\fBno_header\fR" 4
|
|
.IX Item "no_header"
|
|
don't print header information: that is the lines saying \*(L"Certificate\*(R" and \*(L"Data\*(R".
|
|
.Ip "\fBno_version\fR" 4
|
|
.IX Item "no_version"
|
|
don't print out the version number.
|
|
.Ip "\fBno_serial\fR" 4
|
|
.IX Item "no_serial"
|
|
don't print out the serial number.
|
|
.Ip "\fBno_signame\fR" 4
|
|
.IX Item "no_signame"
|
|
don't print out the signature algorithm used.
|
|
.Ip "\fBno_validity\fR" 4
|
|
.IX Item "no_validity"
|
|
don't print the validity, that is the \fBnotBefore\fR and \fBnotAfter\fR fields.
|
|
.Ip "\fBno_subject\fR" 4
|
|
.IX Item "no_subject"
|
|
don't print out the subject name.
|
|
.Ip "\fBno_issuer\fR" 4
|
|
.IX Item "no_issuer"
|
|
don't print out the issuer name.
|
|
.Ip "\fBno_pubkey\fR" 4
|
|
.IX Item "no_pubkey"
|
|
don't print out the public key.
|
|
.Ip "\fBno_sigdump\fR" 4
|
|
.IX Item "no_sigdump"
|
|
don't give a hexadecimal dump of the certificate signature.
|
|
.Ip "\fBno_aux\fR" 4
|
|
.IX Item "no_aux"
|
|
don't print out certificate trust information.
|
|
.Ip "\fBno_extensions\fR" 4
|
|
.IX Item "no_extensions"
|
|
don't print out any X509V3 extensions.
|
|
.Ip "\fBext_default\fR" 4
|
|
.IX Item "ext_default"
|
|
retain default extension behaviour: attempt to print out unsupported certificate extensions.
|
|
.Ip "\fBext_error\fR" 4
|
|
.IX Item "ext_error"
|
|
print an error message for unsupported certificate extensions.
|
|
.Ip "\fBext_parse\fR" 4
|
|
.IX Item "ext_parse"
|
|
\&\s-1ASN1\s0 parse unsupported extensions.
|
|
.Ip "\fBext_dump\fR" 4
|
|
.IX Item "ext_dump"
|
|
hex dump unsupported extensions.
|
|
.Ip "\fBca_default\fR" 4
|
|
.IX Item "ca_default"
|
|
the value used by the \fBca\fR utility, equivalent to \fBno_issuer\fR, \fBno_pubkey\fR, \fBno_header\fR,
|
|
\&\fBno_version\fR, \fBno_sigdump\fR and \fBno_signame\fR.
|
|
.SH "EXAMPLES"
|
|
.IX Header "EXAMPLES"
|
|
Note: in these examples the '\e' means the example should be all on one
|
|
line.
|
|
.PP
|
|
Display the contents of a certificate:
|
|
.PP
|
|
.Vb 1
|
|
\& openssl x509 -in cert.pem -noout -text
|
|
.Ve
|
|
Display the certificate serial number:
|
|
.PP
|
|
.Vb 1
|
|
\& openssl x509 -in cert.pem -noout -serial
|
|
.Ve
|
|
Display the certificate subject name:
|
|
.PP
|
|
.Vb 1
|
|
\& openssl x509 -in cert.pem -noout -subject
|
|
.Ve
|
|
Display the certificate subject name in \s-1RFC2253\s0 form:
|
|
.PP
|
|
.Vb 1
|
|
\& openssl x509 -in cert.pem -noout -subject -nameopt RFC2253
|
|
.Ve
|
|
Display the certificate subject name in oneline form on a terminal
|
|
supporting \s-1UTF8:\s0
|
|
.PP
|
|
.Vb 1
|
|
\& openssl x509 -in cert.pem -noout -subject -nameopt oneline,-escmsb
|
|
.Ve
|
|
Display the certificate \s-1MD5\s0 fingerprint:
|
|
.PP
|
|
.Vb 1
|
|
\& openssl x509 -in cert.pem -noout -fingerprint
|
|
.Ve
|
|
Display the certificate \s-1SHA1\s0 fingerprint:
|
|
.PP
|
|
.Vb 1
|
|
\& openssl x509 -sha1 -in cert.pem -noout -fingerprint
|
|
.Ve
|
|
Convert a certificate from \s-1PEM\s0 to \s-1DER\s0 format:
|
|
.PP
|
|
.Vb 1
|
|
\& openssl x509 -in cert.pem -inform PEM -out cert.der -outform DER
|
|
.Ve
|
|
Convert a certificate to a certificate request:
|
|
.PP
|
|
.Vb 1
|
|
\& openssl x509 -x509toreq -in cert.pem -out req.pem -signkey key.pem
|
|
.Ve
|
|
Convert a certificate request into a self signed certificate using
|
|
extensions for a \s-1CA:\s0
|
|
.PP
|
|
.Vb 2
|
|
\& openssl x509 -req -in careq.pem -extfile openssl.cnf -extensions v3_ca \e
|
|
\& -signkey key.pem -out cacert.pem
|
|
.Ve
|
|
Sign a certificate request using the \s-1CA\s0 certificate above and add user
|
|
certificate extensions:
|
|
.PP
|
|
.Vb 2
|
|
\& openssl x509 -req -in req.pem -extfile openssl.cnf -extensions v3_usr \e
|
|
\& -CA cacert.pem -CAkey key.pem -CAcreateserial
|
|
.Ve
|
|
Set a certificate to be trusted for \s-1SSL\s0 client use and change set its alias to
|
|
\&\*(L"Steve's Class 1 \s-1CA\s0\*(R"
|
|
.PP
|
|
.Vb 2
|
|
\& openssl x509 -in cert.pem -addtrust clientAuth \e
|
|
\& -setalias "Steve's Class 1 CA" -out trust.pem
|
|
.Ve
|
|
.SH "NOTES"
|
|
.IX Header "NOTES"
|
|
The \s-1PEM\s0 format uses the header and footer lines:
|
|
.PP
|
|
.Vb 2
|
|
\& -----BEGIN CERTIFICATE-----
|
|
\& -----END CERTIFICATE-----
|
|
.Ve
|
|
it will also handle files containing:
|
|
.PP
|
|
.Vb 2
|
|
\& -----BEGIN X509 CERTIFICATE-----
|
|
\& -----END X509 CERTIFICATE-----
|
|
.Ve
|
|
Trusted certificates have the lines
|
|
.PP
|
|
.Vb 2
|
|
\& -----BEGIN TRUSTED CERTIFICATE-----
|
|
\& -----END TRUSTED CERTIFICATE-----
|
|
.Ve
|
|
The conversion to \s-1UTF8\s0 format used with the name options assumes that
|
|
T61Strings use the \s-1ISO8859\-1\s0 character set. This is wrong but Netscape
|
|
and \s-1MSIE\s0 do this as do many certificates. So although this is incorrect
|
|
it is more likely to display the majority of certificates correctly.
|
|
.PP
|
|
The \fB\-fingerprint\fR option takes the digest of the \s-1DER\s0 encoded certificate.
|
|
This is commonly called a \*(L"fingerprint\*(R". 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 \s-1MD5\s0 whereas \s-1MSIE\s0 uses \s-1SHA1\s0.
|
|
.PP
|
|
The \fB\-email\fR 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 "CERTIFICATE EXTENSIONS"
|
|
.IX Header "CERTIFICATE EXTENSIONS"
|
|
The \fB\-purpose\fR 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 basicConstraints extension \s-1CA\s0 flag is used to determine whether the
|
|
certificate can be used as a \s-1CA\s0. If the \s-1CA\s0 flag is true then it is a \s-1CA\s0,
|
|
if the \s-1CA\s0 flag is false then it is not a \s-1CA\s0. \fBAll\fR CAs should have the
|
|
\&\s-1CA\s0 flag set to true.
|
|
.PP
|
|
If the basicConstraints extension is absent then the certificate is
|
|
considered to be a \*(L"possible \s-1CA\s0\*(R" 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 \s-1CA:\s0 however
|
|
it is allowed to be a \s-1CA\s0 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 \s-1CA\s0 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 keyUsage extension is present then additional restraints are
|
|
made on the uses of the certificate. A \s-1CA\s0 certificate \fBmust\fR have the
|
|
keyCertSign bit set if the 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
|
|
basicConstraints and keyUsage and V1 certificates above apply to \fBall\fR
|
|
\&\s-1CA\s0 certificates.
|
|
.Ip "\fB\s-1SSL\s0 Client\fR" 4
|
|
.IX Item "SSL Client"
|
|
The extended key usage extension must be absent or include the \*(L"web client
|
|
authentication\*(R" \s-1OID\s0. keyUsage must be absent or it must have the
|
|
digitalSignature bit set. Netscape certificate type must be absent or it must
|
|
have the \s-1SSL\s0 client bit set.
|
|
.Ip "\fB\s-1SSL\s0 Client \s-1CA\s0\fR" 4
|
|
.IX Item "SSL Client CA"
|
|
The extended key usage extension must be absent or include the \*(L"web client
|
|
authentication\*(R" \s-1OID\s0. Netscape certificate type must be absent or it must have
|
|
the \s-1SSL\s0 \s-1CA\s0 bit set: this is used as a work around if the basicConstraints
|
|
extension is absent.
|
|
.Ip "\fB\s-1SSL\s0 Server\fR" 4
|
|
.IX Item "SSL Server"
|
|
The extended key usage extension must be absent or include the \*(L"web server
|
|
authentication\*(R" and/or one of the \s-1SGC\s0 OIDs. keyUsage must be absent or it
|
|
must have the digitalSignature, the keyEncipherment set or both bits set.
|
|
Netscape certificate type must be absent or have the \s-1SSL\s0 server bit set.
|
|
.Ip "\fB\s-1SSL\s0 Server \s-1CA\s0\fR" 4
|
|
.IX Item "SSL Server CA"
|
|
The extended key usage extension must be absent or include the \*(L"web server
|
|
authentication\*(R" and/or one of the \s-1SGC\s0 OIDs. Netscape certificate type must
|
|
be absent or the \s-1SSL\s0 \s-1CA\s0 bit must be set: this is used as a work around if the
|
|
basicConstraints extension is absent.
|
|
.Ip "\fBNetscape \s-1SSL\s0 Server\fR" 4
|
|
.IX Item "Netscape SSL Server"
|
|
For Netscape \s-1SSL\s0 clients to connect to an \s-1SSL\s0 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 normal \s-1SSL\s0 server.
|
|
.Ip "\fBCommon S/MIME Client Tests\fR" 4
|
|
.IX Item "Common S/MIME Client Tests"
|
|
The extended key usage extension must be absent or include the \*(L"email
|
|
protection\*(R" \s-1OID\s0. 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 \s-1SSL\s0 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.
|
|
.Ip "\fBS/MIME Signing\fR" 4
|
|
.IX Item "S/MIME Signing"
|
|
In addition to the common S/MIME client tests the digitalSignature bit must
|
|
be set if the keyUsage extension is present.
|
|
.Ip "\fBS/MIME Encryption\fR" 4
|
|
.IX Item "S/MIME Encryption"
|
|
In addition to the common S/MIME tests the keyEncipherment bit must be set
|
|
if the keyUsage extension is present.
|
|
.Ip "\fBS/MIME \s-1CA\s0\fR" 4
|
|
.IX Item "S/MIME CA"
|
|
The extended key usage extension must be absent or include the \*(L"email
|
|
protection\*(R" \s-1OID\s0. Netscape certificate type must be absent or must have the
|
|
S/MIME \s-1CA\s0 bit set: this is used as a work around if the basicConstraints
|
|
extension is absent.
|
|
.Ip "\fB\s-1CRL\s0 Signing\fR" 4
|
|
.IX Item "CRL Signing"
|
|
The keyUsage extension must be absent or it must have the \s-1CRL\s0 signing bit
|
|
set.
|
|
.Ip "\fB\s-1CRL\s0 Signing \s-1CA\s0\fR" 4
|
|
.IX Item "CRL Signing CA"
|
|
The normal \s-1CA\s0 tests apply. Except in this case the basicConstraints extension
|
|
must be present.
|
|
.SH "BUGS"
|
|
.IX Header "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 \fB\s-1TRUST\s0 \s-1SETTINGS\s0\fR
|
|
is currently being developed. It thus describes the intended behaviour rather
|
|
than the current behaviour. It is hoped that it will represent reality in
|
|
OpenSSL 0.9.5 and later.
|
|
.SH "SEE ALSO"
|
|
.IX Header "SEE ALSO"
|
|
openssl_req(1), openssl_ca(1), openssl_genrsa(1),
|
|
openssl_gendsa(1), openssl_verify(1)
|