1=pod 2 3=head1 NAME 4 5verify - Utility to verify certificates. 6 7=head1 SYNOPSIS 8 9B<openssl> B<verify> 10[B<-CApath directory>] 11[B<-CAfile file>] 12[B<-purpose purpose>] 13[B<-untrusted file>] 14[B<-help>] 15[B<-issuer_checks>] 16[B<-verbose>] 17[B<->] 18[certificates] 19 20 21=head1 DESCRIPTION 22 23The B<verify> command verifies certificate chains. 24 25=head1 COMMAND OPTIONS 26 27=over 4 28 29=item B<-CApath directory> 30 31A directory of trusted certificates. The certificates should have names 32of the form: hash.0 or have symbolic links to them of this 33form ("hash" is the hashed certificate subject name: see the B<-hash> option 34of the B<x509> utility). Under Unix the B<c_rehash> script will automatically 35create symbolic links to a directory of certificates. 36 37=item B<-CAfile file> 38 39A file of trusted certificates. The file should contain multiple certificates 40in PEM format concatenated together. 41 42=item B<-untrusted file> 43 44A file of untrusted certificates. The file should contain multiple certificates 45 46=item B<-purpose purpose> 47 48the intended use for the certificate. Without this option no chain verification 49will be done. Currently accepted uses are B<sslclient>, B<sslserver>, 50B<nssslserver>, B<smimesign>, B<smimeencrypt>. See the B<VERIFY OPERATION> 51section for more information. 52 53=item B<-help> 54 55prints out a usage message. 56 57=item B<-verbose> 58 59print extra information about the operations being performed. 60 61=item B<-issuer_checks> 62 63print out diagnostics relating to searches for the issuer certificate 64of the current certificate. This shows why each candidate issuer 65certificate was rejected. However the presence of rejection messages 66does not itself imply that anything is wrong: during the normal 67verify process several rejections may take place. 68 69=item B<-> 70 71marks the last option. All arguments following this are assumed to be 72certificate files. This is useful if the first certificate filename begins 73with a B<->. 74 75=item B<certificates> 76 77one or more certificates to verify. If no certificate filenames are included 78then an attempt is made to read a certificate from standard input. They should 79all be in PEM format. 80 81 82=back 83 84=head1 VERIFY OPERATION 85 86The B<verify> program uses the same functions as the internal SSL and S/MIME 87verification, therefore this description applies to these verify operations 88too. 89 90There is one crucial difference between the verify operations performed 91by the B<verify> program: wherever possible an attempt is made to continue 92after an error whereas normally the verify operation would halt on the 93first error. This allows all the problems with a certificate chain to be 94determined. 95 96The verify operation consists of a number of separate steps. 97 98Firstly a certificate chain is built up starting from the supplied certificate 99and ending in the root CA. It is an error if the whole chain cannot be built 100up. The chain is built up by looking up the issuers certificate of the current 101certificate. If a certificate is found which is its own issuer it is assumed 102to be the root CA. 103 104The process of 'looking up the issuers certificate' itself involves a number 105of steps. In versions of OpenSSL before 0.9.5a the first certificate whose 106subject name matched the issuer of the current certificate was assumed to be 107the issuers certificate. In OpenSSL 0.9.6 and later all certificates 108whose subject name matches the issuer name of the current certificate are 109subject to further tests. The relevant authority key identifier components 110of the current certificate (if present) must match the subject key identifier 111(if present) and issuer and serial number of the candidate issuer, in addition 112the keyUsage extension of the candidate issuer (if present) must permit 113certificate signing. 114 115The lookup first looks in the list of untrusted certificates and if no match 116is found the remaining lookups are from the trusted certificates. The root CA 117is always looked up in the trusted certificate list: if the certificate to 118verify is a root certificate then an exact match must be found in the trusted 119list. 120 121The second operation is to check every untrusted certificate's extensions for 122consistency with the supplied purpose. If the B<-purpose> option is not included 123then no checks are done. The supplied or "leaf" certificate must have extensions 124compatible with the supplied purpose and all other certificates must also be valid 125CA certificates. The precise extensions required are described in more detail in 126the B<CERTIFICATE EXTENSIONS> section of the B<x509> utility. 127 128The third operation is to check the trust settings on the root CA. The root 129CA should be trusted for the supplied purpose. For compatibility with previous 130versions of SSLeay and OpenSSL a certificate with no trust settings is considered 131to be valid for all purposes. 132 133The final operation is to check the validity of the certificate chain. The validity 134period is checked against the current system time and the notBefore and notAfter 135dates in the certificate. The certificate signatures are also checked at this 136point. 137 138If all operations complete successfully then certificate is considered valid. If 139any operation fails then the certificate is not valid. 140 141=head1 DIAGNOSTICS 142 143When a verify operation fails the output messages can be somewhat cryptic. The 144general form of the error message is: 145 146 server.pem: /C=AU/ST=Queensland/O=CryptSoft Pty Ltd/CN=Test CA (1024 bit) 147 error 24 at 1 depth lookup:invalid CA certificate 148 149The first line contains the name of the certificate being verified followed by 150the subject name of the certificate. The second line contains the error number 151and the depth. The depth is number of the certificate being verified when a 152problem was detected starting with zero for the certificate being verified itself 153then 1 for the CA that signed the certificate and so on. Finally a text version 154of the error number is presented. 155 156An exhaustive list of the error codes and messages is shown below, this also 157includes the name of the error code as defined in the header file x509_vfy.h 158Some of the error codes are defined but never returned: these are described 159as "unused". 160 161=over 4 162 163=item B<0 X509_V_OK: ok> 164 165the operation was successful. 166 167=item B<2 X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT: unable to get issuer certificate> 168 169the issuer certificate could not be found: this occurs if the issuer certificate 170of an untrusted certificate cannot be found. 171 172=item B<3 X509_V_ERR_UNABLE_TO_GET_CRL unable to get certificate CRL> 173 174the CRL of a certificate could not be found. Unused. 175 176=item B<4 X509_V_ERR_UNABLE_TO_DECRYPT_CERT_SIGNATURE: unable to decrypt certificate's signature> 177 178the certificate signature could not be decrypted. This means that the actual signature value 179could not be determined rather than it not matching the expected value, this is only 180meaningful for RSA keys. 181 182=item B<5 X509_V_ERR_UNABLE_TO_DECRYPT_CRL_SIGNATURE: unable to decrypt CRL's signature> 183 184the CRL signature could not be decrypted: this means that the actual signature value 185could not be determined rather than it not matching the expected value. Unused. 186 187=item B<6 X509_V_ERR_UNABLE_TO_DECODE_ISSUER_PUBLIC_KEY: unable to decode issuer public key> 188 189the public key in the certificate SubjectPublicKeyInfo could not be read. 190 191=item B<7 X509_V_ERR_CERT_SIGNATURE_FAILURE: certificate signature failure> 192 193the signature of the certificate is invalid. 194 195=item B<8 X509_V_ERR_CRL_SIGNATURE_FAILURE: CRL signature failure> 196 197the signature of the certificate is invalid. Unused. 198 199=item B<9 X509_V_ERR_CERT_NOT_YET_VALID: certificate is not yet valid> 200 201the certificate is not yet valid: the notBefore date is after the current time. 202 203=item B<10 X509_V_ERR_CERT_HAS_EXPIRED: certificate has expired> 204 205the certificate has expired: that is the notAfter date is before the current time. 206 207=item B<11 X509_V_ERR_CRL_NOT_YET_VALID: CRL is not yet valid> 208 209the CRL is not yet valid. Unused. 210 211=item B<12 X509_V_ERR_CRL_HAS_EXPIRED: CRL has expired> 212 213the CRL has expired. Unused. 214 215=item B<13 X509_V_ERR_ERROR_IN_CERT_NOT_BEFORE_FIELD: format error in certificate's notBefore field> 216 217the certificate notBefore field contains an invalid time. 218 219=item B<14 X509_V_ERR_ERROR_IN_CERT_NOT_AFTER_FIELD: format error in certificate's notAfter field> 220 221the certificate notAfter field contains an invalid time. 222 223=item B<15 X509_V_ERR_ERROR_IN_CRL_LAST_UPDATE_FIELD: format error in CRL's lastUpdate field> 224 225the CRL lastUpdate field contains an invalid time. Unused. 226 227=item B<16 X509_V_ERR_ERROR_IN_CRL_NEXT_UPDATE_FIELD: format error in CRL's nextUpdate field> 228 229the CRL nextUpdate field contains an invalid time. Unused. 230 231=item B<17 X509_V_ERR_OUT_OF_MEM: out of memory> 232 233an error occurred trying to allocate memory. This should never happen. 234 235=item B<18 X509_V_ERR_DEPTH_ZERO_SELF_SIGNED_CERT: self signed certificate> 236 237the passed certificate is self signed and the same certificate cannot be found in the list of 238trusted certificates. 239 240=item B<19 X509_V_ERR_SELF_SIGNED_CERT_IN_CHAIN: self signed certificate in certificate chain> 241 242the certificate chain could be built up using the untrusted certificates but the root could not 243be found locally. 244 245=item B<20 X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY: unable to get local issuer certificate> 246 247the issuer certificate of a locally looked up certificate could not be found. This normally means 248the list of trusted certificates is not complete. 249 250=item B<21 X509_V_ERR_UNABLE_TO_VERIFY_LEAF_SIGNATURE: unable to verify the first certificate> 251 252no signatures could be verified because the chain contains only one certificate and it is not 253self signed. 254 255=item B<22 X509_V_ERR_CERT_CHAIN_TOO_LONG: certificate chain too long> 256 257the certificate chain length is greater than the supplied maximum depth. Unused. 258 259=item B<23 X509_V_ERR_CERT_REVOKED: certificate revoked> 260 261the certificate has been revoked. Unused. 262 263=item B<24 X509_V_ERR_INVALID_CA: invalid CA certificate> 264 265a CA certificate is invalid. Either it is not a CA or its extensions are not consistent 266with the supplied purpose. 267 268=item B<25 X509_V_ERR_PATH_LENGTH_EXCEEDED: path length constraint exceeded> 269 270the basicConstraints pathlength parameter has been exceeded. 271 272=item B<26 X509_V_ERR_INVALID_PURPOSE: unsupported certificate purpose> 273 274the supplied certificate cannot be used for the specified purpose. 275 276=item B<27 X509_V_ERR_CERT_UNTRUSTED: certificate not trusted> 277 278the root CA is not marked as trusted for the specified purpose. 279 280=item B<28 X509_V_ERR_CERT_REJECTED: certificate rejected> 281 282the root CA is marked to reject the specified purpose. 283 284=item B<29 X509_V_ERR_SUBJECT_ISSUER_MISMATCH: subject issuer mismatch> 285 286the current candidate issuer certificate was rejected because its subject name 287did not match the issuer name of the current certificate. Only displayed when 288the B<-issuer_checks> option is set. 289 290=item B<30 X509_V_ERR_AKID_SKID_MISMATCH: authority and subject key identifier mismatch> 291 292the current candidate issuer certificate was rejected because its subject key 293identifier was present and did not match the authority key identifier current 294certificate. Only displayed when the B<-issuer_checks> option is set. 295 296=item B<31 X509_V_ERR_AKID_ISSUER_SERIAL_MISMATCH: authority and issuer serial number mismatch> 297 298the current candidate issuer certificate was rejected because its issuer name 299and serial number was present and did not match the authority key identifier 300of the current certificate. Only displayed when the B<-issuer_checks> option is set. 301 302=item B<32 X509_V_ERR_KEYUSAGE_NO_CERTSIGN:key usage does not include certificate signing> 303 304the current candidate issuer certificate was rejected because its keyUsage extension 305does not permit certificate signing. 306 307=item B<50 X509_V_ERR_APPLICATION_VERIFICATION: application verification failure> 308 309an application specific error. Unused. 310 311=back 312 313=head1 BUGS 314 315Although the issuer checks are a considerably improvement over the old technique they still 316suffer from limitations in the underlying X509_LOOKUP API. One consequence of this is that 317trusted certificates with matching subject name must either appear in a file (as specified by the 318B<-CAfile> option) or a directory (as specified by B<-CApath>. If they occur in both then only 319the certificates in the file will be recognised. 320 321Previous versions of OpenSSL assume certificates with matching subject name are identical and 322mishandled them. 323 324=head1 SEE ALSO 325 326L<x509(1)|x509(1)> 327 328=cut 329