430 lines
15 KiB
Text
430 lines
15 KiB
Text
=pod
|
|
|
|
=head1 NAME
|
|
|
|
verify - Utility to verify certificates.
|
|
|
|
=head1 SYNOPSIS
|
|
|
|
B<openssl> B<verify>
|
|
[B<-CApath directory>]
|
|
[B<-CAfile file>]
|
|
[B<-purpose purpose>]
|
|
[B<-policy arg>]
|
|
[B<-ignore_critical>]
|
|
[B<-crl_check>]
|
|
[B<-crl_check_all>]
|
|
[B<-policy_check>]
|
|
[B<-explicit_policy>]
|
|
[B<-inhibit_any>]
|
|
[B<-inhibit_map>]
|
|
[B<-x509_strict>]
|
|
[B<-extended_crl>]
|
|
[B<-use_deltas>]
|
|
[B<-policy_print>]
|
|
[B<-no_alt_chains>]
|
|
[B<-allow_proxy_certs>]
|
|
[B<-untrusted file>]
|
|
[B<-help>]
|
|
[B<-issuer_checks>]
|
|
[B<-attime timestamp>]
|
|
[B<-verbose>]
|
|
[B<->]
|
|
[certificates]
|
|
|
|
|
|
=head1 DESCRIPTION
|
|
|
|
The B<verify> command verifies certificate chains.
|
|
|
|
=head1 COMMAND OPTIONS
|
|
|
|
=over 4
|
|
|
|
=item B<-CApath directory>
|
|
|
|
A directory of trusted certificates. The certificates should have names
|
|
of the form: hash.0 or have symbolic links to them of this
|
|
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.
|
|
|
|
=item B<-CAfile file>
|
|
A file of trusted certificates. The file should contain multiple certificates
|
|
in PEM format concatenated together.
|
|
|
|
=item B<-untrusted file>
|
|
|
|
A file of untrusted certificates. The file should contain multiple certificates
|
|
in PEM format concatenated together.
|
|
|
|
=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<-help>
|
|
|
|
Print out a usage message.
|
|
|
|
=item B<-verbose>
|
|
|
|
Print extra information about the operations being performed.
|
|
|
|
=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. 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<-attime timestamp>
|
|
|
|
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<-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<-explicit_policy>
|
|
|
|
Set policy variable require-explicit-policy (see RFC5280).
|
|
|
|
=item B<-inhibit_any>
|
|
|
|
Set policy variable inhibit-any-policy (see RFC5280).
|
|
|
|
=item B<-inhibit_map>
|
|
|
|
Set policy variable inhibit-policy-mapping (see RFC5280).
|
|
|
|
=item B<-no_alt_chains>
|
|
|
|
When building a certificate chain, if the first certificate chain found is not
|
|
trusted, then OpenSSL will continue to check to see if an alternative chain can
|
|
be found that is trusted. With this option that behaviour is suppressed so that
|
|
only the first chain found is ever used. Using this option will force the
|
|
behaviour to match that of previous OpenSSL versions.
|
|
|
|
=item B<-allow_proxy_certs>
|
|
|
|
Allow the verification of proxy certificates.
|
|
|
|
=item B<-policy_print>
|
|
|
|
Print out diagnostics related to policy processing.
|
|
|
|
=item B<-crl_check>
|
|
|
|
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<-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<-x509_strict>
|
|
|
|
For strict X.509 compliance, disable non-compliant workarounds for broken
|
|
certificates.
|
|
|
|
=item B<-extended_crl>
|
|
|
|
Enable extended CRL features such as indirect CRLs and alternate CRL
|
|
signing keys.
|
|
|
|
=item B<-use_deltas>
|
|
|
|
Enable support for delta CRLs.
|
|
|
|
=item B<-check_ss_sig>
|
|
|
|
Verify the signature on the self-signed root CA. This is disabled by default
|
|
because it doesn't add any security.
|
|
|
|
=item B<->
|
|
|
|
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>
|
|
|
|
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
|
|
|
|
=head1 VERIFY OPERATION
|
|
|
|
The B<verify> program uses the same functions as the internal SSL and S/MIME
|
|
verification, therefore this description applies to these verify operations
|
|
too.
|
|
|
|
There is one crucial difference between the verify operations performed
|
|
by the B<verify> program: wherever possible an attempt is made to continue
|
|
after an error whereas normally the verify operation would halt on the
|
|
first error. This allows all the problems with a certificate chain to be
|
|
determined.
|
|
|
|
The verify operation consists of a number of separate steps.
|
|
|
|
Firstly a certificate chain is built up starting from the supplied certificate
|
|
and ending in the root CA. It is an error if the whole chain cannot be built
|
|
up. The chain is built up by looking up the issuers certificate of the current
|
|
certificate. If a certificate is found which is its own issuer it is assumed
|
|
to be the root CA.
|
|
|
|
The process of 'looking up the issuers certificate' itself involves a number
|
|
of steps. In versions of OpenSSL before 0.9.5a the first certificate whose
|
|
subject name matched the issuer of the current certificate was assumed to be
|
|
the issuers certificate. In OpenSSL 0.9.6 and later all certificates
|
|
whose subject name matches the issuer name of the current certificate are
|
|
subject to further tests. The relevant authority key identifier components
|
|
of the current certificate (if present) must match the subject key identifier
|
|
(if present) and issuer and serial number of the candidate issuer, in addition
|
|
the keyUsage extension of the candidate issuer (if present) must permit
|
|
certificate signing.
|
|
|
|
The lookup first looks in the list of untrusted certificates and if no match
|
|
is found the remaining lookups are from the trusted certificates. The root CA
|
|
is always looked up in the trusted certificate list: if the certificate to
|
|
verify is a root certificate then an exact match must be found in the trusted
|
|
list.
|
|
|
|
The second operation is to check every untrusted certificate's extensions for
|
|
consistency with the supplied purpose. If the B<-purpose> option is not included
|
|
then no checks are done. The supplied or "leaf" certificate must have extensions
|
|
compatible with the supplied purpose and all other certificates must also be valid
|
|
CA certificates. The precise extensions required are described in more detail in
|
|
the B<CERTIFICATE EXTENSIONS> section of the B<x509> utility.
|
|
|
|
The third operation is to check the trust settings on the root CA. The root
|
|
CA should be trusted for the supplied purpose. For compatibility with previous
|
|
versions of SSLeay and OpenSSL a certificate with no trust settings is considered
|
|
to be valid for all purposes.
|
|
|
|
The final operation is to check the validity of the certificate chain. The validity
|
|
period is checked against the current system time and the notBefore and notAfter
|
|
dates in the certificate. The certificate signatures are also checked at this
|
|
point.
|
|
|
|
If all operations complete successfully then certificate is considered valid. If
|
|
any operation fails then the certificate is not valid.
|
|
|
|
=head1 DIAGNOSTICS
|
|
|
|
When a verify operation fails the output messages can be somewhat cryptic. The
|
|
general form of the error message is:
|
|
|
|
server.pem: /C=AU/ST=Queensland/O=CryptSoft Pty Ltd/CN=Test CA (1024 bit)
|
|
error 24 at 1 depth lookup:invalid CA certificate
|
|
|
|
The first line contains the name of the certificate being verified followed by
|
|
the subject name of the certificate. The second line contains the error number
|
|
and the depth. The depth is number of the certificate being verified when a
|
|
problem was detected starting with zero for the certificate being verified itself
|
|
then 1 for the CA that signed the certificate and so on. Finally a text version
|
|
of the error number is presented.
|
|
|
|
An exhaustive list of the error codes and messages is shown below, this also
|
|
includes the name of the error code as defined in the header file x509_vfy.h
|
|
Some of the error codes are defined but never returned: these are described
|
|
as "unused".
|
|
|
|
=over 4
|
|
|
|
=item B<0 X509_V_OK: ok>
|
|
|
|
the operation was successful.
|
|
|
|
=item B<2 X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT: unable to get issuer certificate>
|
|
|
|
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.
|
|
|
|
=item B<4 X509_V_ERR_UNABLE_TO_DECRYPT_CERT_SIGNATURE: unable to decrypt certificate's signature>
|
|
|
|
the certificate signature could not be decrypted. This means that the actual signature value
|
|
could not be determined rather than it not matching the expected value, this is only
|
|
meaningful for RSA keys.
|
|
|
|
=item B<5 X509_V_ERR_UNABLE_TO_DECRYPT_CRL_SIGNATURE: unable to decrypt CRL's signature>
|
|
|
|
the CRL signature could not be decrypted: this means that the actual signature value
|
|
could not be determined rather than it not matching the expected value. Unused.
|
|
|
|
=item B<6 X509_V_ERR_UNABLE_TO_DECODE_ISSUER_PUBLIC_KEY: unable to decode issuer public key>
|
|
|
|
the public key in the certificate SubjectPublicKeyInfo could not be read.
|
|
|
|
=item B<7 X509_V_ERR_CERT_SIGNATURE_FAILURE: certificate signature failure>
|
|
|
|
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.
|
|
|
|
=item B<9 X509_V_ERR_CERT_NOT_YET_VALID: certificate is not yet valid>
|
|
|
|
the certificate is not yet valid: the notBefore date is after the current time.
|
|
|
|
=item B<10 X509_V_ERR_CERT_HAS_EXPIRED: certificate has expired>
|
|
|
|
the certificate has expired: that is the notAfter date is before the current time.
|
|
|
|
=item B<11 X509_V_ERR_CRL_NOT_YET_VALID: CRL is not yet valid>
|
|
|
|
the CRL is not yet valid.
|
|
|
|
=item B<12 X509_V_ERR_CRL_HAS_EXPIRED: CRL has expired>
|
|
|
|
the CRL has expired.
|
|
|
|
=item B<13 X509_V_ERR_ERROR_IN_CERT_NOT_BEFORE_FIELD: format error in certificate's notBefore field>
|
|
|
|
the certificate notBefore field contains an invalid time.
|
|
|
|
=item B<14 X509_V_ERR_ERROR_IN_CERT_NOT_AFTER_FIELD: format error in certificate's notAfter field>
|
|
|
|
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.
|
|
|
|
=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.
|
|
|
|
=item B<17 X509_V_ERR_OUT_OF_MEM: out of memory>
|
|
|
|
an error occurred trying to allocate memory. This should never happen.
|
|
|
|
=item B<18 X509_V_ERR_DEPTH_ZERO_SELF_SIGNED_CERT: self signed certificate>
|
|
|
|
the passed certificate is self signed and the same certificate cannot be found in the list of
|
|
trusted certificates.
|
|
|
|
=item B<19 X509_V_ERR_SELF_SIGNED_CERT_IN_CHAIN: self signed certificate in certificate chain>
|
|
|
|
the certificate chain could be built up using the untrusted certificates but the root could not
|
|
be found locally.
|
|
|
|
=item B<20 X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY: unable to get local issuer certificate>
|
|
|
|
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>
|
|
|
|
no signatures could be verified because the chain contains only one certificate and it is not
|
|
self signed.
|
|
|
|
=item B<22 X509_V_ERR_CERT_CHAIN_TOO_LONG: certificate chain too long>
|
|
|
|
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.
|
|
|
|
=item B<24 X509_V_ERR_INVALID_CA: invalid CA certificate>
|
|
|
|
a CA certificate is invalid. Either it is not a CA or its extensions are not consistent
|
|
with the supplied purpose.
|
|
|
|
=item B<25 X509_V_ERR_PATH_LENGTH_EXCEEDED: path length constraint exceeded>
|
|
|
|
the basicConstraints pathlength parameter has been exceeded.
|
|
|
|
=item B<26 X509_V_ERR_INVALID_PURPOSE: unsupported certificate purpose>
|
|
|
|
the supplied certificate cannot be used for the specified purpose.
|
|
|
|
=item B<27 X509_V_ERR_CERT_UNTRUSTED: certificate not trusted>
|
|
|
|
the root CA is not marked as trusted for the specified purpose.
|
|
|
|
=item B<28 X509_V_ERR_CERT_REJECTED: certificate rejected>
|
|
|
|
the root CA is marked to reject the specified purpose.
|
|
|
|
=item B<29 X509_V_ERR_SUBJECT_ISSUER_MISMATCH: subject issuer mismatch>
|
|
|
|
the current candidate issuer certificate was rejected because its subject name
|
|
did not match the issuer name of the current certificate. Only displayed when
|
|
the B<-issuer_checks> option is set.
|
|
|
|
=item B<30 X509_V_ERR_AKID_SKID_MISMATCH: authority and subject key identifier mismatch>
|
|
|
|
the current candidate issuer certificate was rejected because its subject key
|
|
identifier was present and did not match the authority key identifier current
|
|
certificate. Only displayed when the B<-issuer_checks> option is set.
|
|
|
|
=item B<31 X509_V_ERR_AKID_ISSUER_SERIAL_MISMATCH: authority and issuer serial number mismatch>
|
|
|
|
the current candidate issuer certificate was rejected because its issuer name
|
|
and serial number was present and did not match the authority key identifier
|
|
of the current certificate. Only displayed when the B<-issuer_checks> option is set.
|
|
|
|
=item B<32 X509_V_ERR_KEYUSAGE_NO_CERTSIGN:key usage does not include certificate signing>
|
|
|
|
the current candidate issuer certificate was rejected because its keyUsage extension
|
|
does not permit certificate signing.
|
|
|
|
=item B<50 X509_V_ERR_APPLICATION_VERIFICATION: application verification failure>
|
|
|
|
an application specific error. Unused.
|
|
|
|
=back
|
|
|
|
=head1 BUGS
|
|
|
|
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
|
|
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<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 HISTORY
|
|
|
|
The -no_alt_chains options was first added to OpenSSL 1.0.1n and 1.0.2b.
|
|
|
|
=cut
|