X-Git-Url: https://git.librecmc.org/?a=blobdiff_plain;f=doc%2Fcrypto%2FBIO_s_bio.pod;h=8d0a55a025c73f49a49d5d29afec0f43056b2793;hb=706c5a4d353eeac4b3217138eeea6b737ff14681;hp=7a3b2db141461cee9168166e8b07409d6220302f;hpb=1e4e5492966007268485920a56613b9c6893f237;p=oweals%2Fopenssl.git diff --git a/doc/crypto/BIO_s_bio.pod b/doc/crypto/BIO_s_bio.pod index 7a3b2db141..8d0a55a025 100644 --- a/doc/crypto/BIO_s_bio.pod +++ b/doc/crypto/BIO_s_bio.pod @@ -2,10 +2,10 @@ =head1 NAME -BIO_s_bio, BIO_make_bio_pair, BIO_destroy_bio_pair, BIO_set_write_buf_size, -BIO_get_write_buf_size, BIO_new_bio_pair, BIO_get_write_guarantee, -BIO_ctrl_get_write_guarantee, BIO_get_read_request, BIO_ctrl_get_read_request, -BIO_ctrl_reset_read_request - BIO pair BIO +BIO_s_bio, BIO_make_bio_pair, BIO_destroy_bio_pair, BIO_shutdown_wr, +BIO_set_write_buf_size, BIO_get_write_buf_size, BIO_new_bio_pair, +BIO_get_write_guarantee, BIO_ctrl_get_write_guarantee, BIO_get_read_request, +BIO_ctrl_get_read_request, BIO_ctrl_reset_read_request - BIO pair BIO =head1 SYNOPSIS @@ -16,6 +16,8 @@ BIO_ctrl_reset_read_request - BIO pair BIO #define BIO_make_bio_pair(b1,b2) (int)BIO_ctrl(b1,BIO_C_MAKE_BIO_PAIR,0,b2) #define BIO_destroy_bio_pair(b) (int)BIO_ctrl(b,BIO_C_DESTROY_BIO_PAIR,0,NULL) + #define BIO_shutdown_wr(b) (int)BIO_ctrl(b, BIO_C_SHUTDOWN_WR, 0, NULL) + #define BIO_set_write_buf_size(b,size) (int)BIO_ctrl(b,BIO_C_SET_WRITE_BUF_SIZE,size,NULL) #define BIO_get_write_buf_size(b,size) (size_t)BIO_ctrl(b,BIO_C_GET_WRITE_BUF_SIZE,size,NULL) @@ -60,6 +62,11 @@ BIO_make_bio_pair() joins two separate BIOs into a connected pair. BIO_destroy_pair() destroys the association between two connected BIOs. Freeing up any half of the pair will automatically destroy the association. +BIO_shutdown_wr() is used to close down a BIO B. After this call no further +writes on BIO B are allowed (they will return an error). Reads on the other +half of the pair will return any pending data or EOF when all pending data has +been read. + BIO_set_write_buf_size() sets the write buffer size of BIO B to B. If the size is not initialized a default value is used. This is currently 17K, sufficient for a maximum size TLS record. @@ -69,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 @@ -77,12 +86,17 @@ value will return a value from BIO_write() less than the amount requested or if buffer is full request a retry. BIO_ctrl_get_write_guarantee() is a function whereas BIO_get_write_guarantee() is a macro. -BIO_get_read_request() and BIO_ctrl_get_read_request() return the amount of data -requested (or the buffer size if it is less) if the last read failed due to an -empty buffer. This can be used to determine how much data should be written to the -other half of the pair so the next read will succeed: this is most useful in TLS/SSL -applications where the amount of data read is usually meaningful rather than just -a buffer size. After a successful read this call will return zero. +BIO_get_read_request() and BIO_ctrl_get_read_request() return the +amount of data requested, or the buffer size if it is less, if the +last read attempt at the other half of the BIO pair failed due to an +empty buffer. This can be used to determine how much data should be +written to the BIO so the next read will succeed: this is most useful +in TLS/SSL applications where the amount of data read is usually +meaningful rather than just a buffer size. After a successful read +this call will return zero. It also will return zero once new data +has been written satisfying the read request or part of it. +Note that BIO_get_read_request() never returns an amount larger +than that returned by BIO_get_write_guarantee(). BIO_ctrl_reset_read_request() can also be used to reset the value returned by BIO_get_read_request() to zero. @@ -106,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