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)

1 files changed, 22 insertions, 6 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