833 lines
25 KiB
Plaintext
833 lines
25 KiB
Plaintext
|
|
=pod
|
|
|
|
=head1 NAME
|
|
|
|
x509 - Certificate display and signing utility
|
|
|
|
=head1 SYNOPSIS
|
|
|
|
B<openssl> B<x509>
|
|
[B<-inform DER|PEM|NET>]
|
|
[B<-outform DER|PEM|NET>]
|
|
[B<-keyform DER|PEM>]
|
|
[B<-CAform DER|PEM>]
|
|
[B<-CAkeyform DER|PEM>]
|
|
[B<-in filename>]
|
|
[B<-out filename>]
|
|
[B<-serial>]
|
|
[B<-hash>]
|
|
[B<-subject_hash>]
|
|
[B<-issuer_hash>]
|
|
[B<-subject>]
|
|
[B<-issuer>]
|
|
[B<-nameopt option>]
|
|
[B<-email>]
|
|
[B<-startdate>]
|
|
[B<-enddate>]
|
|
[B<-purpose>]
|
|
[B<-dates>]
|
|
[B<-modulus>]
|
|
[B<-fingerprint>]
|
|
[B<-alias>]
|
|
[B<-noout>]
|
|
[B<-trustout>]
|
|
[B<-clrtrust>]
|
|
[B<-clrreject>]
|
|
[B<-addtrust arg>]
|
|
[B<-addreject arg>]
|
|
[B<-setalias arg>]
|
|
[B<-days arg>]
|
|
[B<-set_serial n>]
|
|
[B<-signkey filename>]
|
|
[B<-x509toreq>]
|
|
[B<-req>]
|
|
[B<-CA filename>]
|
|
[B<-CAkey filename>]
|
|
[B<-CAcreateserial>]
|
|
[B<-CAserial filename>]
|
|
[B<-text>]
|
|
[B<-C>]
|
|
[B<-md2|-md5|-sha1|-mdc2>]
|
|
[B<-clrext>]
|
|
[B<-extfile filename>]
|
|
[B<-extensions section>]
|
|
[B<-engine id>]
|
|
|
|
=head1 DESCRIPTION
|
|
|
|
The B<x509> 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 "mini CA" or edit
|
|
certificate trust settings.
|
|
|
|
Since there are a large number of options they will split up into
|
|
various sections.
|
|
|
|
=head1 OPTIONS
|
|
|
|
=head2 INPUT, OUTPUT AND GENERAL PURPOSE OPTIONS
|
|
|
|
=over 4
|
|
|
|
=item B<-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 B<-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 now
|
|
obsolete.
|
|
|
|
=item B<-outform DER|PEM|NET>
|
|
|
|
This specifies the output format, the options have the same meaning as the
|
|
B<-inform> option.
|
|
|
|
=item B<-in filename>
|
|
|
|
This specifies the input filename to read a certificate from or standard input
|
|
if this option is not specified.
|
|
|
|
=item B<-out filename>
|
|
|
|
This specifies the output filename to write to or standard output by
|
|
default.
|
|
|
|
=item B<-md2|-md5|-sha1|-mdc2>
|
|
|
|
the digest to use. This affects any signing or display option that uses a message
|
|
digest, such as the B<-fingerprint>, B<-signkey> and B<-CA> options. If not
|
|
specified then SHA1 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.
|
|
|
|
=item B<-engine id>
|
|
|
|
specifying an engine (by it's unique B<id> string) will cause B<req>
|
|
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.
|
|
|
|
=back
|
|
|
|
=head2 DISPLAY OPTIONS
|
|
|
|
Note: the B<-alias> and B<-purpose> options are also display options
|
|
but are described in the B<TRUST SETTINGS> section.
|
|
|
|
=over 4
|
|
|
|
=item B<-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.
|
|
|
|
=item B<-certopt option>
|
|
|
|
customise the output format used with B<-text>. The B<option> argument can be
|
|
a single option or multiple options separated by commas. The B<-certopt> switch
|
|
may be also be used more than once to set multiple options. See the B<TEXT OPTIONS>
|
|
section for more information.
|
|
|
|
=item B<-noout>
|
|
|
|
this option prevents output of the encoded version of the request.
|
|
|
|
=item B<-modulus>
|
|
|
|
this option prints out the value of the modulus of the public key
|
|
contained in the certificate.
|
|
|
|
=item B<-serial>
|
|
|
|
outputs the certificate serial number.
|
|
|
|
=item B<-subject_hash>
|
|
|
|
outputs the "hash" 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.
|
|
|
|
=item B<-issuer_hash>
|
|
|
|
outputs the "hash" of the certificate issuer name.
|
|
|
|
=item B<-hash>
|
|
|
|
synonym for "-hash" for backward compatibility reasons.
|
|
|
|
=item B<-subject>
|
|
|
|
outputs the subject name.
|
|
|
|
=item B<-issuer>
|
|
|
|
outputs the issuer name.
|
|
|
|
=item B<-nameopt option>
|
|
|
|
option which determines how the subject or issuer names are displayed. The
|
|
B<option> argument can be a single option or multiple options separated by
|
|
commas. Alternatively the B<-nameopt> switch may be used more than once to
|
|
set multiple options. See the B<NAME OPTIONS> section for more information.
|
|
|
|
=item B<-email>
|
|
|
|
outputs the email address(es) if any.
|
|
|
|
=item B<-startdate>
|
|
|
|
prints out the start date of the certificate, that is the notBefore date.
|
|
|
|
=item B<-enddate>
|
|
|
|
prints out the expiry date of the certificate, that is the notAfter date.
|
|
|
|
=item B<-dates>
|
|
|
|
prints out the start and expiry dates of a certificate.
|
|
|
|
=item B<-fingerprint>
|
|
|
|
prints out the digest of the DER encoded version of the whole certificate
|
|
(see digest options).
|
|
|
|
=item B<-C>
|
|
|
|
this outputs the certificate in the form of a C source file.
|
|
|
|
=back
|
|
|
|
=head2 TRUST SETTINGS
|
|
|
|
Please note these options are currently experimental and may well change.
|
|
|
|
A B<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".
|
|
|
|
Normally 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 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 SSL client but not SSL server use.
|
|
|
|
See the description of the B<verify> utility for more information on the
|
|
meaning of trust settings.
|
|
|
|
Future versions of OpenSSL will recognize trust settings on any
|
|
certificate: not just root CAs.
|
|
|
|
|
|
=over 4
|
|
|
|
=item B<-trustout>
|
|
|
|
this causes B<x509> to output a B<trusted> 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
|
|
B<-trustout> option a trusted certificate is output. A trusted
|
|
certificate is automatically output if any trust settings are modified.
|
|
|
|
=item B<-setalias arg>
|
|
|
|
sets the alias of the certificate. This will allow the certificate
|
|
to be referred to using a nickname for example "Steve's Certificate".
|
|
|
|
=item B<-alias>
|
|
|
|
outputs the certificate alias, if any.
|
|
|
|
=item B<-clrtrust>
|
|
|
|
clears all the permitted or trusted uses of the certificate.
|
|
|
|
=item B<-clrreject>
|
|
|
|
clears all the prohibited or rejected uses of the certificate.
|
|
|
|
=item B<-addtrust arg>
|
|
|
|
adds a trusted certificate use. Any object name can be used here
|
|
but currently only B<clientAuth> (SSL client use), B<serverAuth>
|
|
(SSL server use) and B<emailProtection> (S/MIME email) are used.
|
|
Other OpenSSL applications may define additional uses.
|
|
|
|
=item B<-addreject arg>
|
|
|
|
adds a prohibited use. It accepts the same values as the B<-addtrust>
|
|
option.
|
|
|
|
=item B<-purpose>
|
|
|
|
this option performs tests on the certificate extensions and outputs
|
|
the results. For a more complete description see the B<CERTIFICATE
|
|
EXTENSIONS> section.
|
|
|
|
=back
|
|
|
|
=head2 SIGNING OPTIONS
|
|
|
|
The B<x509> utility can be used to sign certificates and requests: it
|
|
can thus behave like a "mini CA".
|
|
|
|
=over 4
|
|
|
|
=item B<-signkey filename>
|
|
|
|
this option 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. 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 B<-days> option. Any certificate extensions are retained unless
|
|
the B<-clrext> option is supplied.
|
|
|
|
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.
|
|
|
|
=item B<-clrext>
|
|
|
|
delete any extensions from a certificate. This option is used when a
|
|
certificate is being created from another certificate (for example with
|
|
the B<-signkey> or the B<-CA> options). Normally all extensions are
|
|
retained.
|
|
|
|
=item B<-keyform PEM|DER>
|
|
|
|
specifies the format (DER or PEM) of the private key file used in the
|
|
B<-signkey> option.
|
|
|
|
=item B<-days arg>
|
|
|
|
specifies the number of days to make a certificate valid for. The default
|
|
is 30 days.
|
|
|
|
=item B<-x509toreq>
|
|
|
|
converts a certificate into a certificate request. The B<-signkey> option
|
|
is used to pass the required private key.
|
|
|
|
=item B<-req>
|
|
|
|
by default a certificate is expected on input. With this option a
|
|
certificate request is expected instead.
|
|
|
|
=item B<-set_serial n>
|
|
|
|
specifies the serial number to use. This option can be used with either
|
|
the B<-signkey> or B<-CA> options. If used in conjunction with the B<-CA>
|
|
option the serial number file (as specified by the B<-CAserial> or
|
|
B<-CAcreateserial> options) is not used.
|
|
|
|
The serial number can be decimal or hex (if preceded by B<0x>). Negative
|
|
serial numbers can also be specified but their use is not recommended.
|
|
|
|
=item B<-CA filename>
|
|
|
|
specifies the CA certificate to be used for signing. When this option is
|
|
present B<x509> behaves like a "mini CA". The input file is signed by this
|
|
CA using this option: that is its issuer name is set to the subject name
|
|
of the CA and it is digitally signed using the CAs private key.
|
|
|
|
This option is normally combined with the B<-req> option. Without the
|
|
B<-req> option the input is a certificate which must be self signed.
|
|
|
|
=item B<-CAkey filename>
|
|
|
|
sets the CA private key to sign a certificate with. If this option is
|
|
not specified then it is assumed that the CA private key is present in
|
|
the CA certificate file.
|
|
|
|
=item B<-CAserial filename>
|
|
|
|
sets the CA serial number file to use.
|
|
|
|
When the B<-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
|
|
".srl" appended. For example if the CA certificate file is called
|
|
"mycacert.pem" it expects to find a serial number file called "mycacert.srl".
|
|
|
|
=item B<-CAcreateserial>
|
|
|
|
with this option the CA serial number file is created if it does not exist:
|
|
it will contain the serial number "02" and the certificate being signed will
|
|
have the 1 as its serial number. Normally if the B<-CA> option is specified
|
|
and the serial number file does not exist it is an error.
|
|
|
|
=item B<-extfile filename>
|
|
|
|
file containing certificate extensions to use. If not specified then
|
|
no extensions are added to the certificate.
|
|
|
|
=item B<-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
|
|
"extensions" which contains the section to use.
|
|
|
|
=back
|
|
|
|
=head2 NAME OPTIONS
|
|
|
|
The B<nameopt> command line switch determines how the subject and issuer
|
|
names are displayed. If no B<nameopt> switch is present the default "oneline"
|
|
format is used which is compatible with previous versions of OpenSSL.
|
|
Each option is described in detail below, all options can be preceded by
|
|
a B<-> to turn the option off. Only the first four will normally be used.
|
|
|
|
=over 4
|
|
|
|
=item B<compat>
|
|
|
|
use the old format. This is equivalent to specifying no name options at all.
|
|
|
|
=item B<RFC2253>
|
|
|
|
displays names compatible with RFC2253 equivalent to B<esc_2253>, B<esc_ctrl>,
|
|
B<esc_msb>, B<utf8>, B<dump_nostr>, B<dump_unknown>, B<dump_der>,
|
|
B<sep_comma_plus>, B<dn_rev> and B<sname>.
|
|
|
|
=item B<oneline>
|
|
|
|
a oneline format which is more readable than RFC2253. It is equivalent to
|
|
specifying the B<esc_2253>, B<esc_ctrl>, B<esc_msb>, B<utf8>, B<dump_nostr>,
|
|
B<dump_der>, B<use_quote>, B<sep_comma_plus_space>, B<space_eq> and B<sname>
|
|
options.
|
|
|
|
=item B<multiline>
|
|
|
|
a multiline format. It is equivalent B<esc_ctrl>, B<esc_msb>, B<sep_multiline>,
|
|
B<space_eq>, B<lname> and B<align>.
|
|
|
|
=item B<esc_2253>
|
|
|
|
escape the "special" characters required by RFC2253 in a field That is
|
|
B<,+"E<lt>E<gt>;>. Additionally B<#> is escaped at the beginning of a string
|
|
and a space character at the beginning or end of a string.
|
|
|
|
=item B<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
|
|
RFC2253 \XX notation (where XX are two hex digits representing the
|
|
character value).
|
|
|
|
=item B<esc_msb>
|
|
|
|
escape characters with the MSB set, that is with ASCII values larger than
|
|
127.
|
|
|
|
=item B<use_quote>
|
|
|
|
escapes some characters by surrounding the whole string with B<"> characters,
|
|
without the option all escaping is done with the B<\> character.
|
|
|
|
=item B<utf8>
|
|
|
|
convert all strings to UTF8 format first. This is required by RFC2253. If
|
|
you are lucky enough to have a UTF8 compatible terminal then the use
|
|
of this option (and B<not> setting B<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.
|
|
|
|
=item B<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.
|
|
|
|
=item B<show_type>
|
|
|
|
show the type of the ASN1 character string. The type precedes the
|
|
field contents. For example "BMPSTRING: Hello World".
|
|
|
|
=item B<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 RFC2253
|
|
B<#XXXX...> format.
|
|
|
|
=item B<dump_nostr>
|
|
|
|
dump non character string types (for example OCTET STRING) if this
|
|
option is not set then non character string types will be displayed
|
|
as though each content octet represents a single character.
|
|
|
|
=item B<dump_all>
|
|
|
|
dump all fields. This option when used with B<dump_der> allows the
|
|
DER encoding of the structure to be unambiguously determined.
|
|
|
|
=item B<dump_unknown>
|
|
|
|
dump any field whose OID is not recognised by OpenSSL.
|
|
|
|
=item B<sep_comma_plus>, B<sep_comma_plus_space>, B<sep_semi_plus_space>,
|
|
B<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
|
|
"space" additionally place a space after the separator to make it
|
|
more readable. The B<sep_multiline> uses a linefeed character for
|
|
the RDN separator and a spaced B<+> for the AVA separator. It also
|
|
indents the fields by four characters.
|
|
|
|
=item B<dn_rev>
|
|
|
|
reverse 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.
|
|
|
|
=item B<nofname>, B<sname>, B<lname>, B<oid>
|
|
|
|
these options alter how the field name is displayed. B<nofname> does
|
|
not display the field at all. B<sname> uses the "short name" form
|
|
(CN for commonName for example). B<lname> uses the long form.
|
|
B<oid> represents the OID in numerical form and is useful for
|
|
diagnostic purpose.
|
|
|
|
=item B<align>
|
|
|
|
align field values for a more readable output. Only usable with
|
|
B<sep_multiline>.
|
|
|
|
=item B<space_eq>
|
|
|
|
places spaces round the B<=> character which follows the field
|
|
name.
|
|
|
|
=back
|
|
|
|
=head2 TEXT OPTIONS
|
|
|
|
As well as customising the name output format, it is also possible to
|
|
customise the actual fields printed using the B<certopt> options when
|
|
the B<text> option is present. The default behaviour is to print all fields.
|
|
|
|
=over 4
|
|
|
|
=item B<compatible>
|
|
|
|
use the old format. This is equivalent to specifying no output options at all.
|
|
|
|
=item B<no_header>
|
|
|
|
don't print header information: that is the lines saying "Certificate" and "Data".
|
|
|
|
=item B<no_version>
|
|
|
|
don't print out the version number.
|
|
|
|
=item B<no_serial>
|
|
|
|
don't print out the serial number.
|
|
|
|
=item B<no_signame>
|
|
|
|
don't print out the signature algorithm used.
|
|
|
|
=item B<no_validity>
|
|
|
|
don't print the validity, that is the B<notBefore> and B<notAfter> fields.
|
|
|
|
=item B<no_subject>
|
|
|
|
don't print out the subject name.
|
|
|
|
=item B<no_issuer>
|
|
|
|
don't print out the issuer name.
|
|
|
|
=item B<no_pubkey>
|
|
|
|
don't print out the public key.
|
|
|
|
=item B<no_sigdump>
|
|
|
|
don't give a hexadecimal dump of the certificate signature.
|
|
|
|
=item B<no_aux>
|
|
|
|
don't print out certificate trust information.
|
|
|
|
=item B<no_extensions>
|
|
|
|
don't print out any X509V3 extensions.
|
|
|
|
=item B<ext_default>
|
|
|
|
retain default extension behaviour: attempt to print out unsupported certificate extensions.
|
|
|
|
=item B<ext_error>
|
|
|
|
print an error message for unsupported certificate extensions.
|
|
|
|
=item B<ext_parse>
|
|
|
|
ASN1 parse unsupported extensions.
|
|
|
|
=item B<ext_dump>
|
|
|
|
hex dump unsupported extensions.
|
|
|
|
=item B<ca_default>
|
|
|
|
the value used by the B<ca> utility, equivalent to B<no_issuer>, B<no_pubkey>, B<no_header>,
|
|
B<no_version>, B<no_sigdump> and B<no_signame>.
|
|
|
|
=back
|
|
|
|
=head1 EXAMPLES
|
|
|
|
Note: in these examples the '\' means the example should be all 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
|
|
supporting UTF8:
|
|
|
|
openssl x509 -in cert.pem -noout -subject -nameopt oneline,-esc_msb
|
|
|
|
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 clientAuth \
|
|
-setalias "Steve's Class 1 CA" -out trust.pem
|
|
|
|
=head1 NOTES
|
|
|
|
The PEM format uses the header and footer lines:
|
|
|
|
-----BEGIN CERTIFICATE-----
|
|
-----END CERTIFICATE-----
|
|
|
|
it will also handle files containing:
|
|
|
|
-----BEGIN X509 CERTIFICATE-----
|
|
-----END X509 CERTIFICATE-----
|
|
|
|
Trusted certificates have the lines
|
|
|
|
-----BEGIN TRUSTED CERTIFICATE-----
|
|
-----END TRUSTED CERTIFICATE-----
|
|
|
|
The conversion to UTF8 format used with the name options assumes that
|
|
T61Strings use the ISO8859-1 character set. This is wrong but Netscape
|
|
and MSIE do this as do many certificates. So although this is incorrect
|
|
it is more likely to display the majority of certificates correctly.
|
|
|
|
The B<-fingerprint> option takes the digest of the DER encoded certificate.
|
|
This is commonly called a "fingerprint". Because of the nature of message
|
|
digests the fingerprint of a certificate is unique to that certificate and
|
|
two certificates with the same fingerprint can be considered to be the same.
|
|
|
|
The Netscape fingerprint uses MD5 whereas MSIE uses SHA1.
|
|
|
|
The B<-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.
|
|
|
|
=head1 CERTIFICATE EXTENSIONS
|
|
|
|
The B<-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.
|
|
|
|
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.
|
|
|
|
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. B<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 really 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 again
|
|
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 B<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.
|
|
|
|
A complete description of each test is given below. The comments about
|
|
basicConstraints and keyUsage and V1 certificates above apply to B<all>
|
|
CA certificates.
|
|
|
|
|
|
=over 4
|
|
|
|
=item B<SSL Client>
|
|
|
|
The extended key usage extension must be absent or include the "web client
|
|
authentication" OID. keyUsage 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.
|
|
|
|
=item B<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.
|
|
|
|
=item B<SSL Server>
|
|
|
|
The extended key usage extension must be absent or include the "web server
|
|
authentication" and/or one of the SGC 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 SSL server bit set.
|
|
|
|
=item B<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.
|
|
|
|
=item B<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 normal SSL server.
|
|
|
|
=item B<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 tolerated as an alternative but a warning is shown:
|
|
this is because some Verisign certificates don't set the S/MIME bit.
|
|
|
|
=item B<S/MIME Signing>
|
|
|
|
In addition to the common S/MIME client tests the digitalSignature bit must
|
|
be set if the keyUsage extension is present.
|
|
|
|
=item B<S/MIME Encryption>
|
|
|
|
In addition to the common S/MIME tests the keyEncipherment bit must be set
|
|
if the keyUsage extension is present.
|
|
|
|
=item B<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.
|
|
|
|
=item B<CRL Signing>
|
|
|
|
The keyUsage extension must be absent or it must have the CRL signing bit
|
|
set.
|
|
|
|
=item B<CRL Signing CA>
|
|
|
|
The normal CA tests apply. Except in this case the basicConstraints extension
|
|
must be present.
|
|
|
|
=back
|
|
|
|
=head1 BUGS
|
|
|
|
Extensions in certificates are not transferred to certificate requests and
|
|
vice versa.
|
|
|
|
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.
|
|
|
|
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 behaviour described in the B<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
|
|
OpenSSL 0.9.5 and later.
|
|
|
|
=head1 SEE ALSO
|
|
|
|
L<req(1)|req(1)>, L<ca(1)|ca(1)>, L<genrsa(1)|genrsa(1)>,
|
|
L<gendsa(1)|gendsa(1)>, L<verify(1)|verify(1)>
|
|
|
|
=head1 HISTORY
|
|
|
|
Before OpenSSL 0.9.8, the default digest for RSA keys was MD5.
|
|
|
|
=cut
|