BIO_new_bio_pair() was unnecessarily described in it's own page as well as in
BIO_s_bio.pod. The most logical is to move everything needed from BIO_new_bio_pair.pod to BIO_s_bio.pod (including the nice example) and toss BIO_new_bio_pair.pod. I hope I got all the info over properly. PR: 370
This commit is contained in:
Richard Levitte
parent
dad1535f7a
commit
18be6c4116
2 changed files with 54 additions and 105 deletions
|
|
@ -1,103 +0,0 @@
|
|||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
BIO_new_bio_pair - create a new BIO pair
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
#include <openssl/bio.h>
|
||||
|
||||
int BIO_new_bio_pair(BIO **bio1, size_t writebuf1, BIO **bio2, size_t writebuf2);
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
BIO_new_bio_pair() creates a buffering BIO pair based on the
|
||||
L<SSL_set_bio(3)|SSL_set_bio(3)> method. The BIO pair has two endpoints between which
|
||||
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 connection directly.
|
||||
|
||||
The two new BIOs B<bio1> and B<bio2> are symmetric with respect to their
|
||||
functionality. The size of their buffers is determined by B<writebuf1> and
|
||||
B<writebuf2>. If the size give is 0, the default size is used.
|
||||
|
||||
BIO_new_bio_pair() does not check whether B<bio1> or B<bio2> do point to
|
||||
some other BIO, the values are overwritten, BIO_free() is not called.
|
||||
|
||||
The two BIOs, even though forming a BIO pair and must be BIO_free()'ed
|
||||
separately. This can be of importance, as some SSL-functions like SSL_set_bio()
|
||||
or SSL_free() call BIO_free() implicitly, so that the peer-BIO is left
|
||||
untouched and must also be BIO_free()'ed.
|
||||
|
||||
=head1 EXAMPLE
|
||||
|
||||
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);
|
||||
SSL_set_bio(ssl, internal_bio, internal_bio);
|
||||
SSL_operations();
|
||||
...
|
||||
|
||||
application | TLS-engine
|
||||
| |
|
||||
+----------> SSL_operations()
|
||||
| /\ ||
|
||||
| || \/
|
||||
| BIO-pair (internal_bio)
|
||||
+----------< BIO-pair (network_bio)
|
||||
| |
|
||||
socket |
|
||||
|
||||
...
|
||||
SSL_free(ssl); /* implicitly frees internal_bio */
|
||||
BIO_free(network_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(), to find out whether data is buffered in the BIO
|
||||
and must be transfered to the network. Use BIO_ctrl_get_read_request() to
|
||||
find out, how many bytes must be written into the buffer before the
|
||||
SSL_operation() can successfully be continued.
|
||||
|
||||
=head1 WARNING
|
||||
|
||||
As the data is buffered, SSL_operation() may return with a ERROR_SSL_WANT_READ
|
||||
condition, but there is still data in the write buffer. An application must
|
||||
not rely on the error value of SSL_operation() 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.
|
||||
|
||||
=head1 RETURN VALUES
|
||||
|
||||
The following return values can occur:
|
||||
|
||||
=over 4
|
||||
|
||||
=item 1
|
||||
|
||||
The BIO pair was created successfully. The new BIOs are available in
|
||||
B<bio1> and B<bio2>.
|
||||
|
||||
=item 0
|
||||
|
||||
The operation failed. The NULL pointer is stored into the locations for
|
||||
B<bio1> and B<bio2>. Check the error stack for more information.
|
||||
|
||||
=back
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
L<SSL_set_bio(3)|SSL_set_bio(3)>, L<ssl(3)|ssl(3)>, L<bio(3)|bio(3)>,
|
||||
L<BIO_ctrl_pending(3)|BIO_ctrl_pending(3)>,
|
||||
L<BIO_ctrl_get_read_request(3)|BIO_ctrl_get_read_request(3)>
|
||||
|
||||
=cut
|
||||
|
|
@ -76,7 +76,9 @@ BIO_get_write_buf_size() returns the size of the write buffer.
|
|||
BIO_new_bio_pair() combines the calls to BIO_new(), BIO_make_bio_pair() and
|
||||
BIO_set_write_buf_size() to create a connected pair of BIOs B<bio1>, B<bio2>
|
||||
with write buffer sizes B<writebuf1> and B<writebuf2>. If either size is
|
||||
zero then the default size is used.
|
||||
zero then the default size is used. BIO_new_bio_pair() does not check whether
|
||||
B<bio1> or B<bio2> do point to some other BIO, the values are overwritten,
|
||||
BIO_free() is not called.
|
||||
|
||||
BIO_get_write_guarantee() and BIO_ctrl_get_write_guarantee() return the maximum
|
||||
length of data that can be currently written to the BIO. Writes larger than this
|
||||
|
|
@ -118,9 +120,59 @@ the application then waits for data to be available on the underlying transport
|
|||
before flushing the write buffer it will never succeed because the request was
|
||||
never sent!
|
||||
|
||||
=head1 RETURN VALUES
|
||||
|
||||
BIO_new_bio_pair() returns 1 on success, with the new BIOs available in
|
||||
B<bio1> and B<bio2>, or 0 on failure, with NULL pointers stored into the
|
||||
locations for B<bio1> and B<bio2>. Check the error stack for more information.
|
||||
|
||||
[XXXXX: More return values need to be added here]
|
||||
|
||||
=head1 EXAMPLE
|
||||
|
||||
TBA
|
||||
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);
|
||||
SSL_set_bio(ssl, internal_bio, internal_bio);
|
||||
SSL_operations();
|
||||
...
|
||||
|
||||
application | TLS-engine
|
||||
| |
|
||||
+----------> SSL_operations()
|
||||
| /\ ||
|
||||
| || \/
|
||||
| BIO-pair (internal_bio)
|
||||
+----------< BIO-pair (network_bio)
|
||||
| |
|
||||
socket |
|
||||
|
||||
...
|
||||
SSL_free(ssl); /* implicitly frees internal_bio */
|
||||
BIO_free(network_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(), to find out whether data is buffered in the BIO
|
||||
and must be transfered to the network. Use BIO_ctrl_get_read_request() to
|
||||
find out, how many bytes must be written into the buffer before the
|
||||
SSL_operation() can successfully be continued.
|
||||
|
||||
=head1 WARNING
|
||||
|
||||
As the data is buffered, SSL_operation() may return with a ERROR_SSL_WANT_READ
|
||||
condition, but there is still data in the write buffer. An application must
|
||||
not rely on the error value of SSL_operation() 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.
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue