diff options
author | Matt Caswell <matt@openssl.org> | 2021-04-28 15:23:16 +0100 |
---|---|---|
committer | Matt Caswell <matt@openssl.org> | 2021-05-04 12:00:21 +0100 |
commit | f9548d21bae8667b71254d82478e0094a5a3982d (patch) | |
tree | 0c3f439c5fde3c6884e04594b85f718e0be54708 /doc/man3 | |
parent | 93954ab050b395275a9d8b084ab4aa9e815ce119 (diff) |
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)
Diffstat (limited to 'doc/man3')
-rw-r--r-- | doc/man3/BIO_new.pod | 24 | ||||
-rw-r--r-- | doc/man3/BIO_s_core.pod | 72 | ||||
-rw-r--r-- | doc/man3/OSSL_LIB_CTX.pod | 17 |
3 files changed, 100 insertions, 13 deletions
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 |