| 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>. |