From: Matt Caswell <matt@openssl.org>
Date: Thu, 16 Jan 2020 12:29:01 +0000 (+0000)
Subject: Document the SSL_CTX_with_libctx() function
X-Git-Tag: openssl-3.0.0-alpha1~629
X-Git-Url: https://git.openssl.org/?p=openssl.git;a=commitdiff_plain;h=2280685883f7c19a07a55bcc3ddcd11b6cd82056

Document the SSL_CTX_with_libctx() function

Reviewed-by: Richard Levitte <levitte@openssl.org>
Reviewed-by: Paul Dale <paul.dale@oracle.com>
(Merged from https://github.com/openssl/openssl/pull/10866)
---

diff --git a/doc/man3/SSL_CTX_new.pod b/doc/man3/SSL_CTX_new.pod
index 6680496c16..9c2798d5fc 100644
--- a/doc/man3/SSL_CTX_new.pod
+++ b/doc/man3/SSL_CTX_new.pod
@@ -3,13 +3,14 @@
 =head1 NAME
 
 TLSv1_2_method, TLSv1_2_server_method, TLSv1_2_client_method,
-SSL_CTX_new, SSL_CTX_up_ref, SSLv3_method, SSLv3_server_method,
-SSLv3_client_method, TLSv1_method, TLSv1_server_method, TLSv1_client_method,
-TLSv1_1_method, TLSv1_1_server_method, TLSv1_1_client_method, TLS_method,
-TLS_server_method, TLS_client_method, SSLv23_method, SSLv23_server_method,
-SSLv23_client_method, DTLS_method, DTLS_server_method, DTLS_client_method,
-DTLSv1_method, DTLSv1_server_method, DTLSv1_client_method,
-DTLSv1_2_method, DTLSv1_2_server_method, DTLSv1_2_client_method
+SSL_CTX_new, SSL_CTX_new_with_libctx, SSL_CTX_up_ref, SSLv3_method,
+SSLv3_server_method, SSLv3_client_method, TLSv1_method, TLSv1_server_method,
+TLSv1_client_method, TLSv1_1_method, TLSv1_1_server_method,
+TLSv1_1_client_method, TLS_method, TLS_server_method, TLS_client_method,
+SSLv23_method, SSLv23_server_method, SSLv23_client_method, DTLS_method,
+DTLS_server_method, DTLS_client_method, DTLSv1_method, DTLSv1_server_method,
+DTLSv1_client_method, DTLSv1_2_method, DTLSv1_2_server_method,
+DTLSv1_2_client_method
 - create a new SSL_CTX object as framework for TLS/SSL or DTLS enabled
 functions
 
@@ -17,6 +18,8 @@ functions
 
  #include <openssl/ssl.h>
 
+ SSL_CTX *SSL_CTX_new_with_libctx(OPENSSL_CTX *libctx, const char *propq,
+                                  const SSL_METHOD *method);
  SSL_CTX *SSL_CTX_new(const SSL_METHOD *method);
  int SSL_CTX_up_ref(SSL_CTX *ctx);
 
@@ -70,20 +73,29 @@ functions
 
 =head1 DESCRIPTION
 
-SSL_CTX_new() creates a new B<SSL_CTX> object as framework to
-establish TLS/SSL or DTLS enabled connections. An B<SSL_CTX> object is
-reference counted. Creating an B<SSL_CTX> object for the first time increments
-the reference count. Freeing it (using SSL_CTX_free) decrements it. When the
-reference count drops to zero, any memory or resources allocated to the
-B<SSL_CTX> object are freed. SSL_CTX_up_ref() increments the reference count for
-an existing B<SSL_CTX> structure.
+SSL_CTX_new_with_libctx() creates a new B<SSL_CTX> object as a framework to
+establish TLS/SSL or DTLS enabled connections using the library context
+I<libctx> (see L<OPENSSL_CTX(3)>). 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
+L<provider(7)/Fetching algorithms>. Either or both the I<libctx> or I<propq>
+parameters may be NULL.
+
+SSL_CTX_new() does the same as SSL_CTX_new_with_libctx() except that the default
+library context is used and no property query string is specified.
+
+An B<SSL_CTX> object is reference counted. Creating an B<SSL_CTX> object for the
+first time increments the reference count. Freeing the B<SSL_CTX> (using
+SSL_CTX_free) decrements it. When the reference count drops to zero, any memory
+or resources allocated to the B<SSL_CTX> object are freed. SSL_CTX_up_ref()
+increments the reference count for an existing B<SSL_CTX> structure.
 
 =head1 NOTES
 
-The SSL_CTX object uses B<method> as connection method.
+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 of the following types:
+B<method> can be one of the following types:
 
 =over 4
 
@@ -212,6 +224,8 @@ and TLS_client_method() functions were added in OpenSSL 1.1.0.
 
 All version-specific methods were deprecated in OpenSSL 1.1.0.
 
+SSL_CTX_new_with_libctx() was added in OpenSSL 3.0.
+
 =head1 COPYRIGHT
 
 Copyright 2000-2019 The OpenSSL Project Authors. All Rights Reserved.