X-Git-Url: https://git.openssl.org/?p=openssl.git;a=blobdiff_plain;f=doc%2Fapps%2Fverify.pod;h=bf640685a3fc0740e2adb441ffc79b1b9d8563a5;hp=ff2629d2cf851733b4aa6c5704a4cf594137a74c;hb=2866441a9027b0f7f07c675ba450eff897e16a91;hpb=7c1722c60dfc6b6b95ca604effbe6c1cf844685c diff --git a/doc/apps/verify.pod b/doc/apps/verify.pod index ff2629d2cf..bf640685a3 100644 --- a/doc/apps/verify.pod +++ b/doc/apps/verify.pod @@ -7,13 +7,37 @@ verify - Utility to verify certificates. =head1 SYNOPSIS B B -[B<-CApath directory>] [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<-ignore_critical>] +[B<-inhibit_any>] +[B<-inhibit_map>] [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<-verify_depth num>] +[B<-verify_email email>] +[B<-verify_hostname hostname>] +[B<-verify_ip ip>] +[B<-verify_name name>] +[B<-x509_strict>] [B<->] [certificates] @@ -26,6 +50,11 @@ The B command verifies certificate chains. =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 @@ -34,50 +63,156 @@ form ("hash" is the hashed certificate subject name: see the B<-hash> option of the B utility). Under Unix the B 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 and not +current system time. B 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, B, -B, B, B. See the B -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 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> -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> -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 to the user-initial-policy-set (see +RFC5280). The policy B 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 will not consider certificate purpose during chain verification. +Currently accepted uses are B, B, B, +B, B. See the B 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 certificates. + +=item B<-verify_email email> + +Verify if the B matches the email address in Subject Alternative Name or +the email the subject Distinguished Name. + +=item B<-verify_hostname hostname> + +Verify if the B matches DNS name in Subject Alternative Name or +Common Name in the subject certificate. + +=item B<-verify_ip ip> + +Verify if the B 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. +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<-> -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 -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 +will attempt to read a certificate from standard input. Certificates must be +in PEM format. =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> -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> -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> @@ -194,7 +329,7 @@ the signature of the certificate is invalid. =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> @@ -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> -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> -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> @@ -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> -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> -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> @@ -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> -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> @@ -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> -the certificate has been revoked. Unused. +the certificate has been revoked. =item B<24 X509_V_ERR_INVALID_CA: invalid CA certificate> @@ -312,7 +447,7 @@ an application specific error. Unused. =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 @@ -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 this documentation swapped the meaning of the +B and +B<20 X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY> error codes. + =head1 SEE ALSO L