diff options
Diffstat (limited to 'openssl/doc/apps/x509.pod')
| -rw-r--r-- | openssl/doc/apps/x509.pod | 832 |
1 files changed, 832 insertions, 0 deletions
diff --git a/openssl/doc/apps/x509.pod b/openssl/doc/apps/x509.pod new file mode 100644 index 000000000..f43c17523 --- /dev/null +++ b/openssl/doc/apps/x509.pod @@ -0,0 +1,832 @@ + +=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 "-subject_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 |