verify(1ssl)verify(1ssl)NAMEverify - Utility to verify certificates
SYNOPSIS
openssl verify [-CApath directory] [-CAfile filename] [-purpose pur‐
pose] [-untrusted filename] [-help] [-issuer_checks] [-verbose] [-]
[certificates]
DESCRIPTIONOPTIONS
A directory of trusted certificates. The certificates should have names
of the form hash.0 or have symbolic links to them of this form. Under
UNIX the c_rehash script will automatically create symbolic links to a
directory of certificates. (Hash is the hashed certificate subject
name. See the -hash option of the x509 command.) A file of trusted
certificates. The file should contain multiple certificates in PEM for‐
mat concatenated together. A file of untrusted certificates. The file
should contain multiple certificates The intended use for the certifi‐
cate. Without this option no chain verification will be done. Currently
accepted uses are sslclient, sslserver, nssslserver, smimesign,
smimeencrypt. See the Verify Operation section for more information.
Prints out a usage message. Prints extra information about the opera‐
tions being performed. Prints 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. Dur‐
ing the normal verify process, several rejections may take place.
Marks the last option. All arguments following this are assumed to be
certificate files. This is useful if the first certificate filename
begins with a -. 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.
DESCRIPTION
The verify utility verifies certificate chains. It uses the same func‐
tions as the internal SSL and S/MIME verification. However, there is
one crucial difference between the verify operations performed by the
verify program. Wherever possible an attempt is made to continue after
an error. Usually 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.
First, a certificate chain is built, starting from the supplied cer‐
tificate and ending in the root CA. It is an error if the whole chain
cannot be built. The chain is built by looking up the issuer's cer‐
tificate 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 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 issuer's certificate. In OpenSSL 0.9.6 and later all certifi‐
cates whose subject name matches the issuer name of the current cer‐
tificate 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 -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 Certificate Extensions section of the 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 opera‐
tion 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 the certificate is consid‐
ered valid. If any operation fails then the certificate is not valid.
RESTRICTIONS
Although the issuer checks are a considerably 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 -CAfile option) or a directory (as specified by -CApath. If
they occur in both then only the certificates in the file will be rec‐
ognized.
Previous versions of OpenSSL assume certificates with matching subject
name are identical and mishandled them.
ERRORS
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 fol‐
lowed by the subject name of the certificate. The second line contains
the error number and the depth. The depth is the number of the certifi‐
cate 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.
A 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. The operation was successful. The
issuer certificate could not be found. This occurs if the issuer cer‐
tificate of an untrusted certificate cannot be found. The CRL of a
certificate could not be found. Unused. 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. 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. The
public key in the certificate SubjectPublicKeyInfo could not be read.
The signature of the certificate is invalid. The signature of the cer‐
tificate is invalid. Unused. The certificate is not yet valid. The
notBefore date is after the current time. The certificate has expired.
The notAfter date is before the current time. The CRL is not yet
valid. Unused. The certificate has expired. The notAfter date is
before the current time. The CRL is not yet valid. Unused. The CRL
has expired. Unused. The certificate notBefore field contains an
invalid time. The certificate notAfter field contains an invalid time.
The CRL lastUpdate field contains an invalid time. Unused. The CRL
nextUpdate field contains an invalid time. Unused. An error occurred
trying to allocate memory. This should never happen. The passed cer‐
tificate is self signed and the same certificate cannot be found in the
list of trusted certificates. The certificate chain could be built up
using the untrusted certificates but the root could not be found
locally. The issuer certificate of a locally looked up certificate
could not be found. This normally means the list of trusted certifi‐
cates is not complete. No signatures could be verified because the
chain contains only one certificate and it is not self signed. The
certificate chain length is greater than the supplied maximum depth.
Unused. The certificate has been revoked. Unused. A CA certificate is
invalid. Either it is not a CA or its extensions are not consistent
with the supplied purpose. The basicConstraints pathlength parameter
has been exceeded. The supplied certificate cannot be used for the
specified purpose. The root CA is not marked as trusted for the speci‐
fied purpose. The root CA is marked to reject the specified purpose.
The current candidate issuer certificate was rejected because its sub‐
ject name did not match the issuer name of the current certificate.
This is only displayed when the -issuer_checks option is set. The cur‐
rent candidate issuer certificate was rejected because its subject key
identifier was present and did not match the authority key identifier
current certificate. This is only displayed when the -issuer_checks
option is set. 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. This is only
displayed when the -issuer_checks option is set. The current candidate
issuer certificate was rejected because its keyUsage extension does not
permit certificate signing. An application specific error. Unused.
SEE ALSO
Commands: x509(1ssl)verify(1ssl)
