sort the options in verify man page alphabetically

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

diff --git a/doc/apps/verify.pod b/doc/apps/verify.pod
index ff2629d2cf851733b4aa6c5704a4cf594137a74c..bf640685a3fc0740e2adb441ffc79b1b9d8563a5 100644 (file)
--- a/doc/apps/verify.pod
+++ b/doc/apps/verify.pod
@@ -7,13 +7,37 @@ verify - Utility to verify certificates.
 =head1 SYNOPSIS
 
 B<openssl> B<verify>
 =head1 SYNOPSIS
 
 B<openssl> B<verify>

-[B<-CApath directory>]

 [B<-CAfile file>]
 [B<-CAfile file>]

-[B<-purpose purpose>]
-[B<-untrusted file>]
+[B<-CApath directory>]
+[B<-attime timestamp>]
+[B<-check_ss_sig>]
+[B<-crl_check>]
+[B<-crl_check_all>]
+[B<-explicit_policy>]
+[B<-extended_crl>]

 [B<-help>]
 [B<-help>]

+[B<-ignore_critical>]
+[B<-inhibit_any>]
+[B<-inhibit_map>]

 [B<-issuer_checks>]
 [B<-issuer_checks>]

+[B<-partial_chain>]
+[B<-policy arg>]
+[B<-policy_check>]
+[B<-policy_print>]
+[B<-purpose purpose>]
+[B<-suiteB_128>]
+[B<-suiteB_128_only>]
+[B<-suiteB_192>]
+[B<-trusted_first>]
+[B<-untrusted file>]
+[B<-use_deltas>]

 [B<-verbose>]
 [B<-verbose>]

+[B<-verify_depth num>]
+[B<-verify_email email>]
+[B<-verify_hostname hostname>]
+[B<-verify_ip ip>]
+[B<-verify_name name>]
+[B<-x509_strict>]

 [B<->]
 [certificates]
 
 [B<->]
 [certificates]
 


@@ -26,6 +50,11 @@ The B<verify> command verifies certificate chains.
 
 =over 4
 
 
 =over 4
 

+=item B<-CAfile file>
+
+A file of trusted certificates. The file should contain multiple certificates
+in PEM format concatenated together.
+

 =item B<-CApath directory>
 
 A directory of trusted certificates. The certificates should have names
 =item B<-CApath directory>
 
 A directory of trusted certificates. The certificates should have names


@@ -34,50 +63,156 @@ form ("hash" is the hashed certificate subject name: see the B<-hash> option
 of the B<x509> utility). Under Unix the B<c_rehash> script will automatically
 create symbolic links to a directory of certificates.
 
 of the B<x509> utility). Under Unix the B<c_rehash> script will automatically
 create symbolic links to a directory of certificates.
 

-=item B<-CAfile file>
+=item B<-attime timestamp>

 
 

-A file of trusted certificates. The file should contain multiple certificates
-in PEM format concatenated together.
+Perform validation checks using time specified by B<timestamp> and not
+current system time. B<timestamp> is the number of seconds since
+01.01.1970 (UNIX time).

 
 

-=item B<-untrusted file>
+=item B<-check_ss_sig>

 
 

-A file of untrusted certificates. The file should contain multiple certificates
+Verify the signature on the self-signed root CA. This is disabled by default
+because it doesn't add any security.

 
 

-=item B<-purpose purpose>
+=item B<-crl_check>

 
 

-the intended use for the certificate. Without this option no chain verification
-will be done. Currently accepted uses are B<sslclient>, B<sslserver>,
-B<nssslserver>, B<smimesign>, B<smimeencrypt>. See the B<VERIFY OPERATION>
-section for more information.
+Checks end entity certificate validity by attempting to look up a valid CRL.
+If a valid CRL cannot be found an error occurs.
+
+=item B<-crl_check_all>
+
+Checks the validity of B<all> certificates in the chain by attempting
+to look up valid CRLs.
+
+=item B<-explicit_policy>
+
+Set policy variable require-explicit-policy (see RFC5280).
+
+=item B<-extended_crl>
+
+Enable extended CRL features such as indirect CRLs and alternate CRL
+signing keys.

 
 =item B<-help>
 
 
 =item B<-help>
 

-prints out a usage message.
+Print out a usage message.

 
 

-=item B<-verbose>
+=item B<-ignore_critical>
+
+Normally if an unhandled critical extension is present which is not
+supported by OpenSSL the certificate is rejected (as required by RFC5280).
+If this option is set critical extensions are ignored.
+
+=item B<-inhibit_any>

 
 

-print extra information about the operations being performed.
+Set policy variable inhibit-any-policy (see RFC5280).
+
+=item B<-inhibit_map>
+
+Set policy variable inhibit-policy-mapping (see RFC5280).

 
 =item B<-issuer_checks>
 
 
 =item B<-issuer_checks>
 

