* This can be used to prune a set of possible issuer certificates which
* have been looked up using some simple method such as by subject name.
* These are:
- * 1. Check issuer_name(subject) == subject_name(issuer)
- * 2. If akid(subject) exists, check that it matches issuer
- * 3. Check that issuer public key algorithm matches subject signature algorithm
- * 4. Check that any key_usage(issuer) allows certificate signing
+ * 1. issuer_name(subject) == subject_name(issuer)
+ * 2. If akid(subject) exists, it matches the respective issuer fields.
+ * 3. subject signature algorithm == issuer public key algorithm
+ * 4. If key_usage(issuer) exists, it allows for signing subject.
* Note that this does not include actually checking the signature.
* Returns 0 for OK, or positive for reason for mismatch
* where reason codes match those for X509_verify_cert().
#define S_DOTRUSTED (1 << 1) /* Search trusted store */
#define S_DOALTERNATE (1 << 2) /* Retry with pruned alternate chain */
/*
- * Set up search policy, untrusted if possible, trusted-first if enabled.
+ * Set up search policy, untrusted if possible, trusted-first if enabled,
+ * which is the default.
* If we're doing DANE and not doing PKIX-TA/PKIX-EE, we never look in the
* trust_store, otherwise we might look there first. If not trusted-first,
* and alternate chains are not disabled, try building an alternate chain
=head1 DESCRIPTION
-Many OpenSSL commands and various other uses of the crypto library function
-L<X509_verify_cert(3)> verify X.509 certificates. The details of how each
-command handles errors are documented on the specific command page.
+There are many situations where X.509 certificates are verified
+within the OpenSSL libraries and in various OpenSSL commands.
+
+Certificate verification is implemented by L<X509_verify_cert(3)>.
+It is a complicated process consisting of a number of steps
+and depending on numerous options.
+The most important of them are detailed in the following sections.
+
+In a nutshell, a valid chain of certifciates needs to be built up and verified
+starting from the I<target certificate> that is to be verified
+and ending in a certificate that due to some policy is trusted.
+Verification is done relative to the given I<purpose>, which is the intended use
+of the target certificate, such as SSL server, or by default for any purpose.
+
+The details of how each OpenSSL command handles errors
+are documented on the specific command page.
+
+DANE support is documented in L<openssl-s_client(1)>,
+L<SSL_CTX_dane_enable(3)>, L<SSL_set1_host(3)>,
+L<X509_VERIFY_PARAM_set_flags(3)>, and L<X509_check_host(3)>.
+
+=head2 Trust Anchors
+
+In general, according to RFC 4158 and RFC 5280, a I<trust anchor> is
+any public key and related subject distinguished name (DN) that
+for some reason is considered trusted
+and thus is acceptable as the root of a chain of certificates.
+
+In practice, trust anchors are given in the form of certificates,
+where their essential fields are the public key and the subject DN.
+In addition to the requirements in RFC 5280,
+OpenSSL checks the validity period of such certificates
+and makes use of some further fields.
+In particular, the subject key identifier extension, if present,
+is used for matching trust anchors during chain building.
+
+In the most simple and common case, trust anchors are by default
+all self-signed "root" CA certificates that are placed in the I<trust store>,
+which is a collection of certificates that are trusted for certain uses.
+This is akin to what is used in the trust stores of Mozilla Firefox,
+or Apple's and Microsoft's certificate stores, ...
+
+From the OpenSSL perspective, a trust anchor is a certificate
+that should be augmented with an explicit designation for which
+uses of a target certificate the certificate may serve as a trust anchor.
+In PEM encoding, this is indicated by the C<TRUSTED CERTIFICATE> string.
+Such a designation provides a set of positive trust attributes
+explicitly stating trust for the listed purposes
+and/or a set of negative trust attributes
+explicitly rejecting the use for the listed purposes.
+The purposes are encoded using the values defined for the extended key usages
+(EKUs) that may be given in X.509 extensions of end-entity certificates.
+See also the L</Extended Key Usage> section below.
+
+The currently recognized uses are
+B<clientAuth> (SSL client use), B<serverAuth> (SSL server use),
+B<emailProtection> (S/MIME email use), B<codeSigning> (object signer use),
+B<OCSPSigning> (OCSP responder use), B<OCSP> (OCSP request use),
+B<timeStamping> (TSA server use), and B<anyExtendedKeyUsage>.
+As of OpenSSL 1.1.0, the last of these blocks all uses when rejected or
+enables all uses when trusted.
+
+A certificate, which may be CA certificate or an end-entity certificate,
+is considered a trust anchor for the given use
+if and only if all the following conditions hold:
-Certificate verification is a complicated process, consisting of
-a number of separate steps that are detailed in the following paragraphs.
+=over 4
+
+=item *
+
+It is an an element of the trust store.
+
+=item *
+
+It does not have a negative trust attribute rejecting the given use.
+
+=item *
+
+It has a positive trust attribute accepting the given use
+or (by default) one of the following compatibilty conditions apply:
+It is self-signed or the B<-partial_chain> option is given
+(which corresponds to the B<X509_V_FLAG_PARTIAL_CHAIN> flag being set).
+
+=back
+
+=head2 Certification Path Building
First, a certificate chain is built up starting from the target certificate
-and typically ending in a self-signed "root" CA certificate.
-It is an error if the whole chain cannot be built up
-unless the B<-partial_chain> option is given.
+and ending in a trust anchor.
+
The chain is built up iteratively, looking up in turn
-the certificate of the signer ("issuer") of the current certificate.
-If a certificate is found that appears to be its own issuer
-it is assumed to be the self-signed root, which must be trusted.
-
-The process of looking up the issuer's certificate itself involves a number
-of steps.
-All available certificates with a subject name that 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 certificate.
+a certificate with suitable key usage that
+matches as an issuer of the current "subject" certificate as described below.
If there is such a certificate, the first one found that is currently valid
is taken, otherwise the one that expired most recently of all such certificates.
+For efficiency, no backtracking is performed, thus
+any further candidate issuer certificates that would match equally are ignored.
+
+When a self-signed certificate has been added, chain construction stops.
+In this case it must fully match a trust anchor, otherwise chain building fails.
+
+A candidate issuer certificate matches a subject certificate
+if all of the following conditions hold:
+
+=over 4
+
+=item *
+
+Its subject name matches the issuer name of the subject certificate.
+
+=item *
+
+If the subject certificate has an authority key identifier extension,
+each of its sub-fields equals the corresponding subject key identifier, serial
+number, and issuer field of the candidate issuer certificate,
+as far as the respective fields are present in both certificates.
+
+item *
+
+The certificate signature algorithm used to sign the subject certificate
+is supported and
+equals the public key algorithm of the candidate issuer certificate.
+
+=back
The lookup first searches for issuer certificates in the trust store.
If it does not find a match there it consults
-the list of untrusted "intermediate" CA certificates (if provided).
-The last certificate (which typically is of a root CA) is always looked up
-in the trusted certificate list; an exact match must be found there.
+the list of untrusted ("intermediate" CA) certificates, if provided.
+
+=head2 Certification Path Validation
+
+When the certificate chain building process was successful
+the chain components and their links are checked thoroughly.
+
+The first step is to check that each certificate is well-formed.
+Part of these checks are enabled only if the B<-x509_strict> option is given.
The second step is to check the extensions of every untrusted certificate
-for consistency with the supplied purpose.
-If the B<-purpose> option is not included then no checks are done.
-The target or "leaf" certificate must have extensions compatible with the
-supplied purpose and all other certificates must also be valid CA certificates.
+for consistency with the given purpose.
+If the B<-purpose> option is not included then no such checks are done.
+The target certificate must not have an EKU extension that is incompatible with
+the given purpose, and all other certificates must 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 last certficate,
-typically of a root CA.
-It 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 third step is to check the trust settings on the last certificate
+(which typically is a self-signed root CA certificate).
+It must be trusted for the given use.
+For compatibility with previous versions of OpenSSL, a self-signed certificate
+with no trust attributes is considered to be valid for all uses.
The fourth, and final, step is to check the validity of the certificate chain.
For each element in the chain, including the root CA certificate,
=head2 Trusted Certificate Options
-The following options specify how to select the trusted root certificates,
-also known as trust anchors.
-A collection of trusted roots is called a I<trust store>.
+The following options specify how to supply the certificates
+that can be used as trust anchors for certain uses.
+As mentioned, a collection of such certificates is called a I<trust store>.
Note that OpenSSL does not provide a default set of trust anchors. Many
Linux distributions include a system default and configure OpenSSL to point
to that. Mozilla maintains an influential trust store that can be found at
L<https://www.mozilla.org/en-US/about/governance/policies/security-group/certs/>.
-The certificates to trust can be specified using following options.
+The certificates to add to the trust store
+can be specified using following options.
=over 4
=item B<-CAfile> I<file>
-Load the specified file which contains one or more PEM-format certificates
-of CA's that are trusted.
+Load the specified file which contains a certificate
+or several of them in case the input is in PEM or PKCS#12 format.
+PEM-encoded certificates may also have trust attributes set.
=item B<-no-CAfile>
=item B<-CApath> I<dir>
-Use the specified directory as a list of trust certificates. That is,
-files should be named with the hash of the X.509 SubjectName of each
+Use the specified directory as a collection of trusted certificates,
+i.e., a trust store.
+Files should be named with the hash value of the X.509 SubjectName of each
certificate. This is so that the library can extract the IssuerName,
hash it, and directly lookup the file to get the issuer certificate.
See L<openssl-rehash(1)> for information on creating this type of directory.
=item B<-CAstore> I<uri>
-Use I<uri> as a store of trusted CA certificates. The URI may
-indicate a single certificate, as well as a collection of them.
+Use I<uri> as a store of CA certificates.
+The URI may indicate a single certificate, as well as a collection of them.
With URIs in the C<file:> scheme, this acts as B<-CAfile> or
B<-CApath>, depending on if the URI indicates a single file or
directory.
=item B<-no-CAstore>
-Do not use the default store.
+Do not use the default store of trusted CA certificates.
=back
=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.
+Allow verification to succeed if an incomplete chain can be built.
+That is, a chain ending in a certificate that normally would not be trusted
+(because it has no matching positive trust attributes and is not self-signed)
+but is an element of the trust store.
This certificate may be self-issued or belong to an intermediate CA.
=item B<-check_ss_sig>
=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.
+Parse I<file> as a set of one or more certificates.
+Each of them qualifies as trusted if has a suitable positive trust attribute
+or it is self-signed or the B<-partial_chain> option is specified.
This option implies the B<-no-CAfile>, B<-no-CApath>, and B<-no-CAstore> options
and it cannot be used with the B<-CAfile>, B<-CApath> or B<-CAstore> options, so
-only certificates in the file are trust anchors.
+only certificates specified using the B<-trusted> option 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 (typically of intermedate CAs)
-that may be used to
-construct a certificate chain from the subject certificate to a trust anchor.
+Parse I<file> as a set of one or more certificates.
+All certificates (typically of intermediate CAs) are considered untrusted
+and may be used to
+construct a certificate chain from the target certificate to a trust anchor.
This option may be used multiple times.
=item B<-policy> I<arg>
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>.
+B<smimesign>, B<smimeencrypt>, B<crlsign>, B<ocsphelper>, B<timestampsign>,
+and <any>.
=item B<-verify_depth> I<num>
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)>.
+They can be given using 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
=back
+=head2 Certificate Extensions
+
+Options like B<-purpose> lead to checking the certificate extensions,
+which determine what the target certificate and intermediate CA certificates
+can be used for.
+
+=head3 Basic Constraints
+
+The basicConstraints extension CA flag is used to determine whether the
+certificate can be used as a CA. If the CA flag is true then it is a CA,
+if the CA flag is false then it is not a CA. B<All> CAs should have the
+CA flag set to true.
+
+If the basicConstraints extension is absent,
+which includes the case that it is an X.509v1 certificate,
+then the certificate is considered to be a "possible CA" and
+other extensions are checked according to the intended use of the certificate.
+The treatment of certificates without basicConstraints as a CA
+is presently supported, but this could change in the future.
+
+=head3 Key Usage
+
+If the keyUsage extension is present then additional restraints are
+made on the uses of the certificate. A CA certificate B<must> have the
+keyCertSign bit set if the keyUsage extension is present.
+
+=head3 Extended Key Usage
+
+The extKeyUsage (EKU) extension places additional restrictions on the
+certificate uses. If this extension is present (whether critical or not)
+the key can only be used for the purposes specified.
+
+A complete description of each check is given below. The comments about
+basicConstraints and keyUsage and X.509v1 certificates above apply to B<all>
+CA certificates.
+
+
+=over 4
+
+=item B<SSL Client>
+
+The extended key usage extension must be absent or include the "web client
+authentication" OID. The keyUsage extension must be absent or it must have the
+digitalSignature bit set. The Netscape certificate type must be absent
+or it must have the SSL client bit set.
+
+=item B<SSL Client CA>
+
+The extended key usage extension must be absent or include the "web client
+authentication" OID.
+The Netscape certificate type must be absent or it must have the SSL CA bit set.
+This is used as a work around if the basicConstraints extension is absent.
+
+=item B<SSL Server>
+
+The extended key usage extension must be absent or include the "web server
+authentication" and/or one of the SGC OIDs. The keyUsage extension must be
+absent or it
+must have the digitalSignature, the keyEncipherment set or both bits set.
+The Netscape certificate type must be absent or have the SSL server bit set.
+
+=item B<SSL Server CA>
+
+The extended key usage extension must be absent or include the "web server
+authentication" and/or one of the SGC OIDs. The Netscape certificate type must
+be absent or the SSL CA bit must be set.
+This is used as a work around if the basicConstraints extension is absent.
+
+=item B<Netscape SSL Server>
+
+For Netscape SSL clients to connect to an SSL server it must have the
+keyEncipherment bit set if the keyUsage extension is present. This isn't
+always valid because some cipher suites use the key for digital signing.
+Otherwise it is the same as a normal SSL server.
+
+=item B<Common S/MIME Client Tests>
+
+The extended key usage extension must be absent or include the "email
+protection" OID. The Netscape certificate type must be absent or should have the
+S/MIME bit set. If the S/MIME bit is not set in the Netscape certificate type
+then the SSL client bit is tolerated as an alternative but a warning is shown.
+This is because some Verisign certificates don't set the S/MIME bit.
+
+=item B<S/MIME Signing>
+
+In addition to the common S/MIME client tests the digitalSignature bit or
+the nonRepudiation bit must be set if the keyUsage extension is present.
+
+=item B<S/MIME Encryption>
+
+In addition to the common S/MIME tests the keyEncipherment bit must be set
+if the keyUsage extension is present.
+
+=item B<S/MIME CA>
+
+The extended key usage extension must be absent or include the "email
+protection" OID. The Netscape certificate type must be absent or must have the
+S/MIME CA bit set.
+This is used as a work around if the basicConstraints extension is absent.
+
+=item B<CRL Signing>
+
+The keyUsage extension must be absent or it must have the CRL signing bit
+set.
+
+=item B<CRL Signing CA>
+
+The normal CA tests apply. Except in this case the basicConstraints extension
+must be present.
+
+=back
+
+=head1 BUGS
+
+The issuer checks still suffer from limitations in the underlying X509_LOOKUP
+API. One consequence of this is that trusted certificates with matching
+subject name must appear in a file (as specified by the B<-CAfile> option),
+a directory (as specified by B<-CApath>),
+or a store (as specified by B<-CAstore>).
+If there are multiple such matches, possibly in multiple locations,
+only the first one (in the mentioned order of locations) is recognised.
+
=head1 SEE ALSO
L<X509_verify_cert(3)>,
L<openssl-cmp(1)>,
L<openssl-cms(1)>
-
=head1 HISTORY
The checks enabled by B<-x509_strict> have been extended in OpenSSL 3.0.
B<openssl> B<verify>
[B<-help>]
-[B<-CRLfile> I<file>]
+[B<-CRLfile> I<filename>|I<uri>]
[B<-crl_download>]
[B<-show_chain>]
[B<-verbose>]
-[B<-trusted> I<file>]
-[B<-untrusted> I<file>]
+[B<-trusted> I<filename>|I<uri>]
+[B<-untrusted> I<filename>|I<uri>]
[B<-vfyopt> I<nm>:I<v>]
{- $OpenSSL::safe::opt_name_synopsis -}
{- $OpenSSL::safe::opt_trust_synopsis -}
Print out a usage message.
-=item B<-CRLfile> I<file>
+=item B<-CRLfile> I<filename>|I<uri>
The file or URI should contain one or more CRLs in PEM or DER format.
This option can be specified more than once to include CRLs from multiple
-I<file>s.
+sources.
=item B<-crl_download>
Print extra information about the operations being performed.
-=item B<-trusted> I<file>
+=item B<-trusted> I<filename>|I<uri>
+
+A file or URI of (more or less) trusted certificates.
+See L<openssl-verification-options(1)> for more information on trust settings.
-A file or URI of trusted certificates in PEM, DER, or PKCS#12 format.
This option can be specified more than once to load certificates from multiple
-I<file>s.
+sources.
-=item B<-untrusted> I<file>
+=item B<-untrusted> I<filename>|I<uri>
-A file or URI of untrusted certificates in PEM, DER, or PKCS#12 format
-to use for chain building.
+A file or URI of untrusted certificates to use for chain building.
This option can be specified more than once to load certificates from multiple
-I<file>s.
-
+sources.
=item B<-vfyopt> I<nm>:I<v>
This command ignores many errors, in order to allow all the problems with a
certificate chain to be determined.
-=head1 BUGS
-
-Although the issuer checks are a considerable improvement over the old
-technique they still suffer from limitations in the underlying X509_LOOKUP
-API. One consequence of this is that trusted certificates with matching
-subject name must either appear in a file (as specified by the B<-CAfile>
-option), a directory (as specified by B<-CApath>), or a store (as specified
-by B<-CAstore>). If they occur in more than one location then only the
-certificates in the file will be recognised.
-
-Previous versions of OpenSSL assume certificates with matching subject
-name are identical and mishandled them.
-
-Previous versions of this documentation swapped the meaning of the
-B<X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT> and
-B<X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY> error codes.
-
=head1 SEE ALSO
L<openssl-verification-options(1)>,
=item B<-purpose>
-This option performs tests on the certificate extensions and prints
-the results. For a more complete description see the
-L</CERTIFICATE EXTENSIONS> section.
+This option performs tests on the certificate extensions and outputs
+the results. For a more complete description see
+L<openssl-verification-options(1)/Certificate Extensions>.
=item B<-pubkey>
They allow a finer control over the purposes the root CA can be used for.
For example, a CA may be trusted for SSL client but not SSL server use.
-See the description in L<openssl-verify(1)> for more information
+See L<openssl-verification-options(1)> for more information
on the meaning of trust settings.
Future versions of OpenSSL will recognize trust settings on any
=item B<-addtrust> I<arg>
-Adds a trusted certificate use.
-Any object name can be used here but currently only B<clientAuth> (SSL client
-use), B<serverAuth> (SSL server use), B<emailProtection> (S/MIME email)
-and B<anyExtendedKeyUsage> are used.
-As of OpenSSL 1.1.0, the last of these blocks all purposes when rejected or
-enables all purposes when trusted.
-Other OpenSSL applications may define additional uses.
+Adds an allowed trust anchor purpose.
+Any object name can be used here but currently only those
+listed in L<openssl-verification-options(1)/Trust Anchors> are supported.
+Other OpenSSL applications may define additional purposes.
=item B<-clrreject>
=item B<-addreject> I<arg>
-Adds a prohibited use.
+Adds a prohibited trust anchor purpose.
It accepts the same values as the B<-addtrust> option.
=back
name extension. Only unique email addresses will be printed out: it will
not print the same address more than once.
-=head1 CERTIFICATE EXTENSIONS
-
-The B<-purpose> option checks the certificate extensions and determines
-what the certificate can be used for. The actual checks done are rather
-complex and include various hacks and workarounds to handle broken
-certificates and software.
-
-The same code is used when verifying untrusted certificates in chains
-so this section is useful if a chain is rejected by the verify code.
-
-The basicConstraints extension CA flag is used to determine whether the
-certificate can be used as a CA. If the CA flag is true then it is a CA,
-if the CA flag is false then it is not a CA. B<All> CAs should have the
-CA flag set to true.
-
-If the basicConstraints extension is absent then the certificate is
-considered to be a "possible CA" other extensions are checked according
-to the intended use of the certificate. A warning is given in this case
-because the certificate should really not be regarded as a CA: however
-it is allowed to be a CA to work around some broken software.
-
-If the certificate is a V1 certificate (and thus has no extensions) and
-it is self-signed it is also assumed to be a CA but a warning is again
-given: this is to work around the problem of Verisign roots which are V1
-self-signed certificates.
-
-If the keyUsage extension is present then additional restraints are
-made on the uses of the certificate. A CA certificate B<must> have the
-keyCertSign bit set if the keyUsage extension is present.
-
-The extended key usage extension places additional restrictions on the
-certificate uses. If this extension is present (whether critical or not)
-the key can only be used for the purposes specified.
-
-A complete description of each test is given below. The comments about
-basicConstraints and keyUsage and V1 certificates above apply to B<all>
-CA certificates.
-
-
-=over 4
-
-=item B<SSL Client>
-
-The extended key usage extension must be absent or include the "web client
-authentication" OID. keyUsage must be absent or it must have the
-digitalSignature bit set. Netscape certificate type must be absent or it must
-have the SSL client bit set.
-
-=item B<SSL Client CA>
-
-The extended key usage extension must be absent or include the "web client
-authentication" OID. Netscape certificate type must be absent or it must have
-the SSL CA bit set: this is used as a work around if the basicConstraints
-extension is absent.
-
-=item B<SSL Server>
-
-The extended key usage extension must be absent or include the "web server
-authentication" and/or one of the SGC OIDs. keyUsage must be absent or it
-must have the digitalSignature, the keyEncipherment set or both bits set.
-Netscape certificate type must be absent or have the SSL server bit set.
-
-=item B<SSL Server CA>
-
-The extended key usage extension must be absent or include the "web server
-authentication" and/or one of the SGC OIDs. Netscape certificate type must
-be absent or the SSL CA bit must be set: this is used as a work around if the
-basicConstraints extension is absent.
-
-=item B<Netscape SSL Server>
-
-For Netscape SSL clients to connect to an SSL server it must have the
-keyEncipherment bit set if the keyUsage extension is present. This isn't
-always valid because some cipher suites use the key for digital signing.
-Otherwise it is the same as a normal SSL server.
-
-=item B<Common S/MIME Client Tests>
-
-The extended key usage extension must be absent or include the "email
-protection" OID. Netscape certificate type must be absent or should have the
-S/MIME bit set. If the S/MIME bit is not set in Netscape certificate type
-then the SSL client bit is tolerated as an alternative but a warning is shown:
-this is because some Verisign certificates don't set the S/MIME bit.
-
-=item B<S/MIME Signing>
-
-In addition to the common S/MIME client tests the digitalSignature bit or
-the nonRepudiation bit must be set if the keyUsage extension is present.
-
-=item B<S/MIME Encryption>
-
-In addition to the common S/MIME tests the keyEncipherment bit must be set
-if the keyUsage extension is present.
-
-=item B<S/MIME CA>
-
-The extended key usage extension must be absent or include the "email
-protection" OID. Netscape certificate type must be absent or must have the
-S/MIME CA bit set: this is used as a work around if the basicConstraints
-extension is absent.
-
-=item B<CRL Signing>
-
-The keyUsage extension must be absent or it must have the CRL signing bit
-set.
-
-=item B<CRL Signing CA>
-
-The normal CA tests apply. Except in this case the basicConstraints extension
-must be present.
-
-=back
-
=head1 BUGS
It is possible to produce invalid certificates or requests by specifying the
current certificate of B<ctx>. (This is implemented by calling
SSL_CTX_set0_chain() with B<sk> set to B<NULL>).
-SSL_CTX_build_cert_chain() builds the certificate chain for B<ctx> normally
-this uses the chain store or the verify store if the chain store is not set.
+SSL_CTX_build_cert_chain() builds the certificate chain for B<ctx>.
+Normally this uses the chain store
+or the verify store if the chain store is not set.
If the function is successful the built chain will replace any existing chain.
The B<flags> parameter can be set to B<SSL_BUILD_CHAIN_FLAG_UNTRUSTED> to use
existing chain certificates as untrusted CAs, B<SSL_BUILD_CHAIN_FLAG_NO_ROOT>
B<SSL_BUILD_CHAIN_FLAG_IGNORE_ERROR> ignores any errors during verification:
if flag B<SSL_BUILD_CHAIN_FLAG_CLEAR_ERROR> is also set verification errors
are cleared from the error queue.
+Details of the chain building process are described in
+L<openssl-verification-options(1)/Certification Path Building>.
Each of these functions operates on the I<current> end entity
(i.e. server or client) certificate. This is the last certificate loaded or
are located. The certificates available via B<CAfile>, B<CApath> and
B<CAstore> are trusted.
+Details of the certificate verification and chain checking process are
+described in L<openssl-verification-options(1)/Certification Path Validation>.
+
SSL_CTX_set_default_verify_paths() specifies that the default locations from
which CA certificates are loaded should be used. There is one default directory,
one default file and one default store.
building the certificate chain or when actually performing the verification
of a peer certificate.
-When looking up CA certificates, the OpenSSL library will first search the
-certificates in B<CAfile>, then those in B<CApath>. Certificate matching
-is done based on the subject name, the key identifier (if present), and the
-serial number as taken from the certificate to be verified. If these data
-do not match, the next certificate will be tried. If a first certificate
-matching the parameters is found, the verification process will be performed;
-no other certificates for the same parameters will be searched in case of
-failure.
+When looking up CA certificates for chain building, the OpenSSL library
+will search for suitable certificates first in B<CAfile>, then in B<CApath>.
+Details of the chain building process are described in
+L<openssl-verification-options(1)/Certification Path Building>.
If B<CAstore> is not NULL, it's a URI for to a store, which may
represent a single container or a whole catalogue of containers.
any client certificate chain.
The chain store is used to build the certificate chain.
+Details of the chain building and checking process are described in
+L<openssl-verification-options(1)/Certification Path Building> and
+L<openssl-verification-options(1)/Certification Path Validation>.
If the mode B<SSL_MODE_NO_AUTO_CHAIN> is set or a certificate chain is
configured already (for example using the functions such as
numerical value of the unknown code is returned in a static buffer. This is not
thread safe but will never happen unless an invalid code is passed.
+=head1 BUGS
+
+Previous versions of this documentation swapped the meaning of the
+B<X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT> and
+B<X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY> error codes.
+
=head1 SEE ALSO
L<X509_verify_cert(3)>, L<X509_STORE_CTX_verify(3)>,
X509_STORE_CTX_new_ex, X509_STORE_CTX_new, X509_STORE_CTX_cleanup,
X509_STORE_CTX_free, X509_STORE_CTX_init, X509_STORE_CTX_set0_trusted_stack,
X509_STORE_CTX_set_cert, X509_STORE_CTX_set0_crls,
-X509_STORE_CTX_get0_chain, X509_STORE_CTX_set0_verified_chain,
X509_STORE_CTX_get0_param, X509_STORE_CTX_set0_param,
X509_STORE_CTX_get0_untrusted, X509_STORE_CTX_set0_untrusted,
X509_STORE_CTX_get_num_untrusted,
+X509_STORE_CTX_get0_chain, X509_STORE_CTX_set0_verified_chain,
X509_STORE_CTX_set_default,
X509_STORE_CTX_set_verify,
X509_STORE_CTX_verify_fn
void X509_STORE_CTX_set0_trusted_stack(X509_STORE_CTX *ctx, STACK_OF(X509) *sk);
void X509_STORE_CTX_set_cert(X509_STORE_CTX *ctx, X509 *target);
- STACK_OF(X509) *X509_STORE_CTX_get0_chain(const X509_STORE_CTX *ctx);
- void X509_STORE_CTX_set0_verified_chain(X509_STORE_CTX *ctx, STACK_OF(X509) *chain);
void X509_STORE_CTX_set0_crls(X509_STORE_CTX *ctx, STACK_OF(X509_CRL) *sk);
X509_VERIFY_PARAM *X509_STORE_CTX_get0_param(const X509_STORE_CTX *ctx);
void X509_STORE_CTX_set0_param(X509_STORE_CTX *ctx, X509_VERIFY_PARAM *param);
- int X509_STORE_CTX_set_default(X509_STORE_CTX *ctx, const char *name);
STACK_OF(X509)* X509_STORE_CTX_get0_untrusted(const X509_STORE_CTX *ctx);
void X509_STORE_CTX_set0_untrusted(X509_STORE_CTX *ctx, STACK_OF(X509) *sk);
int X509_STORE_CTX_get_num_untrusted(const X509_STORE_CTX *ctx);
+ STACK_OF(X509) *X509_STORE_CTX_get0_chain(const X509_STORE_CTX *ctx);
+ void X509_STORE_CTX_set0_verified_chain(X509_STORE_CTX *ctx, STACK_OF(X509) *chain);
+ int X509_STORE_CTX_set_default(X509_STORE_CTX *ctx, const char *name);
typedef int (*X509_STORE_CTX_verify_fn)(X509_STORE_CTX *);
void X509_STORE_CTX_set_verify(X509_STORE_CTX *ctx, X509_STORE_CTX_verify_fn verify);
is no longer valid.
If I<ctx> is NULL nothing is done.
-X509_STORE_CTX_init() sets up I<ctx> for a subsequent verification operation.
It must be called before each call to L<X509_verify_cert(3)> or
L<X509_STORE_CTX_verify(3)>, i.e., a context is only good for one verification.
If you want to verify a further certificate or chain with the same I<ctx>
X509_STORE_CTX_set0_trusted_stack() sets the set of trusted certificates of
I<ctx> to I<sk>. This is an alternative way of specifying trusted certificates
-instead of using an B<X509_STORE> where its complexity is not needed.
+instead of using an B<X509_STORE> where its complexity is not needed
+or to make sure that only the given set I<sk> of certificates are trusted.
X509_STORE_CTX_set_cert() sets the target certificate to be verified in I<ctx>
to I<target>.
-X509_STORE_CTX_set0_verified_chain() sets the validated chain used
-by I<ctx> to be I<chain>.
-Ownership of the chain is transferred to I<ctx> and should not be
-free'd by the caller.
+X509_STORE_CTX_set0_verified_chain() sets the validated chain to I<chain>.
+Ownership of the chain is transferred to I<ctx>,
+and so it should not be free'd by the caller.
+
X509_STORE_CTX_get0_chain() returns the internal pointer used by the
-I<ctx> that contains the validated chain.
+I<ctx> that contains the constructed (output) chain.
X509_STORE_CTX_set0_crls() sets a set of CRLs to use to aid certificate
verification to I<sk>. These CRLs will only be used if CRL verification is
X509_STORE_CTX_get0_param() retrieves an internal pointer
to the verification parameters associated with I<ctx>.
+X509_STORE_CTX_set0_param() sets the internal verification parameter pointer
+to I<param>. After this call B<param> should not be used.
+
X509_STORE_CTX_get0_untrusted() retrieves an internal pointer to the
stack of untrusted certificates associated with I<ctx>.
X509_STORE_CTX_verify() will take the first element, if any,
as its default target if the target certificate is not set explicitly.
-X509_STORE_CTX_set0_param() sets the internal verification parameter pointer
-to I<param>. After this call B<param> should not be used.
+X509_STORE_CTX_get_num_untrusted() returns the number of untrusted certificates
+that were used in building the chain.
+This is can be used after calling L<X509_verify_cert(3)> and similar functions.
+With L<X509_STORE_CTX_verify(3)>, this does not count the first chain element.
+
+X509_STORE_CTX_get0_chain() returns the internal pointer used by the
+I<ctx> that contains the validated chain.
+
+Details of the chain building and checking process are described in
+L<openssl-verification-options(1)/Certification Path Building> and
+L<openssl-verification-options(1)/Certification Path Validation>.
+
+X509_STORE_CTX_set0_verified_chain() sets the validated chain used
+by I<ctx> to be I<chain>.
+Ownership of the chain is transferred to I<ctx>,
+and so it should not be free'd by the caller.
X509_STORE_CTX_set_default() looks up and sets the default verification
method to I<name>. This uses the function X509_VERIFY_PARAM_lookup() to
find an appropriate set of parameters from I<name>.
-X509_STORE_CTX_get_num_untrusted() returns the number of untrusted certificates
-that were used in building the chain following a call to L<X509_verify_cert(3)>.
-With L<X509_STORE_CTX_verify(3)>, this does not count the first chain element.
-
X509_STORE_CTX_set_verify() provides the capability for overriding the default
verify function. This function is responsible for verifying chain signatures and
expiration times.
with large numbers of certificates, and a great deal of flexibility in
how validation and policy checks are performed.
+Details of the chain building and checking process are described in
+L<openssl-verification-options(1)/Certification Path Building> and
+L<openssl-verification-options(1)/Certification Path Validation>.
+
L<X509_STORE_new(3)> creates an empty B<X509_STORE> structure, which contains
no information about trusted certificates or where such certificates
are located on disk, and is generally not usable. Normally, trusted
root CA certificates.
This makes it possible to trust self-issued certificates as well as certificates
issued by an intermediate CA without having to trust their ancestor root CA.
-With OpenSSL 1.1.0 and later and <X509_V_FLAG_PARTIAL_CHAIN> set, chain
+With OpenSSL 1.1.0 and later and B<X509_V_FLAG_PARTIAL_CHAIN> set, chain
construction stops as soon as the first certificate contained in the trust store
is added to the chain, whether that certificate is a self-signed "root"
certificate or a not self-signed "intermediate" or self-issued certificate.
projects / openssl.git / commitdiff