1OPENSSL-VERIFICATION-OPTIONS(1ossl) OpenSSLOPENSSL-VERIFICATION-OPTIONS(1ossl)
2
3
4

NAME

6       openssl-verification-options - generic X.509 certificate verification
7       options
8

SYNOPSIS

10       openssl command [ options ... ] [ parameters ... ]
11

DESCRIPTION

13       There are many situations where X.509 certificates are verified within
14       the OpenSSL libraries and in various OpenSSL commands.
15
16       Certificate verification is implemented by X509_verify_cert(3).  It is
17       a complicated process consisting of a number of steps and depending on
18       numerous options.  The most important of them are detailed in the
19       following sections.
20
21       In a nutshell, a valid chain of certificates needs to be built up and
22       verified starting from the target certificate that is to be verified
23       and ending in a certificate that due to some policy is trusted.
24       Verification is done relative to the given purpose, which is the
25       intended use of the target certificate, such as SSL server, or by
26       default for any purpose.
27
28       The details of how each OpenSSL command handles errors are documented
29       on the specific command page.
30
31       DANE support is documented in openssl-s_client(1),
32       SSL_CTX_dane_enable(3), SSL_set1_host(3),
33       X509_VERIFY_PARAM_set_flags(3), and X509_check_host(3).
34
35   Trust Anchors
36       In general, according to RFC 4158 and RFC 5280, a trust anchor is any
37       public key and related subject distinguished name (DN) that for some
38       reason is considered trusted and thus is acceptable as the root of a
39       chain of certificates.
40
41       In practice, trust anchors are given in the form of certificates, where
42       their essential fields are the public key and the subject DN.  In
43       addition to the requirements in RFC 5280, OpenSSL checks the validity
44       period of such certificates and makes use of some further fields.  In
45       particular, the subject key identifier extension, if present, is used
46       for matching trust anchors during chain building.
47
48       In the most simple and common case, trust anchors are by default all
49       self-signed "root" CA certificates that are placed in the trust store,
50       which is a collection of certificates that are trusted for certain
51       uses.  This is akin to what is used in the trust stores of Mozilla
52       Firefox, or Apple's and Microsoft's certificate stores, ...
53
54       From the OpenSSL perspective, a trust anchor is a certificate that
55       should be augmented with an explicit designation for which uses of a
56       target certificate the certificate may serve as a trust anchor.  In PEM
57       encoding, this is indicated by the "TRUSTED CERTIFICATE" string.  Such
58       a designation provides a set of positive trust attributes explicitly
59       stating trust for the listed purposes and/or a set of negative trust
60       attributes explicitly rejecting the use for the listed purposes.  The
61       purposes are encoded using the values defined for the extended key
62       usages (EKUs) that may be given in X.509 extensions of end-entity
63       certificates.  See also the "Extended Key Usage" section below.
64
65       The currently recognized uses are clientAuth (SSL client use),
66       serverAuth (SSL server use), emailProtection (S/MIME email use),
67       codeSigning (object signer use), OCSPSigning (OCSP responder use), OCSP
68       (OCSP request use), timeStamping (TSA server use), and
69       anyExtendedKeyUsage.  As of OpenSSL 1.1.0, the last of these blocks all
70       uses when rejected or enables all uses when trusted.
71
72       A certificate, which may be CA certificate or an end-entity
73       certificate, is considered a trust anchor for the given use if and only
74       if all the following conditions hold:
75
76       •   It is an an element of the trust store.
77
78       •   It does not have a negative trust attribute rejecting the given
79           use.
80
81       •   It has a positive trust attribute accepting the given use or (by
82           default) one of the following compatibilty conditions apply: It is
83           self-signed or the -partial_chain option is given (which
84           corresponds to the X509_V_FLAG_PARTIAL_CHAIN flag being set).
85
86   Certification Path Building
87       First, a certificate chain is built up starting from the target
88       certificate and ending in a trust anchor.
89
90       The chain is built up iteratively, looking up in turn a certificate
91       with suitable key usage that matches as an issuer of the current
92       "subject" certificate as described below.  If there is such a
93       certificate, the first one found that is currently valid is taken,
94       otherwise the one that expired most recently of all such certificates.
95       For efficiency, no backtracking is performed, thus any further
96       candidate issuer certificates that would match equally are ignored.
97
98       When a self-signed certificate has been added, chain construction
99       stops.  In this case it must fully match a trust anchor, otherwise
100       chain building fails.
101
102       A candidate issuer certificate matches a subject certificate if all of
103       the following conditions hold:
104
105       •   Its subject name matches the issuer name of the subject
106           certificate.
107
108       •   If the subject certificate has an authority key identifier
109           extension, each of its sub-fields equals the corresponding subject
110           key identifier, serial number, and issuer field of the candidate
111           issuer certificate, as far as the respective fields are present in
112           both certificates.
113
114       •   The certificate signature algorithm used to sign the subject
115           certificate is supported and equals the public key algorithm of the
116           candidate issuer certificate.
117
118       The lookup first searches for issuer certificates in the trust store.
119       If it does not find a match there it consults the list of untrusted
120       ("intermediate" CA) certificates, if provided.
121
122   Certification Path Validation
123       When the certificate chain building process was successful the chain
124       components and their links are checked thoroughly.
125
126       The first step is to check that each certificate is well-formed.  Part
127       of these checks are enabled only if the -x509_strict option is given.
128
129       The second step is to check the extensions of every untrusted
130       certificate for consistency with the supplied purpose.  If the -purpose
131       option is not given then no such checks are done except for SSL/TLS
132       connection setup, where by default "sslserver" or "sslclient", are
133       checked.  The target or "leaf" certificate, as well as any other
134       untrusted certificates, must have extensions compatible with the
135       specified purpose.  All certificates except the target or "leaf" must
136       also be valid CA certificates.  The precise extensions required are
137       described in more detail in "CERTIFICATE EXTENSIONS" in
138       openssl-x509(1).
139
140       The third step is to check the trust settings on the last certificate
141       (which typically is a self-signed root CA certificate).  It must be
142       trusted for the given use.  For compatibility with previous versions of
143       OpenSSL, a self-signed certificate with no trust attributes is
144       considered to be valid for all uses.
145
146       The fourth, and final, step is to check the validity of the certificate
147       chain.  For each element in the chain, including the root CA
148       certificate, the validity period as specified by the "notBefore" and
149       "notAfter" fields is checked against the current system time.  The
150       -attime flag may be used to use a reference time other than "now."  The
151       certificate signature is checked as well (except for the signature of
152       the typically self-signed root CA certificate, which is verified only
153       if the -check_ss_sig option is given).  When verifying a certificate
154       signature the keyUsage extension (if present) of the candidate issuer
155       certificate is checked to permit digitalSignature for signing proxy
156       certificates or to permit keyCertSign for signing other certificates,
157       respectively.  If all operations complete successfully then certificate
158       is considered valid. If any operation fails then the certificate is not
159       valid.
160

