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