diff options
author | Richard Levitte <levitte@openssl.org> | 2000-09-14 13:11:56 +0000 |
---|---|---|
committer | Richard Levitte <levitte@openssl.org> | 2000-09-14 13:11:56 +0000 |
commit | cc99526db1ee5b948736f6b07958a786fec1240b (patch) | |
tree | 24c07af7e38f014e2baa02ba5ce454e24d64211f /doc/crypto/BIO_new_bio_pair.pod | |
parent | 72660f5f15fcd71215193f993dd95da0d130168a (diff) |
Add a number of documentation files, mostly for SSL routines, but also
for a few BIO routines.
Submitted by Lutz Jaenicke <Lutz.Jaenicke@aet.TU-Cottbus.DE>
Diffstat (limited to 'doc/crypto/BIO_new_bio_pair.pod')
-rw-r--r-- | doc/crypto/BIO_new_bio_pair.pod | 102 |
1 files changed, 102 insertions, 0 deletions
diff --git a/doc/crypto/BIO_new_bio_pair.pod b/doc/crypto/BIO_new_bio_pair.pod new file mode 100644 index 0000000000..c331bd02b8 --- /dev/null +++ b/doc/crypto/BIO_new_bio_pair.pod @@ -0,0 +1,102 @@ +=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. 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 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 +seperately. This can be of importance, as some SSL-functions like SSL_set_bio() +or SSL_free() call BIO_free() implicitely, 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); + SSL_operations(); + ... + + application | TLS-engine + | | + +----------> SSL_operations() + | /\ || + | || \/ + | BIO-pair (internal_bio) + +----------< BIO-pair (network_bio) + | | + socket | + + ... + SSL_free(ssl); /* implicitely 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 IMPORTANT + +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 |