OpenBSD manual page server

Manual Page Search Parameters

BIO_PUSH(3) Library Functions Manual BIO_PUSH(3)

BIO_push, BIO_popadd and remove BIOs from a chain

#include <openssl/bio.h>

BIO *
BIO_push(BIO *b, BIO *append);

BIO *
BIO_pop(BIO *b);

BIOs can be joined together to form chains. A chain normally consist 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. A single BIO can be regarded as a chain with one component.

The BIO_push() function appends the BIO append to b and returns b.

BIO_pop() removes the BIO b from a chain and returns the next BIO in the chain, or NULL if there is no next BIO. The removed BIO then becomes a single BIO with no association with the original chain. it can thus be freed or attached to a different chain.

The names of these functions are perhaps a little misleading. BIO_push() joins two BIO chains whereas BIO_pop() deletes a single BIO from a chain; the deleted BIO does not need to be at the end of a chain.

The process of calling BIO_push() and BIO_pop() on a BIO may have additional consequences: a BIO_ctrl(3) call is made to the affected BIOs. Any effects will be noted in the descriptions of individual BIOs.

BIO_push() returns the beginning of the chain, b.

BIO_pop() returns the next BIO in the chain, or NULL if there is no next BIO.

For these examples suppose md1 and md2 are digest BIOs, b64 is a Base64 BIO and f is a file BIO.

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.

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

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.

March 27, 2018 OpenBSD-current