-print out diagnostics relating to searches for the issuer certificate
-of the current certificate. This shows why each candidate issuer
-certificate was rejected. However the presence of rejection messages
-does not itself imply that anything is wrong: during the normal
-verify process several rejections may take place.
+Print out diagnostics relating to searches for the issuer certificate of the
+current certificate. This shows why each candidate issuer certificate was
+rejected. The presence of rejection messages does not itself imply that
+anything is wrong; during the normal verification process, several
+rejections may take place.
+
+=item B<-partial_chain>
+
+Allow partial certificate chain if at least one certificate is in trusted store.
+
+=item B<-policy arg>
+
+Enable policy processing and add B<arg> to the user-initial-policy-set (see
+RFC5280). The policy B<arg> can be an object name an OID in numeric form.
+This argument can appear more than once.
+
+=item B<-policy_check>
+
+Enables certificate policy processing.
+
+=item B<-policy_print>
+
+Print out diagnostics related to policy processing.
+
+=item B<-purpose purpose>
+
+The intended use for the certificate. If this option is not specified,
+B<verify> will not consider certificate purpose during chain verification.
+Currently accepted uses are B<sslclient>, B<sslserver>, B<nssslserver>,
+B<smimesign>, B<smimeencrypt>. See the B<VERIFY OPERATION> section for more
+information.
+
+=item B<-suiteB_128_only>, B<-suiteB_128>, B<-suiteB_192>
+
+enable the Suite B mode operation at 128 bit Level of Security, 128 bit or
+192 bit, or only 192 bit Level of Security respectively.
+See RFC6460 for details. In particular the supported signature algorithms are
+reduced to support only ECDSA and SHA256 or SHA384 and only the elliptic curves
+P-256 and P-384.
+
+=item B<-trusted_first>
+
+Use certificates in CA file or CA directory before certificates in untrusted
+file when building the trust chain to verify certificates.
+This is mainly useful in environments with Bridge CA or Cross-Certified CAs.
+
+=item B<-untrusted file>
+
+A file of untrusted certificates. The file should contain multiple certificates
+in PEM format concatenated together.
+
+=item B<-use_deltas>
+
+Enable support for delta CRLs.
+
+=item B<-verbose>
+
+Print extra information about the operations being performed.
+
+=item B<-verify_depth num>
+
+Limit the maximum depth of the certificate chain to B<num> certificates.
+
+=item B<-verify_email email>
+
+Verify if the B<email> matches the email address in Subject Alternative Name or
+the email the subject Distinguished Name.
+
+=item B<-verify_hostname hostname>
+
+Verify if the B<hostname> matches DNS name in Subject Alternative Name or
+Common Name in the subject certificate.
+
+=item B<-verify_ip ip>
+
+Verify if the B<ip> matches the IP address in Subject Alternative Name of
+the subject certificate.
+
+=item B<-verify_name name>
+
+Use default verification options like trust model and required certificate
+policies identified by B<name>.
+Supported usages include: default, pkcs7, smime_sign, ssl_client, ssl_server.
+
+=item B<-x509_strict>
+
+For strict X.509 compliance, disable non-compliant workarounds for broken
+certificates.

 
 =item B<->
 
 
 =item B<->
 

-marks the last option. All arguments following this are assumed to be
+Indicates the last option. All arguments following this are assumed to be

 certificate files. This is useful if the first certificate filename begins
 with a B<->.
 
 =item B<certificates>
 
 certificate files. This is useful if the first certificate filename begins
 with a B<->.
 
 =item B<certificates>
 

-one or more certificates to verify. If no certificate filenames are included
-then an attempt is made to read a certificate from standard input. They should
-all be in PEM format.
-
+One or more certificates to verify. If no certificates are given, B<verify>
+will attempt to read a certificate from standard input. Certificates must be
+in PEM format.

 
 =back
 
 
 =back
 


@@ -166,12 +301,12 @@ the operation was successful.
 
 =item B<2 X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT: unable to get issuer certificate>
 
 
 =item B<2 X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT: unable to get issuer certificate>
 

-the issuer certificate could not be found: this occurs if the issuer certificate
-of an untrusted certificate cannot be found.
+the issuer certificate of a looked up certificate could not be found. This
+normally means the list of trusted certificates is not complete.

 
 =item B<3 X509_V_ERR_UNABLE_TO_GET_CRL: unable to get certificate CRL>
 
 
 =item B<3 X509_V_ERR_UNABLE_TO_GET_CRL: unable to get certificate CRL>
 

-the CRL of a certificate could not be found. Unused.
+the CRL of a certificate could not be found.

 
 =item B<4 X509_V_ERR_UNABLE_TO_DECRYPT_CERT_SIGNATURE: unable to decrypt certificate's signature>
 
 
 =item B<4 X509_V_ERR_UNABLE_TO_DECRYPT_CERT_SIGNATURE: unable to decrypt certificate's signature>
 


@@ -194,7 +329,7 @@ the signature of the certificate is invalid.
 
 =item B<8 X509_V_ERR_CRL_SIGNATURE_FAILURE: CRL signature failure>
 
 
 =item B<8 X509_V_ERR_CRL_SIGNATURE_FAILURE: CRL signature failure>
 

