=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
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.
+Note that if a DSA key is used for signing, then this flag is ignored
+and SHA1 is used.
+=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 SETTINGS> section.
this option prevents output of the encoded version of the request.
+=item B<-pubkey>
+
+outputs the 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.
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<SUBJECT AND ISSUER NAME OPTIONS> section for more information.
+set multiple options. See the B<NAME OPTIONS> section for more information.
=item B<-email>
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
+=head2 TRUST SETTINGS
Please note these options are currently experimental and may well change.
=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".
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>
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 SUBJECT AND ISSUER 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 explicitely.
=item B<multiline>
a multiline format. It is equivalent B<esc_ctrl>, B<esc_msb>, B<sep_multiline>,
-B<sp
c_eq>, B<lname> and B<align>.
+B<sp
ace_eq>, B<lname> and B<align>.
=item B<esc_2253>
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
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:
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
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.
=cut
projects / openssl.git / blobdiff