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
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 \
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 \
=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.
=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.
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:
--- /dev/null
+=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
=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
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);
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.
=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
projects / openssl.git / commitdiff