123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103 |
- =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
|