2 {- OpenSSL::safe::output_do_not_edit_headers(); -}
6 openssl-verify - Utility to verify certificates
12 [B<-allow_proxy_certs>]
13 [B<-attime> I<timestamp>]
30 [B<-purpose> I<purpose>]
36 [B<-untrusted> I<file>]
40 [B<-auth_level> I<level>]
41 [B<-verify_depth> I<num>]
42 [B<-verify_email> I<email>]
43 [B<-verify_hostname> I<hostname>]
45 [B<-verify_name> I<name>]
48 [B<-sm2-id> I<string>]
49 [B<-sm2-hex-id> I<hex-string>]
50 {- $OpenSSL::safe::opt_name_synopsis -}
51 {- $OpenSSL::safe::opt_trust_synopsis -}
55 =for openssl ifdef engine sm2-id sm2-hex-id
59 This command verifies certificate chains.
67 Print out a usage message.
69 =item B<-allow_proxy_certs>
71 Allow the verification of proxy certificates.
73 =item B<-attime> I<timestamp>
75 Perform validation checks using time specified by I<timestamp> and not
76 current system time. I<timestamp> is the number of seconds since
77 01.01.1970 (UNIX time).
79 =item B<-check_ss_sig>
81 Verify the signature on the self-signed root CA. This is disabled by default
82 because it doesn't add any security.
84 =item B<-CRLfile> I<file>
86 The I<file> should contain one or more CRLs in PEM format.
87 This option can be specified more than once to include CRLs from multiple
90 =item B<-crl_download>
92 Attempt to download CRL information for this certificate.
96 Checks end entity certificate validity by attempting to look up a valid CRL.
97 If a valid CRL cannot be found an error occurs.
99 =item B<-crl_check_all>
101 Checks the validity of B<all> certificates in the chain by attempting
102 to look up valid CRLs.
104 =item B<-engine> I<id>
106 Specifying an engine I<id> will cause this command to attempt to load the
108 The engine will then be set as the default for all its supported algorithms.
109 If you want to load certificates or CRLs that require engine support via any of
110 the B<-trusted>, B<-untrusted> or B<-CRLfile> options, the B<-engine> option
111 must be specified before those options.
113 =item B<-explicit_policy>
115 Set policy variable require-explicit-policy (see RFC5280).
117 =item B<-extended_crl>
119 Enable extended CRL features such as indirect CRLs and alternate CRL
122 =item B<-ignore_critical>
124 Normally if an unhandled critical extension is present which is not
125 supported by OpenSSL the certificate is rejected (as required by RFC5280).
126 If this option is set critical extensions are ignored.
128 =item B<-inhibit_any>
130 Set policy variable inhibit-any-policy (see RFC5280).
132 =item B<-inhibit_map>
134 Set policy variable inhibit-policy-mapping (see RFC5280).
136 =item B<-no_check_time>
138 This option suppresses checking the validity period of certificates and CRLs
139 against the current time. If option B<-attime> is used to specify
140 a verification time, the check is not suppressed.
142 =item B<-partial_chain>
144 Allow verification to succeed even if a I<complete> chain cannot be built to a
145 self-signed trust-anchor, provided it is possible to construct a chain to a
146 trusted certificate that might not be self-signed.
148 =item B<-policy> I<arg>
150 Enable policy processing and add I<arg> to the user-initial-policy-set (see
151 RFC5280). The policy I<arg> can be an object name an OID in numeric form.
152 This argument can appear more than once.
154 =item B<-policy_check>
156 Enables certificate policy processing.
158 =item B<-policy_print>
160 Print out diagnostics related to policy processing.
162 =item B<-purpose> I<purpose>
164 The intended use for the certificate. If this option is not specified,
165 this command will not consider certificate purpose during chain
167 Currently accepted uses are B<sslclient>, B<sslserver>, B<nssslserver>,
168 B<smimesign>, B<smimeencrypt>. See the L</VERIFY OPERATION> section for more
171 =item B<-suiteB_128_only>, B<-suiteB_128>, B<-suiteB_192>
173 Enable the Suite B mode operation at 128 bit Level of Security, 128 bit or
174 192 bit, or only 192 bit Level of Security respectively.
175 See RFC6460 for details. In particular the supported signature algorithms are
176 reduced to support only ECDSA and SHA256 or SHA384 and only the elliptic curves
179 =item B<-trusted_first>
181 When constructing the certificate chain, use the trusted certificates specified
182 via B<-CAfile>, B<-CApath>, B<-CAstore> or B<-trusted> before any certificates
183 specified via B<-untrusted>.
184 This can be useful in environments with Bridge or Cross-Certified CAs.
185 As of OpenSSL 1.1.0 this option is on by default and cannot be disabled.
187 =item B<-no_alt_chains>
189 By default, unless B<-trusted_first> is specified, when building a certificate
190 chain, if the first certificate chain found is not trusted, then OpenSSL will
191 attempt to replace untrusted issuer certificates with certificates from the
192 trust store to see if an alternative chain can be found that is trusted.
193 As of OpenSSL 1.1.0, with B<-trusted_first> always on, this option has no
196 =item B<-untrusted> I<file>
198 A I<file> of additional untrusted certificates (intermediate issuer CAs) used
199 to construct a certificate chain from the subject certificate to a trust-anchor.
200 The I<file> should contain one or more certificates in PEM format.
201 This option can be specified more than once to include untrusted certificates
202 from multiple I<file>s.
204 =item B<-trusted> I<file>
206 A I<file> of trusted certificates, which must be self-signed, unless the
207 B<-partial_chain> option is specified.
208 The I<file> contains one or more certificates in PEM format.
209 With this option, no additional (e.g., default) certificate lists are
211 That is, the only trust-anchors are those listed in I<file>.
212 This option can be specified more than once to include trusted certificates
213 from multiple I<file>s.
214 This option implies the B<-no-CAfile>, B<-no-CApath> and B<-no-CAstore> options.
215 This option cannot be used in combination with any of the B<-CAfile>,
216 B<-CApath> or B<-CAstore> options.
220 Enable support for delta CRLs.
224 Print extra information about the operations being performed.
226 =item B<-auth_level> I<level>
228 Set the certificate chain authentication security level to I<level>.
229 The authentication security level determines the acceptable signature and
230 public key strength when verifying certificate chains.
231 For a certificate chain to validate, the public keys of all the certificates
232 must meet the specified security I<level>.
233 The signature algorithm security level is enforced for all the certificates in
234 the chain except for the chain's I<trust anchor>, which is either directly
235 trusted or validated by means other than its signature.
236 See L<SSL_CTX_set_security_level(3)> for the definitions of the available
238 The default security level is -1, or "not set".
239 At security level 0 or lower all algorithms are acceptable.
240 Security level 1 requires at least 80-bit-equivalent security and is broadly
241 interoperable, though it will, for example, reject MD5 signatures or RSA keys
242 shorter than 1024 bits.
244 =item B<-verify_depth> I<num>
246 Limit the certificate chain to I<num> intermediate CA certificates.
247 A maximal depth chain can have up to I<num>+2 certificates, since neither the
248 end-entity certificate nor the trust-anchor certificate count against the
249 B<-verify_depth> limit.
251 =item B<-verify_email> I<email>
253 Verify if I<email> matches the email address in Subject Alternative Name or
254 the email in the subject Distinguished Name.
256 =item B<-verify_hostname> I<hostname>
258 Verify if I<hostname> matches DNS name in Subject Alternative Name or
259 Common Name in the subject certificate.
261 =item B<-verify_ip> I<ip>
263 Verify if I<ip> matches the IP address in Subject Alternative Name of
264 the subject certificate.
266 =item B<-verify_name> I<name>
268 Use default verification policies like trust model and required certificate
269 policies identified by I<name>.
270 The trust model determines which auxiliary trust or reject OIDs are applicable
271 to verifying the given certificate chain.
272 See the B<-addtrust> and B<-addreject> options for L<openssl-x509(1)>.
273 Supported policy names include: B<default>, B<pkcs7>, B<smime_sign>,
274 B<ssl_client>, B<ssl_server>.
275 These mimics the combinations of purpose and trust settings used in SSL, CMS
277 As of OpenSSL 1.1.0, the trust model is inferred from the purpose when not
278 specified, so the B<-verify_name> options are functionally equivalent to the
279 corresponding B<-purpose> settings.
281 =item B<-x509_strict>
283 For strict X.509 compliance, disable non-compliant workarounds for broken
288 Display information about the certificate chain that has been built (if
289 successful). Certificates in the chain that came from the untrusted list will be
290 flagged as "untrusted".
294 Specify the ID string to use when verifying an SM2 certificate. The ID string is
295 required by the SM2 signature algorithm for signing and verification.
299 Specify a binary ID string to use when signing or verifying using an SM2
300 certificate. The argument for this option is string of hexadecimal digits.
302 {- $OpenSSL::safe::opt_name_item -}
304 {- $OpenSSL::safe::opt_trust_item -}
308 Indicates the last option. All arguments following this are assumed to be
309 certificate files. This is useful if the first certificate filename begins
312 =item I<certificate> ...
314 One or more certificates to verify. If no certificates are given,
315 this command will attempt to read a certificate from standard input.
316 Certificates must be in PEM format.
320 =head1 VERIFY OPERATION
322 This command uses the same functions as the internal SSL
323 and S/MIME verification, therefore this description applies to these verify
326 There is one crucial difference between the verify operations performed
327 by this command: wherever possible an attempt is made to
328 continue after an error whereas normally the verify operation would halt on
329 the first error. This allows all the problems with a certificate chain to be
332 The verify operation consists of a number of separate steps.
334 Firstly a certificate chain is built up starting from the supplied certificate
335 and ending in the root CA.
336 It is an error if the whole chain cannot be built up.
337 The chain is built up by looking up the issuers certificate of the current
339 If a certificate is found which is its own issuer it is assumed to be the root
342 The process of 'looking up the issuers certificate' itself involves a number of
344 After all certificates whose subject name matches the issuer name of the current
345 certificate are subject to further tests.
346 The relevant authority key identifier components of the current certificate (if
347 present) must match the subject key identifier (if present) and issuer and
348 serial number of the candidate issuer, in addition the keyUsage extension of
349 the candidate issuer (if present) must permit certificate signing.
351 The lookup first looks in the list of untrusted certificates and if no match
352 is found the remaining lookups are from the trusted certificates. The root CA
353 is always looked up in the trusted certificate list: if the certificate to
354 verify is a root certificate then an exact match must be found in the trusted
357 The second operation is to check every untrusted certificate's extensions for
358 consistency with the supplied purpose. If the B<-purpose> option is not included
359 then no checks are done. The supplied or "leaf" certificate must have extensions
360 compatible with the supplied purpose and all other certificates must also be
361 valid CA certificates. The precise extensions required are described in more
362 detail in L<openssl-x509(1)/CERTIFICATE EXTENSIONS>.
364 The third operation is to check the trust settings on the root CA. The root CA
365 should be trusted for the supplied purpose.
366 For compatibility with previous versions of OpenSSL, a certificate with no
367 trust settings is considered to be valid for all purposes.
369 The final operation is to check the validity of the certificate chain. The
370 validity period is checked against the current system time and the notBefore
371 and notAfter dates in the certificate. The certificate signatures are also
372 checked at this point.
374 If all operations complete successfully then certificate is considered valid. If
375 any operation fails then the certificate is not valid.
379 When a verify operation fails the output messages can be somewhat cryptic. The
380 general form of the error message is:
382 server.pem: /C=AU/ST=Queensland/O=CryptSoft Pty Ltd/CN=Test CA (1024 bit)
383 error 24 at 1 depth lookup:invalid CA certificate
385 The first line contains the name of the certificate being verified followed by
386 the subject name of the certificate. The second line contains the error number
387 and the depth. The depth is number of the certificate being verified when a
388 problem was detected starting with zero for the certificate being verified itself
389 then 1 for the CA that signed the certificate and so on. Finally a text version
390 of the error number is presented.
392 A partial list of the error codes and messages is shown below, this also
393 includes the name of the error code as defined in the header file
394 F<< <openssl/x509_vfy.h> >>.
395 Some of the error codes are defined but never returned: these are described
402 The operation was successful.
404 =item B<X509_V_ERR_UNSPECIFIED>
406 Unspecified error; should not happen.
408 =item B<X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT>
410 The issuer certificate of a looked up certificate could not be found. This
411 normally means the list of trusted certificates is not complete.
413 =item B<X509_V_ERR_UNABLE_TO_GET_CRL>
415 The CRL of a certificate could not be found.
417 =item B<X509_V_ERR_UNABLE_TO_DECRYPT_CERT_SIGNATURE>
419 The certificate signature could not be decrypted. This means that the
420 actual signature value could not be determined rather than it not matching
421 the expected value, this is only meaningful for RSA keys.
423 =item B<X509_V_ERR_UNABLE_TO_DECRYPT_CRL_SIGNATURE>
425 The CRL signature could not be decrypted: this means that the actual
426 signature value could not be determined rather than it not matching the
427 expected value. Unused.
429 =item B<X509_V_ERR_UNABLE_TO_DECODE_ISSUER_PUBLIC_KEY>
431 The public key in the certificate SubjectPublicKeyInfo could not be read.
433 =item B<X509_V_ERR_CERT_SIGNATURE_FAILURE>
435 The signature of the certificate is invalid.
437 =item B<X509_V_ERR_CRL_SIGNATURE_FAILURE>
439 The signature of the certificate is invalid.
441 =item B<X509_V_ERR_CERT_NOT_YET_VALID>
443 The certificate is not yet valid: the notBefore date is after the
446 =item B<X509_V_ERR_CERT_HAS_EXPIRED>
448 The certificate has expired: that is the notAfter date is before the
451 =item B<X509_V_ERR_CRL_NOT_YET_VALID>
453 The CRL is not yet valid.
455 =item B<X509_V_ERR_CRL_HAS_EXPIRED>
459 =item B<X509_V_ERR_ERROR_IN_CERT_NOT_BEFORE_FIELD>
461 The certificate notBefore field contains an invalid time.
463 =item B<X509_V_ERR_ERROR_IN_CERT_NOT_AFTER_FIELD>
465 The certificate notAfter field contains an invalid time.
467 =item B<X509_V_ERR_ERROR_IN_CRL_LAST_UPDATE_FIELD>
469 The CRL lastUpdate field contains an invalid time.
471 =item B<X509_V_ERR_ERROR_IN_CRL_NEXT_UPDATE_FIELD>
473 The CRL nextUpdate field contains an invalid time.
475 =item B<X509_V_ERR_OUT_OF_MEM>
477 An error occurred trying to allocate memory. This should never happen.
479 =item B<X509_V_ERR_DEPTH_ZERO_SELF_SIGNED_CERT>
481 The passed certificate is self-signed and the same certificate cannot
482 be found in the list of trusted certificates.
484 =item B<X509_V_ERR_SELF_SIGNED_CERT_IN_CHAIN>
486 The certificate chain could be built up using the untrusted certificates
487 but the root could not be found locally.
489 =item B<X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY>
491 The issuer certificate could not be found: this occurs if the issuer
492 certificate of an untrusted certificate cannot be found.
494 =item B<X509_V_ERR_UNABLE_TO_VERIFY_LEAF_SIGNATURE>
496 No signatures could be verified because the chain contains only one
497 certificate and it is not self signed.
499 =item B<X509_V_ERR_CERT_CHAIN_TOO_LONG>
501 The certificate chain length is greater than the supplied maximum
504 =item B<X509_V_ERR_CERT_REVOKED>
506 The certificate has been revoked.
508 =item B<X509_V_ERR_INVALID_CA>
510 A CA certificate is invalid. Either it is not a CA or its extensions
511 are not consistent with the supplied purpose.
513 =item B<X509_V_ERR_PATH_LENGTH_EXCEEDED>
515 The basicConstraints pathlength parameter has been exceeded.
517 =item B<X509_V_ERR_INVALID_PURPOSE>
519 The supplied certificate cannot be used for the specified purpose.
521 =item B<X509_V_ERR_CERT_UNTRUSTED>
523 The root CA is not marked as trusted for the specified purpose.
525 =item B<X509_V_ERR_CERT_REJECTED>
527 The root CA is marked to reject the specified purpose.
529 =item B<X509_V_ERR_SUBJECT_ISSUER_MISMATCH>
531 Not used as of OpenSSL 1.1.0 as a result of the deprecation of the
532 B<-issuer_checks> option.
534 =item B<X509_V_ERR_AKID_SKID_MISMATCH>
536 Not used as of OpenSSL 1.1.0 as a result of the deprecation of the
537 B<-issuer_checks> option.
539 =item B<X509_V_ERR_AKID_ISSUER_SERIAL_MISMATCH>
541 Not used as of OpenSSL 1.1.0 as a result of the deprecation of the
542 B<-issuer_checks> option.
544 =item B<X509_V_ERR_KEYUSAGE_NO_CERTSIGN>
546 Not used as of OpenSSL 1.1.0 as a result of the deprecation of the
547 B<-issuer_checks> option.
549 =item B<X509_V_ERR_UNABLE_TO_GET_CRL_ISSUER>
551 Unable to get CRL issuer certificate.
553 =item B<X509_V_ERR_UNHANDLED_CRITICAL_EXTENSION>
555 Unhandled critical extension.
557 =item B<X509_V_ERR_KEYUSAGE_NO_CRL_SIGN>
559 Key usage does not include CRL signing.
561 =item B<X509_V_ERR_UNHANDLED_CRITICAL_CRL_EXTENSION>
563 Unhandled critical CRL extension.
565 =item B<X509_V_ERR_INVALID_NON_CA>
567 Invalid non-CA certificate has CA markings.
569 =item B<X509_V_ERR_PROXY_PATH_LENGTH_EXCEEDED>
571 Proxy path length constraint exceeded.
573 =item B<X509_V_ERR_PROXY_SUBJECT_INVALID>
575 Proxy certificate subject is invalid. It MUST be the same as the issuer
576 with a single CN component added.
578 =item B<X509_V_ERR_KEYUSAGE_NO_DIGITAL_SIGNATURE>
580 Key usage does not include digital signature.
582 =item B<X509_V_ERR_PROXY_CERTIFICATES_NOT_ALLOWED>
584 Proxy certificates not allowed, please use B<-allow_proxy_certs>.
586 =item B<X509_V_ERR_INVALID_EXTENSION>
588 Invalid or inconsistent certificate extension.
590 =item B<X509_V_ERR_INVALID_POLICY_EXTENSION>
592 Invalid or inconsistent certificate policy extension.
594 =item B<X509_V_ERR_NO_EXPLICIT_POLICY>
598 =item B<X509_V_ERR_DIFFERENT_CRL_SCOPE>
602 =item B<X509_V_ERR_UNSUPPORTED_EXTENSION_FEATURE>
604 Unsupported extension feature.
606 =item B<X509_V_ERR_UNNESTED_RESOURCE>
608 RFC 3779 resource not subset of parent's resources.
610 =item B<X509_V_ERR_PERMITTED_VIOLATION>
612 Permitted subtree violation.
614 =item B<X509_V_ERR_EXCLUDED_VIOLATION>
616 Excluded subtree violation.
618 =item B<X509_V_ERR_SUBTREE_MINMAX>
620 Name constraints minimum and maximum not supported.
622 =item B<X509_V_ERR_APPLICATION_VERIFICATION>
624 Application verification failure. Unused.
626 =item B<X509_V_ERR_UNSUPPORTED_CONSTRAINT_TYPE>
628 Unsupported name constraint type.
630 =item B<X509_V_ERR_UNSUPPORTED_CONSTRAINT_SYNTAX>
632 Unsupported or invalid name constraint syntax.
634 =item B<X509_V_ERR_UNSUPPORTED_NAME_SYNTAX>
636 Unsupported or invalid name syntax.
638 =item B<X509_V_ERR_CRL_PATH_VALIDATION_ERROR>
640 CRL path validation error.
642 =item B<X509_V_ERR_PATH_LOOP>
646 =item B<X509_V_ERR_SUITE_B_INVALID_VERSION>
648 Suite B: certificate version invalid.
650 =item B<X509_V_ERR_SUITE_B_INVALID_ALGORITHM>
652 Suite B: invalid public key algorithm.
654 =item B<X509_V_ERR_SUITE_B_INVALID_CURVE>
656 Suite B: invalid ECC curve.
658 =item B<X509_V_ERR_SUITE_B_INVALID_SIGNATURE_ALGORITHM>
660 Suite B: invalid signature algorithm.
662 =item B<X509_V_ERR_SUITE_B_LOS_NOT_ALLOWED>
664 Suite B: curve not allowed for this LOS.
666 =item B<X509_V_ERR_SUITE_B_CANNOT_SIGN_P_384_WITH_P_256>
668 Suite B: cannot sign P-384 with P-256.
670 =item B<X509_V_ERR_HOSTNAME_MISMATCH>
674 =item B<X509_V_ERR_EMAIL_MISMATCH>
676 Email address mismatch.
678 =item B<X509_V_ERR_IP_ADDRESS_MISMATCH>
682 =item B<X509_V_ERR_DANE_NO_MATCH>
684 DANE TLSA authentication is enabled, but no TLSA records matched the
686 This error is only possible in L<openssl-s_client(1)>.
688 =item B<X509_V_ERR_EE_KEY_TOO_SMALL>
690 EE certificate key too weak.
692 =item B<X509_ERR_CA_KEY_TOO_SMALL>
694 CA certificate key too weak.
696 =item B<X509_ERR_CA_MD_TOO_WEAK>
698 CA signature digest algorithm too weak.
700 =item B<X509_V_ERR_INVALID_CALL>
702 nvalid certificate verification context.
704 =item B<X509_V_ERR_STORE_LOOKUP>
706 Issuer certificate lookup error.
708 =item B<X509_V_ERR_NO_VALID_SCTS>
710 Certificate Transparency required, but no valid SCTs found.
712 =item B<X509_V_ERR_PROXY_SUBJECT_NAME_VIOLATION>
714 Proxy subject name violation.
716 =item B<X509_V_ERR_OCSP_VERIFY_NEEDED>
718 Returned by the verify callback to indicate an OCSP verification is needed.
720 =item B<X509_V_ERR_OCSP_VERIFY_FAILED>
722 Returned by the verify callback to indicate OCSP verification failed.
724 =item B<X509_V_ERR_OCSP_CERT_UNKNOWN>
726 Returned by the verify callback to indicate that the certificate is not recognized
727 by the OCSP responder.
733 Although the issuer checks are a considerable improvement over the old
734 technique they still suffer from limitations in the underlying X509_LOOKUP
735 API. One consequence of this is that trusted certificates with matching
736 subject name must either appear in a file (as specified by the B<-CAfile>
737 option), a directory (as specified by B<-CApath>), or a store (as specified
738 by B<-CAstore>). If they occur in more than one location then only the
739 certificates in the file will be recognised.
741 Previous versions of OpenSSL assume certificates with matching subject
742 name are identical and mishandled them.
744 Previous versions of this documentation swapped the meaning of the
745 B<X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT> and
746 B<X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY> error codes.
752 L<ossl_store-file(7)>
756 The B<-show_chain> option was added in OpenSSL 1.1.0.
758 The B<-issuer_checks> option is deprecated as of OpenSSL 1.1.0 and
761 The B<-sm2-id> and B<-sm2-hex-id> options were added in OpenSSL 3.0.
765 Copyright 2000-2019 The OpenSSL Project Authors. All Rights Reserved.
767 Licensed under the Apache License 2.0 (the "License"). You may not use
768 this file except in compliance with the License. You can obtain a copy
769 in the file LICENSE in the source distribution or at
770 L<https://www.openssl.org/source/license.html>.