NAME    [Toc]    [Back]

       BIO_new_bio_pair - Create a new BIO pair

SYNOPSIS    [Toc]    [Back]

       #include <openssl/bio.h>

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

DESCRIPTION    [Toc]    [Back]

       The  BIO_new_bio_pair()  function  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,  bio1  and  bio2,  are  symmetric  with
       respect  to their functionality. The size of their buffers
       is determined by writebuf1 and  writebuf2.   If  the  size
       given is 0, the default size is used.

       The  BIO_new_bio_pair()  function  does  not check whether
       bio1 or bio2 point to another BIO. The  values  are  overwritten,
 and the BIO_free() function is not called.

       The  two  BIOs,  even  though  forming a BIO pair, must be
       freed separately, using the BIO_free() function.  This  is
       important    because   some   SSL   functions,   such   as
       SSL_set_bio() and SSL_free(), call BIO_free()  implicitly,
       so  that  the  peer-BIO is left untouched and also must be
       freed using BIO_free().

NOTES    [Toc]    [Back]

       As the data  is  buffered,  the  SSL_operation()  function
       might  return  an ERROR_SSL_WANT_READ condition, but there
       is still data in the write buffer. An application must not
       rely  on  the error value of the SSL_operation() function,
       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.

RETURN VALUES    [Toc]    [Back]

       The following return values can occur: 1

              The BIO pair was created successfully. The new BIOs
              are available in bio1 and bio2.  0

              The  operation  failed.  The NULL pointer is stored
              into the locations for bio1  and  bio2.  Check  the
              error stack for more information.

EXAMPLE    [Toc]    [Back]

       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);         /* 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()  function to find out whether
       data is buffered in the BIO and must be transfered to  the
       network.  Use  the BIO_ctrl_get_read_request() function to
       find out how many bytes must be written  into  the  buffer
       before the SSL_operation() can continue.

SEE ALSO    [Toc]    [Back]

       Functions:  SSL_set_bio(3), ssl(3), bio(3), BIO_ctrl_pending(3), BIO_ctrl_get_read_request(3)



                                              BIO_new_bio_pair(3)