What are and how do I use OpenSSL BIO pairs?

A BIO pair are two source/sink BIOs that are bound together. Anything that is written to one can be read from the other. If you have two BIOS already, you can join them together using BIO_make_bio_pair. Or you can create a new BIO pair with BIO_new_bio_pair.

One use mentioned in the Network Security with OpenSSL book (see page 111) is that the pair can be bound to a SSL engine. Anything written to the BIO pair will be read by the SSL engine. Anything written to the BIO pair can be read from. OpenSSL has a sample of this (see ssl/ssltest.c)

A BIO in OpenSSL is similar to a File handle. You use a pair of them to communicate with each other securely like you would with two sockets. The best explanation I've found is here.

I also got a lot of use out of Herong Yang's site a few months ago when I had to write an application using OpenSSL. The sections on creating and signing certificates using OpenSSL and keytool were a big help when it came to testing my application.

I've written about OpenSSL BIO pairs as a part of a general answer about OpenSSL BIOs:

A "bio" BIO (BIO_s_bio). It is a pipe-like BIO. A pair of such BIOs can be created. Data written to one BIO in the pair will be placed for reading to the second BIO in the pair. And vice versa. It is similar to memory BIO, but memory BIO places data to itself and pipe BIO places data to the BIO which it is paired with.

And also here:

But in addition there is a BIO called BIO_s_bio which has a pipe-like functionality. A pair of such BIOs can be created. Any data written to the first BIO in the pair of BIO_s_bio objects will be read from the second BIO in the pair. And vice versa: writing data to the second BIO will result in reading this data from the first BIO. So BIO_s_bio can be used instead of BIO_s_mem. Passing a single instance of BIO_s_bio object to the SSL_set_bio function would be enough. Application receives data and writes it to its BIO in the BIO_s_bio pair. OpenSSL will then get this data from its BIO in the pair. OpenSSL writes data to its BIO in the pair, and the application gets this data from its BIO in turn.