Debian Codegraph @

upstream/debian-unstable/man1/openssl-verification-options.1ssl

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