From 18be6c411645232e84dbb906b71bd8bdff50fcd9 Mon Sep 17 00:00:00 2001 From: Richard Levitte Date: Thu, 12 Dec 2002 22:12:02 +0000 Subject: 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 --- doc/crypto/BIO_new_bio_pair.pod | 103 ---------------------------------------- doc/crypto/BIO_s_bio.pod | 56 +++++++++++++++++++++- 2 files changed, 54 insertions(+), 105 deletions(-) delete mode 100644 doc/crypto/BIO_new_bio_pair.pod (limited to 'doc') diff --git a/doc/crypto/BIO_new_bio_pair.pod b/doc/crypto/BIO_new_bio_pair.pod deleted file mode 100644 index 1a8dbc577b..0000000000 --- a/doc/crypto/BIO_new_bio_pair.pod +++ /dev/null @@ -1,103 +0,0 @@ -=pod - -=head1 NAME - -BIO_new_bio_pair - create a new BIO pair - -=head1 SYNOPSIS - - #include - - 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 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 and B are symmetric with respect to their -functionality. The size of their buffers is determined by B and -B. If the size give is 0, the default size is used. - -BIO_new_bio_pair() does not check whether B or B 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 and B. - -=item 0 - -The operation failed. The NULL pointer is stored into the locations for -B and B. Check the error stack for more information. - -=back - -=head1 SEE ALSO - -L, L, L, -L, -L - -=cut 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, B with write buffer sizes B and B. 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 or B 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 and B, or 0 on failure, with NULL pointers stored into the +locations for B and B. 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 -- cgit v1.2.3