544 lines
16 KiB
Text
544 lines
16 KiB
Text
|
|
=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>]
|
|
[B<-issuer>]
|
|
[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<-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>]
|
|
|
|
=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 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 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.
|
|
|
|
|
|
=back
|
|
|
|
=head1 DISPLAY OPTIONS
|
|
|
|
Note: the B<-alias> and B<-purpose> options are also display options
|
|
but are described in the B<TRUST OPTIONS> 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<-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<-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<-subject>
|
|
|
|
outputs the subject name.
|
|
|
|
=item B<-issuer>
|
|
|
|
outputs the issuer name.
|
|
|
|
=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.
|
|
|
|
=item B<-C>
|
|
|
|
this outputs the certificate in the form of a C source file.
|
|
|
|
=back
|
|
|
|
=head1 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
|
|
|
|
=head1 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<-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 filename>
|
|
|
|
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
|
|
|
|
=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 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 -config 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 -config 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
|
|
|
|
=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 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.
|
|
|
|
=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
|
|
|
|
The way DNs are printed is in a "historical SSLeay" format which doesn't
|
|
follow any published standard. It should follow some standard like RFC2253
|
|
or RFC1779 with options to make the stuff more readable.
|
|
|
|
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 behavior 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)>
|
|
|
|
=cut
|