Document the new core BIO public API support

Fixes #14409

Reviewed-by: Tomas Mraz <tomas@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/15072)

4 files changed, 106 insertions, 13 deletions

diff --git a/doc/build.info b/doc/build.info
index 738f10d5f1..8ee9ca10e3 100644
--- a/doc/build.info
+++ b/doc/build.info
@@ -630,6 +630,10 @@ DEPEND[html/man3/BIO_s_connect.html]=man3/BIO_s_connect.pod
 GENERATE[html/man3/BIO_s_connect.html]=man3/BIO_s_connect.pod
 DEPEND[man/man3/BIO_s_connect.3]=man3/BIO_s_connect.pod
 GENERATE[man/man3/BIO_s_connect.3]=man3/BIO_s_connect.pod
+DEPEND[html/man3/BIO_s_core.html]=man3/BIO_s_core.pod
+GENERATE[html/man3/BIO_s_core.html]=man3/BIO_s_core.pod
+DEPEND[man/man3/BIO_s_core.3]=man3/BIO_s_core.pod
+GENERATE[man/man3/BIO_s_core.3]=man3/BIO_s_core.pod
 DEPEND[html/man3/BIO_s_fd.html]=man3/BIO_s_fd.pod
 GENERATE[html/man3/BIO_s_fd.html]=man3/BIO_s_fd.pod
 DEPEND[man/man3/BIO_s_fd.3]=man3/BIO_s_fd.pod
@@ -2851,6 +2855,7 @@ html/man3/BIO_read.html \
 html/man3/BIO_s_accept.html \
 html/man3/BIO_s_bio.html \
 html/man3/BIO_s_connect.html \
+html/man3/BIO_s_core.html \
 html/man3/BIO_s_fd.html \
 html/man3/BIO_s_file.html \
 html/man3/BIO_s_mem.html \
@@ -3437,6 +3442,7 @@ man/man3/BIO_read.3 \
 man/man3/BIO_s_accept.3 \
 man/man3/BIO_s_bio.3 \
 man/man3/BIO_s_connect.3 \
+man/man3/BIO_s_core.3 \
 man/man3/BIO_s_fd.3 \
 man/man3/BIO_s_file.3 \
 man/man3/BIO_s_mem.3 \
diff --git a/doc/man3/BIO_new.pod b/doc/man3/BIO_new.pod
index d75e63bbec..5d14a8d6e1 100644
--- a/doc/man3/BIO_new.pod
+++ b/doc/man3/BIO_new.pod
@@ -2,22 +2,28 @@
 
 =head1 NAME
 
-BIO_new, BIO_up_ref, BIO_free, BIO_vfree, BIO_free_all
+BIO_new_ex, BIO_new, BIO_up_ref, BIO_free, BIO_vfree, BIO_free_all
 - BIO allocation and freeing functions
 
 =head1 SYNOPSIS
 
  #include <openssl/bio.h>
 
- BIO *  BIO_new(const BIO_METHOD *type);
- int    BIO_up_ref(BIO *a);
- int    BIO_free(BIO *a);
- void   BIO_vfree(BIO *a);
- void   BIO_free_all(BIO *a);
+ BIO *BIO_new_ex(OSSL_LIB_CTX *libctx, const BIO_METHOD *type);
+ BIO *BIO_new(const BIO_METHOD *type);
+ int BIO_up_ref(BIO *a);
+ int BIO_free(BIO *a);
+ void BIO_vfree(BIO *a);
+ void BIO_free_all(BIO *a);
 
 =head1 DESCRIPTION
 
-The BIO_new() function returns a new BIO using method B<type>.
+The BIO_new_ex() function returns a new BIO using method B<type> associated with
+the library context I<libctx> (see OSSL_LIB_CTX(3)). The library context may be
+NULL to indicate the default library context.
+
+The BIO_new() is the same as BIO_new_ex() except the default library context is
+always used.
 
 BIO_up_ref() increments the reference count associated with the BIO object.
 
@@ -35,7 +41,7 @@ If B<a> is NULL nothing is done.
 
 =head1 RETURN VALUES
 
-BIO_new() returns a newly created BIO or NULL if the call fails.
+BIO_new_ex() and BIO_new() return a newly created BIO or NULL if the call fails.
 
 BIO_up_ref() and BIO_free() return 1 for success and 0 for failure.
 
@@ -53,6 +59,8 @@ on it other than the discarded return value.
 
 BIO_set() was removed in OpenSSL 1.1.0 as BIO type is now opaque.
 
+BIO_new_ex() was added in OpenSSL 3.0.
+
 =head1 EXAMPLES
 
 Create a memory BIO:
