


X509(1)			     OpenSSL			  X509(1)


NAME
       x509 - 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]
       [-in filename] [-out filename] [-serial] [-hash]
       [-subject] [-issuer] [-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 section]

DESCRIPTION
       The 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.

INPUT, OUTPUT AND GENERAL PURPOSE OPTIONS
       -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 -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.

       -outform DER|PEM|NET
	   This specifies the output format, the options have the
	   same meaning as the -inform option.

       -in filename
	   This specifies the input filename to read a
	   certificate from or standard input if this option is
	   not specified.

       -out filename
	   This specifies the output filename to write to or
	   standard output by default.

       -md2|-md5|-sha1|-mdc2
	   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:



23/Mar/2000		      0.9.5a				1





X509(1)			     OpenSSL			  X509(1)


	   SHA1 is always used with DSA keys.

DISPLAY OPTIONS
       Note: the -alias and -purpose options are also display
       options but are described in the TRUST OPTIONS section.

       -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.

       -noout
	   this option prevents output of the encoded version of
	   the request.

       -modulus
	   this option prints out the value of the modulus of the
	   public key contained in the certificate.

       -serial
	   outputs the certificate serial number.

       -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.

       -subject
	   outputs the subject name.

       -issuer
	   outputs the issuer name.

       -startdate
	   prints out the start date of the certificate, that is
	   the notBefore date.

       -enddate
	   prints out the expiry date of the certificate, that is
	   the notAfter date.

       -dates
	   prints out the start and expiry dates of a
	   certificate.

       -fingerprint
	   prints out the digest of the DER encoded version of
	   the whole certificate.

       -C  this outputs the certificate in the form of a C source
	   file.




23/Mar/2000		      0.9.5a				2





X509(1)			     OpenSSL			  X509(1)


TRUST SETTINGS
       Please note these options are currently experimental and
       may well 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".

       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 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.

       -trustout
	   this causes x509 to output a 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 -trustout
	   option a trusted certificate is output. A trusted
	   certificate is automatically output if any trust
	   settings are modified.

       -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".

       -alias
	   outputs the certificate alias, if any.

       -clrtrust
	   clears all the permitted or trusted uses of the
	   certificate.

       -clrreject
	   clears all the prohibited or rejected uses of the
	   certificate.

       -addtrust arg
	   adds a trusted certificate use. Any object name can be
	   used here but currently only clientAuth (SSL client



23/Mar/2000		      0.9.5a				3





X509(1)			     OpenSSL			  X509(1)


	   use), serverAuth (SSL server use) and emailProtection
	   (S/MIME email) are used.  Other OpenSSL applications
	   may define additional uses.

       -addreject arg
	   adds a prohibited use. It accepts the same values as
	   the -addtrust option.

       -purpose
	   this option performs tests on the certificate
	   extensions and outputs the results. For a more
	   complete description see the CERTIFICATE EXTENSIONS
	   section.

SIGNING OPTIONS
       The x509 utility can be used to sign certificates and
       requests: it can thus behave like a "mini CA".

       -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 -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 created using the supplied
	   private key using the subject name in the request.

       -clrext
	   delete any extensions from a certificate. This option
	   is used when a certificate is being created from
	   another certificate (for example with the -signkey or
	   the -CA options). Normally all extensions are
	   retained.

       -keyform PEM|DER
	   specifies the format (DER or PEM) of the private key
	   file used in the -signkey option.

       -days arg
	   specifies the number of days to make a certificate
	   valid for. The default is 30 days.

       -x509toreq
	   converts a certificate into a certificate request. The
	   -signkey option is used to pass the required private
	   key.



23/Mar/2000		      0.9.5a				4





X509(1)			     OpenSSL			  X509(1)


       -req
	   by default a certificate is expected on input. With
	   this option a certificate request is expected instead.

       -CA filename
	   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: 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 -req option.
	   Without the -req option the input is a certificate
	   which must be self signed.

       -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.

       -CAserial filename
	   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 ".srl" appended. For example if
	   the CA certificate file is called "mycacert.pem" it
	   expects to find a serial number file called
	   "mycacert.srl".

       -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 -CA option
	   is specified and the serial number file does not exist
	   it is an error.

       -extfile filename
	   file containing certificate extensions to use. If not
	   specified then no extensions are added to the
	   certificate.

       -extensions section
	   the section to add certificate extensions from. If
	   this option is not specified then the extensions



23/Mar/2000		      0.9.5a				5





X509(1)			     OpenSSL			  X509(1)


	   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.

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


NOTES
       The PEM format uses the header and footer lines:



23/Mar/2000		      0.9.5a				6





X509(1)			     OpenSSL			  X509(1)


	-----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 -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.

CERTIFICATE EXTENSIONS
       The -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. 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



23/Mar/2000		      0.9.5a				7





X509(1)			     OpenSSL			  X509(1)


       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.

       A complete description of each test is given below. The
       comments about basicConstraints and keyUsage and V1
       certificates above apply to all CA certificates.

       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.

       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.  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.

       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 normal SSL
	   server.

       Common S/MIME Client Tests
	   The extended key usage extension must be absent or
	   include the "email protection" OID. Netscape



23/Mar/2000		      0.9.5a				8





X509(1)			     OpenSSL			  X509(1)


	   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.

       S/MIME Signing
	   In addition to the common S/MIME client tests the
	   digitalSignature 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
	   basicConstraints extension must be present.

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 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.



23/Mar/2000		      0.9.5a				9





X509(1)			     OpenSSL			  X509(1)


SEE ALSO
       req(1), ca(1), genrsa(1), gendsa(1), verify(1)























































23/Mar/2000		      0.9.5a			       10





X509(1)			     OpenSSL			  X509(1)



























































23/Mar/2000		      0.9.5a			       11


