diff options
Diffstat (limited to 'doc/crypto/BIO_s_bio.pod')
| -rw-r--r-- | doc/crypto/BIO_s_bio.pod | 56 |
1 files changed, 54 insertions, 2 deletions
diff --git a/doc/crypto/BIO_s_bio.pod b/doc/crypto/BIO_s_bio.pod index 95ae802e47..8d0a55a025 100644 --- a/doc/crypto/BIO_s_bio.pod +++ b/doc/crypto/BIO_s_bio.pod @@ -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 |