5 openssl-verification-options - generic X.509 certificate verification options
16 There are many situations where X.509 certificates are verified
17 within the OpenSSL libraries and in various OpenSSL commands.
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.
24 In a nutshell, a valid chain of certificates needs to be built up and verified
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.
30 The details of how each OpenSSL command handles errors
31 are documented on the specific command page.
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)>.
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.
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.
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, ...
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.
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.
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:
86 It is an an element of the trust store.
90 It does not have a negative trust attribute rejecting the given use.
94 It has a positive trust attribute accepting the given use
95 or (by default) one of the following compatibility conditions apply:
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).
101 =head2 Certification Path Building
103 First, a certificate chain is built up starting from the target certificate
104 and ending in a trust anchor.
106 The chain is built up iteratively, looking up in turn
107 a certificate with suitable key usage that
108 matches as an issuer of the current "subject" certificate as described below.
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.
111 For efficiency, no backtracking is performed, thus
112 any further candidate issuer certificates that would match equally are ignored.
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.
117 A candidate issuer certificate matches a subject certificate
118 if all of the following conditions hold:
124 Its subject name matches the issuer name of the subject certificate.
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.
135 The certificate signature algorithm used to sign the subject certificate
137 equals the public key algorithm of the candidate issuer certificate.
141 The lookup first searches for issuer certificates in the trust store.
142 If it does not find a match there it consults
143 the list of untrusted ("intermediate" CA) certificates, if provided.
145 =head2 Certification Path Validation
147 When the certificate chain building process was successful
148 the chain components and their links are checked thoroughly.
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.
153 The second step is to check the extensions of every untrusted certificate
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.
161 The precise extensions required are described in more detail in
162 L<openssl-x509(1)/CERTIFICATE EXTENSIONS>.
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.
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.
187 =head2 Trusted Certificate Options
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>.
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/>.
198 The certificates to add to the trust store
199 can be specified using following options.
203 =item B<-CAfile> I<file>
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.
211 Do not load the default file of trusted certificates.
213 =item B<-CApath> I<dir>
215 Use the specified directory as a collection of trusted certificates,
217 Files should be named with the hash value of the X.509 SubjectName of each
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.
224 Do not use the default directory of trusted certificates.
226 =item B<-CAstore> I<uri>
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.
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
233 See L<ossl_store-file(7)> for more information on the C<file:> scheme.
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)>).
241 Do not use the default store of trusted CA certificates.
245 =head2 Verification Options
247 The certificate verification can be fine-tuned with the following flags.
253 Print extra information about the operations being performed.
255 =item B<-attime> I<timestamp>
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).
261 =item B<-no_check_time>
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.
267 =item B<-x509_strict>
269 This disables non-compliant workarounds for broken certificates.
270 Thus errors are thrown on certificates not compliant with RFC 5280.
272 When this option is set,
273 among others, the following certificate well-formedness conditions are checked:
279 The basicConstraints of CA certificates must be marked critical.
283 CA certificates must explicitly include the keyUsage extension.
287 If a pathlenConstraint is given the key usage keyCertSign must be allowed.
291 The pathlenConstraint must not be given for non-CA certificates.
295 The issuer name of any certificate must not be empty.
299 The subject name of CA certs, certs with keyUsage crlSign, and certs
300 without subjectAlternativeName must not be empty.
304 If a subjectAlternativeName extension is given it must not be empty.
308 The signatureAlgorithm field and the cert signature must be consistent.
312 Any given authorityKeyIdentifier and any given subjectKeyIdentifier
313 must not be marked critical.
317 The authorityKeyIdentifier must be given for X.509v3 certs unless they
322 The subjectKeyIdentifier must be given for all X.509v3 CA certs.
326 =item B<-ignore_critical>
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.
332 =item B<-issuer_checks>
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.
341 =item B<-crl_check_all>
343 Checks the validity of B<all> certificates in the chain by attempting
344 to look up valid CRLs.
348 Enable support for delta CRLs.
350 =item B<-extended_crl>
352 Enable extended CRL features such as indirect CRLs and alternate CRL
355 =item B<-suiteB_128_only>, B<-suiteB_128>, B<-suiteB_192>
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
363 =item B<-auth_level> I<level>
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.
379 =item B<-partial_chain>
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.
385 This certificate may be self-issued or belong to an intermediate CA.
387 =item B<-check_ss_sig>
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.
395 =item B<-allow_proxy_certs>
397 Allow the verification of proxy certificates.
399 =item B<-trusted_first>
401 As of OpenSSL 1.1.0 this option is on by default and cannot be disabled.
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>.
407 =item B<-no_alt_chains>
409 As of OpenSSL 1.1.0, since B<-trusted_first> always on, this option has no
412 =item B<-trusted> I<file>
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.
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
419 only certificates specified using the B<-trusted> option are trust anchors.
420 This option may be used multiple times.
422 =item B<-untrusted> I<file>
424 Parse I<file> as a set of one or more certificates.
425 All certificates (typically of intermediate CAs) are considered untrusted
427 construct a certificate chain from the target certificate to a trust anchor.
428 This option may be used multiple times.
430 =item B<-policy> I<arg>
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.
436 =item B<-explicit_policy>
438 Set policy variable require-explicit-policy (see RFC5280).
440 =item B<-policy_check>
442 Enables certificate policy processing.
444 =item B<-policy_print>
446 Print out diagnostics related to policy processing.
448 =item B<-inhibit_any>
450 Set policy variable inhibit-any-policy (see RFC5280).
452 =item B<-inhibit_map>
454 Set policy variable inhibit-policy-mapping (see RFC5280).
456 =item B<-purpose> I<purpose>
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>,
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.
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.
470 =item B<-verify_depth> I<num>
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.
477 =item B<-verify_email> I<email>
479 Verify if I<email> matches the email address in Subject Alternative Name or
480 the email in the subject Distinguished Name.
482 =item B<-verify_hostname> I<hostname>
484 Verify if I<hostname> matches DNS name in Subject Alternative Name or
485 Common Name in the subject certificate.
487 =item B<-verify_ip> I<ip>
489 Verify if I<ip> matches the IP address in Subject Alternative Name of
490 the subject certificate.
492 =item B<-verify_name> I<name>
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.
498 They can be given using the B<-addtrust> and B<-addreject> options
499 for L<openssl-x509(1)>.
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
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.
510 =head2 Extended Verification Options
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.
519 The following options can be used to provide data that will allow the
520 OpenSSL command to generate an alternative chain.
524 =item B<-xkey> I<infile>, B<-xcert> I<infile>, B<-xchain>
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
531 =item B<-xchain_build>
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.
537 =item B<-xcertform> B<DER>|B<PEM>|B<P12>
539 The input format for the extra certificate.
540 This option has no effect and is retained for backward compatibility only.
542 =item B<-xkeyform> B<DER>|B<PEM>|B<P12>
544 The input format for the extra key.
545 This option has no effect and is retained for backward compatibility only.
549 =head2 Certificate Extensions
551 Options like B<-purpose> lead to checking the certificate extensions,
552 which determine what the target certificate and intermediate CA certificates
555 =head3 Basic Constraints
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
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.
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.
575 =head3 Extended Key Usage
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.
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>
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.
595 =item B<SSL Client CA>
597 The extended key usage extension must be absent or include the "web client
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.
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
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.
610 =item B<SSL Server CA>
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.
617 =item B<Netscape SSL Server>
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.
624 =item B<Common S/MIME Client Tests>
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.
632 =item B<S/MIME Signing>
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.
637 =item B<S/MIME Encryption>
639 In addition to the common S/MIME tests the keyEncipherment bit must be set
640 if the keyUsage extension is present.
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
647 This is used as a work around if the basicConstraints extension is absent.
651 The keyUsage extension must be absent or it must have the CRL signing bit
654 =item B<CRL Signing CA>
656 The normal CA tests apply. Except in this case the basicConstraints extension
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.
673 L<X509_verify_cert(3)>,
674 L<openssl-verify(1)>,
677 L<openssl-s_client(1)>,
678 L<openssl-s_server(1)>,
685 The checks enabled by B<-x509_strict> have been extended in OpenSSL 3.0.
689 Copyright 2000-2021 The OpenSSL Project Authors. All Rights Reserved.
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>.