BIO_s_bio(3)                OpenSSL                BIO_s_bio(3)





NAME
       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

SYNOPSIS
        #include <openssl/bio.h>

        BIO_METHOD *BIO_s_bio(void);

        #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)

        int BIO_new_bio_pair(BIO **bio1, size_t writebuf1, BIO **bio2, size_t writebuf2);

        #define BIO_get_write_guarantee(b) (int)BIO_ctrl(b,BIO_C_GET_WRITE_GUARANTEE,0,NULL)
        size_t BIO_ctrl_get_write_guarantee(BIO *b);

        #define BIO_get_read_request(b)    (int)BIO_ctrl(b,BIO_C_GET_READ_REQUEST,0,NULL)
        size_t BIO_ctrl_get_read_request(BIO *b);

        int BIO_ctrl_reset_read_request(BIO *b);

DESCRIPTION
       BIO_s_bio() returns the method for a BIO pair. A BIO
       pair is a pair of source/sink BIOs where data written to
       either half of the pair is buffered and can be read from
       the other half. Both halves must usually by handled by
       the same application thread since no locking is done on
       the internal data structures.

       Since BIO chains typically end in a source/sink BIO it
       is possible to make this one half of a BIO pair and have
       all the data processed by the chain under application
       control.

       One typical use of BIO pairs is to place TLS/SSL I/O
       under application control, this can be used when the
       application wishes to use a non standard transport for
       TLS/SSL or the normal socket routines are inappropriate.

       Calls to BIO_read() will read data from the buffer or
       request a retry if no data is available.

       Calls to BIO_write() will place data in the buffer or
       request a retry if the buffer is full.

       The standard calls BIO_ctrl_pending() and
       BIO_ctrl_wpending() can be used to determine the amount
       of pending data in the read or write buffer.

       BIO_reset() clears any data in the write buffer.

       BIO_make_bio_pair() joins two separate BIOs into a con-
       nected 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 pend-
       ing data has been read.

       BIO_set_write_buf_size() sets the write buffer size of
       BIO b to size.  If the size is not initialized a default
       value is used. This is currently 17K, sufficient for a
       maximum size TLS record.

       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 cre-
       ate a connected pair of BIOs bio1, bio2 with write
       buffer sizes writebuf1 and writebuf2. If either size is
       zero then the default size is used.  BIO_new_bio_pair()
       does not check whether bio1 or 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_guaran-
       tee() return the maximum length of data that can be cur-
       rently written to the BIO. Writes larger than this value
       will return a value from BIO_write() less than the
       amount requested or if the 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 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.

NOTES
       Both halves of a BIO pair should be freed. That is even
       if one half is implicit freed due to a BIO_free_all() or
       SSL_free() call the other half needs to be freed.

       When used in bidirectional applications (such as
       TLS/SSL) care should be taken to flush any data in the
       write buffer. This can be done by calling BIO_pending()
       on the other half of the pair and, if any data is pend-
       ing, reading it and sending it to the underlying trans-
       port. This must be done before any normal processing
       (such as calling select() ) due to a request and
       BIO_should_read() being true.

       To see why this is important consider a case where a
       request is sent using BIO_write() and a response read
       with BIO_read(), this can occur during an TLS/SSL hand-
       shake for example. BIO_write() will succeed and place
       data in the write buffer. BIO_read() will initially fail
       and BIO_should_read() will be true. If 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!

RETURN VALUES
       BIO_new_bio_pair() returns 1 on success, with the new
       BIOs available in bio1 and bio2, or 0 on failure, with
       NULL pointers stored into the locations for bio1 and
       bio2. Check the error stack for more information.

       [XXXXX: More return values need to be added here]

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 net-
       work. 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.

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 dead-
       lock may occur as the peer might be waiting for the data
       before being able to continue.

SEE ALSO
       SSL_set_bio(3), ssl(3), bio(3), BIO_should_retry(3),
       BIO_read(3)



0.9.7c                     2002-12-12              BIO_s_bio(3)
