]>
Commit | Line | Data |
---|---|---|
13938ace DSH |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
fa1194d3 | 5 | verify - Utility to verify certificates. |
13938ace DSH |
6 | |
7 | =head1 SYNOPSIS | |
8 | ||
9 | B<openssl> B<verify> | |
13938ace | 10 | [B<-CAfile file>] |
2866441a HK |
11 | [B<-CApath directory>] |
12 | [B<-attime timestamp>] | |
cd028c8e | 13 | [B<-check_ss_sig>] |
e5fa864f DSH |
14 | [B<-crl_check>] |
15 | [B<-crl_check_all>] | |
e5fa864f | 16 | [B<-explicit_policy>] |
e5fa864f | 17 | [B<-extended_crl>] |
13938ace | 18 | [B<-help>] |
2866441a HK |
19 | [B<-ignore_critical>] |
20 | [B<-inhibit_any>] | |
21 | [B<-inhibit_map>] | |
709e8595 | 22 | [B<-issuer_checks>] |
cd028c8e | 23 | [B<-partial_chain>] |
2866441a HK |
24 | [B<-policy arg>] |
25 | [B<-policy_check>] | |
26 | [B<-policy_print>] | |
27 | [B<-purpose purpose>] | |
cd028c8e HK |
28 | [B<-suiteB_128>] |
29 | [B<-suiteB_128_only>] | |
30 | [B<-suiteB_192>] | |
2866441a HK |
31 | [B<-trusted_first>] |
32 | [B<-untrusted file>] | |
33 | [B<-use_deltas>] | |
13938ace | 34 | [B<-verbose>] |
cd028c8e HK |
35 | [B<-verify_depth num>] |
36 | [B<-verify_email email>] | |
37 | [B<-verify_hostname hostname>] | |
38 | [B<-verify_ip ip>] | |
39 | [B<-verify_name name>] | |
2866441a | 40 | [B<-x509_strict>] |
13938ace DSH |
41 | [B<->] |
42 | [certificates] | |
43 | ||
44 | ||
45 | =head1 DESCRIPTION | |
46 | ||
47 | The B<verify> command verifies certificate chains. | |
48 | ||
49 | =head1 COMMAND OPTIONS | |
50 | ||
51 | =over 4 | |
52 | ||
2866441a HK |
53 | =item B<-CAfile file> |
54 | ||
55 | A file of trusted certificates. The file should contain multiple certificates | |
56 | in PEM format concatenated together. | |
57 | ||
13938ace DSH |
58 | =item B<-CApath directory> |
59 | ||
60 | A directory of trusted certificates. The certificates should have names | |
61 | of the form: hash.0 or have symbolic links to them of this | |
62 | form ("hash" is the hashed certificate subject name: see the B<-hash> option | |
63 | of the B<x509> utility). Under Unix the B<c_rehash> script will automatically | |
64 | create symbolic links to a directory of certificates. | |
65 | ||
2866441a | 66 | =item B<-attime timestamp> |
13938ace | 67 | |
2866441a HK |
68 | Perform validation checks using time specified by B<timestamp> and not |
69 | current system time. B<timestamp> is the number of seconds since | |
70 | 01.01.1970 (UNIX time). | |
13938ace | 71 | |
2866441a | 72 | =item B<-check_ss_sig> |
13938ace | 73 | |
2866441a HK |
74 | Verify the signature on the self-signed root CA. This is disabled by default |
75 | because it doesn't add any security. | |
13938ace | 76 | |
2866441a | 77 | =item B<-crl_check> |
6d3d5793 | 78 | |
2866441a HK |
79 | Checks end entity certificate validity by attempting to look up a valid CRL. |
80 | If a valid CRL cannot be found an error occurs. | |
6d3d5793 | 81 | |
2866441a | 82 | =item B<-crl_check_all> |
13938ace | 83 | |
2866441a HK |
84 | Checks the validity of B<all> certificates in the chain by attempting |
85 | to look up valid CRLs. | |
86 | ||
87 | =item B<-explicit_policy> | |
88 | ||
89 | Set policy variable require-explicit-policy (see RFC5280). | |
90 | ||
91 | =item B<-extended_crl> | |
92 | ||
93 | Enable extended CRL features such as indirect CRLs and alternate CRL | |
94 | signing keys. | |
13938ace DSH |
95 | |
96 | =item B<-help> | |
97 | ||
3a778a29 | 98 | Print out a usage message. |
13938ace | 99 | |
2866441a | 100 | =item B<-ignore_critical> |
13938ace | 101 | |
2866441a HK |
102 | Normally if an unhandled critical extension is present which is not |
103 | supported by OpenSSL the certificate is rejected (as required by RFC5280). | |
104 | If this option is set critical extensions are ignored. | |
105 | ||
106 | =item B<-inhibit_any> | |
107 | ||
108 | Set policy variable inhibit-any-policy (see RFC5280). | |
109 | ||
110 | =item B<-inhibit_map> | |
111 | ||
112 | Set policy variable inhibit-policy-mapping (see RFC5280). | |
13938ace | 113 | |
709e8595 DSH |
114 | =item B<-issuer_checks> |
115 | ||
3a778a29 BL |
116 | Print out diagnostics relating to searches for the issuer certificate of the |
117 | current certificate. This shows why each candidate issuer certificate was | |
118 | rejected. The presence of rejection messages does not itself imply that | |
119 | anything is wrong; during the normal verification process, several | |
120 | rejections may take place. | |
709e8595 | 121 | |
2866441a | 122 | =item B<-partial_chain> |
9ed03faa | 123 | |
2866441a | 124 | Allow partial certificate chain if at least one certificate is in trusted store. |
9ed03faa | 125 | |
e5fa864f DSH |
126 | =item B<-policy arg> |
127 | ||
3a778a29 BL |
128 | Enable policy processing and add B<arg> to the user-initial-policy-set (see |
129 | RFC5280). The policy B<arg> can be an object name an OID in numeric form. | |
130 | This argument can appear more than once. | |
e5fa864f DSH |
131 | |
132 | =item B<-policy_check> | |
133 | ||
134 | Enables certificate policy processing. | |
135 | ||
e5fa864f DSH |
136 | =item B<-policy_print> |
137 | ||
3a778a29 | 138 | Print out diagnostics related to policy processing. |
e5fa864f | 139 | |
2866441a | 140 | =item B<-purpose purpose> |
e5fa864f | 141 | |
2866441a HK |
142 | The intended use for the certificate. If this option is not specified, |
143 | B<verify> will not consider certificate purpose during chain verification. | |
144 | Currently accepted uses are B<sslclient>, B<sslserver>, B<nssslserver>, | |
145 | B<smimesign>, B<smimeencrypt>. See the B<VERIFY OPERATION> section for more | |
146 | information. | |
e5fa864f | 147 | |
2866441a | 148 | =item B<-suiteB_128_only>, B<-suiteB_128>, B<-suiteB_192> |
e5fa864f | 149 | |
2866441a HK |
150 | enable the Suite B mode operation at 128 bit Level of Security, 128 bit or |
151 | 192 bit, or only 192 bit Level of Security respectively. | |
152 | See RFC6460 for details. In particular the supported signature algorithms are | |
153 | reduced to support only ECDSA and SHA256 or SHA384 and only the elliptic curves | |
154 | P-256 and P-384. | |
e5fa864f | 155 | |
2866441a | 156 | =item B<-trusted_first> |
e5fa864f | 157 | |
2866441a HK |
158 | Use certificates in CA file or CA directory before certificates in untrusted |
159 | file when building the trust chain to verify certificates. | |
160 | This is mainly useful in environments with Bridge CA or Cross-Certified CAs. | |
e5fa864f | 161 | |
2866441a | 162 | =item B<-untrusted file> |
e5fa864f | 163 | |
2866441a HK |
164 | A file of untrusted certificates. The file should contain multiple certificates |
165 | in PEM format concatenated together. | |
e5fa864f DSH |
166 | |
167 | =item B<-use_deltas> | |
168 | ||
169 | Enable support for delta CRLs. | |
170 | ||
2866441a | 171 | =item B<-verbose> |
cd028c8e | 172 | |
2866441a | 173 | Print extra information about the operations being performed. |
cd028c8e HK |
174 | |
175 | =item B<-verify_depth num> | |
176 | ||
177 | Limit the maximum depth of the certificate chain to B<num> certificates. | |
178 | ||
179 | =item B<-verify_email email> | |
180 | ||
181 | Verify if the B<email> matches the email address in Subject Alternative Name or | |
182 | the email the subject Distinguished Name. | |
183 | ||
184 | =item B<-verify_hostname hostname> | |
185 | ||
186 | Verify if the B<hostname> matches DNS name in Subject Alternative Name or | |
187 | Common Name in the subject certificate. | |
188 | ||
189 | =item B<-verify_ip ip> | |
190 | ||
191 | Verify if the B<ip> matches the IP address in Subject Alternative Name of | |
192 | the subject certificate. | |
193 | ||
194 | =item B<-verify_name name> | |
195 | ||
196 | Use default verification options like trust model and required certificate | |
197 | policies identified by B<name>. | |
198 | Supported usages include: default, pkcs7, smime_sign, ssl_client, ssl_server. | |
199 | ||
2866441a HK |
200 | =item B<-x509_strict> |
201 | ||
202 | For strict X.509 compliance, disable non-compliant workarounds for broken | |
203 | certificates. | |
204 | ||
13938ace DSH |
205 | =item B<-> |
206 | ||
3a778a29 | 207 | Indicates the last option. All arguments following this are assumed to be |
7b418a47 DSH |
208 | certificate files. This is useful if the first certificate filename begins |
209 | with a B<->. | |
13938ace DSH |
210 | |
211 | =item B<certificates> | |
212 | ||
3a778a29 BL |
213 | One or more certificates to verify. If no certificates are given, B<verify> |
214 | will attempt to read a certificate from standard input. Certificates must be | |
215 | in PEM format. | |
13938ace DSH |
216 | |
217 | =back | |
218 | ||
219 | =head1 VERIFY OPERATION | |
220 | ||
221 | The B<verify> program uses the same functions as the internal SSL and S/MIME | |
222 | verification, therefore this description applies to these verify operations | |
223 | too. | |
224 | ||
225 | There is one crucial difference between the verify operations performed | |
226 | by the B<verify> program: wherever possible an attempt is made to continue | |
227 | after an error whereas normally the verify operation would halt on the | |
228 | first error. This allows all the problems with a certificate chain to be | |
229 | determined. | |
230 | ||
231 | The verify operation consists of a number of separate steps. | |
232 | ||
233 | Firstly a certificate chain is built up starting from the supplied certificate | |
234 | and ending in the root CA. It is an error if the whole chain cannot be built | |
709e8595 DSH |
235 | up. The chain is built up by looking up the issuers certificate of the current |
236 | certificate. If a certificate is found which is its own issuer it is assumed | |
237 | to be the root CA. | |
238 | ||
239 | The process of 'looking up the issuers certificate' itself involves a number | |
240 | of steps. In versions of OpenSSL before 0.9.5a the first certificate whose | |
241 | subject name matched the issuer of the current certificate was assumed to be | |
242 | the issuers certificate. In OpenSSL 0.9.6 and later all certificates | |
243 | whose subject name matches the issuer name of the current certificate are | |
244 | subject to further tests. The relevant authority key identifier components | |
245 | of the current certificate (if present) must match the subject key identifier | |
246 | (if present) and issuer and serial number of the candidate issuer, in addition | |
247 | the keyUsage extension of the candidate issuer (if present) must permit | |
248 | certificate signing. | |
249 | ||
13938ace | 250 | The lookup first looks in the list of untrusted certificates and if no match |
19d2bb57 | 251 | is found the remaining lookups are from the trusted certificates. The root CA |
13938ace DSH |
252 | is always looked up in the trusted certificate list: if the certificate to |
253 | verify is a root certificate then an exact match must be found in the trusted | |
254 | list. | |
255 | ||
256 | The second operation is to check every untrusted certificate's extensions for | |
257 | consistency with the supplied purpose. If the B<-purpose> option is not included | |
258 | then no checks are done. The supplied or "leaf" certificate must have extensions | |
259 | compatible with the supplied purpose and all other certificates must also be valid | |
260 | CA certificates. The precise extensions required are described in more detail in | |
7b418a47 | 261 | the B<CERTIFICATE EXTENSIONS> section of the B<x509> utility. |
13938ace DSH |
262 | |
263 | The third operation is to check the trust settings on the root CA. The root | |
19d2bb57 | 264 | CA should be trusted for the supplied purpose. For compatibility with previous |
13938ace DSH |
265 | versions of SSLeay and OpenSSL a certificate with no trust settings is considered |
266 | to be valid for all purposes. | |
267 | ||
268 | The final operation is to check the validity of the certificate chain. The validity | |
269 | period is checked against the current system time and the notBefore and notAfter | |
270 | dates in the certificate. The certificate signatures are also checked at this | |
271 | point. | |
272 | ||
273 | If all operations complete successfully then certificate is considered valid. If | |
274 | any operation fails then the certificate is not valid. | |
275 | ||
7b418a47 DSH |
276 | =head1 DIAGNOSTICS |
277 | ||
278 | When a verify operation fails the output messages can be somewhat cryptic. The | |
279 | general form of the error message is: | |
280 | ||
281 | server.pem: /C=AU/ST=Queensland/O=CryptSoft Pty Ltd/CN=Test CA (1024 bit) | |
282 | error 24 at 1 depth lookup:invalid CA certificate | |
283 | ||
284 | The first line contains the name of the certificate being verified followed by | |
285 | the subject name of the certificate. The second line contains the error number | |
286 | and the depth. The depth is number of the certificate being verified when a | |
287 | problem was detected starting with zero for the certificate being verified itself | |
288 | then 1 for the CA that signed the certificate and so on. Finally a text version | |
289 | of the error number is presented. | |
290 | ||
291 | An exhaustive list of the error codes and messages is shown below, this also | |
292 | includes the name of the error code as defined in the header file x509_vfy.h | |
293 | Some of the error codes are defined but never returned: these are described | |
294 | as "unused". | |
295 | ||
296 | =over 4 | |
297 | ||
298 | =item B<0 X509_V_OK: ok> | |
299 | ||
300 | the operation was successful. | |
301 | ||
302 | =item B<2 X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT: unable to get issuer certificate> | |
303 | ||
7d3d1788 DSH |
304 | the issuer certificate of a looked up certificate could not be found. This |
305 | normally means the list of trusted certificates is not complete. | |
7b418a47 | 306 | |
7c1722c6 | 307 | =item B<3 X509_V_ERR_UNABLE_TO_GET_CRL: unable to get certificate CRL> |
7b418a47 | 308 | |
db50661f | 309 | the CRL of a certificate could not be found. |
7b418a47 DSH |
310 | |
311 | =item B<4 X509_V_ERR_UNABLE_TO_DECRYPT_CERT_SIGNATURE: unable to decrypt certificate's signature> | |
312 | ||
313 | the certificate signature could not be decrypted. This means that the actual signature value | |
314 | could not be determined rather than it not matching the expected value, this is only | |
315 | meaningful for RSA keys. | |
316 | ||
19d2bb57 | 317 | =item B<5 X509_V_ERR_UNABLE_TO_DECRYPT_CRL_SIGNATURE: unable to decrypt CRL's signature> |
7b418a47 DSH |
318 | |
319 | the CRL signature could not be decrypted: this means that the actual signature value | |
320 | could not be determined rather than it not matching the expected value. Unused. | |
321 | ||
322 | =item B<6 X509_V_ERR_UNABLE_TO_DECODE_ISSUER_PUBLIC_KEY: unable to decode issuer public key> | |
323 | ||
324 | the public key in the certificate SubjectPublicKeyInfo could not be read. | |
325 | ||
326 | =item B<7 X509_V_ERR_CERT_SIGNATURE_FAILURE: certificate signature failure> | |
327 | ||
328 | the signature of the certificate is invalid. | |
329 | ||
330 | =item B<8 X509_V_ERR_CRL_SIGNATURE_FAILURE: CRL signature failure> | |
331 | ||
db50661f | 332 | the signature of the certificate is invalid. |
7b418a47 DSH |
333 | |
334 | =item B<9 X509_V_ERR_CERT_NOT_YET_VALID: certificate is not yet valid> | |
335 | ||
336 | the certificate is not yet valid: the notBefore date is after the current time. | |
337 | ||
e1c279b6 | 338 | =item B<10 X509_V_ERR_CERT_HAS_EXPIRED: certificate has expired> |
7b418a47 | 339 | |
e1c279b6 | 340 | the certificate has expired: that is the notAfter date is before the current time. |
7b418a47 | 341 | |
e1c279b6 | 342 | =item B<11 X509_V_ERR_CRL_NOT_YET_VALID: CRL is not yet valid> |
7b418a47 | 343 | |
db50661f | 344 | the CRL is not yet valid. |
7b418a47 DSH |
345 | |
346 | =item B<12 X509_V_ERR_CRL_HAS_EXPIRED: CRL has expired> | |
347 | ||
db50661f | 348 | the CRL has expired. |
7b418a47 DSH |
349 | |
350 | =item B<13 X509_V_ERR_ERROR_IN_CERT_NOT_BEFORE_FIELD: format error in certificate's notBefore field> | |
351 | ||
352 | the certificate notBefore field contains an invalid time. | |
13938ace | 353 | |
7b418a47 DSH |
354 | =item B<14 X509_V_ERR_ERROR_IN_CERT_NOT_AFTER_FIELD: format error in certificate's notAfter field> |
355 | ||
356 | the certificate notAfter field contains an invalid time. | |
357 | ||
358 | =item B<15 X509_V_ERR_ERROR_IN_CRL_LAST_UPDATE_FIELD: format error in CRL's lastUpdate field> | |
359 | ||
db50661f | 360 | the CRL lastUpdate field contains an invalid time. |
7b418a47 DSH |
361 | |
362 | =item B<16 X509_V_ERR_ERROR_IN_CRL_NEXT_UPDATE_FIELD: format error in CRL's nextUpdate field> | |
363 | ||
db50661f | 364 | the CRL nextUpdate field contains an invalid time. |
7b418a47 DSH |
365 | |
366 | =item B<17 X509_V_ERR_OUT_OF_MEM: out of memory> | |
367 | ||
19d2bb57 | 368 | an error occurred trying to allocate memory. This should never happen. |
7b418a47 DSH |
369 | |
370 | =item B<18 X509_V_ERR_DEPTH_ZERO_SELF_SIGNED_CERT: self signed certificate> | |
371 | ||
372 | the passed certificate is self signed and the same certificate cannot be found in the list of | |
373 | trusted certificates. | |
374 | ||
375 | =item B<19 X509_V_ERR_SELF_SIGNED_CERT_IN_CHAIN: self signed certificate in certificate chain> | |
376 | ||
377 | the certificate chain could be built up using the untrusted certificates but the root could not | |
378 | be found locally. | |
379 | ||
380 | =item B<20 X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY: unable to get local issuer certificate> | |
381 | ||
7d3d1788 DSH |
382 | the issuer certificate could not be found: this occurs if the issuer |
383 | certificate of an untrusted certificate cannot be found. | |
7b418a47 DSH |
384 | |
385 | =item B<21 X509_V_ERR_UNABLE_TO_VERIFY_LEAF_SIGNATURE: unable to verify the first certificate> | |
386 | ||
387 | no signatures could be verified because the chain contains only one certificate and it is not | |
388 | self signed. | |
389 | ||
390 | =item B<22 X509_V_ERR_CERT_CHAIN_TOO_LONG: certificate chain too long> | |
391 | ||
392 | the certificate chain length is greater than the supplied maximum depth. Unused. | |
393 | ||
394 | =item B<23 X509_V_ERR_CERT_REVOKED: certificate revoked> | |
395 | ||
db50661f | 396 | the certificate has been revoked. |
7b418a47 DSH |
397 | |
398 | =item B<24 X509_V_ERR_INVALID_CA: invalid CA certificate> | |
399 | ||
400 | a CA certificate is invalid. Either it is not a CA or its extensions are not consistent | |
401 | with the supplied purpose. | |
402 | ||
403 | =item B<25 X509_V_ERR_PATH_LENGTH_EXCEEDED: path length constraint exceeded> | |
404 | ||
405 | the basicConstraints pathlength parameter has been exceeded. | |
406 | ||
407 | =item B<26 X509_V_ERR_INVALID_PURPOSE: unsupported certificate purpose> | |
408 | ||
409 | the supplied certificate cannot be used for the specified purpose. | |
410 | ||
411 | =item B<27 X509_V_ERR_CERT_UNTRUSTED: certificate not trusted> | |
412 | ||
413 | the root CA is not marked as trusted for the specified purpose. | |
414 | ||
415 | =item B<28 X509_V_ERR_CERT_REJECTED: certificate rejected> | |
416 | ||
417 | the root CA is marked to reject the specified purpose. | |
418 | ||
709e8595 DSH |
419 | =item B<29 X509_V_ERR_SUBJECT_ISSUER_MISMATCH: subject issuer mismatch> |
420 | ||
421 | the current candidate issuer certificate was rejected because its subject name | |
422 | did not match the issuer name of the current certificate. Only displayed when | |
423 | the B<-issuer_checks> option is set. | |
424 | ||
425 | =item B<30 X509_V_ERR_AKID_SKID_MISMATCH: authority and subject key identifier mismatch> | |
426 | ||
427 | the current candidate issuer certificate was rejected because its subject key | |
428 | identifier was present and did not match the authority key identifier current | |
429 | certificate. Only displayed when the B<-issuer_checks> option is set. | |
430 | ||
431 | =item B<31 X509_V_ERR_AKID_ISSUER_SERIAL_MISMATCH: authority and issuer serial number mismatch> | |
432 | ||
433 | the current candidate issuer certificate was rejected because its issuer name | |
434 | and serial number was present and did not match the authority key identifier | |
435 | of the current certificate. Only displayed when the B<-issuer_checks> option is set. | |
436 | ||
437 | =item B<32 X509_V_ERR_KEYUSAGE_NO_CERTSIGN:key usage does not include certificate signing> | |
438 | ||
439 | the current candidate issuer certificate was rejected because its keyUsage extension | |
440 | does not permit certificate signing. | |
441 | ||
7b418a47 DSH |
442 | =item B<50 X509_V_ERR_APPLICATION_VERIFICATION: application verification failure> |
443 | ||
444 | an application specific error. Unused. | |
445 | ||
446 | =back | |
13938ace | 447 | |
709e8595 DSH |
448 | =head1 BUGS |
449 | ||
2af071c0 | 450 | Although the issuer checks are a considerable improvement over the old technique they still |
709e8595 DSH |
451 | suffer from limitations in the underlying X509_LOOKUP API. One consequence of this is that |
452 | trusted certificates with matching subject name must either appear in a file (as specified by the | |
453 | B<-CAfile> option) or a directory (as specified by B<-CApath>. If they occur in both then only | |
454 | the certificates in the file will be recognised. | |
455 | ||
456 | Previous versions of OpenSSL assume certificates with matching subject name are identical and | |
457 | mishandled them. | |
458 | ||
7d3d1788 DSH |
459 | Previous versions of this documentation swapped the meaning of the |
460 | B<X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT> and | |
461 | B<20 X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY> error codes. | |
462 | ||
13938ace DSH |
463 | =head1 SEE ALSO |
464 | ||
bb075f88 | 465 | L<x509(1)|x509(1)> |
13938ace DSH |
466 | |
467 | =cut |