BIO_new_bio_pair man page on DigitalUNIX

Man page or keyword search:  
man Server   12896 pages
apropos Keyword Search (all sections)
Output format
DigitalUNIX logo
[printable version]

BIO_new_bio_pair(3)					   BIO_new_bio_pair(3)

       BIO_new_bio_pair - Create a new BIO pair

       #include <openssl/bio.h>

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

       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  con‐
       nect  one  endpoint as underlying input/output BIO to an SSL and access
       the other one controlled by the program instead of accessing  the  net‐
       work 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 func‐
       tions,  such  as	 SSL_set_bio() and SSL_free(), call BIO_free() implic‐
       itly, so that the peer-BIO is left untouched and	 also  must  be	 freed
       using BIO_free().

       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.

       The following return values can occur: 1

	      The BIO pair was created successfully. The new BIOs  are	avail‐
	      able in bio1 and bio2.  0

	      The  operation failed. The NULL pointer is stored into the loca‐
	      tions for bio1 and bio2. Check the error stack for more informa‐

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

	application |	TLS-engine
	   |	    |
	   +----------> SSL_operations()
		    |	  /\	||
		    |	  ||	\/
		    |	BIO-pair (internal_bio)
	   +----------< BIO-pair (network_bio)
	   |	    |
	 socket	    |

	 SSL_free(ssl);		/* implicitly frees internal_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 applica‐
       tion 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.

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


List of man pages available for DigitalUNIX

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
Vote for polarhome
Free Shell Accounts :: the biggest list on the net