diff --git a/doc/build.info b/doc/build.info index 738f10d5f1ca67ca7eb11c4c6b42c2cb75fe8ede..8ee9ca10e372e613780ee22ad9376cbfa56a1acc 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 d75e63bbecb50da4b9488eece04e519548c7701a..5d14a8d6e1c952f375b6ce0e13cecf4321805b66 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 - 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. +The BIO_new_ex() function returns a new BIO using method B associated with +the library context I (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 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 0000000000000000000000000000000000000000..fbcd0b5c9c07f61df2af8bfafdbf617648b5309a --- /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 + + 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 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. + +=cut diff --git a/doc/man3/OSSL_LIB_CTX.pod b/doc/man3/OSSL_LIB_CTX.pod index 5ba85cc48568a9ebc6372dfd727e1998c0b2b998..9796c8575c6dd06f24f43cc3b3522a62dced0db9 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 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 argument. +Some OpenSSL functions, such as L, 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. 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