OPTIONS

162   Trusted Certificate Options
163       The following options specify how to supply the certificates that can
164       be used as trust anchors for certain uses.  As mentioned, a collection
165       of such certificates is called a trust store.
166
167       Note that OpenSSL does not provide a default set of trust anchors.
168       Many Linux distributions include a system default and configure OpenSSL
169       to point to that.  Mozilla maintains an influential trust store that
170       can be found at
171       <https://www.mozilla.org/en-US/about/governance/policies/security-group/certs/>.
172
173       The certificates to add to the trust store can be specified using
174       following options.
175
176       -CAfile file
177           Load the specified file which contains a certificate or several of
178           them in case the input is in PEM or PKCS#12 format.  PEM-encoded
179           certificates may also have trust attributes set.
180
181       -no-CAfile
182           Do not load the default file of trusted certificates.
183
184       -CApath dir
185           Use the specified directory as a collection of trusted
186           certificates, i.e., a trust store.  Files should be named with the
187           hash value of the X.509 SubjectName of each certificate. This is so
188           that the library can extract the IssuerName, hash it, and directly
189           lookup the file to get the issuer certificate.  See
190           openssl-rehash(1) for information on creating this type of
191           directory.
192
193       -no-CApath
194           Do not use the default directory of trusted certificates.
195
196       -CAstore uri
197           Use uri as a store of CA certificates.  The URI may indicate a
198           single certificate, as well as a collection of them.  With URIs in
199           the "file:" scheme, this acts as -CAfile or -CApath, depending on
200           if the URI indicates a single file or directory.  See
201           ossl_store-file(7) for more information on the "file:" scheme.
202
203           These certificates are also used when building the server
204           certificate chain (for example with openssl-s_server(1)) or client
205           certificate chain (for example with openssl-s_time(1)).
206
207       -no-CAstore
208           Do not use the default store of trusted CA certificates.
209
210   Verification Options
211       The certificate verification can be fine-tuned with the following
212       flags.
213
214       -verbose
215           Print extra information about the operations being performed.
216
217       -attime timestamp
218           Perform validation checks using time specified by timestamp and not
219           current system time. timestamp is the number of seconds since
220           January 1, 1970 (i.e., the Unix Epoch).
221
222       -no_check_time
223           This option suppresses checking the validity period of certificates
224           and CRLs against the current time. If option -attime is used to
225           specify a verification time, the check is not suppressed.
226
227       -x509_strict
228           This disables non-compliant workarounds for broken certificates.
229           Thus errors are thrown on certificates not compliant with RFC 5280.
230
231           When this option is set, among others, the following certificate
232           well-formedness conditions are checked:
233
234           •   The basicConstraints of CA certificates must be marked
235               critical.
236
237           •   CA certificates must explicitly include the keyUsage extension.
238
239           •   If a pathlenConstraint is given the key usage keyCertSign must
240               be allowed.
241
242           •   The pathlenConstraint must not be given for non-CA
243               certificates.
244
245           •   The issuer name of any certificate must not be empty.
246
247           •   The subject name of CA certs, certs with keyUsage crlSign, and
248               certs without subjectAlternativeName must not be empty.
249
250           •   If a subjectAlternativeName extension is given it must not be
251               empty.
252
253           •   The signatureAlgorithm field and the cert signature must be
254               consistent.
255
256           •   Any given authorityKeyIdentifier and any given
257               subjectKeyIdentifier must not be marked critical.
258
259           •   The authorityKeyIdentifier must be given for X.509v3 certs
260               unless they are self-signed.
261
262           •   The subjectKeyIdentifier must be given for all X.509v3 CA
263               certs.
264
265       -ignore_critical
266           Normally if an unhandled critical extension is present that is not
267           supported by OpenSSL the certificate is rejected (as required by
268           RFC5280).  If this option is set critical extensions are ignored.
269
270       -issuer_checks
271           Ignored.
272
273       -crl_check
274           Checks end entity certificate validity by attempting to look up a
275           valid CRL.  If a valid CRL cannot be found an error occurs.
276
277       -crl_check_all
278           Checks the validity of all certificates in the chain by attempting
279           to look up valid CRLs.
280
281       -use_deltas
282           Enable support for delta CRLs.
283
284       -extended_crl
285           Enable extended CRL features such as indirect CRLs and alternate
286           CRL signing keys.
287
288       -suiteB_128_only, -suiteB_128, -suiteB_192
289           Enable the Suite B mode operation at 128 bit Level of Security, 128
290           bit or 192 bit, or only 192 bit Level of Security respectively.
291           See RFC6460 for details. In particular the supported signature
292           algorithms are reduced to support only ECDSA and SHA256 or SHA384
293           and only the elliptic curves P-256 and P-384.
294
295       -auth_level level
296           Set the certificate chain authentication security level to level.
297           The authentication security level determines the acceptable
298           signature and public key strength when verifying certificate
299           chains.  For a certificate chain to validate, the public keys of
300           all the certificates must meet the specified security level.  The
301           signature algorithm security level is enforced for all the
302           certificates in the chain except for the chain's trust anchor,
303           which is either directly trusted or validated by means other than
304           its signature.  See SSL_CTX_set_security_level(3) for the
305           definitions of the available levels.  The default security level is
306           -1, or "not set".  At security level 0 or lower all algorithms are
307           acceptable.  Security level 1 requires at least 80-bit-equivalent
308           security and is broadly interoperable, though it will, for example,
309           reject MD5 signatures or RSA keys shorter than 1024 bits.
310
311       -partial_chain
312           Allow verification to succeed if an incomplete chain can be built.
313           That is, a chain ending in a certificate that normally would not be
314           trusted (because it has no matching positive trust attributes and
315           is not self-signed) but is an element of the trust store.  This
316           certificate may be self-issued or belong to an intermediate CA.
317
318       -check_ss_sig
319           Verify the signature of the last certificate in a chain if the
320           certificate is supposedly self-signed.  This is prohibited and will
321           result in an error if it is a non-conforming CA certificate with
322           key usage restrictions not including the keyCertSign bit.  This
323           verification is disabled by default because it doesn't add any
324           security.
325
326       -allow_proxy_certs
327           Allow the verification of proxy certificates.
328
329       -trusted_first
330           As of OpenSSL 1.1.0 this option is on by default and cannot be
331           disabled.
332
333           When constructing the certificate chain, the trusted certificates
334           specified via -CAfile, -CApath, -CAstore or -trusted are always
335           used before any certificates specified via -untrusted.
336
337       -no_alt_chains
338           As of OpenSSL 1.1.0, since -trusted_first always on, this option
339           has no effect.
340
341       -trusted file
342           Parse file as a set of one or more certificates.  Each of them
343           qualifies as trusted if has a suitable positive trust attribute or
344           it is self-signed or the -partial_chain option is specified.  This
345           option implies the -no-CAfile, -no-CApath, and -no-CAstore options
346           and it cannot be used with the -CAfile, -CApath or -CAstore
347           options, so only certificates specified using the -trusted option
348           are trust anchors.  This option may be used multiple times.
349
350       -untrusted file
351           Parse file as a set of one or more certificates.  All certificates
352           (typically of intermediate CAs) are considered untrusted and may be
353           used to construct a certificate chain from the target certificate
354           to a trust anchor.  This option may be used multiple times.
355
356       -policy arg
357           Enable policy processing and add arg to the user-initial-policy-set
358           (see RFC5280). The policy arg can be an object name an OID in
359           numeric form.  This argument can appear more than once.
360
361       -explicit_policy
362           Set policy variable require-explicit-policy (see RFC5280).
363
364       -policy_check
365           Enables certificate policy processing.
366
367       -policy_print
368           Print out diagnostics related to policy processing.
369
370       -inhibit_any
371           Set policy variable inhibit-any-policy (see RFC5280).
372
373       -inhibit_map
374           Set policy variable inhibit-policy-mapping (see RFC5280).
375
376       -purpose purpose
377           The intended use for the certificate.  Currently defined purposes
378           are "sslclient", "sslserver", "nssslserver", "smimesign",
379           "smimeencrypt", "crlsign", "ocsphelper", "timestampsign", and
380           "any".  If peer certificate verification is enabled, by default the
381           TLS implementation as well as the commands s_client and s_server
382           check for consistency with TLS server or TLS client use,
383           respectively.
384
385           While IETF RFC 5280 says that id-kp-serverAuth and id-kp-clientAuth
386           are only for WWW use, in practice they are used for all kinds of
387           TLS clients and servers, and this is what OpenSSL assumes as well.
388
389       -verify_depth num
390           Limit the certificate chain to num intermediate CA certificates.  A
391           maximal depth chain can have up to num+2 certificates, since
392           neither the end-entity certificate nor the trust-anchor certificate
393           count against the -verify_depth limit.
394
395       -verify_email email
396           Verify if email matches the email address in Subject Alternative
397           Name or the email in the subject Distinguished Name.
398
399       -verify_hostname hostname
400           Verify if hostname matches DNS name in Subject Alternative Name or
401           Common Name in the subject certificate.
402
403       -verify_ip ip
404           Verify if ip matches the IP address in Subject Alternative Name of
405           the subject certificate.
406
407       -verify_name name
408           Use default verification policies like trust model and required
409           certificate policies identified by name.  The trust model
410           determines which auxiliary trust or reject OIDs are applicable to
411           verifying the given certificate chain.  They can be given using the
412           -addtrust and -addreject options for openssl-x509(1).  Supported
413           policy names include: default, pkcs7, smime_sign, ssl_client,
414           ssl_server.  These mimics the combinations of purpose and trust
415           settings used in SSL, CMS and S/MIME.  As of OpenSSL 1.1.0, the
416           trust model is inferred from the purpose when not specified, so the
417           -verify_name options are functionally equivalent to the
418           corresponding -purpose settings.
419
420   Extended Verification Options
421       Sometimes there may be more than one certificate chain leading to an
422       end-entity certificate.  This usually happens when a root or
423       intermediate CA signs a certificate for another a CA in other
424       organization.  Another reason is when a CA might have intermediates
425       that use two different signature formats, such as a SHA-1 and a SHA-256
426       digest.
427
428       The following options can be used to provide data that will allow the
429       OpenSSL command to generate an alternative chain.
430
431       -xkey infile, -xcert infile, -xchain
432           Specify an extra certificate, private key and certificate chain.
433           These behave in the same manner as the -cert, -key and -cert_chain
434           options.  When specified, the callback returning the first valid
435           chain will be in use by the client.
436
437       -xchain_build
438           Specify whether the application should build the certificate chain
439           to be provided to the server for the extra certificates via the
440           -xkey, -xcert, and -xchain options.
441
442       -xcertform DER|PEM|P12
443           The input format for the extra certificate.  This option has no
444           effect and is retained for backward compatibility only.
445
446       -xkeyform DER|PEM|P12
447           The input format for the extra key.  This option has no effect and
448           is retained for backward compatibility only.
449
450   Certificate Extensions
451       Options like -purpose lead to checking the certificate extensions,
452       which determine what the target certificate and intermediate CA
453       certificates can be used for.
454
455       Basic Constraints
456
457       The basicConstraints extension CA flag is used to determine whether the
458       certificate can be used as a CA. If the CA flag is true then it is a
459       CA, if the CA flag is false then it is not a CA. All CAs should have
460       the CA flag set to true.
461
462       If the basicConstraints extension is absent, which includes the case
463       that it is an X.509v1 certificate, then the certificate is considered
464       to be a "possible CA" and other extensions are checked according to the
465       intended use of the certificate.  The treatment of certificates without
466       basicConstraints as a CA is presently supported, but this could change
467       in the future.
468
469       Key Usage
470
471       If the keyUsage extension is present then additional restraints are
472       made on the uses of the certificate. A CA certificate must have the
473       keyCertSign bit set if the keyUsage extension is present.
474
475       Extended Key Usage
476
477       The extKeyUsage (EKU) extension places additional restrictions on the
478       certificate uses. If this extension is present (whether critical or
479       not) the key can only be used for the purposes specified.
480
481       A complete description of each check is given below. The comments about
482       basicConstraints and keyUsage and X.509v1 certificates above apply to
483       all CA certificates.
484
485       SSL Client
486           The extended key usage extension must be absent or include the "web
487           client authentication" OID.  The keyUsage extension must be absent
488           or it must have the digitalSignature bit set.  The Netscape
489           certificate type must be absent or it must have the SSL client bit
490           set.
491
492       SSL Client CA
493           The extended key usage extension must be absent or include the "web
494           client authentication" OID.  The Netscape certificate type must be
495           absent or it must have the SSL CA bit set.  This is used as a work
496           around if the basicConstraints extension is absent.
497
498       SSL Server
499           The extended key usage extension must be absent or include the "web
500           server authentication" and/or one of the SGC OIDs.  The keyUsage
501           extension must be absent or it must have the digitalSignature, the
502           keyEncipherment set or both bits set.  The Netscape certificate
503           type must be absent or have the SSL server bit set.
504
505       SSL Server CA
506           The extended key usage extension must be absent or include the "web
507           server authentication" and/or one of the SGC OIDs.  The Netscape
508           certificate type must be absent or the SSL CA bit must be set.
509           This is used as a work around if the basicConstraints extension is
510           absent.
511
512       Netscape SSL Server
513           For Netscape SSL clients to connect to an SSL server it must have
514           the keyEncipherment bit set if the keyUsage extension is present.
515           This isn't always valid because some cipher suites use the key for
516           digital signing.  Otherwise it is the same as a normal SSL server.
517
518       Common S/MIME Client Tests
519           The extended key usage extension must be absent or include the
520           "email protection" OID.  The Netscape certificate type must be
521           absent or should have the S/MIME bit set. If the S/MIME bit is not
522           set in the Netscape certificate type then the SSL client bit is
523           tolerated as an alternative but a warning is shown.  This is
524           because some Verisign certificates don't set the S/MIME bit.
525
526       S/MIME Signing
527           In addition to the common S/MIME client tests the digitalSignature
528           bit or the nonRepudiation bit must be set if the keyUsage extension
529           is present.
530
531       S/MIME Encryption
532           In addition to the common S/MIME tests the keyEncipherment bit must
533           be set if the keyUsage extension is present.
534
535       S/MIME CA
536           The extended key usage extension must be absent or include the
537           "email protection" OID.  The Netscape certificate type must be
538           absent or must have the S/MIME CA bit set.  This is used as a work
539           around if the basicConstraints extension is absent.
540
541       CRL Signing
542           The keyUsage extension must be absent or it must have the CRL
543           signing bit set.
544
545       CRL Signing CA
546           The normal CA tests apply. Except in this case the basicConstraints
547           extension must be present.
548

BUGS

550       The issuer checks still suffer from limitations in the underlying
551       X509_LOOKUP API.  One consequence of this is that trusted certificates
552       with matching subject name must appear in a file (as specified by the
553       -CAfile option), a directory (as specified by -CApath), or a store (as
554       specified by -CAstore).  If there are multiple such matches, possibly
555       in multiple locations, only the first one (in the mentioned order of
556       locations) is recognised.
557

SEE ALSO

559       X509_verify_cert(3), openssl-verify(1), openssl-ocsp(1), openssl-ts(1),
560       openssl-s_client(1), openssl-s_server(1), openssl-smime(1),
561       openssl-cmp(1), openssl-cms(1)
562

HISTORY

564       The checks enabled by -x509_strict have been extended in OpenSSL 3.0.
565
567       Copyright 2000-2021 The OpenSSL Project Authors. All Rights Reserved.
568
569       Licensed under the Apache License 2.0 (the "License").  You may not use
570       this file except in compliance with the License.  You can obtain a copy
571       in the file LICENSE in the source distribution or at
572       <https://www.openssl.org/source/license.html>.
573
574
575
5763.0.9                             2023-07-27OPENSSL-VERIFICATION-OPTIONS(1ossl)
Impressum