diff --git a/doc/man3/BIO_s_core.pod b/doc/man3/BIO_s_core.pod
new file mode 100644
index 0000000000..fbcd0b5c9c
--- /dev/null
+++ b/doc/man3/BIO_s_core.pod
@@ -0,0 +1,72 @@
+=pod
+
+=head1 NAME
+
+BIO_s_core, BIO_new_from_core_bio - OSSL_CORE_BIO functions
+
+=head1 SYNOPSIS
+
+ #include <openssl/bio.h>
+
+ const BIO_METHOD *BIO_s_core(void);
+
+ BIO *BIO_new_from_core_bio(OSSL_LIB_CTX *libctx, OSSL_CORE_BIO *corebio);
+
+=head1 DESCRIPTION
+
+BIO_s_core() returns the core BIO method function.
+
+A core BIO is treated as source/sink BIO which communicates to some external
+BIO. This is primarily useful to provider authors. A number of calls from
+libcrypto into a provider supply an OSSL_CORE_BIO parameter. This represents
+a BIO within libcrypto, but cannot be used directly by a provider. Instead it
+should be wrapped using a BIO_s_core().
+
+Once a BIO is contructed based on BIO_s_core(), the associated OSSL_CORE_BIO
+object should be set on it using BIO_set_data(3). Note that the BIO will only
+operate correctly if it is associated with a library context constructed using
+OSSL_LIB_CTX_new_from_dispatch(3). To associate the BIO with a library context
+construct it using BIO_new_ex(3).
+
+BIO_new_from_core_bio() is a convenience function that constructs a new BIO
+based on BIO_s_core() and that is associated with the given library context. It
+then also sets the OSSL_CORE_BIO object on the BIO using BIO_set_data(3).
+
+=head1 RETURN VALUES
+
+BIO_s_core() return a core BIO B<BIO_METHOD> structure.
+
+BIO_new_from_core_bio() returns a BIO structure on success or NULL on failure.
+A failure will most commonly be because the library context was not constructed
+using OSSL_LIB_CTX_new_from_dispatch(3).
+
+=head1 HISTORY
+
+BIO_s_core() and BIO_new_from_core_bio() were added in OpenSSL 3.0.
+
+=head1 EXAMPLES
+
+Create a core BIO and write some data to it:
+
+ int some_function(OSSL_LIB_CTX *libctx, OSSL_CORE_BIO *corebio) {
+     BIO *cbio = BIO_new_from_core_bio(libctx, corebio);
+
+     if (cbio == NULL)
+         return 0;
+
+     BIO_puts(cbio, "Hello World\n");
+
+     BIO_free(cbio);
+     return 1;
+ }
+
+=head1 COPYRIGHT
+
+Copyright 2021 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the Apache License 2.0 (the "License").  You may not use
+this file except in compliance with the License.  You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
diff --git a/doc/man3/OSSL_LIB_CTX.pod b/doc/man3/OSSL_LIB_CTX.pod
index 5ba85cc485..9796c8575c 100644
--- a/doc/man3/OSSL_LIB_CTX.pod
+++ b/doc/man3/OSSL_LIB_CTX.pod
@@ -2,8 +2,9 @@
 
 =head1 NAME
 
-OSSL_LIB_CTX, OSSL_LIB_CTX_new, OSSL_LIB_CTX_free, OSSL_LIB_CTX_load_config,
-OSSL_LIB_CTX_get0_global_default, OSSL_LIB_CTX_set0_default
+OSSL_LIB_CTX, OSSL_LIB_CTX_new, OSSL_LIB_CTX_new_from_dispatch,
+OSSL_LIB_CTX_free, OSSL_LIB_CTX_load_config, OSSL_LIB_CTX_get0_global_default,
+OSSL_LIB_CTX_set0_default
 - OpenSSL library context
 
 =head1 SYNOPSIS
@@ -13,6 +14,7 @@ OSSL_LIB_CTX_get0_global_default, OSSL_LIB_CTX_set0_default
  typedef struct ossl_lib_ctx_st OSSL_LIB_CTX;
 
  OSSL_LIB_CTX *OSSL_LIB_CTX_new(void);
+ OSSL_LIB_CTX *OSSL_LIB_CTX_new_from_dispatch(const OSSL_DISPATCH *in);
  int OSSL_LIB_CTX_load_config(OSSL_LIB_CTX *ctx, const char *config_file);
  void OSSL_LIB_CTX_free(OSSL_LIB_CTX *ctx);
  OSSL_LIB_CTX *OSSL_LIB_CTX_get0_global_default(void);
@@ -32,6 +34,13 @@ See L<OPENSSL_thread_stop_ex(3)> for more information.
 
 OSSL_LIB_CTX_new() creates a new OpenSSL library context.
 
+OSSL_LIB_CTX_new_from_dispatch() creates a new OpenSSL library context
+initialised to use callbacks from the OSSL_DISPATCH structure. This is primarily
+useful for provider authors. The dispatch structure passed should be the same
+one as passed to a provider's OSSL_provider_init function in the I<in> argument.
+Some OpenSSL functions, such as L<BIO_new_from_core_bio(3)>, require the library
+context to be created in this way in order to work.
+
 OSSL_LIB_CTX_load_config() loads a configuration file using the given C<ctx>.
 This can be used to associate a library context with providers that are loaded
 from a configuration.
@@ -69,9 +78,7 @@ OSSL_LIB_CTX_free() doesn't return any value.
 
 =head1 HISTORY
 
-OSSL_LIB_CTX, OSSL_LIB_CTX_new(), OSSL_LIB_CTX_load_config(),
-OSSL_LIB_CTX_free(), OSSL_LIB_CTX_get0_global_default() and
-OSSL_LIB_CTX_set0_default() were added in OpenSSL 3.0.
+All of the functions described on this page were added in OpenSSL 3.0.
 
 =head1 COPYRIGHT