5 openssl-verify - Utility to verify certificates
12 [B<-CApath> I<directory>]
15 [B<-allow_proxy_certs>]
16 [B<-attime> I<timestamp>]
28 [B<-nameopt> I<option>]
34 [B<-purpose> I<purpose>]
40 [B<-untrusted> I<file>]
44 [B<-auth_level> I<level>]
45 [B<-verify_depth> I<num>]
46 [B<-verify_email> I<email>]
47 [B<-verify_hostname> I<hostname>]
49 [B<-verify_name> I<name>]
52 [B<-sm2-id> I<string>]
53 [B<-sm2-hex-id> I<hex-string>]
57 =for openssl ifdef engine sm2-id sm2-hex-id
61 This command verifies certificate chains.
69 Print out a usage message.
71 =item B<-CAfile> I<file>, B<-no-CAfile>, B<-CApath> I<dir>, B<-no-CApath>
73 See L<openssl(1)/Trusted Certificate Options> for more information.
75 =item B<-allow_proxy_certs>
77 Allow the verification of proxy certificates.
79 =item B<-attime> I<timestamp>
81 Perform validation checks using time specified by I<timestamp> and not
82 current system time. I<timestamp> is the number of seconds since
83 01.01.1970 (UNIX time).
85 =item B<-check_ss_sig>
87 Verify the signature on the self-signed root CA. This is disabled by default
88 because it doesn't add any security.
90 =item B<-CRLfile> I<file>
92 The I<file> should contain one or more CRLs in PEM format.
93 This option can be specified more than once to include CRLs from multiple
96 =item B<-crl_download>
98 Attempt to download CRL information for this certificate.
102 Checks end entity certificate validity by attempting to look up a valid CRL.
103 If a valid CRL cannot be found an error occurs.
105 =item B<-crl_check_all>
107 Checks the validity of B<all> certificates in the chain by attempting
108 to look up valid CRLs.
110 =item B<-engine> I<id>
112 Specifying an engine I<id> will cause this command to attempt to load the
114 The engine will then be set as the default for all its supported algorithms.
115 If you want to load certificates or CRLs that require engine support via any of
116 the B<-trusted>, B<-untrusted> or B<-CRLfile> options, the B<-engine> option
117 must be specified before those options.
119 =item B<-explicit_policy>
121 Set policy variable require-explicit-policy (see RFC5280).
123 =item B<-extended_crl>
125 Enable extended CRL features such as indirect CRLs and alternate CRL
128 =item B<-ignore_critical>
130 Normally if an unhandled critical extension is present which is not
131 supported by OpenSSL the certificate is rejected (as required by RFC5280).
132 If this option is set critical extensions are ignored.
134 =item B<-inhibit_any>
136 Set policy variable inhibit-any-policy (see RFC5280).
138 =item B<-inhibit_map>
140 Set policy variable inhibit-policy-mapping (see RFC5280).
142 =item B<-nameopt> I<option>
144 Option which determines how the subject or issuer names are displayed. The
145 I<option> argument can be a single option or multiple options separated by
146 commas. Alternatively the B<-nameopt> switch may be used more than once to
147 set multiple options. See the L<openssl-x509(1)> manual page for details.
149 =item B<-no_check_time>
151 This option suppresses checking the validity period of certificates and CRLs
152 against the current time. If option B<-attime> is used to specify
153 a verification time, the check is not suppressed.
155 =item B<-partial_chain>
157 Allow verification to succeed even if a I<complete> chain cannot be built to a
158 self-signed trust-anchor, provided it is possible to construct a chain to a
159 trusted certificate that might not be self-signed.
161 =item B<-policy> I<arg>
163 Enable policy processing and add I<arg> to the user-initial-policy-set (see
164 RFC5280). The policy I<arg> can be an object name an OID in numeric form.
165 This argument can appear more than once.
167 =item B<-policy_check>
169 Enables certificate policy processing.
171 =item B<-policy_print>
173 Print out diagnostics related to policy processing.
175 =item B<-purpose> I<purpose>
177 The intended use for the certificate. If this option is not specified,
178 this command will not consider certificate purpose during chain
180 Currently accepted uses are B<sslclient>, B<sslserver>, B<nssslserver>,
181 B<smimesign>, B<smimeencrypt>. See the L</VERIFY OPERATION> section for more
184 =item B<-suiteB_128_only>, B<-suiteB_128>, B<-suiteB_192>
186 Enable the Suite B mode operation at 128 bit Level of Security, 128 bit or
187 192 bit, or only 192 bit Level of Security respectively.
188 See RFC6460 for details. In particular the supported signature algorithms are
189 reduced to support only ECDSA and SHA256 or SHA384 and only the elliptic curves
192 =item B<-trusted_first>
194 When constructing the certificate chain, use the trusted certificates specified
195 via B<-CAfile>, B<-CApath> or B<-trusted> before any certificates specified via
197 This can be useful in environments with Bridge or Cross-Certified CAs.
198 As of OpenSSL 1.1.0 this option is on by default and cannot be disabled.
200 =item B<-no_alt_chains>
202 By default, unless B<-trusted_first> is specified, when building a certificate
203 chain, if the first certificate chain found is not trusted, then OpenSSL will
204 attempt to replace untrusted issuer certificates with certificates from the
205 trust store to see if an alternative chain can be found that is trusted.
206 As of OpenSSL 1.1.0, with B<-trusted_first> always on, this option has no
209 =item B<-untrusted> I<file>
211 A I<file> of additional untrusted certificates (intermediate issuer CAs) used
212 to construct a certificate chain from the subject certificate to a trust-anchor.
213 The I<file> should contain one or more certificates in PEM format.
214 This option can be specified more than once to include untrusted certificates
215 from multiple I<file>s.
217 =item B<-trusted> I<file>
219 A I<file> of trusted certificates, which must be self-signed, unless the
220 B<-partial_chain> option is specified.
221 The I<file> contains one or more certificates in PEM format.
222 With this option, no additional (e.g., default) certificate lists are
224 That is, the only trust-anchors are those listed in I<file>.
225 This option can be specified more than once to include trusted certificates
226 from multiple I<file>s.
227 This option implies the B<-no-CAfile> and B<-no-CApath> options.
228 This option cannot be used in combination with either of the B<-CAfile> or
233 Enable support for delta CRLs.
237 Print extra information about the operations being performed.
239 =item B<-auth_level> I<level>
241 Set the certificate chain authentication security level to I<level>.
242 The authentication security level determines the acceptable signature and
243 public key strength when verifying certificate chains.
244 For a certificate chain to validate, the public keys of all the certificates
245 must meet the specified security I<level>.
246 The signature algorithm security level is enforced for all the certificates in
247 the chain except for the chain's I<trust anchor>, which is either directly
248 trusted or validated by means other than its signature.
249 See L<SSL_CTX_set_security_level(3)> for the definitions of the available
251 The default security level is -1, or "not set".
252 At security level 0 or lower all algorithms are acceptable.
253 Security level 1 requires at least 80-bit-equivalent security and is broadly
254 interoperable, though it will, for example, reject MD5 signatures or RSA keys
255 shorter than 1024 bits.
257 =item B<-verify_depth> I<num>
259 Limit the certificate chain to I<num> intermediate CA certificates.
260 A maximal depth chain can have up to I<num>+2 certificates, since neither the
261 end-entity certificate nor the trust-anchor certificate count against the
262 B<-verify_depth> limit.
264 =item B<-verify_email> I<email>
266 Verify if I<email> matches the email address in Subject Alternative Name or
267 the email in the subject Distinguished Name.
269 =item B<-verify_hostname> I<hostname>
271 Verify if I<hostname> matches DNS name in Subject Alternative Name or
272 Common Name in the subject certificate.
274 =item B<-verify_ip> I<ip>
276 Verify if I<ip> matches the IP address in Subject Alternative Name of
277 the subject certificate.
279 =item B<-verify_name> I<name>
281 Use default verification policies like trust model and required certificate
282 policies identified by I<name>.
283 The trust model determines which auxiliary trust or reject OIDs are applicable
284 to verifying the given certificate chain.
285 See the B<-addtrust> and B<-addreject> options for L<openssl-x509(1)>.
286 Supported policy names include: B<default>, B<pkcs7>, B<smime_sign>,
287 B<ssl_client>, B<ssl_server>.
288 These mimics the combinations of purpose and trust settings used in SSL, CMS
290 As of OpenSSL 1.1.0, the trust model is inferred from the purpose when not
291 specified, so the B<-verify_name> options are functionally equivalent to the
292 corresponding B<-purpose> settings.
294 =item B<-x509_strict>
296 For strict X.509 compliance, disable non-compliant workarounds for broken
301 Display information about the certificate chain that has been built (if
302 successful). Certificates in the chain that came from the untrusted list will be
303 flagged as "untrusted".
307 Specify the ID string to use when verifying an SM2 certificate. The ID string is
308 required by the SM2 signature algorithm for signing and verification.
312 Specify a binary ID string to use when signing or verifying using an SM2
313 certificate. The argument for this option is string of hexadecimal digits.
317 Indicates the last option. All arguments following this are assumed to be
318 certificate files. This is useful if the first certificate filename begins
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) or a directory (as specified by B<-CApath>). If they occur in
747 both then only the certificates in the file will be recognised.
749 Previous versions of OpenSSL assume certificates with matching subject
750 name are identical and mishandled them.
752 Previous versions of this documentation swapped the meaning of the
753 B<X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT> and
754 B<X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY> error codes.
763 The B<-show_chain> option was added in OpenSSL 1.1.0.
765 The B<-issuer_checks> option is deprecated as of OpenSSL 1.1.0 and
768 The B<-sm2-id> and B<-sm2-hex-id> options were added in OpenSSL 3.0.
772 Copyright 2000-2019 The OpenSSL Project Authors. All Rights Reserved.
774 Licensed under the Apache License 2.0 (the "License"). You may not use
775 this file except in compliance with the License. You can obtain a copy
776 in the file LICENSE in the source distribution or at
777 L<https://www.openssl.org/source/license.html>.