RT1596: Add clarifying doc.

[openssl.git] / doc / apps / x509.pod

diff --git a/doc/apps/x509.pod b/doc/apps/x509.pod
index 062a919f3fd57ea1fc4682174d0f8e7885f27015..7dde927cb49d9fae4d9de49a75c38f464b1dffc8 100644 (file)
--- a/doc/apps/x509.pod
+++ b/doc/apps/x509.pod
@@ -8,6 +8,7 @@ x509 - Certificate display and signing utility
 =head1 SYNOPSIS
 
 B<openssl> B<x509>
+[B<-help>]
 [B<-inform DER|PEM|NET>]
 [B<-outform DER|PEM|NET>]
 [B<-keyform DER|PEM>]
@@ -55,7 +56,7 @@ B<openssl> B<x509>
 [B<-text>]
 [B<-certopt option>]
 [B<-C>]
-[B<-md2|-md5|-sha1|-mdc2>]
+[B<-[digest]>]
 [B<-clrext>]
 [B<-extfile filename>]
 [B<-extensions section>]
@@ -77,6 +78,10 @@ various sections.
 
 =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
@@ -101,12 +106,15 @@ if this option is not specified.
 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 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.
+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>
 
@@ -286,9 +294,12 @@ 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.
+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>
@@ -321,7 +332,8 @@ 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
@@ -330,7 +342,7 @@ 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)|openssl(1)>.
+see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>.
 
 =item B<-clrext>
 
@@ -416,7 +428,7 @@ 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. See the
-L<x509v3_config(5)|x509v3_config(5)> manual page for details of the
+L<x509v3_config(5)> manual page for details of the
 extension section format.
 
 =item B<-force_pubkey key>
@@ -442,7 +454,7 @@ a B<-> to turn the option off. Only the first four will normally be used.
 
 =item B<compat>
 
-use the old format. This is equivalent to specifying no name options at all.
+use the old format.
 
 =item B<RFC2253>
 
@@ -455,7 +467,7 @@ B<sep_comma_plus>, B<dn_rev> and B<sname>.
 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.
+options.  This is the I<default> of no name options are given explicitely.
 
 =item B<multiline>
 
@@ -539,7 +551,8 @@ 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.
+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>
 
@@ -865,21 +878,14 @@ 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)>,
-L<x509v3_config(5)|x509v3_config(5)> 
+L<req(1)>, L<ca(1)>, L<genrsa(1)>,
+L<gendsa(1)>, L<verify(1)>,
+L<x509v3_config(5)> 
 
 =head1 HISTORY
 
-Before OpenSSL 0.9.8, the default digest for RSA keys was MD5.
-
 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