[openssl] master update
dev at ddvo.net
dev at ddvo.net
Sat Jun 26 13:39:01 UTC 2021
The branch master has been updated
via 4acda8635ed55ddf831d1bb3dc6086054f01cc61 (commit)
from 426005eea5afd64bb76006f0fda69502ab3e008d (commit)
- Log -----------------------------------------------------------------
commit 4acda8635ed55ddf831d1bb3dc6086054f01cc61
Author: Dr. David von Oheimb <David.von.Oheimb at siemens.com>
Date: Tue Feb 16 11:17:07 2021 +0100
DOC: Clarify the role of EKUs including defaults for TLS client and server use
Reviewed-by: Paul Dale <pauli at openssl.org>
(Merged from https://github.com/openssl/openssl/pull/14199)
-----------------------------------------------------------------------
Summary of changes:
doc/man1/openssl-verification-options.pod | 27 ++++++++++++++++++---------
doc/man1/openssl-x509.pod.in | 10 ++++++----
doc/man3/SSL_CTX_new.pod | 28 ++++++++++++++++++++++------
doc/man3/SSL_CTX_set_verify.pod | 2 +-
doc/man3/SSL_new.pod | 2 +-
doc/man3/X509_STORE_CTX_new.pod | 5 ++++-
doc/man3/X509_VERIFY_PARAM_set_flags.pod | 2 +-
doc/man3/X509_check_purpose.pod | 3 +++
doc/man5/x509v3_config.pod | 18 +++++++++++-------
9 files changed, 67 insertions(+), 30 deletions(-)
diff --git a/doc/man1/openssl-verification-options.pod b/doc/man1/openssl-verification-options.pod
index 1c91c77852..c634ccae15 100644
--- a/doc/man1/openssl-verification-options.pod
+++ b/doc/man1/openssl-verification-options.pod
@@ -151,10 +151,13 @@ 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 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.
+for consistency with the supplied purpose.
+If the B<-purpose> option is not given then no such checks are done
+except for SSL/TLS connection setup,
+where by default C<sslserver> or C<sslclient>, are checked.
+The target or "leaf" certificate, as well as any other untrusted certificates,
+must have extensions compatible with the specified purpose.
+All certificates except the target or "leaf" must also be valid CA certificates.
The precise extensions required are described in more detail in
L<openssl-x509(1)/CERTIFICATE EXTENSIONS>.
@@ -452,11 +455,17 @@ Set policy variable inhibit-policy-mapping (see RFC5280).
=item B<-purpose> I<purpose>
-The intended use for the certificate. If this option is not specified, this
-command will not consider certificate purpose during chain verification.
-Currently accepted uses are B<sslclient>, B<sslserver>, B<nssslserver>,
-B<smimesign>, B<smimeencrypt>, B<crlsign>, B<ocsphelper>, B<timestampsign>,
-and <any>.
+The intended use for the certificate.
+Currently defined purposes are C<sslclient>, C<sslserver>, C<nssslserver>,
+C<smimesign>, C<smimeencrypt>, C<crlsign>, C<ocsphelper>, C<timestampsign>,
+and C<any>.
+If peer certificate verification is enabled, by default the TLS implementation
+as well as the commands B<s_client> and B<s_server> check for consistency
+with TLS server or TLS client use, respectively.
+
+While IETF RFC 5280 says that B<id-kp-serverAuth> and B<id-kp-clientAuth>
+are only for WWW use, in practice they are used for all kinds of TLS clients
+and servers, and this is what OpenSSL assumes as well.
=item B<-verify_depth> I<num>
diff --git a/doc/man1/openssl-x509.pod.in b/doc/man1/openssl-x509.pod.in
index 0e073d6b05..9c77a216c2 100644
--- a/doc/man1/openssl-x509.pod.in
+++ b/doc/man1/openssl-x509.pod.in
@@ -551,10 +551,12 @@ Clears all the permitted or trusted uses of the certificate.
=item B<-addtrust> I<arg>
-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.
+Adds a trusted certificate use.
+Any object name can be used here but currently only B<clientAuth>,
+B<serverAuth>, B<emailProtection>, and B<anyExtendedKeyUsage> are defined.
+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.
=item B<-clrreject>
diff --git a/doc/man3/SSL_CTX_new.pod b/doc/man3/SSL_CTX_new.pod
index 6bab45631f..61de1a6551 100644
--- a/doc/man3/SSL_CTX_new.pod
+++ b/doc/man3/SSL_CTX_new.pod
@@ -74,8 +74,11 @@ functions
=head1 DESCRIPTION
SSL_CTX_new_ex() creates a new B<SSL_CTX> object, which holds various
-configuration and data relevant to TLS/SSL or DTLS session establishment. The
-library context I<libctx> (see L<OSSL_LIB_CTX(3)>) is used to provide the
+configuration and data relevant to SSL/TLS or DTLS session establishment.
+These are later inherited by the B<SSL> object representing an active session.
+The I<method> parameter specifies whether the context will be used for the
+client or server side or both - for details see the L</NOTES> below.
+The library context I<libctx> (see L<OSSL_LIB_CTX(3)>) is used to provide the
cryptographic algorithms needed for the session. Any cryptographic algorithms
that are used by any B<SSL> objects created from this B<SSL_CTX> will be fetched
from the I<libctx> using the property query string I<propq> (see
@@ -97,10 +100,21 @@ provide serialization of access for these cases.
=head1 NOTES
+On session estabilishment, by default, no peer credentials verification is done.
+This must be explicitly requested, typically using L<SSL_CTX_set_verify(3)>.
+For verifying peer certificates many options can be set using various functions
+such as L<SSL_CTX_load_verify_locations(3)> and L<SSL_CTX_set1_param(3)>.
+The L<X509_VERIFY_PARAM_set_purpose(3)> function can be used, also in conjunction
+with L<SSL_CTX_get0_param(3)>, to set the intended purpose of the session.
+The default is B<X509_PURPOSE_SSL_SERVER> on the client side
+and B<X509_PURPOSE_SSL_CLIENT> on the server side.
+
The SSL_CTX object uses I<method> as the connection method.
-The methods exist in a generic type (for client and server use), a server only
-type, and a client only type.
-B<method> can be one of the following types:
+Three method variants are available: a generic method (for either client or
+server use), a server-only method, and a client-only method.
+
+The I<method> parameter of SSL_CTX_new_ex() and SSL_CTX_new()
+can be one of the following:
=over 4
@@ -214,7 +228,9 @@ SSL_CTX_up_ref() returns 1 for success and 0 for failure.
=head1 SEE ALSO
-L<SSL_CTX_set_options(3)>, L<SSL_CTX_free(3)>, L<SSL_accept(3)>,
+L<SSL_CTX_set_options(3)>, L<SSL_CTX_free(3)>,
+SSL_CTX_set_verify(3), L<SSL_CTX_set1_param(3)>, L<SSL_CTX_get0_param(3)>,
+L<SSL_connect(3)>, L<SSL_accept(3)>,
L<SSL_CTX_set_min_proto_version(3)>, L<ssl(7)>, L<SSL_set_connect_state(3)>
=head1 HISTORY
diff --git a/doc/man3/SSL_CTX_set_verify.pod b/doc/man3/SSL_CTX_set_verify.pod
index b72227c924..5e3ebef8e6 100644
--- a/doc/man3/SSL_CTX_set_verify.pod
+++ b/doc/man3/SSL_CTX_set_verify.pod
@@ -9,7 +9,7 @@ SSL_verify_cb,
SSL_verify_client_post_handshake,
SSL_set_post_handshake_auth,
SSL_CTX_set_post_handshake_auth
-- set peer certificate verification parameters
+- set various SSL/TLS parameters for peer certificate verification
=head1 SYNOPSIS
diff --git a/doc/man3/SSL_new.pod b/doc/man3/SSL_new.pod
index c7c5758cb1..02cbd036b5 100644
--- a/doc/man3/SSL_new.pod
+++ b/doc/man3/SSL_new.pod
@@ -61,7 +61,7 @@ L<SSL_set_tmp_dh_callback(3)>, or L<SSL_set_dh_auto(3)>
L<SSL_set_min_proto_version(3)> or L<SSL_set_max_proto_version(3)> (Note: Only
from OpenSSL 1.1.1h and above)
-=item any Verify mode, callback or depth set via L<SSL_set_verify(3)> or
+=item any verify mode, callback or depth set via L<SSL_set_verify(3)> or
L<SSL_set_verify_depth(3)> or any configured X509 verification parameters
=item any msg callback or info callback set via L<SSL_set_msg_callback(3)> or
diff --git a/doc/man3/X509_STORE_CTX_new.pod b/doc/man3/X509_STORE_CTX_new.pod
index b982dc9c7e..56a36bfecd 100644
--- a/doc/man3/X509_STORE_CTX_new.pod
+++ b/doc/man3/X509_STORE_CTX_new.pod
@@ -138,7 +138,10 @@ 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>.
+find an appropriate set of parameters from the purpose identifier I<name>.
+Currently defined purposes are C<sslclient>, C<sslserver>, C<nssslserver>,
+C<smimesign>, C<smimeencrypt>, C<crlsign>, C<ocsphelper>, C<timestampsign>,
+and C<any>.
X509_STORE_CTX_set_verify() provides the capability for overriding the default
verify function. This function is responsible for verifying chain signatures and
diff --git a/doc/man3/X509_VERIFY_PARAM_set_flags.pod b/doc/man3/X509_VERIFY_PARAM_set_flags.pod
index 2041176d4f..1213627be7 100644
--- a/doc/man3/X509_VERIFY_PARAM_set_flags.pod
+++ b/doc/man3/X509_VERIFY_PARAM_set_flags.pod
@@ -89,7 +89,7 @@ X509_VERIFY_PARAM_clear_flags() clears the flags B<flags> in B<param>.
X509_VERIFY_PARAM_set_purpose() sets the verification purpose in B<param>
to B<purpose>. This determines the acceptable purpose of the certificate
-chain, for example SSL client or SSL server.
+chain, for example B<X509_PURPOSE_SSL_CLIENT>.
X509_VERIFY_PARAM_set_trust() sets the trust setting in B<param> to
B<trust>.
diff --git a/doc/man3/X509_check_purpose.pod b/doc/man3/X509_check_purpose.pod
index e0f1353842..619ed7831a 100644
--- a/doc/man3/X509_check_purpose.pod
+++ b/doc/man3/X509_check_purpose.pod
@@ -29,6 +29,9 @@ Below are the potential ID's that can be checked:
# define X509_PURPOSE_OCSP_HELPER 8
# define X509_PURPOSE_TIMESTAMP_SIGN 9
+The checks performed take into account the X.509 extensions
+keyUsage, extendedKeyUsage, and basicConstraints.
+
=head1 RETURN VALUES
For non-CA checks
diff --git a/doc/man5/x509v3_config.pod b/doc/man5/x509v3_config.pod
index f8bc6d0ff1..fb7c3aaff7 100644
--- a/doc/man5/x509v3_config.pod
+++ b/doc/man5/x509v3_config.pod
@@ -142,15 +142,15 @@ Examples:
=head2 Extended Key Usage
This extension consists of a list of values indicating purposes for which
-the certificate public key can be used for, Each value can be either a
-short text name or an OID.
+the certificate public key can be used.
+Each value can be either a short text name or an OID.
The following text names, and their intended meaning, are known:
- Value Meaning
- ----- -------
- serverAuth SSL/TLS Web Server Authentication
- clientAuth SSL/TLS Web Client Authentication
- codeSigning Code signing
+ Value Meaning according to RFC 5280 etc.
+ ----- ----------------------------------
+ serverAuth SSL/TLS WWW Server Authentication
+ clientAuth SSL/TLS WWW Client Authentication
+ codeSigning Code Signing
emailProtection E-mail Protection (S/MIME)
timeStamping Trusted Timestamping
OCSPSigning OCSP Signing
@@ -160,6 +160,10 @@ The following text names, and their intended meaning, are known:
msCTLSign Microsoft Trust List Signing
msEFS Microsoft Encrypted File System
+While IETF RFC 5280 says that B<id-kp-serverAuth> and B<id-kp-clientAuth>
+are only for WWW use, in practice they are used for all kinds of TLS clients
+and servers, and this is what OpenSSL assumes as well.
+
Examples:
extendedKeyUsage = critical, codeSigning, 1.2.3.4
More information about the openssl-commits
mailing list