BIO_new_bio_pair - Create a new BIO pair
size_t writebuf2 );
The BIO_new_bio_pair() function creates a buffering BIO
pair. It has two endpoints between data can be buffered.
Its typical use is to connect one endpoint as underlying
input/output BIO to an SSL and access the other one controlled
by the program instead of accessing the network
The two new BIOs, bio1 and bio2, are symmetric with
respect to their functionality. The size of their buffers
is determined by writebuf1 and writebuf2. If the size
given is 0, the default size is used.
The BIO_new_bio_pair() function does not check whether
bio1 or bio2 point to another BIO. The values are overwritten,
and the BIO_free() function is not called.
The two BIOs, even though forming a BIO pair, must be
freed separately, using the BIO_free() function. This is
important because some SSL functions, such as
SSL_set_bio() and SSL_free(), call BIO_free() implicitly,
so that the peer-BIO is left untouched and also must be
freed using BIO_free().
As the data is buffered, the SSL_operation() function
might return an ERROR_SSL_WANT_READ condition, but there
is still data in the write buffer. An application must not
rely on the error value of the SSL_operation() function,
but must assure that the write buffer is always flushed
first. Otherwise, a deadlock may occur as the peer might
be waiting for the data before being able to continue.
The following return values can occur: 1
The BIO pair was created successfully. The new BIOs
are available in bio1 and bio2. 0
The operation failed. The NULL pointer is stored
into the locations for bio1 and bio2. Check the
error stack for more information.
The BIO pair can be used to have full control over the
network access of an application. The application can call
select() on the socket as required without having to go
through the SSL interface.
BIO *internal_bio, *network_bio;
BIO_new_bio_pair(internal_bio, 0, network_bio, 0);
application | TLS-engine
| /\ ||
| || \/
| BIO-pair (internal_bio)
+----------< BIO-pair (network_bio)
SSL_free(ssl); /* implicitly frees internal_bio
As the BIO pair will only buffer the data and never
directly access the connection, it behaves non-blocking
and will return as soon as the write buffer is full or the
read buffer is drained. Then the application has to flush
the write buffer and/or fill the read buffer.
Use the BIO_ctrl_pending() function to find out whether
data is buffered in the BIO and must be transfered to the
network. Use the BIO_ctrl_get_read_request() function to
find out how many bytes must be written into the buffer
before the SSL_operation() can continue.
Functions: SSL_set_bio(3), ssl(3), bio(3), BIO_ctrl_pending(3), BIO_ctrl_get_read_request(3)
[ Back ]