DOC: Clarify the role of EKUs including defaults for TLS client and server use

Reviewed-by: Paul Dale <pauli@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/14199)

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