4 {- join("\n", @autowarntext) -}
10 openssl-verify - Utility to verify certificates
16 [B<-allow_proxy_certs>]
17 [B<-attime> I<timestamp>]
29 [B<-nameopt> I<option>]
35 [B<-purpose> I<purpose>]
41 [B<-untrusted> I<file>]
45 [B<-auth_level> I<level>]
46 [B<-verify_depth> I<num>]
47 [B<-verify_email> I<email>]
48 [B<-verify_hostname> I<hostname>]
50 [B<-verify_name> I<name>]
53 [B<-sm2-id> I<string>]
54 [B<-sm2-hex-id> I<hex-string>]
55 {- $OpenSSL::safe::opt_trust_synopsis -}
59 =for openssl ifdef engine sm2-id sm2-hex-id
63 This command verifies certificate chains.
71 Print out a usage message.
73 =item B<-allow_proxy_certs>
75 Allow the verification of proxy certificates.
77 =item B<-attime> I<timestamp>
79 Perform validation checks using time specified by I<timestamp> and not
80 current system time. I<timestamp> is the number of seconds since
81 01.01.1970 (UNIX time).
83 =item B<-check_ss_sig>
85 Verify the signature on the self-signed root CA. This is disabled by default
86 because it doesn't add any security.
88 =item B<-CRLfile> I<file>
90 The I<file> should contain one or more CRLs in PEM format.
91 This option can be specified more than once to include CRLs from multiple
94 =item B<-crl_download>
96 Attempt to download CRL information for this certificate.
100 Checks end entity certificate validity by attempting to look up a valid CRL.
101 If a valid CRL cannot be found an error occurs.
103 =item B<-crl_check_all>
105 Checks the validity of B<all> certificates in the chain by attempting
106 to look up valid CRLs.
108 =item B<-engine> I<id>
110 Specifying an engine I<id> will cause this command to attempt to load the
112 The engine will then be set as the default for all its supported algorithms.
113 If you want to load certificates or CRLs that require engine support via any of
114 the B<-trusted>, B<-untrusted> or B<-CRLfile> options, the B<-engine> option
115 must be specified before those options.
117 =item B<-explicit_policy>
119 Set policy variable require-explicit-policy (see RFC5280).
121 =item B<-extended_crl>
123 Enable extended CRL features such as indirect CRLs and alternate CRL
126 =item B<-ignore_critical>
128 Normally if an unhandled critical extension is present which is not
129 supported by OpenSSL the certificate is rejected (as required by RFC5280).
130 If this option is set critical extensions are ignored.
132 =item B<-inhibit_any>
134 Set policy variable inhibit-any-policy (see RFC5280).
136 =item B<-inhibit_map>
138 Set policy variable inhibit-policy-mapping (see RFC5280).
140 =item B<-nameopt> I<option>
142 Option which determines how the subject or issuer names are displayed. The
143 I<option> argument can be a single option or multiple options separated by
144 commas. Alternatively the B<-nameopt> switch may be used more than once to
145 set multiple options. See the L<openssl-x509(1)> manual page for details.
147 =item B<-no_check_time>
149 This option suppresses checking the validity period of certificates and CRLs
150 against the current time. If option B<-attime> is used to specify
151 a verification time, the check is not suppressed.
153 =item B<-partial_chain>
155 Allow verification to succeed even if a I<complete> chain cannot be built to a
156 self-signed trust-anchor, provided it is possible to construct a chain to a
157 trusted certificate that might not be self-signed.
159 =item B<-policy> I<arg>
161 Enable policy processing and add I<arg> to the user-initial-policy-set (see
162 RFC5280). The policy I<arg> can be an object name an OID in numeric form.
163 This argument can appear more than once.
165 =item B<-policy_check>
167 Enables certificate policy processing.
169 =item B<-policy_print>
171 Print out diagnostics related to policy processing.
173 =item B<-purpose> I<purpose>
175 The intended use for the certificate. If this option is not specified,
176 this command will not consider certificate purpose during chain
178 Currently accepted uses are B<sslclient>, B<sslserver>, B<nssslserver>,
179 B<smimesign>, B<smimeencrypt>. See the L</VERIFY OPERATION> section for more
182 =item B<-suiteB_128_only>, B<-suiteB_128>, B<-suiteB_192>
184 Enable the Suite B mode operation at 128 bit Level of Security, 128 bit or
185 192 bit, or only 192 bit Level of Security respectively.
186 See RFC6460 for details. In particular the supported signature algorithms are
187 reduced to support only ECDSA and SHA256 or SHA384 and only the elliptic curves
190 =item B<-trusted_first>
192 When constructing the certificate chain, use the trusted certificates specified
193 via B<-CAfile>, B<-CApath>, B<-CAstore> or B<-trusted> before any certificates
194 specified via B<-untrusted>.
195 This can be useful in environments with Bridge or Cross-Certified CAs.
196 As of OpenSSL 1.1.0 this option is on by default and cannot be disabled.
198 =item B<-no_alt_chains>
200 By default, unless B<-trusted_first> is specified, when building a certificate
201 chain, if the first certificate chain found is not trusted, then OpenSSL will
202 attempt to replace untrusted issuer certificates with certificates from the
203 trust store to see if an alternative chain can be found that is trusted.
204 As of OpenSSL 1.1.0, with B<-trusted_first> always on, this option has no
207 =item B<-untrusted> I<file>
209 A I<file> of additional untrusted certificates (intermediate issuer CAs) used
210 to construct a certificate chain from the subject certificate to a trust-anchor.
211 The I<file> should contain one or more certificates in PEM format.
212 This option can be specified more than once to include untrusted certificates
213 from multiple I<file>s.
215 =item B<-trusted> I<file>
217 A I<file> of trusted certificates, which must be self-signed, unless the
218 B<-partial_chain> option is specified.
219 The I<file> contains one or more certificates in PEM format.
220 With this option, no additional (e.g., default) certificate lists are
222 That is, the only trust-anchors are those listed in I<file>.
223 This option can be specified more than once to include trusted certificates
224 from multiple I<file>s.
225 This option implies the B<-no-CAfile>, B<-no-CApath> and B<-no-CAstore> options.
226 This option cannot be used in combination with any of the B<-CAfile>,
227 B<-CApath> or B<-CAstore> options.
231 Enable support for delta CRLs.
235 Print extra information about the operations being performed.
237 =item B<-auth_level> I<level>
239 Set the certificate chain authentication security level to I<level>.
240 The authentication security level determines the acceptable signature and
241 public key strength when verifying certificate chains.
242 For a certificate chain to validate, the public keys of all the certificates
243 must meet the specified security I<level>.
244 The signature algorithm security level is enforced for all the certificates in
245 the chain except for the chain's I<trust anchor>, which is either directly
246 trusted or validated by means other than its signature.
247 See L<SSL_CTX_set_security_level(3)> for the definitions of the available
249 The default security level is -1, or "not set".
250 At security level 0 or lower all algorithms are acceptable.
251 Security level 1 requires at least 80-bit-equivalent security and is broadly
252 interoperable, though it will, for example, reject MD5 signatures or RSA keys
253 shorter than 1024 bits.
255 =item B<-verify_depth> I<num>
257 Limit the certificate chain to I<num> intermediate CA certificates.
258 A maximal depth chain can have up to I<num>+2 certificates, since neither the
259 end-entity certificate nor the trust-anchor certificate count against the
260 B<-verify_depth> limit.
262 =item B<-verify_email> I<email>
264 Verify if I<email> matches the email address in Subject Alternative Name or
265 the email in the subject Distinguished Name.
267 =item B<-verify_hostname> I<hostname>
269 Verify if I<hostname> matches DNS name in Subject Alternative Name or
270 Common Name in the subject certificate.
272 =item B<-verify_ip> I<ip>
274 Verify if I<ip> matches the IP address in Subject Alternative Name of
275 the subject certificate.
277 =item B<-verify_name> I<name>
279 Use default verification policies like trust model and required certificate
280 policies identified by I<name>.
281 The trust model determines which auxiliary trust or reject OIDs are applicable
282 to verifying the given certificate chain.
283 See the B<-addtrust> and B<-addreject> options for L<openssl-x509(1)>.
284 Supported policy names include: B<default>, B<pkcs7>, B<smime_sign>,
285 B<ssl_client>, B<ssl_server>.
286 These mimics the combinations of purpose and trust settings used in SSL, CMS
288 As of OpenSSL 1.1.0, the trust model is inferred from the purpose when not
289 specified, so the B<-verify_name> options are functionally equivalent to the
290 corresponding B<-purpose> settings.
292 =item B<-x509_strict>
294 For strict X.509 compliance, disable non-compliant workarounds for broken
299 Display information about the certificate chain that has been built (if
300 successful). Certificates in the chain that came from the untrusted list will be
301 flagged as "untrusted".
305 Specify the ID string to use when verifying an SM2 certificate. The ID string is
306 required by the SM2 signature algorithm for signing and verification.
310 Specify a binary ID string to use when signing or verifying using an SM2
311 certificate. The argument for this option is string of hexadecimal digits.
315 Indicates the last option. All arguments following this are assumed to be
316 certificate files. This is useful if the first certificate filename begins
319 {- $OpenSSL::safe::opt_trust_item -}
321 =item I<certificate> ...
323 One or more certificates to verify. If no certificates are given,
324 this command will attempt to read a certificate from standard input.
325 Certificates must be in PEM format.
329 =head1 VERIFY OPERATION
331 This command uses the same functions as the internal SSL
332 and S/MIME verification, therefore this description applies to these verify
335 There is one crucial difference between the verify operations performed
336 by this command: wherever possible an attempt is made to
337 continue after an error whereas normally the verify operation would halt on
338 the first error. This allows all the problems with a certificate chain to be
341 The verify operation consists of a number of separate steps.
343 Firstly a certificate chain is built up starting from the supplied certificate
344 and ending in the root CA.
345 It is an error if the whole chain cannot be built up.
346 The chain is built up by looking up the issuers certificate of the current
348 If a certificate is found which is its own issuer it is assumed to be the root
351 The process of 'looking up the issuers certificate' itself involves a number of
353 After all certificates whose subject name matches the issuer name of the current
354 certificate are subject to further tests.
355 The relevant authority key identifier components of the current certificate (if
356 present) must match the subject key identifier (if present) and issuer and
357 serial number of the candidate issuer, in addition the keyUsage extension of
358 the candidate issuer (if present) must permit certificate signing.
360 The lookup first looks in the list of untrusted certificates and if no match
361 is found the remaining lookups are from the trusted certificates. The root CA
362 is always looked up in the trusted certificate list: if the certificate to
363 verify is a root certificate then an exact match must be found in the trusted
366 The second operation is to check every untrusted certificate's extensions for
367 consistency with the supplied purpose. If the B<-purpose> option is not included
368 then no checks are done. The supplied or "leaf" certificate must have extensions
369 compatible with the supplied purpose and all other certificates must also be
370 valid CA certificates. The precise extensions required are described in more
371 detail in L<openssl-x509(1)/CERTIFICATE EXTENSIONS>.
373 The third operation is to check the trust settings on the root CA. The root CA
374 should be trusted for the supplied purpose.
375 For compatibility with previous versions of OpenSSL, a certificate with no
376 trust settings is considered to be valid for all purposes.
378 The final operation is to check the validity of the certificate chain. The
379 validity period is checked against the current system time and the notBefore
380 and notAfter dates in the certificate. The certificate signatures are also
381 checked at this point.
383 If all operations complete successfully then certificate is considered valid. If
384 any operation fails then the certificate is not valid.
388 When a verify operation fails the output messages can be somewhat cryptic. The
389 general form of the error message is:
391 server.pem: /C=AU/ST=Queensland/O=CryptSoft Pty Ltd/CN=Test CA (1024 bit)
392 error 24 at 1 depth lookup:invalid CA certificate
394 The first line contains the name of the certificate being verified followed by
395 the subject name of the certificate. The second line contains the error number
396 and the depth. The depth is number of the certificate being verified when a
397 problem was detected starting with zero for the certificate being verified itself
398 then 1 for the CA that signed the certificate and so on. Finally a text version
399 of the error number is presented.
401 A partial list of the error codes and messages is shown below, this also
402 includes the name of the error code as defined in the header file
403 F<< <openssl/x509_vfy.h> >>.
404 Some of the error codes are defined but never returned: these are described
411 The operation was successful.
413 =item B<X509_V_ERR_UNSPECIFIED>
415 Unspecified error; should not happen.
417 =item B<X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT>
419 The issuer certificate of a looked up certificate could not be found. This
420 normally means the list of trusted certificates is not complete.
422 =item B<X509_V_ERR_UNABLE_TO_GET_CRL>
424 The CRL of a certificate could not be found.
426 =item B<X509_V_ERR_UNABLE_TO_DECRYPT_CERT_SIGNATURE>
428 The certificate signature could not be decrypted. This means that the
429 actual signature value could not be determined rather than it not matching
430 the expected value, this is only meaningful for RSA keys.
432 =item B<X509_V_ERR_UNABLE_TO_DECRYPT_CRL_SIGNATURE>
434 The CRL signature could not be decrypted: this means that the actual
435 signature value could not be determined rather than it not matching the
436 expected value. Unused.
438 =item B<X509_V_ERR_UNABLE_TO_DECODE_ISSUER_PUBLIC_KEY>
440 The public key in the certificate SubjectPublicKeyInfo could not be read.
442 =item B<X509_V_ERR_CERT_SIGNATURE_FAILURE>
444 The signature of the certificate is invalid.
446 =item B<X509_V_ERR_CRL_SIGNATURE_FAILURE>
448 The signature of the certificate is invalid.
450 =item B<X509_V_ERR_CERT_NOT_YET_VALID>
452 The certificate is not yet valid: the notBefore date is after the
455 =item B<X509_V_ERR_CERT_HAS_EXPIRED>
457 The certificate has expired: that is the notAfter date is before the
460 =item B<X509_V_ERR_CRL_NOT_YET_VALID>
462 The CRL is not yet valid.
464 =item B<X509_V_ERR_CRL_HAS_EXPIRED>
468 =item B<X509_V_ERR_ERROR_IN_CERT_NOT_BEFORE_FIELD>
470 The certificate notBefore field contains an invalid time.
472 =item B<X509_V_ERR_ERROR_IN_CERT_NOT_AFTER_FIELD>
474 The certificate notAfter field contains an invalid time.
476 =item B<X509_V_ERR_ERROR_IN_CRL_LAST_UPDATE_FIELD>
478 The CRL lastUpdate field contains an invalid time.
480 =item B<X509_V_ERR_ERROR_IN_CRL_NEXT_UPDATE_FIELD>
482 The CRL nextUpdate field contains an invalid time.
484 =item B<X509_V_ERR_OUT_OF_MEM>
486 An error occurred trying to allocate memory. This should never happen.
488 =item B<X509_V_ERR_DEPTH_ZERO_SELF_SIGNED_CERT>
490 The passed certificate is self-signed and the same certificate cannot
491 be found in the list of trusted certificates.
493 =item B<X509_V_ERR_SELF_SIGNED_CERT_IN_CHAIN>
495 The certificate chain could be built up using the untrusted certificates
496 but the root could not be found locally.
498 =item B<X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY>
500 The issuer certificate could not be found: this occurs if the issuer
501 certificate of an untrusted certificate cannot be found.
503 =item B<X509_V_ERR_UNABLE_TO_VERIFY_LEAF_SIGNATURE>
505 No signatures could be verified because the chain contains only one
506 certificate and it is not self signed.
508 =item B<X509_V_ERR_CERT_CHAIN_TOO_LONG>
510 The certificate chain length is greater than the supplied maximum
513 =item B<X509_V_ERR_CERT_REVOKED>
515 The certificate has been revoked.
517 =item B<X509_V_ERR_INVALID_CA>
519 A CA certificate is invalid. Either it is not a CA or its extensions
520 are not consistent with the supplied purpose.
522 =item B<X509_V_ERR_PATH_LENGTH_EXCEEDED>
524 The basicConstraints pathlength parameter has been exceeded.
526 =item B<X509_V_ERR_INVALID_PURPOSE>
528 The supplied certificate cannot be used for the specified purpose.
530 =item B<X509_V_ERR_CERT_UNTRUSTED>
532 The root CA is not marked as trusted for the specified purpose.
534 =item B<X509_V_ERR_CERT_REJECTED>
536 The root CA is marked to reject the specified purpose.
538 =item B<X509_V_ERR_SUBJECT_ISSUER_MISMATCH>
540 Not used as of OpenSSL 1.1.0 as a result of the deprecation of the
541 B<-issuer_checks> option.
543 =item B<X509_V_ERR_AKID_SKID_MISMATCH>
545 Not used as of OpenSSL 1.1.0 as a result of the deprecation of the
546 B<-issuer_checks> option.
548 =item B<X509_V_ERR_AKID_ISSUER_SERIAL_MISMATCH>
550 Not used as of OpenSSL 1.1.0 as a result of the deprecation of the
551 B<-issuer_checks> option.
553 =item B<X509_V_ERR_KEYUSAGE_NO_CERTSIGN>
555 Not used as of OpenSSL 1.1.0 as a result of the deprecation of the
556 B<-issuer_checks> option.
558 =item B<X509_V_ERR_UNABLE_TO_GET_CRL_ISSUER>
560 Unable to get CRL issuer certificate.
562 =item B<X509_V_ERR_UNHANDLED_CRITICAL_EXTENSION>
564 Unhandled critical extension.
566 =item B<X509_V_ERR_KEYUSAGE_NO_CRL_SIGN>
568 Key usage does not include CRL signing.
570 =item B<X509_V_ERR_UNHANDLED_CRITICAL_CRL_EXTENSION>
572 Unhandled critical CRL extension.
574 =item B<X509_V_ERR_INVALID_NON_CA>
576 Invalid non-CA certificate has CA markings.
578 =item B<X509_V_ERR_PROXY_PATH_LENGTH_EXCEEDED>
580 Proxy path length constraint exceeded.
582 =item B<X509_V_ERR_PROXY_SUBJECT_INVALID>
584 Proxy certificate subject is invalid. It MUST be the same as the issuer
585 with a single CN component added.
587 =item B<X509_V_ERR_KEYUSAGE_NO_DIGITAL_SIGNATURE>
589 Key usage does not include digital signature.
591 =item B<X509_V_ERR_PROXY_CERTIFICATES_NOT_ALLOWED>
593 Proxy certificates not allowed, please use B<-allow_proxy_certs>.
595 =item B<X509_V_ERR_INVALID_EXTENSION>
597 Invalid or inconsistent certificate extension.
599 =item B<X509_V_ERR_INVALID_POLICY_EXTENSION>
601 Invalid or inconsistent certificate policy extension.
603 =item B<X509_V_ERR_NO_EXPLICIT_POLICY>
607 =item B<X509_V_ERR_DIFFERENT_CRL_SCOPE>
611 =item B<X509_V_ERR_UNSUPPORTED_EXTENSION_FEATURE>
613 Unsupported extension feature.
615 =item B<X509_V_ERR_UNNESTED_RESOURCE>
617 RFC 3779 resource not subset of parent's resources.
619 =item B<X509_V_ERR_PERMITTED_VIOLATION>
621 Permitted subtree violation.
623 =item B<X509_V_ERR_EXCLUDED_VIOLATION>
625 Excluded subtree violation.
627 =item B<X509_V_ERR_SUBTREE_MINMAX>
629 Name constraints minimum and maximum not supported.
631 =item B<X509_V_ERR_APPLICATION_VERIFICATION>
633 Application verification failure. Unused.
635 =item B<X509_V_ERR_UNSUPPORTED_CONSTRAINT_TYPE>
637 Unsupported name constraint type.
639 =item B<X509_V_ERR_UNSUPPORTED_CONSTRAINT_SYNTAX>
641 Unsupported or invalid name constraint syntax.
643 =item B<X509_V_ERR_UNSUPPORTED_NAME_SYNTAX>
645 Unsupported or invalid name syntax.
647 =item B<X509_V_ERR_CRL_PATH_VALIDATION_ERROR>
649 CRL path validation error.
651 =item B<X509_V_ERR_PATH_LOOP>
655 =item B<X509_V_ERR_SUITE_B_INVALID_VERSION>
657 Suite B: certificate version invalid.
659 =item B<X509_V_ERR_SUITE_B_INVALID_ALGORITHM>
661 Suite B: invalid public key algorithm.
663 =item B<X509_V_ERR_SUITE_B_INVALID_CURVE>
665 Suite B: invalid ECC curve.
667 =item B<X509_V_ERR_SUITE_B_INVALID_SIGNATURE_ALGORITHM>
669 Suite B: invalid signature algorithm.
671 =item B<X509_V_ERR_SUITE_B_LOS_NOT_ALLOWED>
673 Suite B: curve not allowed for this LOS.
675 =item B<X509_V_ERR_SUITE_B_CANNOT_SIGN_P_384_WITH_P_256>
677 Suite B: cannot sign P-384 with P-256.
679 =item B<X509_V_ERR_HOSTNAME_MISMATCH>
683 =item B<X509_V_ERR_EMAIL_MISMATCH>
685 Email address mismatch.
687 =item B<X509_V_ERR_IP_ADDRESS_MISMATCH>
691 =item B<X509_V_ERR_DANE_NO_MATCH>
693 DANE TLSA authentication is enabled, but no TLSA records matched the
695 This error is only possible in L<openssl-s_client(1)>.
697 =item B<X509_V_ERR_EE_KEY_TOO_SMALL>
699 EE certificate key too weak.
701 =item B<X509_ERR_CA_KEY_TOO_SMALL>
703 CA certificate key too weak.
705 =item B<X509_ERR_CA_MD_TOO_WEAK>
707 CA signature digest algorithm too weak.
709 =item B<X509_V_ERR_INVALID_CALL>
711 nvalid certificate verification context.
713 =item B<X509_V_ERR_STORE_LOOKUP>
715 Issuer certificate lookup error.
717 =item B<X509_V_ERR_NO_VALID_SCTS>
719 Certificate Transparency required, but no valid SCTs found.
721 =item B<X509_V_ERR_PROXY_SUBJECT_NAME_VIOLATION>
723 Proxy subject name violation.
725 =item B<X509_V_ERR_OCSP_VERIFY_NEEDED>
727 Returned by the verify callback to indicate an OCSP verification is needed.
729 =item B<X509_V_ERR_OCSP_VERIFY_FAILED>
731 Returned by the verify callback to indicate OCSP verification failed.
733 =item B<X509_V_ERR_OCSP_CERT_UNKNOWN>
735 Returned by the verify callback to indicate that the certificate is not recognized
736 by the OCSP responder.
742 Although the issuer checks are a considerable improvement over the old
743 technique they still suffer from limitations in the underlying X509_LOOKUP
744 API. One consequence of this is that trusted certificates with matching
745 subject name must either appear in a file (as specified by the B<-CAfile>
746 option), a directory (as specified by B<-CApath>), or a store (as specified
747 by B<-CAstore>). If they occur in more than one location then only the
748 certificates in the file will be recognised.
750 Previous versions of OpenSSL assume certificates with matching subject
751 name are identical and mishandled them.
753 Previous versions of this documentation swapped the meaning of the
754 B<X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT> and
755 B<X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY> error codes.
761 L<ossl_store-file(7)>
765 The B<-show_chain> option was added in OpenSSL 1.1.0.
767 The B<-issuer_checks> option is deprecated as of OpenSSL 1.1.0 and
770 The B<-sm2-id> and B<-sm2-hex-id> options were added in OpenSSL 3.0.
774 Copyright 2000-2019 The OpenSSL Project Authors. All Rights Reserved.
776 Licensed under the Apache License 2.0 (the "License"). You may not use
777 this file except in compliance with the License. You can obtain a copy
778 in the file LICENSE in the source distribution or at
779 L<https://www.openssl.org/source/license.html>.