]>
Commit | Line | Data |
---|---|---|
b6f18ed2 DO |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
5 | openssl-verification-options - generic X.509 certificate verification options | |
6 | ||
7 | =head1 SYNOPSIS | |
8 | ||
9 | B<openssl> | |
10 | I<command> | |
11 | [ I<options> ... ] | |
12 | [ I<parameters> ... ] | |
13 | ||
14 | =head1 DESCRIPTION | |
15 | ||
f9ac6f69 DDO |
16 | There are many situations where X.509 certificates are verified |
17 | within the OpenSSL libraries and in various OpenSSL commands. | |
18 | ||
19 | Certificate verification is implemented by L<X509_verify_cert(3)>. | |
20 | It is a complicated process consisting of a number of steps | |
21 | and depending on numerous options. | |
22 | The most important of them are detailed in the following sections. | |
23 | ||
028593f5 | 24 | In a nutshell, a valid chain of certificates needs to be built up and verified |
f9ac6f69 DDO |
25 | starting from the I<target certificate> that is to be verified |
26 | and ending in a certificate that due to some policy is trusted. | |
27 | Verification is done relative to the given I<purpose>, which is the intended use | |
28 | of the target certificate, such as SSL server, or by default for any purpose. | |
29 | ||
30 | The details of how each OpenSSL command handles errors | |
31 | are documented on the specific command page. | |
32 | ||
33 | DANE support is documented in L<openssl-s_client(1)>, | |
34 | L<SSL_CTX_dane_enable(3)>, L<SSL_set1_host(3)>, | |
35 | L<X509_VERIFY_PARAM_set_flags(3)>, and L<X509_check_host(3)>. | |
36 | ||
37 | =head2 Trust Anchors | |
38 | ||
39 | In general, according to RFC 4158 and RFC 5280, a I<trust anchor> is | |
40 | any public key and related subject distinguished name (DN) that | |
41 | for some reason is considered trusted | |
42 | and thus is acceptable as the root of a chain of certificates. | |
43 | ||
44 | In practice, trust anchors are given in the form of certificates, | |
45 | where their essential fields are the public key and the subject DN. | |
46 | In addition to the requirements in RFC 5280, | |
47 | OpenSSL checks the validity period of such certificates | |
48 | and makes use of some further fields. | |
49 | In particular, the subject key identifier extension, if present, | |
50 | is used for matching trust anchors during chain building. | |
51 | ||
52 | In the most simple and common case, trust anchors are by default | |
53 | all self-signed "root" CA certificates that are placed in the I<trust store>, | |
54 | which is a collection of certificates that are trusted for certain uses. | |
55 | This is akin to what is used in the trust stores of Mozilla Firefox, | |
56 | or Apple's and Microsoft's certificate stores, ... | |
57 | ||
58 | From the OpenSSL perspective, a trust anchor is a certificate | |
59 | that should be augmented with an explicit designation for which | |
60 | uses of a target certificate the certificate may serve as a trust anchor. | |
61 | In PEM encoding, this is indicated by the C<TRUSTED CERTIFICATE> string. | |
62 | Such a designation provides a set of positive trust attributes | |
63 | explicitly stating trust for the listed purposes | |
64 | and/or a set of negative trust attributes | |
65 | explicitly rejecting the use for the listed purposes. | |
66 | The purposes are encoded using the values defined for the extended key usages | |
67 | (EKUs) that may be given in X.509 extensions of end-entity certificates. | |
68 | See also the L</Extended Key Usage> section below. | |
69 | ||
70 | The currently recognized uses are | |
71 | B<clientAuth> (SSL client use), B<serverAuth> (SSL server use), | |
72 | B<emailProtection> (S/MIME email use), B<codeSigning> (object signer use), | |
73 | B<OCSPSigning> (OCSP responder use), B<OCSP> (OCSP request use), | |
74 | B<timeStamping> (TSA server use), and B<anyExtendedKeyUsage>. | |
75 | As of OpenSSL 1.1.0, the last of these blocks all uses when rejected or | |
76 | enables all uses when trusted. | |
77 | ||
78 | A certificate, which may be CA certificate or an end-entity certificate, | |
79 | is considered a trust anchor for the given use | |
80 | if and only if all the following conditions hold: | |
b6f18ed2 | 81 | |
f9ac6f69 DDO |
82 | =over 4 |
83 | ||
84 | =item * | |
85 | ||
86 | It is an an element of the trust store. | |
87 | ||
88 | =item * | |
89 | ||
90 | It does not have a negative trust attribute rejecting the given use. | |
91 | ||
92 | =item * | |
93 | ||
94 | It has a positive trust attribute accepting the given use | |
e304aa87 | 95 | or (by default) one of the following compatibility conditions apply: |
f9ac6f69 DDO |
96 | It is self-signed or the B<-partial_chain> option is given |
97 | (which corresponds to the B<X509_V_FLAG_PARTIAL_CHAIN> flag being set). | |
98 | ||
99 | =back | |
100 | ||
101 | =head2 Certification Path Building | |
b6f18ed2 DO |
102 | |
103 | First, a certificate chain is built up starting from the target certificate | |
f9ac6f69 DDO |
104 | and ending in a trust anchor. |
105 | ||
b6f18ed2 | 106 | The chain is built up iteratively, looking up in turn |
f9ac6f69 DDO |
107 | a certificate with suitable key usage that |
108 | matches as an issuer of the current "subject" certificate as described below. | |
c476c06f DDO |
109 | If there is such a certificate, the first one found that is currently valid |
110 | is taken, otherwise the one that expired most recently of all such certificates. | |
f9ac6f69 DDO |
111 | For efficiency, no backtracking is performed, thus |
112 | any further candidate issuer certificates that would match equally are ignored. | |
113 | ||
114 | When a self-signed certificate has been added, chain construction stops. | |
115 | In this case it must fully match a trust anchor, otherwise chain building fails. | |
116 | ||
117 | A candidate issuer certificate matches a subject certificate | |
118 | if all of the following conditions hold: | |
119 | ||
120 | =over 4 | |
121 | ||
122 | =item * | |
123 | ||
124 | Its subject name matches the issuer name of the subject certificate. | |
125 | ||
126 | =item * | |
127 | ||
128 | If the subject certificate has an authority key identifier extension, | |
129 | each of its sub-fields equals the corresponding subject key identifier, serial | |
130 | number, and issuer field of the candidate issuer certificate, | |
131 | as far as the respective fields are present in both certificates. | |
132 | ||
c727cddc | 133 | =item * |
f9ac6f69 DDO |
134 | |
135 | The certificate signature algorithm used to sign the subject certificate | |
136 | is supported and | |
137 | equals the public key algorithm of the candidate issuer certificate. | |
138 | ||
139 | =back | |
b6f18ed2 DO |
140 | |
141 | The lookup first searches for issuer certificates in the trust store. | |
142 | If it does not find a match there it consults | |
f9ac6f69 DDO |
143 | the list of untrusted ("intermediate" CA) certificates, if provided. |
144 | ||
145 | =head2 Certification Path Validation | |
146 | ||
147 | When the certificate chain building process was successful | |
148 | the chain components and their links are checked thoroughly. | |
149 | ||
150 | The first step is to check that each certificate is well-formed. | |
151 | Part of these checks are enabled only if the B<-x509_strict> option is given. | |
b6f18ed2 DO |
152 | |
153 | The second step is to check the extensions of every untrusted certificate | |
4acda863 DDO |
154 | for consistency with the supplied purpose. |
155 | If the B<-purpose> option is not given then no such checks are done | |
156 | except for SSL/TLS connection setup, | |
157 | where by default C<sslserver> or C<sslclient>, are checked. | |
158 | The target or "leaf" certificate, as well as any other untrusted certificates, | |
159 | must have extensions compatible with the specified purpose. | |
160 | All certificates except the target or "leaf" must also be valid CA certificates. | |
b6f18ed2 DO |
161 | The precise extensions required are described in more detail in |
162 | L<openssl-x509(1)/CERTIFICATE EXTENSIONS>. | |
163 | ||
f9ac6f69 DDO |
164 | The third step is to check the trust settings on the last certificate |
165 | (which typically is a self-signed root CA certificate). | |
166 | It must be trusted for the given use. | |
167 | For compatibility with previous versions of OpenSSL, a self-signed certificate | |
168 | with no trust attributes is considered to be valid for all uses. | |
b6f18ed2 DO |
169 | |
170 | The fourth, and final, step is to check the validity of the certificate chain. | |
171 | For each element in the chain, including the root CA certificate, | |
172 | the validity period as specified by the C<notBefore> and C<notAfter> fields | |
173 | is checked against the current system time. | |
174 | The B<-attime> flag may be used to use a reference time other than "now." | |
175 | The certificate signature is checked as well | |
176 | (except for the signature of the typically self-signed root CA certificate, | |
177 | which is verified only if the B<-check_ss_sig> option is given). | |
178 | When verifying a certificate signature | |
179 | the keyUsage extension (if present) of the candidate issuer certificate | |
180 | is checked to permit digitalSignature for signing proxy certificates | |
181 | or to permit keyCertSign for signing other certificates, respectively. | |
182 | If all operations complete successfully then certificate is considered | |
183 | valid. If any operation fails then the certificate is not valid. | |
184 | ||
185 | =head1 OPTIONS | |
186 | ||
ac093b3f AS |
187 | =head2 Trusted Certificate Options |
188 | ||
f9ac6f69 DDO |
189 | The following options specify how to supply the certificates |
190 | that can be used as trust anchors for certain uses. | |
191 | As mentioned, a collection of such certificates is called a I<trust store>. | |
ac093b3f AS |
192 | |
193 | Note that OpenSSL does not provide a default set of trust anchors. Many | |
194 | Linux distributions include a system default and configure OpenSSL to point | |
195 | to that. Mozilla maintains an influential trust store that can be found at | |
196 | L<https://www.mozilla.org/en-US/about/governance/policies/security-group/certs/>. | |
197 | ||
f9ac6f69 DDO |
198 | The certificates to add to the trust store |
199 | can be specified using following options. | |
ac093b3f AS |
200 | |
201 | =over 4 | |
202 | ||
203 | =item B<-CAfile> I<file> | |
204 | ||
f9ac6f69 DDO |
205 | Load the specified file which contains a certificate |
206 | or several of them in case the input is in PEM or PKCS#12 format. | |
207 | PEM-encoded certificates may also have trust attributes set. | |
ac093b3f AS |
208 | |
209 | =item B<-no-CAfile> | |
210 | ||
211 | Do not load the default file of trusted certificates. | |
212 | ||
213 | =item B<-CApath> I<dir> | |
214 | ||
f9ac6f69 DDO |
215 | Use the specified directory as a collection of trusted certificates, |
216 | i.e., a trust store. | |
217 | Files should be named with the hash value of the X.509 SubjectName of each | |
ac093b3f AS |
218 | certificate. This is so that the library can extract the IssuerName, |
219 | hash it, and directly lookup the file to get the issuer certificate. | |
220 | See L<openssl-rehash(1)> for information on creating this type of directory. | |
221 | ||
222 | =item B<-no-CApath> | |
223 | ||
224 | Do not use the default directory of trusted certificates. | |
225 | ||
226 | =item B<-CAstore> I<uri> | |
227 | ||
f9ac6f69 DDO |
228 | Use I<uri> as a store of CA certificates. |
229 | The URI may indicate a single certificate, as well as a collection of them. | |
ac093b3f AS |
230 | With URIs in the C<file:> scheme, this acts as B<-CAfile> or |
231 | B<-CApath>, depending on if the URI indicates a single file or | |
232 | directory. | |
233 | See L<ossl_store-file(7)> for more information on the C<file:> scheme. | |
234 | ||
235 | These certificates are also used when building the server certificate | |
236 | chain (for example with L<openssl-s_server(1)>) or client certificate | |
237 | chain (for example with L<openssl-s_time(1)>). | |
238 | ||
239 | =item B<-no-CAstore> | |
240 | ||
f9ac6f69 | 241 | Do not use the default store of trusted CA certificates. |
ac093b3f AS |
242 | |
243 | =back | |
244 | ||
b6f18ed2 DO |
245 | =head2 Verification Options |
246 | ||
247 | The certificate verification can be fine-tuned with the following flags. | |
248 | ||
249 | =over 4 | |
250 | ||
251 | =item B<-verbose> | |
252 | ||
253 | Print extra information about the operations being performed. | |
254 | ||
255 | =item B<-attime> I<timestamp> | |
256 | ||
257 | Perform validation checks using time specified by I<timestamp> and not | |
258 | current system time. I<timestamp> is the number of seconds since | |
259 | January 1, 1970 (i.e., the Unix Epoch). | |
260 | ||
261 | =item B<-no_check_time> | |
262 | ||
263 | This option suppresses checking the validity period of certificates and CRLs | |
264 | against the current time. If option B<-attime> is used to specify | |
265 | a verification time, the check is not suppressed. | |
266 | ||
267 | =item B<-x509_strict> | |
268 | ||
269 | This disables non-compliant workarounds for broken certificates. | |
270 | Thus errors are thrown on certificates not compliant with RFC 5280. | |
271 | ||
272 | When this option is set, | |
273 | among others, the following certificate well-formedness conditions are checked: | |
274 | ||
275 | =over 4 | |
276 | ||
2fc02378 | 277 | =item * |
b6f18ed2 DO |
278 | |
279 | The basicConstraints of CA certificates must be marked critical. | |
280 | ||
2fc02378 | 281 | =item * |
b6f18ed2 DO |
282 | |
283 | CA certificates must explicitly include the keyUsage extension. | |
284 | ||
2fc02378 | 285 | =item * |
b6f18ed2 DO |
286 | |
287 | If a pathlenConstraint is given the key usage keyCertSign must be allowed. | |
288 | ||
2fc02378 | 289 | =item * |
b6f18ed2 DO |
290 | |
291 | The pathlenConstraint must not be given for non-CA certificates. | |
292 | ||
2fc02378 | 293 | =item * |
b6f18ed2 DO |
294 | |
295 | The issuer name of any certificate must not be empty. | |
296 | ||
2fc02378 | 297 | =item * |
b6f18ed2 DO |
298 | |
299 | The subject name of CA certs, certs with keyUsage crlSign, and certs | |
300 | without subjectAlternativeName must not be empty. | |
301 | ||
2fc02378 | 302 | =item * |
b6f18ed2 DO |
303 | |
304 | If a subjectAlternativeName extension is given it must not be empty. | |
305 | ||
2fc02378 | 306 | =item * |
b6f18ed2 DO |
307 | |
308 | The signatureAlgorithm field and the cert signature must be consistent. | |
309 | ||
2fc02378 | 310 | =item * |
b6f18ed2 DO |
311 | |
312 | Any given authorityKeyIdentifier and any given subjectKeyIdentifier | |
313 | must not be marked critical. | |
314 | ||
2fc02378 | 315 | =item * |
b6f18ed2 DO |
316 | |
317 | The authorityKeyIdentifier must be given for X.509v3 certs unless they | |
318 | are self-signed. | |
319 | ||
2fc02378 | 320 | =item * |
b6f18ed2 DO |
321 | |
322 | The subjectKeyIdentifier must be given for all X.509v3 CA certs. | |
323 | ||
324 | =back | |
325 | ||
326 | =item B<-ignore_critical> | |
327 | ||
328 | Normally if an unhandled critical extension is present that is not | |
329 | supported by OpenSSL the certificate is rejected (as required by RFC5280). | |
330 | If this option is set critical extensions are ignored. | |
331 | ||
332 | =item B<-issuer_checks> | |
333 | ||
334 | Ignored. | |
335 | ||
336 | =item B<-crl_check> | |
337 | ||
338 | Checks end entity certificate validity by attempting to look up a valid CRL. | |
339 | If a valid CRL cannot be found an error occurs. | |
340 | ||
341 | =item B<-crl_check_all> | |
342 | ||
343 | Checks the validity of B<all> certificates in the chain by attempting | |
344 | to look up valid CRLs. | |
345 | ||
346 | =item B<-use_deltas> | |
347 | ||
348 | Enable support for delta CRLs. | |
349 | ||
350 | =item B<-extended_crl> | |
351 | ||
352 | Enable extended CRL features such as indirect CRLs and alternate CRL | |
353 | signing keys. | |
354 | ||
355 | =item B<-suiteB_128_only>, B<-suiteB_128>, B<-suiteB_192> | |
356 | ||
357 | Enable the Suite B mode operation at 128 bit Level of Security, 128 bit or | |
358 | 192 bit, or only 192 bit Level of Security respectively. | |
359 | See RFC6460 for details. In particular the supported signature algorithms are | |
360 | reduced to support only ECDSA and SHA256 or SHA384 and only the elliptic curves | |
361 | P-256 and P-384. | |
362 | ||
363 | =item B<-auth_level> I<level> | |
364 | ||
365 | Set the certificate chain authentication security level to I<level>. | |
366 | The authentication security level determines the acceptable signature and | |
367 | public key strength when verifying certificate chains. For a certificate | |
368 | chain to validate, the public keys of all the certificates must meet the | |
369 | specified security I<level>. The signature algorithm security level is | |
370 | enforced for all the certificates in the chain except for the chain's | |
371 | I<trust anchor>, which is either directly trusted or validated by means | |
372 | other than its signature. See L<SSL_CTX_set_security_level(3)> for the | |
373 | definitions of the available levels. The default security level is -1, | |
374 | or "not set". At security level 0 or lower all algorithms are acceptable. | |
375 | Security level 1 requires at least 80-bit-equivalent security and is broadly | |
376 | interoperable, though it will, for example, reject MD5 signatures or RSA | |
377 | keys shorter than 1024 bits. | |
378 | ||
379 | =item B<-partial_chain> | |
380 | ||
f9ac6f69 DDO |
381 | Allow verification to succeed if an incomplete chain can be built. |
382 | That is, a chain ending in a certificate that normally would not be trusted | |
383 | (because it has no matching positive trust attributes and is not self-signed) | |
384 | but is an element of the trust store. | |
b6f18ed2 DO |
385 | This certificate may be self-issued or belong to an intermediate CA. |
386 | ||
387 | =item B<-check_ss_sig> | |
388 | ||
389 | Verify the signature of | |
390 | the last certificate in a chain if the certificate is supposedly self-signed. | |
391 | This is prohibited and will result in an error if it is a non-conforming CA | |
392 | certificate with key usage restrictions not including the keyCertSign bit. | |
393 | This verification is disabled by default because it doesn't add any security. | |
394 | ||
395 | =item B<-allow_proxy_certs> | |
396 | ||
397 | Allow the verification of proxy certificates. | |
398 | ||
399 | =item B<-trusted_first> | |
400 | ||
401 | As of OpenSSL 1.1.0 this option is on by default and cannot be disabled. | |
402 | ||
403 | When constructing the certificate chain, the trusted certificates specified | |
404 | via B<-CAfile>, B<-CApath>, B<-CAstore> or B<-trusted> are always used | |
405 | before any certificates specified via B<-untrusted>. | |
406 | ||
407 | =item B<-no_alt_chains> | |
408 | ||
409 | As of OpenSSL 1.1.0, since B<-trusted_first> always on, this option has no | |
410 | effect. | |
411 | ||
412 | =item B<-trusted> I<file> | |
413 | ||
f9ac6f69 DDO |
414 | Parse I<file> as a set of one or more certificates. |
415 | Each of them qualifies as trusted if has a suitable positive trust attribute | |
416 | or it is self-signed or the B<-partial_chain> option is specified. | |
b6f18ed2 DO |
417 | This option implies the B<-no-CAfile>, B<-no-CApath>, and B<-no-CAstore> options |
418 | and it cannot be used with the B<-CAfile>, B<-CApath> or B<-CAstore> options, so | |
f9ac6f69 | 419 | only certificates specified using the B<-trusted> option are trust anchors. |
b6f18ed2 DO |
420 | This option may be used multiple times. |
421 | ||
422 | =item B<-untrusted> I<file> | |
423 | ||
f9ac6f69 DDO |
424 | Parse I<file> as a set of one or more certificates. |
425 | All certificates (typically of intermediate CAs) are considered untrusted | |
426 | and may be used to | |
427 | construct a certificate chain from the target certificate to a trust anchor. | |
b6f18ed2 DO |
428 | This option may be used multiple times. |
429 | ||
430 | =item B<-policy> I<arg> | |
431 | ||
432 | Enable policy processing and add I<arg> to the user-initial-policy-set (see | |
433 | RFC5280). The policy I<arg> can be an object name an OID in numeric form. | |
434 | This argument can appear more than once. | |
435 | ||
436 | =item B<-explicit_policy> | |
437 | ||
438 | Set policy variable require-explicit-policy (see RFC5280). | |
439 | ||
440 | =item B<-policy_check> | |
441 | ||
442 | Enables certificate policy processing. | |
443 | ||
444 | =item B<-policy_print> | |
445 | ||
446 | Print out diagnostics related to policy processing. | |
447 | ||
448 | =item B<-inhibit_any> | |
449 | ||
450 | Set policy variable inhibit-any-policy (see RFC5280). | |
451 | ||
452 | =item B<-inhibit_map> | |
453 | ||
454 | Set policy variable inhibit-policy-mapping (see RFC5280). | |
455 | ||
456 | =item B<-purpose> I<purpose> | |
457 | ||
4acda863 DDO |
458 | The intended use for the certificate. |
459 | Currently defined purposes are C<sslclient>, C<sslserver>, C<nssslserver>, | |
460 | C<smimesign>, C<smimeencrypt>, C<crlsign>, C<ocsphelper>, C<timestampsign>, | |
461 | and C<any>. | |
462 | If peer certificate verification is enabled, by default the TLS implementation | |
463 | as well as the commands B<s_client> and B<s_server> check for consistency | |
464 | with TLS server or TLS client use, respectively. | |
465 | ||
466 | While IETF RFC 5280 says that B<id-kp-serverAuth> and B<id-kp-clientAuth> | |
467 | are only for WWW use, in practice they are used for all kinds of TLS clients | |
468 | and servers, and this is what OpenSSL assumes as well. | |
b6f18ed2 DO |
469 | |
470 | =item B<-verify_depth> I<num> | |
471 | ||
472 | Limit the certificate chain to I<num> intermediate CA certificates. | |
473 | A maximal depth chain can have up to I<num>+2 certificates, since neither the | |
474 | end-entity certificate nor the trust-anchor certificate count against the | |
475 | B<-verify_depth> limit. | |
476 | ||
477 | =item B<-verify_email> I<email> | |
478 | ||
479 | Verify if I<email> matches the email address in Subject Alternative Name or | |
480 | the email in the subject Distinguished Name. | |
481 | ||
482 | =item B<-verify_hostname> I<hostname> | |
483 | ||
484 | Verify if I<hostname> matches DNS name in Subject Alternative Name or | |
485 | Common Name in the subject certificate. | |
486 | ||
487 | =item B<-verify_ip> I<ip> | |
488 | ||
489 | Verify if I<ip> matches the IP address in Subject Alternative Name of | |
490 | the subject certificate. | |
491 | ||
492 | =item B<-verify_name> I<name> | |
493 | ||
494 | Use default verification policies like trust model and required certificate | |
495 | policies identified by I<name>. | |
496 | The trust model determines which auxiliary trust or reject OIDs are applicable | |
497 | to verifying the given certificate chain. | |
f9ac6f69 DDO |
498 | They can be given using the B<-addtrust> and B<-addreject> options |
499 | for L<openssl-x509(1)>. | |
b6f18ed2 DO |
500 | Supported policy names include: B<default>, B<pkcs7>, B<smime_sign>, |
501 | B<ssl_client>, B<ssl_server>. | |
502 | These mimics the combinations of purpose and trust settings used in SSL, CMS | |
503 | and S/MIME. | |
504 | As of OpenSSL 1.1.0, the trust model is inferred from the purpose when not | |
505 | specified, so the B<-verify_name> options are functionally equivalent to the | |
506 | corresponding B<-purpose> settings. | |
507 | ||
508 | =back | |
509 | ||
510 | =head2 Extended Verification Options | |
511 | ||
512 | Sometimes there may be more than one certificate chain leading to an | |
513 | end-entity certificate. | |
514 | This usually happens when a root or intermediate CA signs a certificate | |
515 | for another a CA in other organization. | |
516 | Another reason is when a CA might have intermediates that use two different | |
517 | signature formats, such as a SHA-1 and a SHA-256 digest. | |
518 | ||
519 | The following options can be used to provide data that will allow the | |
520 | OpenSSL command to generate an alternative chain. | |
521 | ||
522 | =over 4 | |
523 | ||
524 | =item B<-xkey> I<infile>, B<-xcert> I<infile>, B<-xchain> | |
525 | ||
526 | Specify an extra certificate, private key and certificate chain. These behave | |
527 | in the same manner as the B<-cert>, B<-key> and B<-cert_chain> options. When | |
528 | specified, the callback returning the first valid chain will be in use by the | |
529 | client. | |
530 | ||
531 | =item B<-xchain_build> | |
532 | ||
533 | Specify whether the application should build the certificate chain to be | |
534 | provided to the server for the extra certificates via the B<-xkey>, | |
535 | B<-xcert>, and B<-xchain> options. | |
536 | ||
537 | =item B<-xcertform> B<DER>|B<PEM>|B<P12> | |
538 | ||
539 | The input format for the extra certificate. | |
540 | This option has no effect and is retained for backward compatibility only. | |
541 | ||
542 | =item B<-xkeyform> B<DER>|B<PEM>|B<P12> | |
543 | ||
544 | The input format for the extra key. | |
545 | This option has no effect and is retained for backward compatibility only. | |
546 | ||
547 | =back | |
548 | ||
f9ac6f69 DDO |
549 | =head2 Certificate Extensions |
550 | ||
551 | Options like B<-purpose> lead to checking the certificate extensions, | |
552 | which determine what the target certificate and intermediate CA certificates | |
553 | can be used for. | |
554 | ||
555 | =head3 Basic Constraints | |
556 | ||
557 | The basicConstraints extension CA flag is used to determine whether the | |
558 | certificate can be used as a CA. If the CA flag is true then it is a CA, | |
559 | if the CA flag is false then it is not a CA. B<All> CAs should have the | |
560 | CA flag set to true. | |
561 | ||
562 | If the basicConstraints extension is absent, | |
563 | which includes the case that it is an X.509v1 certificate, | |
564 | then the certificate is considered to be a "possible CA" and | |
565 | other extensions are checked according to the intended use of the certificate. | |
566 | The treatment of certificates without basicConstraints as a CA | |
567 | is presently supported, but this could change in the future. | |
568 | ||
569 | =head3 Key Usage | |
570 | ||
571 | If the keyUsage extension is present then additional restraints are | |
572 | made on the uses of the certificate. A CA certificate B<must> have the | |
573 | keyCertSign bit set if the keyUsage extension is present. | |
574 | ||
575 | =head3 Extended Key Usage | |
576 | ||
577 | The extKeyUsage (EKU) extension places additional restrictions on the | |
578 | certificate uses. If this extension is present (whether critical or not) | |
579 | the key can only be used for the purposes specified. | |
580 | ||
581 | A complete description of each check is given below. The comments about | |
582 | basicConstraints and keyUsage and X.509v1 certificates above apply to B<all> | |
583 | CA certificates. | |
584 | ||
585 | ||
586 | =over 4 | |
587 | ||
588 | =item B<SSL Client> | |
589 | ||
590 | The extended key usage extension must be absent or include the "web client | |
591 | authentication" OID. The keyUsage extension must be absent or it must have the | |
592 | digitalSignature bit set. The Netscape certificate type must be absent | |
593 | or it must have the SSL client bit set. | |
594 | ||
595 | =item B<SSL Client CA> | |
596 | ||
597 | The extended key usage extension must be absent or include the "web client | |
598 | authentication" OID. | |
599 | The Netscape certificate type must be absent or it must have the SSL CA bit set. | |
600 | This is used as a work around if the basicConstraints extension is absent. | |
601 | ||
602 | =item B<SSL Server> | |
603 | ||
604 | The extended key usage extension must be absent or include the "web server | |
605 | authentication" and/or one of the SGC OIDs. The keyUsage extension must be | |
606 | absent or it | |
607 | must have the digitalSignature, the keyEncipherment set or both bits set. | |
608 | The Netscape certificate type must be absent or have the SSL server bit set. | |
609 | ||
610 | =item B<SSL Server CA> | |
611 | ||
612 | The extended key usage extension must be absent or include the "web server | |
613 | authentication" and/or one of the SGC OIDs. The Netscape certificate type must | |
614 | be absent or the SSL CA bit must be set. | |
615 | This is used as a work around if the basicConstraints extension is absent. | |
616 | ||
617 | =item B<Netscape SSL Server> | |
618 | ||
619 | For Netscape SSL clients to connect to an SSL server it must have the | |
620 | keyEncipherment bit set if the keyUsage extension is present. This isn't | |
621 | always valid because some cipher suites use the key for digital signing. | |
622 | Otherwise it is the same as a normal SSL server. | |
623 | ||
624 | =item B<Common S/MIME Client Tests> | |
625 | ||
626 | The extended key usage extension must be absent or include the "email | |
627 | protection" OID. The Netscape certificate type must be absent or should have the | |
628 | S/MIME bit set. If the S/MIME bit is not set in the Netscape certificate type | |
629 | then the SSL client bit is tolerated as an alternative but a warning is shown. | |
630 | This is because some Verisign certificates don't set the S/MIME bit. | |
631 | ||
632 | =item B<S/MIME Signing> | |
633 | ||
634 | In addition to the common S/MIME client tests the digitalSignature bit or | |
635 | the nonRepudiation bit must be set if the keyUsage extension is present. | |
636 | ||
637 | =item B<S/MIME Encryption> | |
638 | ||
639 | In addition to the common S/MIME tests the keyEncipherment bit must be set | |
640 | if the keyUsage extension is present. | |
641 | ||
642 | =item B<S/MIME CA> | |
643 | ||
644 | The extended key usage extension must be absent or include the "email | |
645 | protection" OID. The Netscape certificate type must be absent or must have the | |
646 | S/MIME CA bit set. | |
647 | This is used as a work around if the basicConstraints extension is absent. | |
648 | ||
649 | =item B<CRL Signing> | |
650 | ||
651 | The keyUsage extension must be absent or it must have the CRL signing bit | |
652 | set. | |
653 | ||
654 | =item B<CRL Signing CA> | |
655 | ||
656 | The normal CA tests apply. Except in this case the basicConstraints extension | |
657 | must be present. | |
658 | ||
659 | =back | |
660 | ||
661 | =head1 BUGS | |
662 | ||
663 | The issuer checks still suffer from limitations in the underlying X509_LOOKUP | |
664 | API. One consequence of this is that trusted certificates with matching | |
665 | subject name must appear in a file (as specified by the B<-CAfile> option), | |
666 | a directory (as specified by B<-CApath>), | |
667 | or a store (as specified by B<-CAstore>). | |
668 | If there are multiple such matches, possibly in multiple locations, | |
669 | only the first one (in the mentioned order of locations) is recognised. | |
670 | ||
b6f18ed2 DO |
671 | =head1 SEE ALSO |
672 | ||
673 | L<X509_verify_cert(3)>, | |
674 | L<openssl-verify(1)>, | |
675 | L<openssl-ocsp(1)>, | |
676 | L<openssl-ts(1)>, | |
677 | L<openssl-s_client(1)>, | |
678 | L<openssl-s_server(1)>, | |
679 | L<openssl-smime(1)>, | |
680 | L<openssl-cmp(1)>, | |
681 | L<openssl-cms(1)> | |
682 | ||
b6f18ed2 DO |
683 | =head1 HISTORY |
684 | ||
685 | The checks enabled by B<-x509_strict> have been extended in OpenSSL 3.0. | |
686 | ||
687 | =head1 COPYRIGHT | |
688 | ||
fecb3aae | 689 | Copyright 2000-2022 The OpenSSL Project Authors. All Rights Reserved. |
b6f18ed2 DO |
690 | |
691 | Licensed under the Apache License 2.0 (the "License"). You may not use | |
692 | this file except in compliance with the License. You can obtain a copy | |
693 | in the file LICENSE in the source distribution or at | |
694 | L<https://www.openssl.org/source/license.html>. | |
695 | ||
696 | =cut |