mirror/openssl
2
0
Fork 0
mirror of https://github.com/openssl/openssl.git synced 2025-03-19 19:50:42 +08:00
Code Issues Packages Projects Releases Wiki Activity

Document the new core BIO public API support

Browse Source 
Fixes #14409

Reviewed-by: Tomas Mraz <tomas@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/15072)
This commit is contained in:
Matt Caswell 2021-04-28 15:23:16 +01:00
parent 93954ab050
commit f9548d21ba
4 changed files with 106 additions and 13 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
doc/build.info
View File

@ -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 \

24
doc/man3/BIO_new.pod
View File

@ -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:

72
doc/man3/BIO_s_core.pod Normal file
View File

@ -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

17
doc/man3/OSSL_LIB_CTX.pod
View File

@ -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