[openssl] master update
dev at ddvo.net
dev at ddvo.net
Tue Jun 8 05:48:54 UTC 2021
The branch master has been updated
via 09345c8cab01d0030234a001c7b2d64eac1e75ae (commit)
via 3cd4e5e73f8efc652c00fc8071b035bef7dc149c (commit)
via f9ac6f6956a23bd89e1d6bc9b5dcbb3df06544a1 (commit)
via 2576b9c31c66aabd2464a2c404a15421208607eb (commit)
via f1343f45d6bf636b0778396bd6e2b68ff5884a3b (commit)
via 62d2386bf8a8712e2b433e55f694ff898e4aded7 (commit)
from 69e0f8cca691dc474300422c48e14713ace8dd2c (commit)
- Log -----------------------------------------------------------------
commit 09345c8cab01d0030234a001c7b2d64eac1e75ae
Author: Dr. David von Oheimb <David.von.Oheimb at siemens.com>
Date: Thu Mar 4 08:47:51 2021 +0100
Move trust-related decls from x509.h.in to x509_vfy.h.in
Reviewed-by: Paul Dale <pauli at openssl.org>
(Merged from https://github.com/openssl/openssl/pull/13735)
commit 3cd4e5e73f8efc652c00fc8071b035bef7dc149c
Author: Dr. David von Oheimb <David.von.Oheimb at siemens.com>
Date: Thu Mar 4 07:36:21 2021 +0100
x509.h.in: extended 'documenting' comment on X509_TRUST_OK_ANY_EKU
This hopefully alleviates the fact that the name is unclear/misleading.
Reviewed-by: Paul Dale <pauli at openssl.org>
(Merged from https://github.com/openssl/openssl/pull/13735)
commit f9ac6f6956a23bd89e1d6bc9b5dcbb3df06544a1
Author: Dr. David von Oheimb <David.von.Oheimb at siemens.com>
Date: Wed Dec 23 23:29:04 2020 +0100
Improve the documentation of cert path building and validation
Reviewed-by: Paul Dale <pauli at openssl.org>
(Merged from https://github.com/openssl/openssl/pull/13735)
commit 2576b9c31c66aabd2464a2c404a15421208607eb
Author: Dr. David von Oheimb <David.von.Oheimb at siemens.com>
Date: Mon Jan 4 08:50:42 2021 +0100
X509_STORE_CTX_new.pod and x509_vfy.h.in: rename some params for clarity, improve their doc
Reviewed-by: Paul Dale <pauli at openssl.org>
(Merged from https://github.com/openssl/openssl/pull/13735)
commit f1343f45d6bf636b0778396bd6e2b68ff5884a3b
Author: Dr. David von Oheimb <David.von.Oheimb at siemens.com>
Date: Mon Jan 4 08:49:17 2021 +0100
x509_vfy.c: Improve a couple of internally documenting comments
Reviewed-by: Paul Dale <pauli at openssl.org>
(Merged from https://github.com/openssl/openssl/pull/13735)
commit 62d2386bf8a8712e2b433e55f694ff898e4aded7
Author: Dr. David von Oheimb <David.von.Oheimb at siemens.com>
Date: Mon Jan 4 08:48:24 2021 +0100
x509_trs.c: rename to x509_trust.c and correct comment in trust_compat()
Reviewed-by: Paul Dale <pauli at openssl.org>
(Merged from https://github.com/openssl/openssl/pull/13735)
-----------------------------------------------------------------------
Summary of changes:
crypto/x509/build.info | 2 +-
crypto/x509/v3_purp.c | 8 +-
crypto/x509/{x509_trs.c => x509_trust.c} | 2 +-
crypto/x509/x509_vfy.c | 20 +-
doc/man1/openssl-verification-options.pod | 344 +++++++++++++++++++++++-----
doc/man1/openssl-verify.pod.in | 43 ++--
doc/man1/openssl-x509.pod.in | 134 +----------
doc/man3/SSL_CTX_add1_chain_cert.pod | 7 +-
doc/man3/SSL_CTX_load_verify_locations.pod | 15 +-
doc/man3/SSL_CTX_set1_verify_cert_store.pod | 3 +
doc/man3/X509_STORE_CTX_get_error.pod | 6 +
doc/man3/X509_STORE_CTX_new.pod | 57 +++--
doc/man3/X509_STORE_add_cert.pod | 4 +
doc/man3/X509_VERIFY_PARAM_set_flags.pod | 2 +-
include/openssl/x509.h.in | 70 ------
include/openssl/x509_vfy.h.in | 77 ++++++-
16 files changed, 460 insertions(+), 334 deletions(-)
rename crypto/x509/{x509_trs.c => x509_trust.c} (99%)
diff --git a/crypto/x509/build.info b/crypto/x509/build.info
index 05c8e3003b..8820f983bb 100644
--- a/crypto/x509/build.info
+++ b/crypto/x509/build.info
@@ -5,7 +5,7 @@ SOURCE[../../libcrypto]=\
x509_set.c x509cset.c x509rset.c x509_err.c \
x509name.c x509_v3.c x509_ext.c x509_att.c \
x509_meth.c x509_lu.c x_all.c x509_txt.c \
- x509_trs.c by_file.c by_dir.c by_store.c x509_vpm.c \
+ x509_trust.c by_file.c by_dir.c by_store.c x509_vpm.c \
x_crl.c t_crl.c x_req.c t_req.c x_x509.c t_x509.c \
x_pubkey.c x_x509a.c x_attrib.c x_exten.c x_name.c \
v3_bcons.c v3_bitst.c v3_conf.c v3_extku.c v3_ia5.c v3_utf8.c v3_lib.c \
diff --git a/crypto/x509/v3_purp.c b/crypto/x509/v3_purp.c
index bcec4194fa..a6ebbd5f94 100644
--- a/crypto/x509/v3_purp.c
+++ b/crypto/x509/v3_purp.c
@@ -894,10 +894,10 @@ static int no_check_purpose(const X509_PURPOSE *xp, const X509 *x,
* 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().
diff --git a/crypto/x509/x509_trs.c b/crypto/x509/x509_trust.c
similarity index 99%
rename from crypto/x509/x509_trs.c
rename to crypto/x509/x509_trust.c
index bbde32af70..ff578aee73 100644
--- a/crypto/x509/x509_trs.c
+++ b/crypto/x509/x509_trust.c
@@ -239,7 +239,7 @@ static int trust_1oid(X509_TRUST *trust, X509 *x, int flags)
static int trust_compat(X509_TRUST *trust, X509 *x, int flags)
{
- /* Call for side-effect of computing hash and caching extensions */
+ /* Call for side-effect of setting EXFLAG_SS for self-signed-certs */
if (X509_check_purpose(x, -1, 0) != 1)
return X509_TRUST_UNTRUSTED;
if ((flags & X509_TRUST_NO_SS_COMPAT) == 0 && (x->ex_flags & EXFLAG_SS))
diff --git a/crypto/x509/x509_vfy.c b/crypto/x509/x509_vfy.c
index bb54a064bc..f020d4864d 100644
--- a/crypto/x509/x509_vfy.c
+++ b/crypto/x509/x509_vfy.c
@@ -356,8 +356,8 @@ static int check_issued(ossl_unused X509_STORE_CTX *ctx, X509 *x, X509 *issuer)
return 0;
}
-/*
- * Alternative lookup method: look from a STACK stored in other_ctx.
+/*-
+ * Alternative get_issuer method: look up from a STACK_OF(X509) in other_ctx.
* Returns -1 on internal error.
*/
static int get_issuer_sk(X509 **issuer, X509_STORE_CTX *ctx, X509 *x)
@@ -368,7 +368,10 @@ static int get_issuer_sk(X509 **issuer, X509_STORE_CTX *ctx, X509 *x)
return 0;
}
-/* Returns NULL on internal error (such as out of memory) */
+/*-
+ * Alternative lookup method: look from a STACK stored in other_ctx.
+ * Returns NULL on internal error (such as out of memory).
+ */
static STACK_OF(X509) *lookup_certs_sk(X509_STORE_CTX *ctx,
const X509_NAME *nm)
{
@@ -834,7 +837,7 @@ static int check_trust(X509_STORE_CTX *ctx, int num_untrusted)
for (i = num_untrusted; i < num; i++) {
x = sk_X509_value(ctx->chain, i);
trust = X509_check_trust(x, ctx->param->trust, 0);
- /* If explicitly trusted return trusted */
+ /* If explicitly trusted (so not neutral nor rejected) return trusted */
if (trust == X509_TRUST_TRUSTED)
goto trusted;
if (trust == X509_TRUST_REJECTED)
@@ -1816,7 +1819,7 @@ static int internal_verify(X509_STORE_CTX *ctx)
}
}
- /* in addition to RFC 5280, do also for trusted (root) cert */
+ /* In addition to RFC 5280 requirements do also for trust anchor cert */
/* Calls verify callback as needed */
if (!ossl_x509_check_cert_time(ctx, xs, n))
return 0;
@@ -2451,8 +2454,8 @@ int X509_STORE_CTX_init(X509_STORE_CTX *ctx, X509_STORE *store, X509 *x509,
}
/*
- * Set alternative lookup method: just a STACK of trusted certificates. This
- * avoids X509_STORE nastiness where it isn't needed.
+ * Set alternative get_issuer method: just from a STACK of trusted certificates.
+ * This avoids the complexity of X509_STORE where it is not needed.
*/
void X509_STORE_CTX_set0_trusted_stack(X509_STORE_CTX *ctx, STACK_OF(X509) *sk)
{
@@ -3004,7 +3007,8 @@ static int build_chain(X509_STORE_CTX *ctx)
#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
diff --git a/doc/man1/openssl-verification-options.pod b/doc/man1/openssl-verification-options.pod
index bc7658a9f9..1c91c77852 100644
--- a/doc/man1/openssl-verification-options.pod
+++ b/doc/man1/openssl-verification-options.pod
@@ -13,51 +13,156 @@ I<command>
=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,
@@ -78,23 +183,25 @@ valid. If any operation fails then the certificate is not valid.
=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>
@@ -102,8 +209,9 @@ Do not load the default file of trusted certificates.
=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.
@@ -114,8 +222,8 @@ Do not use the default directory of trusted certificates.
=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.
@@ -127,7 +235,7 @@ chain (for example with L<openssl-s_time(1)>).
=item B<-no-CAstore>
-Do not use the default store.
+Do not use the default store of trusted CA certificates.
=back
@@ -267,9 +375,10 @@ 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.
+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>
@@ -299,20 +408,20 @@ 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.
+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>
@@ -346,7 +455,8 @@ Set policy variable inhibit-policy-mapping (see RFC5280).
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>
@@ -376,7 +486,8 @@ 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)>.
+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
@@ -426,6 +537,128 @@ This option has no effect and is retained for backward compatibility only.
=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)>,
@@ -438,7 +671,6 @@ L<openssl-smime(1)>,
L<openssl-cmp(1)>,
L<openssl-cms(1)>
-
=head1 HISTORY
The checks enabled by B<-x509_strict> have been extended in OpenSSL 3.0.
diff --git a/doc/man1/openssl-verify.pod.in b/doc/man1/openssl-verify.pod.in
index ef9ced3a5c..7e51af6eac 100644
--- a/doc/man1/openssl-verify.pod.in
+++ b/doc/man1/openssl-verify.pod.in
@@ -9,12 +9,12 @@ openssl-verify - certificate verification command
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 -}
@@ -36,11 +36,11 @@ problems, this program attempts to display all of them.
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>
@@ -56,19 +56,19 @@ flagged as "untrusted".
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>
@@ -126,23 +126,6 @@ F<< <openssl/x509_vfy.h> >>.
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)>,
diff --git a/doc/man1/openssl-x509.pod.in b/doc/man1/openssl-x509.pod.in
index 24c7a5a34a..65b6487481 100644
--- a/doc/man1/openssl-x509.pod.in
+++ b/doc/man1/openssl-x509.pod.in
@@ -305,9 +305,9 @@ Prints the OCSP responder address(es) if any.
=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>
@@ -518,7 +518,7 @@ Trust settings currently are only used with a root CA.
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
@@ -545,13 +545,10 @@ Clears all the permitted or trusted uses of the certificate.
=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>
@@ -559,7 +556,7 @@ Clears all the prohibited or rejected uses of the certificate.
=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
@@ -732,119 +729,6 @@ The B<-email> option searches the subject name and the subject alternative
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
diff --git a/doc/man3/SSL_CTX_add1_chain_cert.pod b/doc/man3/SSL_CTX_add1_chain_cert.pod
index cd6beb311a..81394f1ad5 100644
--- a/doc/man3/SSL_CTX_add1_chain_cert.pod
+++ b/doc/man3/SSL_CTX_add1_chain_cert.pod
@@ -52,8 +52,9 @@ SSL_CTX_clear_chain_certs() clears any existing chain associated with 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>
@@ -63,6 +64,8 @@ sanity checking and rearranging them if necessary), the flag
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
diff --git a/doc/man3/SSL_CTX_load_verify_locations.pod b/doc/man3/SSL_CTX_load_verify_locations.pod
index 7408a2080d..da64738700 100644
--- a/doc/man3/SSL_CTX_load_verify_locations.pod
+++ b/doc/man3/SSL_CTX_load_verify_locations.pod
@@ -33,6 +33,9 @@ locations for B<ctx>, at which CA certificates for verification purposes
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.
@@ -85,14 +88,10 @@ The certificates in B<CApath> are only looked up when required, e.g. when
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.
diff --git a/doc/man3/SSL_CTX_set1_verify_cert_store.pod b/doc/man3/SSL_CTX_set1_verify_cert_store.pod
index 780a3c72fa..d83fff9b2f 100644
--- a/doc/man3/SSL_CTX_set1_verify_cert_store.pod
+++ b/doc/man3/SSL_CTX_set1_verify_cert_store.pod
@@ -52,6 +52,9 @@ the server's certificate chain and a SSL/TLS server will use it to verify
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
diff --git a/doc/man3/X509_STORE_CTX_get_error.pod b/doc/man3/X509_STORE_CTX_get_error.pod
index fad51ea756..023025afca 100644
--- a/doc/man3/X509_STORE_CTX_get_error.pod
+++ b/doc/man3/X509_STORE_CTX_get_error.pod
@@ -460,6 +460,12 @@ If an unrecognised error code is passed to X509_verify_cert_error_string() the
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)>,
diff --git a/doc/man3/X509_STORE_CTX_new.pod b/doc/man3/X509_STORE_CTX_new.pod
index f2f6a01c44..b982dc9c7e 100644
--- a/doc/man3/X509_STORE_CTX_new.pod
+++ b/doc/man3/X509_STORE_CTX_new.pod
@@ -5,10 +5,10 @@
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
@@ -24,24 +24,24 @@ X509_STORE_CTX_verify_fn
void X509_STORE_CTX_free(X509_STORE_CTX *ctx);
int X509_STORE_CTX_init(X509_STORE_CTX *ctx, X509_STORE *trust_store,
- X509 *target, STACK_OF(X509) *chain);
+ X509 *target, STACK_OF(X509) *untrusted);
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 *x);
- 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_set_cert(X509_STORE_CTX *ctx, X509 *target);
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);
@@ -66,7 +66,6 @@ X509_STORE_CTX_free() completely frees up I<ctx>. After this call I<ctx>
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>
@@ -75,9 +74,9 @@ The trusted certificate store is set to I<trust_store> of type B<X509_STORE>.
This may be NULL because there are no trusted certificates or because
they are provided simply as a list using X509_STORE_CTX_set0_trusted_stack().
The certificate to be verified is set to I<target>,
-and a list of additional certificates may be provided in I<chain>,
+and a list of additional certificates may be provided in I<untrusted>,
which will be untrusted but may be used to build the chain.
-Each of the I<trust_store>, I<target> and I<chain> parameters can be NULL.
+Each of the I<trust_store>, I<target> and I<untrusted> parameters can be NULL.
Yet note that L<X509_verify_cert(3)> and L<X509_STORE_CTX_verify(3)>
will need a verification target.
This can also be set using X509_STORE_CTX_set_cert().
@@ -87,17 +86,18 @@ this can be also set indirectly using X509_STORE_CTX_set0_untrusted().
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>.
+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<x>.
+to I<target>.
+
+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_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_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
@@ -108,6 +108,9 @@ for example in a PKCS#7 structure.
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>.
@@ -116,17 +119,27 @@ of untrusted certificates associated with I<ctx> to I<sk>.
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.
diff --git a/doc/man3/X509_STORE_add_cert.pod b/doc/man3/X509_STORE_add_cert.pod
index b1034a3c09..f53a345621 100644
--- a/doc/man3/X509_STORE_add_cert.pod
+++ b/doc/man3/X509_STORE_add_cert.pod
@@ -53,6 +53,10 @@ It admits multiple lookup mechanisms and efficient scaling performance
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
diff --git a/doc/man3/X509_VERIFY_PARAM_set_flags.pod b/doc/man3/X509_VERIFY_PARAM_set_flags.pod
index 6265915d9c..9eedb339d1 100644
--- a/doc/man3/X509_VERIFY_PARAM_set_flags.pod
+++ b/doc/man3/X509_VERIFY_PARAM_set_flags.pod
@@ -317,7 +317,7 @@ trust store to be treated as trust anchors, in the same way as self-signed
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.
diff --git a/include/openssl/x509.h.in b/include/openssl/x509.h.in
index 38c7b42c22..39aae063f6 100644
--- a/include/openssl/x509.h.in
+++ b/include/openssl/x509.h.in
@@ -111,54 +111,6 @@ typedef struct X509_req_st X509_REQ;
typedef struct x509_cert_aux_st X509_CERT_AUX;
typedef struct x509_cinf_st X509_CINF;
-/* This is used for a table of trust checking functions */
-
-typedef struct x509_trust_st {
- int trust;
- int flags;
- int (*check_trust) (struct x509_trust_st *, X509 *, int);
- char *name;
- int arg1;
- void *arg2;
-} X509_TRUST;
-{-
- generate_stack_macros("X509_TRUST");
--}
-
-
-/* standard trust ids */
-
-# define X509_TRUST_DEFAULT 0 /* Only valid in purpose settings */
-
-# define X509_TRUST_COMPAT 1
-# define X509_TRUST_SSL_CLIENT 2
-# define X509_TRUST_SSL_SERVER 3
-# define X509_TRUST_EMAIL 4
-# define X509_TRUST_OBJECT_SIGN 5
-# define X509_TRUST_OCSP_SIGN 6
-# define X509_TRUST_OCSP_REQUEST 7
-# define X509_TRUST_TSA 8
-
-/* Keep these up to date! */
-# define X509_TRUST_MIN 1
-# define X509_TRUST_MAX 8
-
-/* trust_flags values */
-# define X509_TRUST_DYNAMIC (1U << 0)
-# define X509_TRUST_DYNAMIC_NAME (1U << 1)
-/* No compat trust if self-signed, preempts "DO_SS" */
-# define X509_TRUST_NO_SS_COMPAT (1U << 2)
-/* Compat trust if no explicit accepted trust EKUs */
-# define X509_TRUST_DO_SS_COMPAT (1U << 3)
-/* Accept "anyEKU" as a wildcard trust OID */
-# define X509_TRUST_OK_ANY_EKU (1U << 4)
-
-/* check_trust return codes */
-
-# define X509_TRUST_TRUSTED 1
-# define X509_TRUST_REJECTED 2
-# define X509_TRUST_UNTRUSTED 3
-
/* Flags for X509_print_ex() */
# define X509_FLAG_COMPAT 0
@@ -625,21 +577,10 @@ ASN1_OCTET_STRING *X509_get0_distinguishing_id(X509 *x);
void X509_REQ_set0_distinguishing_id(X509_REQ *x, ASN1_OCTET_STRING *d_id);
ASN1_OCTET_STRING *X509_REQ_get0_distinguishing_id(X509_REQ *x);
-int X509_trusted(const X509 *x);
int X509_alias_set1(X509 *x, const unsigned char *name, int len);
int X509_keyid_set1(X509 *x, const unsigned char *id, int len);
unsigned char *X509_alias_get0(X509 *x, int *len);
unsigned char *X509_keyid_get0(X509 *x, int *len);
-int (*X509_TRUST_set_default(int (*trust) (int, X509 *, int))) (int, X509 *,
- int);
-int X509_TRUST_set(int *t, int trust);
-int X509_add1_trust_object(X509 *x, const ASN1_OBJECT *obj);
-int X509_add1_reject_object(X509 *x, const ASN1_OBJECT *obj);
-void X509_trust_clear(X509 *x);
-void X509_reject_clear(X509 *x);
-
-STACK_OF(ASN1_OBJECT) *X509_get0_trust_objects(X509 *x);
-STACK_OF(ASN1_OBJECT) *X509_get0_reject_objects(X509 *x);
DECLARE_ASN1_FUNCTIONS(X509_REVOKED)
DECLARE_ASN1_FUNCTIONS(X509_CRL_INFO)
@@ -1134,17 +1075,6 @@ int X509_PUBKEY_get0_param(ASN1_OBJECT **ppkalg,
X509_ALGOR **pa, const X509_PUBKEY *pub);
int X509_PUBKEY_eq(const X509_PUBKEY *a, const X509_PUBKEY *b);
-int X509_check_trust(X509 *x, int id, int flags);
-int X509_TRUST_get_count(void);
-X509_TRUST *X509_TRUST_get0(int idx);
-int X509_TRUST_get_by_id(int id);
-int X509_TRUST_add(int id, int flags, int (*ck) (X509_TRUST *, X509 *, int),
- const char *name, int arg1, void *arg2);
-void X509_TRUST_cleanup(void);
-int X509_TRUST_get_flags(const X509_TRUST *xp);
-char *X509_TRUST_get0_name(const X509_TRUST *xp);
-int X509_TRUST_get_trust(const X509_TRUST *xp);
-
# ifdef __cplusplus
}
# endif
diff --git a/include/openssl/x509_vfy.h.in b/include/openssl/x509_vfy.h.in
index 126c1d658a..80f18bd787 100644
--- a/include/openssl/x509_vfy.h.in
+++ b/include/openssl/x509_vfy.h.in
@@ -72,11 +72,76 @@ typedef enum {
.generate_stack_macros("X509_VERIFY_PARAM");
-}
+/* This is used for a table of trust checking functions */
+typedef struct x509_trust_st {
+ int trust;
+ int flags;
+ int (*check_trust) (struct x509_trust_st *, X509 *, int);
+ char *name;
+ int arg1;
+ void *arg2;
+} X509_TRUST;
+{-
+ generate_stack_macros("X509_TRUST");
+-}
+
+/* standard trust ids */
+# define X509_TRUST_DEFAULT 0 /* Only valid in purpose settings */
+# define X509_TRUST_COMPAT 1
+# define X509_TRUST_SSL_CLIENT 2
+# define X509_TRUST_SSL_SERVER 3
+# define X509_TRUST_EMAIL 4
+# define X509_TRUST_OBJECT_SIGN 5
+# define X509_TRUST_OCSP_SIGN 6
+# define X509_TRUST_OCSP_REQUEST 7
+# define X509_TRUST_TSA 8
+/* Keep these up to date! */
+# define X509_TRUST_MIN 1
+# define X509_TRUST_MAX 8
+
+/* trust_flags values */
+# define X509_TRUST_DYNAMIC (1U << 0)
+# define X509_TRUST_DYNAMIC_NAME (1U << 1)
+/* No compat trust if self-signed, preempts "DO_SS" */
+# define X509_TRUST_NO_SS_COMPAT (1U << 2)
+/* Compat trust if no explicit accepted trust EKUs */
+# define X509_TRUST_DO_SS_COMPAT (1U << 3)
+/* Accept "anyEKU" as a wildcard rejection OID and as a wildcard trust OID */
+# define X509_TRUST_OK_ANY_EKU (1U << 4)
+
+/* check_trust return codes */
+# define X509_TRUST_TRUSTED 1
+# define X509_TRUST_REJECTED 2
+# define X509_TRUST_UNTRUSTED 3
+
+int X509_TRUST_set(int *t, int trust);
+int X509_TRUST_get_count(void);
+X509_TRUST *X509_TRUST_get0(int idx);
+int X509_TRUST_get_by_id(int id);
+int X509_TRUST_add(int id, int flags, int (*ck) (X509_TRUST *, X509 *, int),
+ const char *name, int arg1, void *arg2);
+void X509_TRUST_cleanup(void);
+int X509_TRUST_get_flags(const X509_TRUST *xp);
+char *X509_TRUST_get0_name(const X509_TRUST *xp);
+int X509_TRUST_get_trust(const X509_TRUST *xp);
+
+int X509_trusted(const X509 *x);
+int X509_add1_trust_object(X509 *x, const ASN1_OBJECT *obj);
+int X509_add1_reject_object(X509 *x, const ASN1_OBJECT *obj);
+void X509_trust_clear(X509 *x);
+void X509_reject_clear(X509 *x);
+STACK_OF(ASN1_OBJECT) *X509_get0_trust_objects(X509 *x);
+STACK_OF(ASN1_OBJECT) *X509_get0_reject_objects(X509 *x);
+
+int (*X509_TRUST_set_default(int (*trust) (int, X509 *, int))) (int, X509 *,
+ int);
+int X509_check_trust(X509 *x, int id, int flags);
+
+int X509_verify_cert(X509_STORE_CTX *ctx);
+int X509_STORE_CTX_verify(X509_STORE_CTX *ctx);
STACK_OF(X509) *X509_build_chain(X509 *target, STACK_OF(X509) *certs,
X509_STORE *store, int with_self_signed,
OSSL_LIB_CTX *libctx, const char *propq);
-int X509_verify_cert(X509_STORE_CTX *ctx);
-int X509_STORE_CTX_verify(X509_STORE_CTX *ctx);
int X509_STORE_set_depth(X509_STORE *store, int depth);
@@ -401,8 +466,8 @@ X509_STORE_CTX *X509_STORE_CTX_new(void);
int X509_STORE_CTX_get1_issuer(X509 **issuer, X509_STORE_CTX *ctx, X509 *x);
void X509_STORE_CTX_free(X509_STORE_CTX *ctx);
-int X509_STORE_CTX_init(X509_STORE_CTX *ctx, X509_STORE *store,
- X509 *target, STACK_OF(X509) *chain);
+int X509_STORE_CTX_init(X509_STORE_CTX *ctx, X509_STORE *trust_store,
+ X509 *target, STACK_OF(X509) *untrusted);
void X509_STORE_CTX_set0_trusted_stack(X509_STORE_CTX *ctx, STACK_OF(X509) *sk);
void X509_STORE_CTX_cleanup(X509_STORE_CTX *ctx);
@@ -601,9 +666,9 @@ X509_CRL *X509_STORE_CTX_get0_current_crl(const X509_STORE_CTX *ctx);
X509_STORE_CTX *X509_STORE_CTX_get0_parent_ctx(const X509_STORE_CTX *ctx);
STACK_OF(X509) *X509_STORE_CTX_get0_chain(const X509_STORE_CTX *ctx);
STACK_OF(X509) *X509_STORE_CTX_get1_chain(const X509_STORE_CTX *ctx);
-void X509_STORE_CTX_set_cert(X509_STORE_CTX *c, X509 *x);
+void X509_STORE_CTX_set_cert(X509_STORE_CTX *ctx, X509 *target);
void X509_STORE_CTX_set0_verified_chain(X509_STORE_CTX *c, STACK_OF(X509) *sk);
-void X509_STORE_CTX_set0_crls(X509_STORE_CTX *c, STACK_OF(X509_CRL) *sk);
+void X509_STORE_CTX_set0_crls(X509_STORE_CTX *ctx, STACK_OF(X509_CRL) *sk);
int X509_STORE_CTX_set_purpose(X509_STORE_CTX *ctx, int purpose);
int X509_STORE_CTX_set_trust(X509_STORE_CTX *ctx, int trust);
int X509_STORE_CTX_purpose_inherit(X509_STORE_CTX *ctx, int def_purpose,
More information about the openssl-commits
mailing list