-the signature of the certificate is invalid. Unused.
+the signature of the certificate is invalid.

 
 =item B<9 X509_V_ERR_CERT_NOT_YET_VALID: certificate is not yet valid>
 
 
 =item B<9 X509_V_ERR_CERT_NOT_YET_VALID: certificate is not yet valid>
 


@@ -206,11 +341,11 @@ the certificate has expired: that is the notAfter date is before the current tim
 
 =item B<11 X509_V_ERR_CRL_NOT_YET_VALID: CRL is not yet valid>
 
 
 =item B<11 X509_V_ERR_CRL_NOT_YET_VALID: CRL is not yet valid>
 

-the CRL is not yet valid. Unused.
+the CRL is not yet valid.

 
 =item B<12 X509_V_ERR_CRL_HAS_EXPIRED: CRL has expired>
 
 
 =item B<12 X509_V_ERR_CRL_HAS_EXPIRED: CRL has expired>
 

-the CRL has expired. Unused.
+the CRL has expired.

 
 =item B<13 X509_V_ERR_ERROR_IN_CERT_NOT_BEFORE_FIELD: format error in certificate's notBefore field>
 
 
 =item B<13 X509_V_ERR_ERROR_IN_CERT_NOT_BEFORE_FIELD: format error in certificate's notBefore field>
 


@@ -222,11 +357,11 @@ the certificate notAfter field contains an invalid time.
 
 =item B<15 X509_V_ERR_ERROR_IN_CRL_LAST_UPDATE_FIELD: format error in CRL's lastUpdate field>
 
 
 =item B<15 X509_V_ERR_ERROR_IN_CRL_LAST_UPDATE_FIELD: format error in CRL's lastUpdate field>
 

-the CRL lastUpdate field contains an invalid time. Unused.
+the CRL lastUpdate field contains an invalid time.

 
 =item B<16 X509_V_ERR_ERROR_IN_CRL_NEXT_UPDATE_FIELD: format error in CRL's nextUpdate field>
 
 
 =item B<16 X509_V_ERR_ERROR_IN_CRL_NEXT_UPDATE_FIELD: format error in CRL's nextUpdate field>
 

-the CRL nextUpdate field contains an invalid time. Unused.
+the CRL nextUpdate field contains an invalid time.

 
 =item B<17 X509_V_ERR_OUT_OF_MEM: out of memory>
 
 
 =item B<17 X509_V_ERR_OUT_OF_MEM: out of memory>
 


@@ -244,8 +379,8 @@ be found locally.
 
 =item B<20 X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY: unable to get local issuer certificate>
 
 
 =item B<20 X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY: unable to get local issuer certificate>
 

-the issuer certificate of a locally looked up certificate could not be found. This normally means
-the list of trusted certificates is not complete.
+the issuer certificate could not be found: this occurs if the issuer
+certificate of an untrusted certificate cannot be found.

 
 =item B<21 X509_V_ERR_UNABLE_TO_VERIFY_LEAF_SIGNATURE: unable to verify the first certificate>
 
 
 =item B<21 X509_V_ERR_UNABLE_TO_VERIFY_LEAF_SIGNATURE: unable to verify the first certificate>
 


@@ -258,7 +393,7 @@ the certificate chain length is greater than the supplied maximum depth. Unused.
 
 =item B<23 X509_V_ERR_CERT_REVOKED: certificate revoked>
 
 
 =item B<23 X509_V_ERR_CERT_REVOKED: certificate revoked>
 

-the certificate has been revoked. Unused.
+the certificate has been revoked.

 
 =item B<24 X509_V_ERR_INVALID_CA: invalid CA certificate>
 
 
 =item B<24 X509_V_ERR_INVALID_CA: invalid CA certificate>
 


@@ -312,7 +447,7 @@ an application specific error. Unused.
 
 =head1 BUGS
 
 
 =head1 BUGS
 

-Although the issuer checks are a considerably improvement over the old technique they still
+Although the issuer checks are a considerable improvement over the old technique they still

 suffer from limitations in the underlying X509_LOOKUP API. One consequence of this is that
 trusted certificates with matching subject name must either appear in a file (as specified by the
 B<-CAfile> option) or a directory (as specified by B<-CApath>. If they occur in both then only
 suffer from limitations in the underlying X509_LOOKUP API. One consequence of this is that
 trusted certificates with matching subject name must either appear in a file (as specified by the
 B<-CAfile> option) or a directory (as specified by B<-CApath>. If they occur in both then only


@@ -321,6 +456,10 @@ the certificates in the file will be recognised.
 Previous versions of OpenSSL assume certificates with matching subject name are identical and
 mishandled them.
 
 Previous versions of OpenSSL assume certificates with matching subject name are identical and
 mishandled them.
 

+Previous versions of this documentation swapped the meaning of the
+B<X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT> and
+B<20 X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY> error codes.
+

 =head1 SEE ALSO
 
 L<x509(1)|x509(1)>
 =head1 SEE ALSO
 
 L<x509(1)|x509(1)>