-
=pod
=head1 NAME
=head1 SYNOPSIS
B<openssl> B<x509>
+[B<-help>]
[B<-inform DER|PEM|NET>]
[B<-outform DER|PEM|NET>]
[B<-keyform DER|PEM>]
[B<-out filename>]
[B<-serial>]
[B<-hash>]
+[B<-subject_hash>]
+[B<-issuer_hash>]
+[B<-ocspid>]
[B<-subject>]
[B<-issuer>]
[B<-nameopt option>]
[B<-email>]
+[B<-ocsp_uri>]
[B<-startdate>]
[B<-enddate>]
[B<-purpose>]
[B<-dates>]
+[B<-checkend num>]
[B<-modulus>]
+[B<-pubkey>]
[B<-fingerprint>]
[B<-alias>]
[B<-noout>]
[B<-days arg>]
[B<-set_serial n>]
[B<-signkey filename>]
+[B<-passin arg>]
[B<-x509toreq>]
[B<-req>]
[B<-CA filename>]
[B<-CAkey filename>]
[B<-CAcreateserial>]
[B<-CAserial filename>]
+[B<-force_pubkey key>]
[B<-text>]
+[B<-certopt option>]
[B<-C>]
-[B<-md2|-md5|-sha1|-mdc2>]
+[B<-[digest]>]
[B<-clrext>]
[B<-extfile filename>]
[B<-extensions section>]
+[B<-engine id>]
=head1 DESCRIPTION
Since there are a large number of options they will split up into
various sections.
+=head1 OPTIONS
-=head1 INPUT, OUTPUT AND GENERAL PURPOSE OPTIONS
+=head2 Input, Output, and General Purpose Options
=over 4
+=item B<-help>
+
+Print out a usage message.
+
=item B<-inform DER|PEM|NET>
This specifies the input format normally the command will expect an X509
=item B<-outform DER|PEM|NET>
-This specifies the output format, the options have the same meaning as the
+This specifies the output format, the options have the same meaning as the
B<-inform> option.
=item B<-in filename>
This specifies the output filename to write to or standard output by
default.
-=item B<-md2|-md5|-sha1|-mdc2>
+=item B<-[digest]>
-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.
+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.
+Any digest supported by the OpenSSL B<dgst> command can be used.
+If not specified then SHA1 is used with B<-fingerprint> or
+the default digest for the signing algorithm is used, typically SHA256.
+=item B<-engine id>
+
+specifying an engine (by its unique B<id> string) will cause B<x509>
+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
-=head1 DISPLAY OPTIONS
+=head2 Display Options
Note: the B<-alias> and B<-purpose> options are also display options
-but are described in the B<TRUST OPTIONS> section.
+but are described in the B<TRUST SETTINGS> section.
=over 4
this option prevents output of the encoded version of the request.
+=item B<-pubkey>
+
+outputs the certificate's SubjectPublicKeyInfo block in PEM format.
+
=item B<-modulus>
this option prints out the value of the modulus of the public key
outputs the certificate serial number.
-=item B<-hash>
+=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<-ocspid>
+
+outputs the OCSP hash values for the subject name and public key.
+
+=item B<-hash>
+
+synonym for "-subject_hash" for backward compatibility reasons.
+
+=item B<-subject_hash_old>
+
+outputs the "hash" of the certificate subject name using the older algorithm
+as used by OpenSSL versions before 1.0.0.
+
+=item B<-issuer_hash_old>
+
+outputs the "hash" of the certificate issuer name using the older algorithm
+as used by OpenSSL versions before 1.0.0.
+
=item B<-subject>
outputs the subject name.
outputs the email address(es) if any.
+=item B<-ocsp_uri>
+
+outputs the OCSP responder address(es) if any.
+
=item B<-startdate>
prints out the start date of the certificate, that is the notBefore date.
prints out the start and expiry dates of a certificate.
+=item B<-checkend arg>
+
+checks if the certificate expires within the next B<arg> seconds and exits
+non-zero if yes it will expire or zero if not.
+
=item B<-fingerprint>
prints out the digest of the DER encoded version of the whole certificate
=back
-=head1 TRUST SETTINGS
-
-Please note these options are currently experimental and may well change.
+=head2 Trust Settings
A B<trusted certificate> is an ordinary certificate which has several
additional pieces of information attached to it such as the permitted
=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.
+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), B<emailProtection> (S/MIME email) and
+B<anyExtendedKeyUsage> are used.
+As of OpenSSL 1.1.0, the last of these blocks all purposes when rejected or
+enables all purposes when trusted.
Other OpenSSL applications may define additional uses.
=item B<-addreject arg>
=back
-=head1 SIGNING OPTIONS
+=head2 Signing Options
The B<x509> utility can be used to sign certificates and requests: it
can thus behave like a "mini CA".
=item B<-signkey filename>
this option causes the input file to be self signed using the supplied
-private key.
+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.
+the B<-clrext> option is supplied; this includes, for example, any existing
+key identifier extensions.
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<-passin arg>
+
+the key password source. For more information about the format of B<arg>
+see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>.
+
=item B<-clrext>
delete any extensions from a certificate. This option is used when a
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.
+The serial number can be decimal or hex (if preceded by B<0x>).
=item B<-CA filename>
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
+".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.
+have the 1 as its serial number. If the B<-CA> option is specified
+and the serial number file does not exist a random number is generated;
+this is the recommended practice.
=item B<-extfile filename>
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.
+"extensions" which contains the section to use. See the
+L<x509v3_config(5)> manual page for details of the
+extension section format.
+
+=item B<-force_pubkey key>
+
+when a certificate is created set its public key to B<key> instead of the
+key in the certificate or certificate request. This option is useful for
+creating certificates where the algorithm can't normally sign requests, for
+example DH.
+
+The format or B<key> can be specified using the B<-keyform> option.
=back
-=head1 NAME OPTIONS
+=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"
=item B<compat>
-use the old format. This is equivalent to specifying no name options at all.
+use the old format.
=item B<RFC2253>
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_spc>, B<spc_eq> and B<sname>
-options.
+B<dump_der>, B<use_quote>, B<sep_comma_plus_space>, B<space_eq> and B<sname>
+options. This is the I<default> of no name options are given explicitly.
=item B<multiline>
a multiline format. It is equivalent B<esc_ctrl>, B<esc_msb>, B<sep_multiline>,
-B<spc_eq>, B<lname> and B<align>.
+B<space_eq>, B<lname> and B<align>.
=item B<esc_2253>
-escape the "special" characters required by RFC2253 in a field That is
+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_2254>
+
+escape the "special" characters required by RFC2254 in a field. That is
+the B<NUL> character as well as and B<()*>.
+
=item B<esc_ctrl>
escape control characters. That is those with ASCII values less than
Also if this option is off any UTF8Strings will be converted to their
character form first.
-=item B<no_type>
+=item B<ignore_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
"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.
+indents the fields by four characters. If no field separator is specified
+then B<sep_comma_plus_space> is used by default.
=item B<dn_rev>
align field values for a more readable output. Only usable with
B<sep_multiline>.
-=item B<spc_eq>
+=item B<space_eq>
places spaces round the B<=> character which follows the field
name.
=back
-=head1 TEXT OPTIONS
+=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
=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>.
+the value used by the B<ca> utility, equivalent to B<no_issuer>, B<no_pubkey>,
+B<no_header>, and B<no_version>.
=back
Display the certificate subject name in oneline form on a terminal
supporting UTF8:
- openssl x509 -in cert.pem -noout -subject -nameopt oneline,-escmsb
+ openssl x509 -in cert.pem -noout -subject -nameopt oneline,-esc_msb
Display the certificate MD5 fingerprint:
extensions for a CA:
openssl x509 -req -in careq.pem -extfile openssl.cnf -extensions v3_ca \
- -signkey key.pem -out cacert.pem
+ -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
+ -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
+ openssl x509 -in cert.pem -addtrust clientAuth \
+ -setalias "Steve's Class 1 CA" -out trust.pem
=head1 NOTES
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.
+extension is absent.
=item B<CRL Signing>
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)>
+L<req(1)>, L<ca(1)>, L<genrsa(1)>,
+L<gendsa(1)>, L<verify(1)>,
+L<x509v3_config(5)>
+
+=head1 HISTORY
+
+The hash algorithm used in the B<-subject_hash> and B<-issuer_hash> options
+before OpenSSL 1.0.0 was based on the deprecated MD5 algorithm and the encoding
+of the distinguished name. In OpenSSL 1.0.0 and later it is based on a
+canonical version of the DN using SHA1. This means that any directories using
+the old form must have their links rebuilt using B<c_rehash> or similar.
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
=cut