NAME

BIO_push, BIO_pop, BIO_set_next — manipulate BIO chains

SYNOPSIS

#include <openssl/bio.h> BIO *
BIO_push(BIO *b, BIO *new_tail); BIO *
BIO_pop(BIO *b); void
BIO_set_next(BIO *b, BIO *new_tail);

DESCRIPTION

BIOs can be joined together to form chains. A chain normally consists of one or more filter BIOs and one source/sink BIO at the end. Data read from or written to the first BIO traverses the chain to the end. Every BIO is a member of exactly one chain. It is either at the beginning of its chain or there is exactly one preceding BIO. It is either at the end of its chain or there is exactly one following BIO. If there is neither a preceding nor a following BIO, it can be regarded as a chain with one member. Every chain has exactly one beginning and exactly one end. BIO_push() appends the chain starting at new_tail to the end of the chain that contains b. Unless b is NULL, it then calls BIO_ctrl(3) on b with an argument of BIO_CTRL_PUSH. If b or new_tail is NULL, nothing is appended. In LibreSSL, if new_tail is not at the beginning of its chain, the head of that chain up to but not including new_tail is cut off and becomes a separate chain. For portability, it is best to make sure that new_tail is at the beginning of its chain before calling BIO_push(). The LibreSSL implementation of BIO_push() never creates cycles. If a call would result in a cycle, nothing is changed and the call fails. BIO_pop() removes the BIO b from its chain. Despite the word “pop” in the function name, b can be at the beginning, in the middle, or at the end of its chain. Before removal, BIO_ctrl(3) is called on b with an argument of BIO_CTRL_POP. The removed BIO b becomes the only member of its own chain and can thus be freed or attached to a different chain. If b is NULL, no action occurs. BIO_set_next() appends the chain starting with new_tail to the chain ending with b. In LibreSSL, if new_tail is not at the beginning of its chain, the head of that chain up to but not including new_tail is cut off and becomes a separate chain, and if b is not at the end of its chain, the tail of that chain starting after b is cut off and becomes a separate chain. For portability, it is best to make sure that b is at the end of its chain and that new_tail is at the beginning of its chain before calling BIO_set_next() and to avoid calling BIO_pop() on new_tail afterwards. In LibreSSL, the only built-in BIO type for which BIO_ctrl(3) calls with an argument of BIO_CTRL_PUSH or BIO_CTRL_POP have any effect is BIO_f_ssl(3).

RETURN VALUES

BIO_push() returns b for success or a different pointer for failure. In particular, it fails and returns new_tail if b is NULL. In LibreSSL, it fails and returns NULL if appending would create a cycle. BIO_pop() returns the BIO that followed b in its chain, or NULL if b is NULL or was at the end of its chain.

EXAMPLES

For these examples suppose md1 and md2 are digest BIOs, b64 is a Base64 BIO and f is a file BIO (see BIO_f_md(3), BIO_f_base64(3), and BIO_s_file(3), respectively). If the call

BIO_push(b64, f);

is made then the new chain will be b64-f. After making the calls

BIO_push(md2, b64); 
BIO_push(md1, md2);

the new chain is md1-md2-b64-f. Data written to md1 will be digested by md1 and md2, Base64-encoded and written to f. It should be noted that reading causes data to pass in the reverse direction. That is, data is read from f, Base64-decoded and digested by md1 and md2. If this call is made:

BIO_pop(md2);

The call will return b64 and the new chain will be md1-b64-f; data can be written to md1 as before. Even though LibreSSL handles some of the edge cases gracefully, the following idiom is recommended for portable error checking:

if (b == NULL || new_tail == NULL || b == new_tail) 
	/* Report the problem and bail out. */ 
if (BIO_push(b, new_tail) != b) 
	/* Report that nothing was changed 
	 * because it would have created a cycle. */

Even with the portable idiom, old and non-LibreSSL library implementations may silently attempt to create cycles instead of rejecting them and returning NULL, which may result in infinite loops, infinite recursion, or segmentation faults either right away or later on.

SEE ALSO

BIO_find_type(3), BIO_new(3), BIO_read(3)

HISTORY

BIO_push() first appeared in SSLeay 0.6.0. BIO_pop() first appeared in SSLeay 0.6.4. Both functions have been available since OpenBSD 2.4. BIO_set_next() first appeared in OpenSSL 1.1.0 and has been available since OpenBSD 7.1.