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)

6 files changed, 32 insertions, 10 deletions

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