mirror/openssl
2
0
Fork 0
mirror of https://github.com/openssl/openssl.git synced 2025-02-17 14:32:04 +08:00
Code Issues Packages Projects Releases Wiki Activity

Update man3/verify documentation, error text

Browse Source 
Move the x509_V_ERR_xxx definitions from openssl-verify to
X509_STORE_CTX_get_error.pod.  Add some missing ones.  Consistently
start with a lowercase letter, unless it's an acronym.

Fix some markup mistakes in X509_verify_cert.

Reviewed-by: Dmitry Belyavskiy <beldmit@gmail.com>
Reviewed-by: Matthias St. Pierre <Matthias.St.Pierre@ncp-e.com>
(Merged from https://github.com/openssl/openssl/pull/10132)
This commit is contained in:
Rich Salz 2019-10-12 17:45:56 -04:00 committed by Dr. Matthias St. Pierre
parent cf0843c091
commit 21d08b9ee9
14 changed files with 513 additions and 965 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

21
crypto/x509/x509_txt.c
View File

@ -111,9 +111,9 @@ const char *X509_verify_cert_error_string(long n)
case X509_V_ERR_NO_EXPLICIT_POLICY:
return "no explicit policy";
case X509_V_ERR_DIFFERENT_CRL_SCOPE:
return "Different CRL scope";
return "different CRL scope";
case X509_V_ERR_UNSUPPORTED_EXTENSION_FEATURE:
return "Unsupported extension feature";
return "unsupported extension feature";
case X509_V_ERR_UNNESTED_RESOURCE:
return "RFC 3779 resource not subset of parent's resources";
case X509_V_ERR_PERMITTED_VIOLATION:
@ -133,7 +133,7 @@ const char *X509_verify_cert_error_string(long n)
case X509_V_ERR_CRL_PATH_VALIDATION_ERROR:
return "CRL path validation error";
case X509_V_ERR_PATH_LOOP:
return "Path Loop";
return "path loop";
case X509_V_ERR_SUITE_B_INVALID_VERSION:
return "Suite B: certificate version invalid";
case X509_V_ERR_SUITE_B_INVALID_ALGORITHM:
@ -147,13 +147,13 @@ const char *X509_verify_cert_error_string(long n)
case X509_V_ERR_SUITE_B_CANNOT_SIGN_P_384_WITH_P_256:
return "Suite B: cannot sign P-384 with P-256";
case X509_V_ERR_HOSTNAME_MISMATCH:
return "Hostname mismatch";
return "hostname mismatch";
case X509_V_ERR_EMAIL_MISMATCH:
return "Email address mismatch";
return "email address mismatch";
case X509_V_ERR_IP_ADDRESS_MISMATCH:
return "IP address mismatch";
case X509_V_ERR_DANE_NO_MATCH:
return "No matching DANE TLSA records";
return "no matching DANE TLSA records";
case X509_V_ERR_EE_KEY_TOO_SMALL:
return "EE certificate key too weak";
case X509_V_ERR_CA_KEY_TOO_SMALL:
@ -161,9 +161,9 @@ const char *X509_verify_cert_error_string(long n)
case X509_V_ERR_CA_MD_TOO_WEAK:
return "CA signature digest algorithm too weak";
case X509_V_ERR_INVALID_CALL:
return "Invalid certificate verification context";
return "invalid certificate verification context";
case X509_V_ERR_STORE_LOOKUP:
return "Issuer certificate lookup error";
return "issuer certificate lookup error";
case X509_V_ERR_NO_VALID_SCTS:
return "Certificate Transparency required, but no valid SCTs found";
case X509_V_ERR_PROXY_SUBJECT_NAME_VIOLATION:
@ -175,10 +175,9 @@ const char *X509_verify_cert_error_string(long n)
case X509_V_ERR_OCSP_CERT_UNKNOWN:
return "OCSP unknown cert";
case X509_V_ERR_SIGNATURE_ALGORITHM_MISMATCH:
return "Subject signature algorithm and issuer public key algorithm mismatch";
return "subject signature algorithm and issuer public key algorithm mismatch";
case X509_V_ERR_NO_ISSUER_PUBLIC_KEY:
return "Issuer certificate doesn't have a public key";
return "issuer certificate doesn't have a public key";
default:
/* Printing an error number into a static buffer is not thread-safe */
return "unknown certificate verification error";

41
doc/man1/openssl-cms.pod.in
View File

@ -39,34 +39,6 @@ B<openssl> B<cms>
[B<-text>]
[B<-noout>]
[B<-print>]
[B<-attime> I<timestamp>]
[B<-check_ss_sig>]
[B<-crl_check>]
[B<-crl_check_all>]
[B<-explicit_policy>]
[B<-extended_crl>]
[B<-ignore_critical>]
[B<-inhibit_any>]
[B<-inhibit_map>]
[B<-no_check_time>]
[B<-partial_chain>]
[B<-policy> I<arg>]
[B<-policy_check>]
[B<-policy_print>]
[B<-purpose> I<purpose>]
[B<-suiteB_128>]
[B<-suiteB_128_only>]
[B<-suiteB_192>]
[B<-trusted_first>]
[B<-no_alt_chains>]
[B<-use_deltas>]
[B<-auth_level> I<num>]
[B<-verify_depth> I<num>]
[B<-verify_email> I<email>]
[B<-verify_hostname> I<hostname>]
[B<-verify_ip> I<ip>]
[B<-verify_name> I<name>]
[B<-x509_strict>]
[B<-md> I<digest>]
[B<-I<cipher>>]
[B<-nointern>]
@ -78,7 +50,6 @@ B<openssl> B<cms>
[B<-crlfeol>]
[B<-asciicrlf>]
[B<-nodetach>]
[B<-certfile> I<file>]
[B<-certsout> I<file>]
[B<-signer> I<file>]
[B<-recip> I<file>]
@ -97,6 +68,7 @@ B<openssl> B<cms>
[B<-to> I<addr>]
[B<-from> I<addr>]
[B<-subject> I<subj>]
{- $OpenSSL::safe::opt_v_synopsis -}
{- $OpenSSL::safe::opt_trust_synopsis -}
{- $OpenSSL::safe::opt_r_synopsis -}
[I<cert.pem> ...]
@ -462,16 +434,9 @@ portion of a message so they may be included manually. If signing
then many S/MIME mail clients check the signers certificate's email
address matches that specified in the From: address.
=item B<-attime>, B<-check_ss_sig>, B<-crl_check>, B<-crl_check_all>,
B<-explicit_policy>, B<-extended_crl>, B<-ignore_critical>, B<-inhibit_any>,
B<-inhibit_map>, B<-no_alt_chains>, B<-no_check_time>, B<-partial_chain>, B<-policy>,
B<-policy_check>, B<-policy_print>, B<-purpose>, B<-suiteB_128>,
B<-suiteB_128_only>, B<-suiteB_192>, B<-trusted_first>, B<-use_deltas>,
B<-auth_level>, B<-verify_depth>, B<-verify_email>, B<-verify_hostname>,
B<-verify_ip>, B<-verify_name>, B<-x509_strict>
{- $OpenSSL::safe::opt_v_item -}
Set various certificate chain validation options. See the
L<openssl-verify(1)> manual page for details.
Any verification errors cause the command to exit.
{- $OpenSSL::safe::opt_trust_item -}

11
doc/man1/openssl-dgst.pod.in
View File

@ -27,6 +27,7 @@ B<openssl> B<dgst>|I<digest>
[B<-hmac> I<key>]
[B<-fips-fingerprint>]
[B<-engine> I<id>]
[B<-engine_impl> I<id>]
{- $OpenSSL::safe::opt_engine_synopsis -}
{- $OpenSSL::safe::opt_r_synopsis -}
[I<file> ...]
@ -170,17 +171,17 @@ option.
Compute HMAC using a specific key for certain OpenSSL-FIPS operations.
=item B<-engine_impl>
When used with the B<-engine> option, it specifies to also use
engine I<id> for digest operations.
{- $OpenSSL::safe::opt_r_item -}
{- $OpenSSL::safe::opt_engine_item -}
The engine is not used for digests unless the B<-engine_impl> option is
used or it is configured to do so, see L<config(5)/Engine Configuration Module>.
=item B<-engine_impl>
When used with the B<-engine> option, it specifies to also use
engine I<id> for digest operations.
=item I<file> ...
File or files to digest. If no files are specified then standard input is

42
doc/man1/openssl-ocsp.pod.in
View File

@ -31,34 +31,6 @@ B<openssl> B<ocsp>
[B<-multi> I<process-count>]
[B<-header>]
[B<-path>]
[B<-attime> I<timestamp>]
[B<-check_ss_sig>]
[B<-crl_check>]
[B<-crl_check_all>]
[B<-explicit_policy>]
[B<-extended_crl>]
[B<-ignore_critical>]
[B<-inhibit_any>]
[B<-inhibit_map>]
[B<-no_check_time>]
[B<-partial_chain>]
[B<-policy> I<arg>]
[B<-policy_check>]
[B<-policy_print>]
[B<-purpose> I<purpose>]
[B<-suiteB_128>]
[B<-suiteB_128_only>]
[B<-suiteB_192>]
[B<-trusted_first>]
[B<-no_alt_chains>]
[B<-use_deltas>]
[B<-auth_level> I<num>]
[B<-verify_depth> I<num>]
[B<-verify_email> I<email>]
[B<-verify_hostname> I<hostname>]
[B<-verify_ip> I<ip>]
[B<-verify_name> I<name>]
[B<-x509_strict>]
[B<-VAfile> I<file>]
[B<-validity_period> I<n>]
[B<-status_age> I<n>]
@ -88,6 +60,7 @@ B<openssl> B<ocsp>
[B<-rcid> I<digest>]
[B<-I<digest>>]
{- $OpenSSL::safe::opt_trust_synopsis -}
{- $OpenSSL::safe::opt_v_synopsis -}
=for openssl ifdef multi
@ -206,17 +179,6 @@ each child is willing to wait for the client's OCSP response.
This option is available on POSIX systems (that support the fork() and other
required unix system-calls).
=item B<-attime>, B<-check_ss_sig>, B<-crl_check>, B<-crl_check_all>,
B<-explicit_policy>, B<-extended_crl>, B<-ignore_critical>, B<-inhibit_any>,
B<-inhibit_map>, B<-no_alt_chains>, B<-no_check_time>, B<-partial_chain>, B<-policy>,
B<-policy_check>, B<-policy_print>, B<-purpose>, B<-suiteB_128>,
B<-suiteB_128_only>, B<-suiteB_192>, B<-trusted_first>, B<-use_deltas>,
B<-auth_level>, B<-verify_depth>, B<-verify_email>, B<-verify_hostname>,
B<-verify_ip>, B<-verify_name>, B<-x509_strict>
Set different certificate verification options.
See L<openssl-verify(1)> manual page for details.
=item B<-verify_other> I<file>
File containing additional certificates to search when attempting to locate
@ -307,6 +269,8 @@ digest used by subsequent certificate identifiers.
{- $OpenSSL::safe::opt_trust_item -}
{- $OpenSSL::safe::opt_v_item -}
=back
=head2 OCSP Server Options

45
doc/man1/openssl-s_client.pod.in
View File

@ -36,35 +36,7 @@ B<openssl> B<s_client>
[B<-dane_tlsa_domain> I<domain>]
[B<-dane_tlsa_rrdata> I<rrdata>]
[B<-dane_ee_no_namechecks>]
[B<-attime> I<timestamp>]
[B<-check_ss_sig>]
[B<-crl_check>]
[B<-crl_check_all>]
[B<-explicit_policy>]
[B<-extended_crl>]
[B<-ignore_critical>]
[B<-inhibit_any>]
[B<-inhibit_map>]
[B<-no_check_time>]
[B<-partial_chain>]
[B<-policy> I<arg>]
[B<-policy_check>]
[B<-policy_print>]
[B<-purpose> I<purpose>]
[B<-suiteB_128>]
[B<-suiteB_128_only>]
[B<-suiteB_192>]
[B<-trusted_first>]
[B<-no_alt_chains>]
[B<-use_deltas>]
[B<-auth_level> I<num>]
[B<-verify_depth> I<num>]
[B<-verify_email> I<email>]
[B<-verify_hostname> I<hostname>]
[B<-verify_ip> I<ip>]
[B<-verify_name> I<name>]
[B<-build_chain>]
[B<-x509_strict>]
[B<-reconnect>]
[B<-showcerts>]
[B<-debug>]
@ -119,6 +91,7 @@ B<openssl> B<s_client>
{- $OpenSSL::safe::opt_trust_synopsis -}
{- $OpenSSL::safe::opt_r_synopsis -}
{- $OpenSSL::safe::opt_engine_synopsis -}
{- $OpenSSL::safe::opt_v_synopsis -}
[I<host>:I<port>]
=for openssl ifdef engine ssl_client_engine ct noct ctlogfile
@ -347,17 +320,6 @@ records already make it possible for a remote domain to redirect client
connections to any server of its choice, and in any case SMTP and XMPP clients
do not execute scripts downloaded from remote servers.
=item B<-attime>, B<-check_ss_sig>, B<-crl_check>, B<-crl_check_all>,
B<-explicit_policy>, B<-extended_crl>, B<-ignore_critical>, B<-inhibit_any>,
B<-inhibit_map>, B<-no_alt_chains>, B<-no_check_time>, B<-partial_chain>, B<-policy>,
B<-policy_check>, B<-policy_print>, B<-purpose>, B<-suiteB_128>,
B<-suiteB_128_only>, B<-suiteB_192>, B<-trusted_first>, B<-use_deltas>,
B<-auth_level>, B<-verify_depth>, B<-verify_email>, B<-verify_hostname>,
B<-verify_ip>, B<-verify_name>, B<-x509_strict>
Set various certificate chain validation options. See the
L<openssl-verify(1)> manual page for details.
=item B<-reconnect>
Reconnects to the same server 5 times using the same session ID, this can
@ -668,6 +630,11 @@ happen whether or not a certificate has been provided via B<-cert>.
{- $OpenSSL::safe::opt_engine_item -}
{- $OpenSSL::safe::opt_v_item -}
Verification errors are displayed, for debugging, but the command will
proceed unless the B<-verify_return_error> option is used.
=item I<host>:I<port>
Rather than providing B<-connect>, the target hostname and optional port may

54
doc/man1/openssl-s_server.pod.in
View File

@ -107,36 +107,6 @@ B<openssl> B<s_server>
[B<-dhparam> I<infile>]
[B<-record_padding> I<val>]
[B<-debug_broken_protocol>]
[B<-policy> I<val>]
[B<-purpose> I<val>]
[B<-verify_name> I<val>]
[B<-verify_depth> I<int>]
[B<-auth_level> I<int>]
[B<-attime> I<intmax>]
[B<-verify_hostname> I<val>]
[B<-verify_email> I<val>]
[B<-verify_ip>]
[B<-ignore_critical>]
[B<-issuer_checks>]
[B<-crl_check>]
[B<-crl_check_all>]
[B<-policy_check>]
[B<-explicit_policy>]
[B<-inhibit_any>]
[B<-inhibit_map>]
[B<-x509_strict>]
[B<-extended_crl>]
[B<-use_deltas>]
[B<-policy_print>]
[B<-check_ss_sig>]
[B<-trusted_first>]
[B<-suiteB_128_only>]
[B<-suiteB_128>]
[B<-suiteB_192>]
[B<-partial_chain>]
[B<-no_alt_chains>]
[B<-no_check_time>]
[B<-allow_proxy_certs>]
[B<-nbio>]
[B<-psk_identity> I<val>]
[B<-psk_hint> I<val>]
@ -161,6 +131,7 @@ B<openssl> B<s_server>
[B<-http_server_binmode>]
{- $OpenSSL::safe::opt_name_synopsis -}
{- $OpenSSL::safe::opt_version_synopsis -}
{- $OpenSSL::safe::opt_v_synopsis -}
{- $OpenSSL::safe::opt_x_synopsis -}
{- $OpenSSL::safe::opt_trust_synopsis -}
{- $OpenSSL::safe::opt_r_synopsis -}
@ -565,23 +536,6 @@ load the parameters from the server certificate file.
If this fails then a static set of parameters hard coded into this command
will be used.
=item B<-attime>, B<-check_ss_sig>, B<-crl_check>, B<-crl_check_all>,
B<-explicit_policy>, B<-extended_crl>, B<-ignore_critical>, B<-inhibit_any>,
B<-inhibit_map>, B<-no_alt_chains>, B<-no_check_time>, B<-partial_chain>, B<-policy>,
B<-policy_check>, B<-policy_print>, B<-purpose>, B<-suiteB_128>,
B<-suiteB_128_only>, B<-suiteB_192>, B<-trusted_first>, B<-use_deltas>,
B<-auth_level>, B<-verify_depth>, B<-verify_email>, B<-verify_hostname>,
B<-verify_ip>, B<-verify_name>, B<-x509_strict>
Set different peer certificate verification options.
See the L<openssl-verify(1)> manual page for details.
=item B<-crl_check>, B<-crl_check_all>
Check the peer certificate has not been revoked by its CA.
The CRL(s) are appended to the certificate file. With the B<-crl_check_all>
option all CRLs of all CAs in the chain are checked.
=item B<-nbio>
Turns on non blocking I/O.
@ -692,6 +646,12 @@ by the client in binary mode.
{- $OpenSSL::safe::opt_engine_item -}
{- $OpenSSL::safe::opt_v_item -}
If the server requests a client certificate, then
verification errors are displayed, for debugging, but the command will
proceed unless the B<-verify_return_error> option is used.
=back
=head1 CONNECTED COMMANDS

6
doc/man1/openssl-s_time.pod.in
View File

@ -72,12 +72,6 @@ Currently the verify operation continues after errors so all the problems
with a certificate chain can be seen. As a side effect the connection
will never fail due to a server certificate verify failure.
=item B<-CApath> I<directory>
The directory to use for server certificate verification. This directory
must be in "hash format", see L<openssl-verify(1)> for more information.
These are also used when building the client certificate chain.
=item B<-new>
Performs the timing test using a new session ID for each connection.

39
doc/man1/openssl-smime.pod.in
View File

@ -19,33 +19,6 @@ B<openssl> B<smime>
[B<-crlfeol>]
[B<-I<cipher>>]
[B<-in> I<file>]
[B<-attime> I<timestamp>]
[B<-check_ss_sig>]
[B<-crl_check>]
[B<-crl_check_all>]
[B<-explicit_policy>]
[B<-extended_crl>]
[B<-ignore_critical>]
[B<-inhibit_any>]
[B<-inhibit_map>]
[B<-partial_chain>]
[B<-policy> I<arg>]
[B<-policy_check>]
[B<-policy_print>]
[B<-purpose> I<purpose>]
[B<-suiteB_128>]
[B<-suiteB_128_only>]
[B<-suiteB_192>]
[B<-trusted_first>]
[B<-no_alt_chains>]
[B<-use_deltas>]
[B<-auth_level> I<num>]
[B<-verify_depth> I<num>]
[B<-verify_email> I<email>]
[B<-verify_hostname> I<hostname>]
[B<-verify_ip> I<ip>]
[B<-verify_name> I<name>]
[B<-x509_strict>]
[B<-certfile> I<file>]
[B<-signer> I<file>]
[B<-recip> I< file>]
@ -66,6 +39,7 @@ B<openssl> B<smime>
[B<-md> I<digest>]
{- $OpenSSL::safe::opt_trust_synopsis -}
{- $OpenSSL::safe::opt_r_synopsis -}
{- $OpenSSL::safe::opt_v_synopsis -}
I<cert.pem> ...
=for openssl ifdef engine
@ -283,16 +257,9 @@ portion of a message so they may be included manually. If signing
then many S/MIME mail clients check the signers certificate's email
address matches that specified in the From: address.
=item B<-attime>, B<-check_ss_sig>, B<-crl_check>, B<-crl_check_all>,
B<-explicit_policy>, B<-extended_crl>, B<-ignore_critical>, B<-inhibit_any>,
B<-inhibit_map>, B<-no_alt_chains>, B<-partial_chain>, B<-policy>,
B<-policy_check>, B<-policy_print>, B<-purpose>, B<-suiteB_128>,
B<-suiteB_128_only>, B<-suiteB_192>, B<-trusted_first>, B<-use_deltas>,
B<-auth_level>, B<-verify_depth>, B<-verify_email>, B<-verify_hostname>,
B<-verify_ip>, B<-verify_name>, B<-x509_strict>
{- $OpenSSL::safe::opt_v_item -}
Set various options of certificate chain verification. See
L<openssl-verify(1)> manual page for details.
Any verification errors cause the command to exit.
{- $OpenSSL::safe::opt_trust_item -}

61
doc/man1/openssl-ts.pod.in
View File

@ -33,6 +33,7 @@ B<-reply>
[B<-chain> I<certs_file.pem>]
[B<-tspolicy> I<object_id>]
[B<-in> I<response.tsr>]
[B<-untrusted> I<file>]
[B<-token_in>]
[B<-out> I<response.tsr>]
[B<-token_out>]
@ -46,42 +47,8 @@ B<-verify>
[B<-queryfile> I<request.tsq>]
[B<-in> I<response.tsr>]
[B<-token_in>]
[B<-CApath> I<trusted_cert_path>]
[B<-CAfile> I<trusted_certs.pem>]
[B<-CAstore> I<trusted_certs_uri>]
[B<-untrusted> I<cert_file.pem>]
[I<verify options>]
I<verify options:>
[B<-attime> I<timestamp>]
[B<-check_ss_sig>]
[B<-crl_check>]
[B<-crl_check_all>]
[B<-explicit_policy>]
[B<-extended_crl>]
[B<-ignore_critical>]
[B<-inhibit_any>]
[B<-inhibit_map>]
[B<-issuer_checks>]
[B<-no_alt_chains>]
[B<-no_check_time>]
[B<-partial_chain>]
[B<-policy> I<arg>]
[B<-policy_check>]
[B<-policy_print>]
[B<-purpose> I<purpose>]
[B<-suiteB_128>]
[B<-suiteB_128_only>]
[B<-suiteB_192>]
[B<-trusted_first>]
[B<-use_deltas>]
[B<-auth_level> I<num>]
[B<-verify_depth> I<num>]
[B<-verify_email> I<email>]
[B<-verify_hostname> I<hostname>]
[B<-verify_ip> I<ip>]
[B<-verify_name> I<name>]
[B<-x509_strict>]
{- $OpenSSL::safe::opt_trust_synopsis -}
{- $OpenSSL::safe::opt_v_synopsis -}
=for openssl ifdef engine
@ -344,12 +311,6 @@ This flag can be used together with the B<-in> option and indicates
that the input is a DER encoded timestamp token (ContentInfo) instead
of a timestamp response (TimeStampResp). (Optional)
=item B<-CAfile> I<file>, B<-CApath> I<dir>, B<-CAstore> I<uri>
See L<openssl(1)/Trusted Certificate Options> for more information.
At least one of B<-CApath>, B<-CAfile> or B<-CAstore> must be specified.
=item B<-untrusted> I<cert_file.pem>
Set of additional untrusted certificates in PEM format which may be
@ -358,17 +319,13 @@ certificate. This file must contain the TSA signing certificate and
all intermediate CA certificates unless the response includes them.
(Optional)
=item I<verify options>
{- $OpenSSL::safe::opt_trust_item -}
The options B<-attime>, B<-check_ss_sig>, B<-crl_check>,
B<-crl_check_all>, B<-explicit_policy>, B<-extended_crl>, B<-ignore_critical>,
B<-inhibit_any>, B<-inhibit_map>, B<-issuer_checks>, B<-no_alt_chains>,
B<-no_check_time>, B<-partial_chain>, B<-policy>, B<-policy_check>,
B<-policy_print>, B<-purpose>, B<-suiteB_128>, B<-suiteB_128_only>,
B<-suiteB_192>, B<-trusted_first>, B<-use_deltas>, B<-auth_level>,
B<-verify_depth>, B<-verify_email>, B<-verify_hostname>, B<-verify_ip>,
B<-verify_name>, and B<-x509_strict> can be used to control timestamp
verification. See L<openssl-verify(1)>.
At least one of B<-CApath>, B<-CAfile> or B<-CAstore> must be specified.
{- $OpenSSL::safe::opt_v_item -}
Any verification errors cause the command to exit.
=back

664
doc/man1/openssl-verify.pod.in
View File

@ -9,46 +9,18 @@ openssl-verify - Utility to verify certificates
B<openssl> B<verify>
[B<-help>]
[B<-allow_proxy_certs>]
[B<-attime> I<timestamp>]
[B<-check_ss_sig>]
[B<-CRLfile> I<file>]
[B<-crl_download>]
[B<-crl_check>]
[B<-crl_check_all>]
[B<-explicit_policy>]
[B<-extended_crl>]
[B<-ignore_critical>]
[B<-inhibit_any>]
[B<-inhibit_map>]
[B<-no_check_time>]
[B<-partial_chain>]
[B<-policy> I<arg>]
[B<-policy_check>]
[B<-policy_print>]
[B<-purpose> I<purpose>]
[B<-suiteB_128>]
[B<-suiteB_128_only>]
[B<-suiteB_192>]
[B<-trusted_first>]
[B<-no_alt_chains>]
[B<-untrusted> I<file>]
[B<-trusted> I<file>]
[B<-use_deltas>]
[B<-verbose>]
[B<-auth_level> I<level>]
[B<-verify_depth> I<num>]
[B<-verify_email> I<email>]
[B<-verify_hostname> I<hostname>]
[B<-verify_ip> I<ip>]
[B<-verify_name> I<name>]
[B<-x509_strict>]
[B<-show_chain>]
[B<-sm2-id> I<string>]
[B<-sm2-hex-id> I<hex-string>]
[B<-sm2-id> I<hexstring>]
[B<-sm2-hex-id> I<hexstring>]
[B<-verbose>]
[B<-trusted> I<file>]
[B<-untrusted> I<file>]
{- $OpenSSL::safe::opt_name_synopsis -}
{- $OpenSSL::safe::opt_trust_synopsis -}
{- $OpenSSL::safe::opt_engine_synopsis -}
{- $OpenSSL::safe::opt_v_synopsis -}
[B<-->]
[I<certificate> ...]
@ -66,20 +38,9 @@ This command verifies certificate chains.
Print out a usage message.
=item B<-allow_proxy_certs>
=item B<-CAfile> I<file>, B<-no-CAfile>, B<-CApath> I<dir>, B<-no-CApath>
Allow the verification of proxy certificates.
=item B<-attime> I<timestamp>
Perform validation checks using time specified by I<timestamp> and not
current system time. I<timestamp> is the number of seconds since
01.01.1970 (UNIX time).
=item B<-check_ss_sig>
Verify the signature on the self-signed root CA. This is disabled by default
because it doesn't add any security.
See L<openssl(1)/Trusted Certificate Options> for more information.
=item B<-CRLfile> I<file>
@ -91,285 +52,61 @@ I<file>s.
Attempt to download CRL information for this certificate.
=item B<-crl_check>
Checks end entity certificate validity by attempting to look up a valid CRL.
If a valid CRL cannot be found an error occurs.
=item B<-crl_check_all>
Checks the validity of B<all> certificates in the chain by attempting
to look up valid CRLs.
=item B<-explicit_policy>
Set policy variable require-explicit-policy (see RFC5280).
=item B<-extended_crl>
Enable extended CRL features such as indirect CRLs and alternate CRL
signing keys.
=item B<-ignore_critical>
Normally if an unhandled critical extension is present which is not
supported by OpenSSL the certificate is rejected (as required by RFC5280).
If this option is set critical extensions are ignored.
=item B<-inhibit_any>
Set policy variable inhibit-any-policy (see RFC5280).
=item B<-inhibit_map>
Set policy variable inhibit-policy-mapping (see RFC5280).
=item B<-no_check_time>
This option suppresses checking the validity period of certificates and CRLs
against the current time. If option B<-attime> is used to specify
a verification time, the check is not suppressed.
=item B<-partial_chain>
Allow verification to succeed even if a I<complete> chain cannot be built to a
self-signed trust-anchor, provided it is possible to construct a chain to a
trusted certificate that might not be self-signed.
=item B<-policy> I<arg>
Enable policy processing and add I<arg> to the user-initial-policy-set (see
RFC5280). The policy I<arg> can be an object name an OID in numeric form.
This argument can appear more than once.
=item B<-policy_check>
Enables certificate policy processing.
=item B<-policy_print>
Print out diagnostics related to policy processing.
=item B<-purpose> I<purpose>
The intended use for the certificate. If this option is not specified,
this command will not consider certificate purpose during chain
verification.
Currently accepted uses are B<sslclient>, B<sslserver>, B<nssslserver>,
B<smimesign>, B<smimeencrypt>. See the L</VERIFY OPERATION> section for more
information.
=item B<-suiteB_128_only>, B<-suiteB_128>, B<-suiteB_192>
Enable the Suite B mode operation at 128 bit Level of Security, 128 bit or
192 bit, or only 192 bit Level of Security respectively.
See RFC6460 for details. In particular the supported signature algorithms are
reduced to support only ECDSA and SHA256 or SHA384 and only the elliptic curves
P-256 and P-384.
=item B<-trusted_first>
When constructing the certificate chain, use the trusted certificates specified
via B<-CAfile>, B<-CApath>, B<-CAstore> or B<-trusted> before any certificates
specified via B<-untrusted>.
This can be useful in environments with Bridge or Cross-Certified CAs.
As of OpenSSL 1.1.0 this option is on by default and cannot be disabled.
=item B<-no_alt_chains>
By default, unless B<-trusted_first> is specified, when building a certificate
chain, if the first certificate chain found is not trusted, then OpenSSL will
attempt to replace untrusted issuer certificates with certificates from the
trust store to see if an alternative chain can be found that is trusted.
As of OpenSSL 1.1.0, with B<-trusted_first> always on, this option has no
effect.
=item B<-untrusted> I<file>
A I<file> of additional untrusted certificates (intermediate issuer CAs) used
to construct a certificate chain from the subject certificate to a trust-anchor.
The I<file> should contain one or more certificates in PEM format.
This option can be specified more than once to include untrusted certificates
from multiple I<file>s.
=item B<-trusted> I<file>
A I<file> of trusted certificates, which must be self-signed, unless the
B<-partial_chain> option is specified.
The I<file> contains one or more certificates in PEM format.
With this option, no additional (e.g., default) certificate lists are
consulted.
That is, the only trust-anchors are those listed in I<file>.
This option can be specified more than once to include trusted certificates
from multiple I<file>s.
This option implies the B<-no-CAfile>, B<-no-CApath> and B<-no-CAstore> options.
This option cannot be used in combination with any of the B<-CAfile>,
B<-CApath> or B<-CAstore> options.
=item B<-use_deltas>
Enable support for delta CRLs.
=item B<-verbose>
Print extra information about the operations being performed.
=item B<-auth_level> I<level>
Set the certificate chain authentication security level to I<level>.
The authentication security level determines the acceptable signature and
public key strength when verifying certificate chains.
For a certificate chain to validate, the public keys of all the certificates
must meet the specified security I<level>.
The signature algorithm security level is enforced for all the certificates in
the chain except for the chain's I<trust anchor>, which is either directly
trusted or validated by means other than its signature.
See L<SSL_CTX_set_security_level(3)> for the definitions of the available
levels.
The default security level is -1, or "not set".
At security level 0 or lower all algorithms are acceptable.
Security level 1 requires at least 80-bit-equivalent security and is broadly
interoperable, though it will, for example, reject MD5 signatures or RSA keys
shorter than 1024 bits.
=item B<-verify_depth> I<num>
Limit the certificate chain to I<num> intermediate CA certificates.
A maximal depth chain can have up to I<num>+2 certificates, since neither the
end-entity certificate nor the trust-anchor certificate count against the
B<-verify_depth> limit.
=item B<-verify_email> I<email>
Verify if I<email> matches the email address in Subject Alternative Name or
the email in the subject Distinguished Name.
=item B<-verify_hostname> I<hostname>
Verify if I<hostname> matches DNS name in Subject Alternative Name or
Common Name in the subject certificate.
=item B<-verify_ip> I<ip>
Verify if I<ip> matches the IP address in Subject Alternative Name of
the subject certificate.
=item B<-verify_name> I<name>
Use default verification policies like trust model and required certificate
policies identified by I<name>.
The trust model determines which auxiliary trust or reject OIDs are applicable
to verifying the given certificate chain.
See the B<-addtrust> and B<-addreject> options for L<openssl-x509(1)>.
Supported policy names include: B<default>, B<pkcs7>, B<smime_sign>,
B<ssl_client>, B<ssl_server>.
These mimics the combinations of purpose and trust settings used in SSL, CMS
and S/MIME.
As of OpenSSL 1.1.0, the trust model is inferred from the purpose when not
specified, so the B<-verify_name> options are functionally equivalent to the
corresponding B<-purpose> settings.
=item B<-x509_strict>
For strict X.509 compliance, disable non-compliant workarounds for broken
certificates.
=item B<-show_chain>
Display information about the certificate chain that has been built (if
successful). Certificates in the chain that came from the untrusted list will be
flagged as "untrusted".
=item B<-sm2-id>
=item B<-sm2-id> I<hexstring>
Specify the ID string to use when verifying an SM2 certificate. The ID string is
required by the SM2 signature algorithm for signing and verification.
=item B<-sm2-hex-id>
=item B<-sm2-hex-id> I<hexstring>
Specify a binary ID string to use when signing or verifying using an SM2
certificate. The argument for this option is string of hexadecimal digits.
{- $OpenSSL::safe::opt_name_item -}
=item B<-verbose>
{- $OpenSSL::safe::opt_trust_item -}
Print extra information about the operations being performed.
=item B<-trusted> I<file>
A file of trusted certificates.
=item B<-untrusted> I<file>
A file of untrusted certificates.
{- $OpenSSL::safe::opt_name_item -}
{- $OpenSSL::safe::opt_engine_item -}
To load certificates or CRLs that require engine support, specify the
B<-engine> option before any of the
B<-trusted>, B<-untrusted> or B<-CRLfile> options.
{- $OpenSSL::safe::opt_trust_item -}
{- $OpenSSL::safe::opt_v_item -}
=item B<-->
Indicates the last option. All arguments following this are assumed to be
certificate files. This is useful if the first certificate filename begins
with a B<-->.
with a B<->.
=item I<certificate> ...
One or more certificates to verify. If no certificates are given,
this command will attempt to read a certificate from standard input.
Certificates must be in PEM format.
If a certificate chain has multiple problems, this program tries to
display all of them.
=back
=head1 VERIFY OPERATION
This command uses the same functions as the internal SSL
and S/MIME verification, therefore this description applies to these verify
operations too.
There is one crucial difference between the verify operations performed
by this command: wherever possible an attempt is made to
continue after an error whereas normally the verify operation would halt on
the first error. This allows all the problems with a certificate chain to be
determined.
The verify operation consists of a number of separate steps.
Firstly a certificate chain is built up starting from the supplied certificate
and ending in the root CA.
It is an error if the whole chain cannot be built up.
The chain is built up by looking up the issuers certificate of the current
certificate.
If a certificate is found which is its own issuer it is assumed to be the root
CA.
The process of 'looking up the issuers certificate' itself involves a number of
steps.
After all certificates whose subject name matches the issuer name of the current
certificate are subject to further tests.
The relevant authority key identifier components of the current certificate (if
present) must match the subject key identifier (if present) and issuer and
serial number of the candidate issuer, in addition the keyUsage extension of
the candidate issuer (if present) must permit certificate signing.
The lookup first looks in the list of untrusted certificates and if no match
is found the remaining lookups are from the trusted certificates. The root CA
is always looked up in the trusted certificate list: if the certificate to
verify is a root certificate then an exact match must be found in the trusted
list.
The second operation is to check every untrusted certificate's extensions for
consistency with the supplied purpose. If the B<-purpose> option is not included
then no checks are done. The supplied or "leaf" certificate must have extensions
compatible with the supplied purpose and all other certificates must also be
valid CA certificates. The precise extensions required are described in more
detail in L<openssl-x509(1)/CERTIFICATE EXTENSIONS>.
The third operation is to check the trust settings on the root CA. The root CA
should be trusted for the supplied purpose.
For compatibility with previous versions of OpenSSL, a certificate with no
trust settings is considered to be valid for all purposes.
The final operation is to check the validity of the certificate chain. The
validity period is checked against the current system time and the notBefore
and notAfter dates in the certificate. The certificate signatures are also
checked at this point.
If all operations complete successfully then certificate is considered valid. If
any operation fails then the certificate is not valid.
=head1 DIAGNOSTICS
When a verify operation fails the output messages can be somewhat cryptic. The
@ -385,344 +122,12 @@ problem was detected starting with zero for the certificate being verified itsel
then 1 for the CA that signed the certificate and so on. Finally a text version
of the error number is presented.
A partial list of the error codes and messages is shown below, this also
includes the name of the error code as defined in the header file
A list of the error codes and messages can be found in
L<X509_STORE_CTX_get_error(3)>; the full list is defined in the header file
F<< <openssl/x509_vfy.h> >>.
Some of the error codes are defined but never returned: these are described
as "unused".
=over 4
=item B<X509_V_OK>
The operation was successful.
=item B<X509_V_ERR_UNSPECIFIED>
Unspecified error; should not happen.
=item B<X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT>
The issuer certificate of a looked up certificate could not be found. This
normally means the list of trusted certificates is not complete.
=item B<X509_V_ERR_UNABLE_TO_GET_CRL>
The CRL of a certificate could not be found.
=item B<X509_V_ERR_UNABLE_TO_DECRYPT_CERT_SIGNATURE>
The certificate signature could not be decrypted. This means that the
actual signature value could not be determined rather than it not matching
the expected value, this is only meaningful for RSA keys.
=item B<X509_V_ERR_UNABLE_TO_DECRYPT_CRL_SIGNATURE>
The CRL signature could not be decrypted: this means that the actual
signature value could not be determined rather than it not matching the
expected value. Unused.
=item B<X509_V_ERR_UNABLE_TO_DECODE_ISSUER_PUBLIC_KEY>
The public key in the certificate SubjectPublicKeyInfo could not be read.
=item B<X509_V_ERR_CERT_SIGNATURE_FAILURE>
The signature of the certificate is invalid.
=item B<X509_V_ERR_CRL_SIGNATURE_FAILURE>
The signature of the certificate is invalid.
=item B<X509_V_ERR_CERT_NOT_YET_VALID>
The certificate is not yet valid: the notBefore date is after the
current time.
=item B<X509_V_ERR_CERT_HAS_EXPIRED>
The certificate has expired: that is the notAfter date is before the
current time.
=item B<X509_V_ERR_CRL_NOT_YET_VALID>
The CRL is not yet valid.
=item B<X509_V_ERR_CRL_HAS_EXPIRED>
The CRL has expired.
=item B<X509_V_ERR_ERROR_IN_CERT_NOT_BEFORE_FIELD>
The certificate notBefore field contains an invalid time.
=item B<X509_V_ERR_ERROR_IN_CERT_NOT_AFTER_FIELD>
The certificate notAfter field contains an invalid time.
=item B<X509_V_ERR_ERROR_IN_CRL_LAST_UPDATE_FIELD>
The CRL lastUpdate field contains an invalid time.
=item B<X509_V_ERR_ERROR_IN_CRL_NEXT_UPDATE_FIELD>
The CRL nextUpdate field contains an invalid time.
=item B<X509_V_ERR_OUT_OF_MEM>
An error occurred trying to allocate memory. This should never happen.
=item B<X509_V_ERR_DEPTH_ZERO_SELF_SIGNED_CERT>
The passed certificate is self-signed and the same certificate cannot
be found in the list of trusted certificates.
=item B<X509_V_ERR_SELF_SIGNED_CERT_IN_CHAIN>
The certificate chain could be built up using the untrusted certificates
but the root could not be found locally.
=item B<X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY>
The issuer certificate could not be found: this occurs if the issuer
certificate of an untrusted certificate cannot be found.
=item B<X509_V_ERR_UNABLE_TO_VERIFY_LEAF_SIGNATURE>
No signatures could be verified because the chain contains only one
certificate and it is not self signed.
=item B<X509_V_ERR_CERT_CHAIN_TOO_LONG>
The certificate chain length is greater than the supplied maximum
depth. Unused.
=item B<X509_V_ERR_CERT_REVOKED>
The certificate has been revoked.
=item B<X509_V_ERR_INVALID_CA>
A CA certificate is invalid. Either it is not a CA or its extensions
are not consistent with the supplied purpose.
=item B<X509_V_ERR_PATH_LENGTH_EXCEEDED>
The basicConstraints pathlength parameter has been exceeded.
=item B<X509_V_ERR_INVALID_PURPOSE>
The supplied certificate cannot be used for the specified purpose.
=item B<X509_V_ERR_CERT_UNTRUSTED>
The root CA is not marked as trusted for the specified purpose.
=item B<X509_V_ERR_CERT_REJECTED>
The root CA is marked to reject the specified purpose.
=item B<X509_V_ERR_SUBJECT_ISSUER_MISMATCH>
Not used as of OpenSSL 1.1.0 as a result of the deprecation of the
B<-issuer_checks> option.
=item B<X509_V_ERR_AKID_SKID_MISMATCH>
Not used as of OpenSSL 1.1.0 as a result of the deprecation of the
B<-issuer_checks> option.
=item B<X509_V_ERR_AKID_ISSUER_SERIAL_MISMATCH>
Not used as of OpenSSL 1.1.0 as a result of the deprecation of the
B<-issuer_checks> option.
=item B<X509_V_ERR_KEYUSAGE_NO_CERTSIGN>
Not used as of OpenSSL 1.1.0 as a result of the deprecation of the
B<-issuer_checks> option.
=item B<X509_V_ERR_UNABLE_TO_GET_CRL_ISSUER>
Unable to get CRL issuer certificate.
=item B<X509_V_ERR_UNHANDLED_CRITICAL_EXTENSION>
Unhandled critical extension.
=item B<X509_V_ERR_KEYUSAGE_NO_CRL_SIGN>
Key usage does not include CRL signing.
=item B<X509_V_ERR_UNHANDLED_CRITICAL_CRL_EXTENSION>
Unhandled critical CRL extension.
=item B<X509_V_ERR_INVALID_NON_CA>
Invalid non-CA certificate has CA markings.
=item B<X509_V_ERR_PROXY_PATH_LENGTH_EXCEEDED>
Proxy path length constraint exceeded.
=item B<X509_V_ERR_PROXY_SUBJECT_INVALID>
Proxy certificate subject is invalid. It MUST be the same as the issuer
with a single CN component added.
=item B<X509_V_ERR_KEYUSAGE_NO_DIGITAL_SIGNATURE>
Key usage does not include digital signature.
=item B<X509_V_ERR_PROXY_CERTIFICATES_NOT_ALLOWED>
Proxy certificates not allowed, please use B<-allow_proxy_certs>.
=item B<X509_V_ERR_INVALID_EXTENSION>
Invalid or inconsistent certificate extension.
=item B<X509_V_ERR_INVALID_POLICY_EXTENSION>
Invalid or inconsistent certificate policy extension.
=item B<X509_V_ERR_NO_EXPLICIT_POLICY>
No explicit policy.
=item B<X509_V_ERR_DIFFERENT_CRL_SCOPE>
Different CRL scope.
=item B<X509_V_ERR_UNSUPPORTED_EXTENSION_FEATURE>
Unsupported extension feature.
=item B<X509_V_ERR_UNNESTED_RESOURCE>
RFC 3779 resource not subset of parent's resources.
=item B<X509_V_ERR_PERMITTED_VIOLATION>
Permitted subtree violation.
=item B<X509_V_ERR_EXCLUDED_VIOLATION>
Excluded subtree violation.
=item B<X509_V_ERR_SUBTREE_MINMAX>
Name constraints minimum and maximum not supported.
=item B<X509_V_ERR_APPLICATION_VERIFICATION>
Application verification failure. Unused.
=item B<X509_V_ERR_UNSUPPORTED_CONSTRAINT_TYPE>
Unsupported name constraint type.
=item B<X509_V_ERR_UNSUPPORTED_CONSTRAINT_SYNTAX>
Unsupported or invalid name constraint syntax.
=item B<X509_V_ERR_UNSUPPORTED_NAME_SYNTAX>
Unsupported or invalid name syntax.
=item B<X509_V_ERR_CRL_PATH_VALIDATION_ERROR>
CRL path validation error.
=item B<X509_V_ERR_PATH_LOOP>
Path loop.
=item B<X509_V_ERR_SUITE_B_INVALID_VERSION>
Suite B: certificate version invalid.
=item B<X509_V_ERR_SUITE_B_INVALID_ALGORITHM>
Suite B: invalid public key algorithm.
=item B<X509_V_ERR_SUITE_B_INVALID_CURVE>
Suite B: invalid ECC curve.
=item B<X509_V_ERR_SUITE_B_INVALID_SIGNATURE_ALGORITHM>
Suite B: invalid signature algorithm.
=item B<X509_V_ERR_SUITE_B_LOS_NOT_ALLOWED>
Suite B: curve not allowed for this LOS.
=item B<X509_V_ERR_SUITE_B_CANNOT_SIGN_P_384_WITH_P_256>
Suite B: cannot sign P-384 with P-256.
=item B<X509_V_ERR_HOSTNAME_MISMATCH>
Hostname mismatch.
=item B<X509_V_ERR_EMAIL_MISMATCH>
Email address mismatch.
=item B<X509_V_ERR_IP_ADDRESS_MISMATCH>
IP address mismatch.
=item B<X509_V_ERR_DANE_NO_MATCH>
DANE TLSA authentication is enabled, but no TLSA records matched the
certificate chain.
This error is only possible in L<openssl-s_client(1)>.
=item B<X509_V_ERR_EE_KEY_TOO_SMALL>
EE certificate key too weak.
=item B<X509_ERR_CA_KEY_TOO_SMALL>
CA certificate key too weak.
=item B<X509_ERR_CA_MD_TOO_WEAK>
CA signature digest algorithm too weak.
=item B<X509_V_ERR_INVALID_CALL>
nvalid certificate verification context.
=item B<X509_V_ERR_STORE_LOOKUP>
Issuer certificate lookup error.
=item B<X509_V_ERR_NO_VALID_SCTS>
Certificate Transparency required, but no valid SCTs found.
=item B<X509_V_ERR_PROXY_SUBJECT_NAME_VIOLATION>
Proxy subject name violation.
=item B<X509_V_ERR_OCSP_VERIFY_NEEDED>
Returned by the verify callback to indicate an OCSP verification is needed.
=item B<X509_V_ERR_OCSP_VERIFY_FAILED>
Returned by the verify callback to indicate OCSP verification failed.
=item B<X509_V_ERR_OCSP_CERT_UNKNOWN>
Returned by the verify callback to indicate that the certificate is not recognized
by the OCSP responder.
=back
This command ignores many errors, in order to allow all the problems with a
certificate chain to be determined.
=head1 BUGS
@ -751,9 +156,6 @@ L<ossl_store-file(7)>
The B<-show_chain> option was added in OpenSSL 1.1.0.
The B<-issuer_checks> option is deprecated as of OpenSSL 1.1.0 and
is silently ignored.
The B<-sm2-id> and B<-sm2-hex-id> options were added in OpenSSL 3.0.
=head1 COPYRIGHT

255
doc/man1/openssl.pod
View File

@ -781,6 +781,258 @@ client.
The input format for the extra certificate and key, respectively.
See L<openssl(1)/Format Options> for details.
=item B<-xchain_build>
Specify whether the application should build the certificate chain to be
provided to the server for the extra certificates via the B<-xkey>,
B<-xcert>, and B<-xchain> options.
=item B<-xcertform> B<DER>|B<PEM>, B<-xkeyform> B<DER>|B<PEM>
The input format for the extra certifcate and key, respectively.
See L<openssl(1)/Format Options> for details.
=back
=head2 Verification Options
Many OpenSSL commands verify certificates. The details of how each
command handles errors are documented on the specific command page.
Verification is a complicated process, consisting of a number of separate
steps that are detailed in the following paragraphs.
First, a certificate chain is built up starting from the supplied certificate
and ending in a root CA. It is an error if the whole chain cannot be
built up. The chain is built up by looking up the certificate that
signed (or issued) the certificate. It then repeats the process, until
it gets to a certificate that is self-issued.
The process of looking up the issuer's certificate itself involves a number
of steps. After all certificates whose subject name matches the issuer
name of the current certificate are subject to further tests. The relevant
authority key identifier components of the current certificate (if present)
must match the subject key identifier (if present) and issuer and serial
number of the candidate issuer, in addition the keyUsage extension of the
candidate issuer (if present) must permit certificate signing.
The lookup first looks in the list of untrusted certificates and if no match
is found the remaining lookups are from the trusted certificates. The root CA
is always looked up in the trusted certificate list: if the certificate to
verify is a root certificate then an exact match must be found in the trusted
list.
The second step is to check every untrusted certificate's extensions
for consistency with the supplied purpose. If the B<-purpose> option is
not included then no checks are done. The supplied or "leaf" certificate
must have extensions compatible with the supplied purpose and all other
certificates must also be valid CA certificates. The precise extensions
required are described in more detail in
L<openssl-x509(1)/CERTIFICATE EXTENSIONS>.
The third step is to check the trust settings on the root CA. The root
CA should be trusted for the supplied purpose. For compatibility with
previous versions of OpenSSL, a certificate with no trust settings is
considered to be valid for all purposes.
The fourth, and final, step is to check the validity of the certificate
chain. The validity period is checked against the system time
and the C<notBefore> and C<notAfter> dates in the certificate. The certificate
signatures are also checked at this point. The B<-attime> flag may be
used to specify a time other than "now."
If all operations complete successfully then certificate is considered
valid. If any operation fails then the certificate is not valid.
The details of the processing steps can be fine-tuned with the
following flags.
=over 4
=item B<-verbose>
Print extra information about the operations being performed.
=item B<-attime> I<timestamp>
Perform validation checks using time specified by I<timestamp> and not
current system time. I<timestamp> is the number of seconds since
January 1, 1970 (i.e., the Unix Epoch).
=item B<-no_check_time>
This option suppresses checking the validity period of certificates and CRLs
against the current time. If option B<-attime> is used to specify
a verification time, the check is not suppressed.
=item B<-x509_strict>
This disables non-compliant workarounds for broken certificates.
=item B<-ignore_critical>
Normally if an unhandled critical extension is present which is not
supported by OpenSSL the certificate is rejected (as required by RFC5280).
If this option is set critical extensions are ignored.
=item B<-issuer_checks>
Ignored.
=item B<-crl_check>
Checks end entity certificate validity by attempting to look up a valid CRL.
If a valid CRL cannot be found an error occurs.
=item B<-crl_check_all>
Checks the validity of B<all> certificates in the chain by attempting
to look up valid CRLs.
=item B<-use_deltas>
Enable support for delta CRLs.
=item B<-extended_crl>
Enable extended CRL features such as indirect CRLs and alternate CRL
signing keys.
=item B<-suiteB_128_only>, B<-suiteB_128>, B<-suiteB_192>
Enable the Suite B mode operation at 128 bit Level of Security, 128 bit or
192 bit, or only 192 bit Level of Security respectively.
See RFC6460 for details. In particular the supported signature algorithms are
reduced to support only ECDSA and SHA256 or SHA384 and only the elliptic curves
P-256 and P-384.
=item B<-auth_level> I<level>
Set the certificate chain authentication security level to I<level>.
The authentication security level determines the acceptable signature and
public key strength when verifying certificate chains. For a certificate
chain to validate, the public keys of all the certificates must meet the
specified security I<level>. The signature algorithm security level is
enforced for all the certificates in the chain except for the chain's
I<trust anchor>, which is either directly trusted or validated by means
other than its signature. See L<SSL_CTX_set_security_level(3)> for the
definitions of the available levels. The default security level is -1,
or "not set". At security level 0 or lower all algorithms are acceptable.
Security level 1 requires at least 80-bit-equivalent security and is broadly
interoperable, though it will, for example, reject MD5 signatures or RSA
keys shorter than 1024 bits.
=item B<-partial_chain>
Allow verification to succeed even if a I<complete> chain cannot be built to a
self-signed trust-anchor, provided it is possible to construct a chain to a
trusted certificate that might not be self-signed.
=item B<-check_ss_sig>
Verify the signature on the self-signed root CA. This is disabled by default
because it doesn't add any security.
=item B<-allow_proxy_certs>
Allow the verification of proxy certificates.
=item B<-trusted_first>
As of OpenSSL 1.1.0 this option is on by default and cannot be disabled.
=item B<-no_alt_chains>
As of OpenSSL 1.1.0, since B<-trusted_first> always on, this option has no
effect.
=item B<-trusted> I<file>
Parse I<file> as a set of one or more certificates in PEM format.
All certificates must be self-signed, unless the
B<-partial_chain> option is specified.
This option implies the B<-no-CAfile> and B<-no-CApath> options and it
cannot be used with either the B<-CAfile> or B<-CApath> options, so
only certificates in the file are trust anchors.
This option may be used multiple times.
=item B<-untrusted> I<file>
Parse I<file> as a set of one or more certificates in PEM format.
All certificates are untrusted certificates that may be used to
construct a certificate chain from the subject certificate to a trust anchor.
This option may be used multiple times.
=item B<-policy> I<arg>
Enable policy processing and add I<arg> to the user-initial-policy-set (see
RFC5280). The policy I<arg> can be an object name an OID in numeric form.
This argument can appear more than once.
=item B<-explicit_policy>
Set policy variable require-explicit-policy (see RFC5280).
=item B<-policy_check>
Enables certificate policy processing.
=item B<-policy_print>
Print out diagnostics related to policy processing.
=item B<-inhibit_any>
Set policy variable inhibit-any-policy (see RFC5280).
=item B<-inhibit_map>
Set policy variable inhibit-policy-mapping (see RFC5280).
=item B<-purpose> I<purpose>
The intended use for the certificate. If this option is not specified, this
command will not consider certificate purpose during chain verification.
Currently accepted uses are B<sslclient>, B<sslserver>, B<nssslserver>,
B<smimesign>, B<smimeencrypt>.
=item B<-verify_depth> I<num>
Limit the certificate chain to I<num> intermediate CA certificates.
A maximal depth chain can have up to I<num>+2 certificates, since neither the
end-entity certificate nor the trust-anchor certificate count against the
B<-verify_depth> limit.
=item B<-verify_email> I<email>
Verify if I<email> matches the email address in Subject Alternative Name or
the email in the subject Distinguished Name.
=item B<-verify_hostname> I<hostname>
Verify if I<hostname> matches DNS name in Subject Alternative Name or
Common Name in the subject certificate.
=item B<-verify_ip> I<ip>
Verify if I<ip> matches the IP address in Subject Alternative Name of
the subject certificate.
=item B<-verify_name> I<name>
Use default verification policies like trust model and required certificate
policies identified by I<name>.
The trust model determines which auxiliary trust or reject OIDs are applicable
to verifying the given certificate chain.
See the B<-addtrust> and B<-addreject> options for L<openssl-x509(1)>.
Supported policy names include: B<default>, B<pkcs7>, B<smime_sign>,
B<ssl_client>, B<ssl_server>.
These mimics the combinations of purpose and trust settings used in SSL, CMS
and S/MIME.
As of OpenSSL 1.1.0, the trust model is inferred from the purpose when not
specified, so the B<-verify_name> options are functionally equivalent to the
corresponding B<-purpose> settings.
=back
=head2 Name Format Options
@ -1122,6 +1374,9 @@ The B<list> -I<XXX>B<-algorithms> options were added in OpenSSL 1.0.0;
For notes on the availability of other commands, see their individual
manual pages.
The B<-issuer_checks> option is deprecated as of OpenSSL 1.1.0 and
is silently ignored.
=head1 COPYRIGHT
Copyright 2000-2019 The OpenSSL Project Authors. All Rights Reserved.

206
doc/man3/X509_STORE_CTX_get_error.pod
View File

@ -97,160 +97,163 @@ error codes are defined but currently never returned: these are described as
=item B<X509_V_OK: ok>
the operation was successful.
The operation was successful.
=item B<X509_V_ERR_UNSPECIFIED: unspecified certificate verification error>
Unspecified error; should not happen.
=item B<X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT: unable to get issuer certificate>
the issuer certificate of a locally looked up certificate could not be found.
The issuer certificate of a locally looked up certificate could not be found.
This normally means the list of trusted certificates is not complete.
=item B<X509_V_ERR_UNABLE_TO_GET_CRL: unable to get certificate CRL>
the CRL of a certificate could not be found.
The CRL of a certificate could not be found.
=item B<X509_V_ERR_UNABLE_TO_DECRYPT_CERT_SIGNATURE: unable to decrypt certificate's signature>
the certificate signature could not be decrypted. This means that the actual
The certificate signature could not be decrypted. This means that the actual
signature value could not be determined rather than it not matching the
expected value, this is only meaningful for RSA keys.
=item B<X509_V_ERR_UNABLE_TO_DECRYPT_CRL_SIGNATURE: unable to decrypt CRL's signature>
the CRL signature could not be decrypted: this means that the actual signature
The CRL signature could not be decrypted: this means that the actual signature
value could not be determined rather than it not matching the expected value.
Unused.
=item B<X509_V_ERR_UNABLE_TO_DECODE_ISSUER_PUBLIC_KEY: unable to decode issuer public key>
the public key in the certificate SubjectPublicKeyInfo could not be read.
The public key in the certificate C<SubjectPublicKeyInfo> field could
not be read.
=item B<X509_V_ERR_CERT_SIGNATURE_FAILURE: certificate signature failure>
the signature of the certificate is invalid.
The signature of the certificate is invalid.
=item B<X509_V_ERR_CRL_SIGNATURE_FAILURE: CRL signature failure>
the signature of the certificate is invalid.
The signature of the certificate is invalid.
=item B<X509_V_ERR_CERT_NOT_YET_VALID: certificate is not yet valid>
the certificate is not yet valid: the notBefore date is after the current time.
The certificate is not yet valid: the C<notBefore> date is after the
current time.
=item B<X509_V_ERR_CERT_HAS_EXPIRED: certificate has expired>
the certificate has expired: that is the notAfter date is before the current time.
The certificate has expired: that is the C<notAfter> date is before the
current time.
=item B<X509_V_ERR_CRL_NOT_YET_VALID: CRL is not yet valid>
the CRL is not yet valid.
The CRL is not yet valid.
=item B<X509_V_ERR_CRL_HAS_EXPIRED: CRL has expired>
the CRL has expired.
The CRL has expired.
=item B<X509_V_ERR_ERROR_IN_CERT_NOT_BEFORE_FIELD: format error in certificate's notBefore field>
the certificate notBefore field contains an invalid time.
The certificate B<notBefore> field contains an invalid time.
=item B<X509_V_ERR_ERROR_IN_CERT_NOT_AFTER_FIELD: format error in certificate's notAfter field>
the certificate notAfter field contains an invalid time.
The certificate B<notAfter> field contains an invalid time.
=item B<X509_V_ERR_ERROR_IN_CRL_LAST_UPDATE_FIELD: format error in CRL's lastUpdate field>
the CRL lastUpdate field contains an invalid time.
The CRL B<lastUpdate> field contains an invalid time.
=item B<X509_V_ERR_ERROR_IN_CRL_NEXT_UPDATE_FIELD: format error in CRL's nextUpdate field>
the CRL nextUpdate field contains an invalid time.
The CRL B<nextUpdate> field contains an invalid time.
=item B<X509_V_ERR_OUT_OF_MEM: out of memory>
an error occurred trying to allocate memory. This should never happen.
An error occurred trying to allocate memory.
=item B<X509_V_ERR_DEPTH_ZERO_SELF_SIGNED_CERT: self signed certificate>
the passed certificate is self signed and the same certificate cannot be found
The passed certificate is self-signed and the same certificate cannot be found
in the list of trusted certificates.
=item B<X509_V_ERR_SELF_SIGNED_CERT_IN_CHAIN: self signed certificate in certificate chain>
the certificate chain could be built up using the untrusted certificates but
The certificate chain could be built up using the untrusted certificates but
the root could not be found locally.
=item B<X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY: unable to get local issuer certificate>
the issuer certificate could not be found: this occurs if the issuer certificate
The issuer certificate could not be found: this occurs if the issuer certificate
of an untrusted certificate cannot be found.
=item B<X509_V_ERR_UNABLE_TO_VERIFY_LEAF_SIGNATURE: unable to verify the first certificate>
no signatures could be verified because the chain contains only one certificate
No signatures could be verified because the chain contains only one certificate
and it is not self signed.
=item B<X509_V_ERR_CERT_CHAIN_TOO_LONG: certificate chain too long>
the certificate chain length is greater than the supplied maximum depth. Unused.
The certificate chain length is greater than the supplied maximum depth. Unused.
=item B<X509_V_ERR_CERT_REVOKED: certificate revoked>
the certificate has been revoked.
The certificate has been revoked.
=item B<X509_V_ERR_INVALID_CA: invalid CA certificate>
a CA certificate is invalid. Either it is not a CA or its extensions are not
A CA certificate is invalid. Either it is not a CA or its extensions are not
consistent with the supplied purpose.
=item B<X509_V_ERR_PATH_LENGTH_EXCEEDED: path length constraint exceeded>
the basicConstraints path-length parameter has been exceeded.
The basicConstraints path-length parameter has been exceeded.
=item B<X509_V_ERR_INVALID_PURPOSE: unsupported certificate purpose>
the supplied certificate cannot be used for the specified purpose.
The supplied certificate cannot be used for the specified purpose.
=item B<X509_V_ERR_CERT_UNTRUSTED: certificate not trusted>
the root CA is not marked as trusted for the specified purpose.
The root CA is not marked as trusted for the specified purpose.
=item B<X509_V_ERR_CERT_REJECTED: certificate rejected>
the root CA is marked to reject the specified purpose.
The root CA is marked to reject the specified purpose.
=item B<X509_V_ERR_SUBJECT_ISSUER_MISMATCH: subject issuer mismatch>
the current candidate issuer certificate was rejected because its subject name
did not match the issuer name of the current certificate. This is only set
if issuer check debugging is enabled it is used for status notification and
is B<not> in itself an error.
The current candidate issuer certificate was rejected because its subject name
did not match the issuer name of the current certificate.
=item B<X509_V_ERR_AKID_SKID_MISMATCH: authority and subject key identifier mismatch>
the current candidate issuer certificate was rejected because its subject key
The current candidate issuer certificate was rejected because its subject key
identifier was present and did not match the authority key identifier current
certificate. This is only set if issuer check debugging is enabled it is used
for status notification and is B<not> in itself an error.
certificate.
Not used as of OpenSSL 1.1.0.
=item B<X509_V_ERR_AKID_ISSUER_SERIAL_MISMATCH: authority and issuer serial number mismatch>
the current candidate issuer certificate was rejected because its issuer name
The current candidate issuer certificate was rejected because its issuer name
and serial number was present and did not match the authority key identifier of
the current certificate. This is only set if issuer check debugging is enabled
it is used for status notification and is B<not> in itself an error.
the current certificate.
Not used as of OpenSSL 1.1.0.
=item B<X509_V_ERR_KEYUSAGE_NO_CERTSIGN:key usage does not include certificate signing>
the current candidate issuer certificate was rejected because its keyUsage
extension does not permit certificate signing. This is only set if issuer check
debugging is enabled it is used for status notification and is B<not> in itself
an error.
The current candidate issuer certificate was rejected because its B<keyUsage>
extension does not permit certificate signing.
Not used as of OpenSSL 1.1.0.
=item B<X509_V_ERR_INVALID_EXTENSION: invalid or inconsistent certificate extension>
A certificate extension had an invalid value (for example an incorrect
encoding) or some value inconsistent with other extensions.
=item B<X509_V_ERR_INVALID_POLICY_EXTENSION: invalid or inconsistent certificate policy extension>
A certificate policies extension had an invalid value (for example an incorrect
@ -301,8 +304,121 @@ happen if extended CRL checking is enabled.
=item B<X509_V_ERR_APPLICATION_VERIFICATION: application verification failure>
an application specific error. This will never be returned unless explicitly
set by an application.
An application specific error. This will never be returned unless explicitly
set by an application callback.
=item B<X509_V_ERR_UNABLE_TO_GET_CRL_ISSUER: unable to get CRL issuer certificate>
Unable to get CRL issuer certificate.
=item B<X509_V_ERR_UNHANDLED_CRITICAL_EXTENSION: unhandled critical extension>
Unhandled critical extension.
=item B<X509_V_ERR_KEYUSAGE_NO_CRL_SIGN: key usage does not include CRL signing>
Key usage does not include CRL signing.
=item B<X509_V_ERR_UNHANDLED_CRITICAL_CRL_EXTENSION: unhandled critical CRL extension>
Unhandled critical CRL extension.
=item B<X509_V_ERR_INVALID_NON_CA: invalid non-CA certificate (has CA markings)>
Invalid non-CA certificate has CA markings.
=item B<X509_V_ERR_PROXY_PATH_LENGTH_EXCEEDED: proxy path length contraint exceeded>
Proxy path length constraint exceeded.
=item B<X509_V_ERR_KEYUSAGE_NO_DIGITAL_SIGNATURE: key usage does not include digital signature>
Key usage does not include digital signature, and therefore cannot sign
certificates.
=item B<X509_V_ERR_PROXY_CERTIFICATES_NOT_ALLOWED: proxy certificates not allowed, please set the appropriate flag>
Proxy certificates not allowed unless the B<-allow_proxy_certs> option is used.
=item B<X509_V_ERR_UNNESTED_RESOURCE: RFC 3779 resource not subset of parent's resrouces>
See RFC 3779 for details.
=item B<X509_V_ERR_UNSUPPORTED_NAME_SYNTAX: unsupported or invalid name syntax>
Unsupported or invalid name syntax.
=item B<X509_V_ERR_PATH_LOOP: path loop>
Path loop.
=item B<X509_V_ERR_HOSTNAME_MISMATCH: hostname mismatch>
Hostname mismatch.
=item B<X509_V_ERR_EMAIL_MISMATCH: email address mismatch>
Email address mismatch.
=item B<X509_V_ERR_IP_ADDRESS_MISMATCH: IP address mismatch>
IP address mismatch.
=item B<X509_V_ERR_DANE_NO_MATCH: no matching DANE TLSA records>
DANE TLSA authentication is enabled, but no TLSA records matched the
certificate chain.
This error is only possible in L<openssl-s_client(1)>.
=item B<X509_V_ERR_EE_KEY_TOO_SMALL: EE certificate key too weak>
EE certificate key too weak.
=item B<X509_ERR_CA_KEY_TOO_SMALL: CA certificate key too weak>
CA certificate key too weak.
=item B<X509_ERR_CA_MD_TOO_WEAK: CA signature digest algorithm too weak>
CA signature digest algorithm too weak.
=item B<X509_V_ERR_INVALID_CALL: invalid certificate verification context>
invalid certificate verification context.
=item B<X509_V_ERR_STORE_LOOKUP: issuer certificate lookup error>
Issuer certificate lookup error.
=item B<X509_V_ERR_NO_VALID_SCTS: certificate transparency required, but no valid SCTs found>
Certificate Transparency required, but no valid SCTs found.
=item B<X509_V_ERR_PROXY_SUBJECT_NAME_VIOLATION: proxy subject name violation>
Proxy subject name violation.
=item B<X509_V_ERR_OCSP_VERIFY_NEEDED: OCSP verification needed>
Returned by the verify callback to indicate an OCSP verification is needed.
=item B<X509_V_ERR_OCSP_VERIFY_FAILED: OCSP verification failed>
Returned by the verify callback to indicate OCSP verification failed.
=item B<X509_V_ERR_OCSP_CERT_UNKNOWN: OCSP unknown cert>
Returned by the verify callback to indicate that the certificate is not
recognized by the OCSP responder.
=item B<509_V_ERROR_NO_ISSUER_PUBLI_KEY, issuer certificate doesn't have a public key>
The issuer certificate does not have a public key.
=item B<X509_V_ERROR_SIGNATURE_ALGORITHM_MISMATCH, Subject signature algorithm and issuer public key algoritm mismatch>
The issuer's public key is not of the type required by the signature in
the subject's certificate.
=back

25
doc/man3/X509_verify_cert.pod
View File

@ -16,17 +16,6 @@ The X509_verify_cert() function attempts to discover and validate a
certificate chain based on parameters in B<ctx>. A complete description of
the process is contained in the L<openssl-verify(1)> manual page.
=head1 RETURN VALUES
If a complete chain can be built and validated this function returns 1,
otherwise it return zero, in exceptional circumstances it can also
return a negative code.
If the function fails additional error information can be obtained by
examining B<ctx> using, for example X509_STORE_CTX_get_error().
=head1 NOTES
Applications rarely call this function directly but it is used by
OpenSSL internally for certificate validation, in both the S/MIME and
SSL/TLS code.
@ -39,10 +28,20 @@ a retry operation is requested during internal lookups (which never happens
with standard lookup methods).
Applications must check for <= 0 return value on error.
=head1 RETURN VALUES
If a complete chain can be built and validated this function returns 1,
otherwise it return zero, in exceptional circumstances it can also
return a negative code.
If the function fails additional error information can be obtained by
examining B<ctx> using, for example X509_STORE_CTX_get_error().
=head1 BUGS
This function uses the header B<x509.h> as opposed to most chain verification
functions which use B<x509_vfy.h>.
This function uses the header F<< <x509.h> >>
as opposed to most chain verification
functions which use F<< <x509_vfy.h> >>.
=head1 SEE ALSO

8
doc/perlvars.pm
View File

@ -10,7 +10,9 @@
# Verify options
$OpenSSL::safe::opt_v_synopsis = ""
. "[B<-allow_proxy_certs>]\n"
. "[B<-attime> I<timestamp>]\n"
. "[B<-no_check_time>]\n"
. "[B<-check_ss_sig>]\n"
. "[B<-crl_check>]\n"
. "[B<-crl_check_all>]\n"
@ -36,10 +38,10 @@ $OpenSSL::safe::opt_v_synopsis = ""
. "[B<-verify_hostname> I<hostname>]\n"
. "[B<-verify_ip> I<ip>]\n"
. "[B<-verify_name> I<name>]\n"
. "[B<-x509_strict>]\n"
. "[B<-certfile> I<file>]";
. "[B<-x509_strict>]\n";
$OpenSSL::safe::opt_v_item = ""
. "=item B<-attime>, B<-check_ss_sig>, B<-crl_check>, B<-crl_check_all>,\n"
. "=item B<-allow_proxy_certs>, B<-attime>, B<-no_check_time>,\n"
. "B<-check_ss_sig>, B<-crl_check>, B<-crl_check_all>,\n"
. "B<-explicit_policy>, B<-extended_crl>, B<-ignore_critical>, B<-inhibit_any>,\n"
. "B<-inhibit_map>, B<-no_alt_chains>, B<-partial_chain>, B<-policy>,\n"
. "B<-policy_check>, B<-policy_print>, B<-purpose>, B<-suiteB_128>,\n"