NAME

BIO_callback_fn_ex, BIO_set_callback_ex, BIO_get_callback_ex, BIO_callback_fn, BIO_set_callback, BIO_get_callback, BIO_set_callback_arg, BIO_get_callback_arg, BIO_debug_callback — BIO callback functions

SYNOPSIS

#include <openssl/bio.h>

typedef long
(*BIO_callback_fn_ex)(BIO *b, int oper, const char *argp, size_t len, int argi, long argl, int ret, size_t *processed);

void
BIO_set_callback_ex(BIO *b, BIO_callback_fn_ex cb_ex);

BIO_callback_fn_ex
BIO_get_callback_ex(const BIO *b);

typedef long
(*BIO_callback_fn)(BIO *b, int oper, const char *argp, int argi, long argl, long ret);

void
BIO_set_callback(BIO *b, BIO_callback_fn cb);

BIO_callback_fn
BIO_get_callback(BIO *b);

void
BIO_set_callback_arg(BIO *b, char *pointer);

char *
BIO_get_callback_arg(const BIO *b);

long
BIO_debug_callback(BIO *bio, int oper, const char *argp, int argi, long argl, long ret);

DESCRIPTION

BIO_set_callback_ex() and BIO_get_callback_ex() set and retrieve the BIO callback. The callback is called during most high-level BIO operations. It can be used for debugging purposes to trace operations on a BIO or to modify its operation.

BIO_set_callback() and BIO_get_callback() are deprecated functions that set and retrieve the old-style BIO callback, which is only used if no new-style callback is set with BIO_set_callback_ex().

BIO_set_callback_arg() stores the pointer internally in b and BIO_get_callback_arg() retrieves it from b. The name of these two functions is badly misleading: the pointer is never passed as an argument to any callback function. But of course, callback functions can call BIO_get_callback_arg() and access the pointer, just like any other code can.

BIO_debug_callback() is a standard debugging callback which prints out information related to each BIO operation. If BIO_set_callback_arg() was called with a non-NULL argument, information is sent to the BIO pointed to by the pointer; otherwise, standard error output is used.

The arguments of the callback functions are as follows:

b

The BIO the callback is attached to.

oper

The operation being performed, which is one of BIO_CB_CTRL, BIO_CB_FREE, BIO_CB_GETS, BIO_CB_PUTS, BIO_CB_READ, or BIO_CB_WRITE. For some operations, the callback is called twice, once before and once after the actual operation. The latter case has oper OR'ed with BIO_CB_RETURN.

argp, argi, argl

The meaning of these three arguments depends on the value of oper, that is on the operation being performed.

len

The length of the data requested to be read or written. This is only useful if oper is BIO_CB_READ, BIO_CB_WRITE, or BIO_CB_GETS.

ret

When oper does not include BIO_CB_RETURN, i.e. when the callback is invoked before an operation, the value passed into the callback via ret is always 1. In this case, if the callback returns a negative value, the library aborts the requested operation and instead returns the negative return value from the callback to the application. If the callback returns a non-negative value, that return value is ignored by the library, and the operation is performed normally.

When oper includes BIO_CB_RETURN, i.e. when the callback is invoked after an operation, the value passed into the callback via ret is the return value that the operation would return to the application if no callback were present. When a callback is present, the operation only passes this value to the callback and instead of it returns the return value of the callback to the application.

processed

The location pointed to is updated with the number of bytes actually read or written. Only used for BIO_CB_READ, BIO_CB_WRITE, BIO_CB_GETS, and BIO_CB_PUTS.

The callback should normally simply return ret when it has finished processing, unless it specifically wishes to abort the operation or to modify the value returned to the application.

The callbacks are called as follows:

In BIO_free(BIO *b):

before the free operation:
cb_ex(b, BIO_CB_FREE, NULL, 0, 0, 0, 1, NULL)
or cb(b, BIO_CB_FREE, NULL,    0, 0, 1)

In BIO_read(BIO *b, void *out, int outl):

before the read operation:
cb_ex(b, BIO_CB_READ, out, outl, 0, 0, 1, NULL)
or cb(b, BIO_CB_READ, out, outl,    0, 1)

after the read operation:
cb_ex(b, BIO_CB_READ|BIO_CB_RETURN, out, outl, 0, 0, ret, &bytes)
or cb(b, BIO_CB_READ|BIO_CB_RETURN, out, outl,    0, ret)

In BIO_write(BIO *b, const void *in, int inl):

before the write operation:
cb_ex(b, BIO_CB_WRITE, in, inl, 0, 0, 1, NULL)
or cb(b, BIO_CB_WRITE, in, inl,    0, 1)

after the write operation:
cb_ex(b, BIO_CB_WRITE|BIO_CB_RETURN, in, inl, 0, 0, ret, &bytes)
or cb(b, BIO_CB_WRITE|BIO_CB_RETURN, in, inl,    0, ret)

In BIO_gets(BIO *b, char *out, int outl):

before the read operation:
cb_ex(b, BIO_CB_GETS, out, outl, 0, 0, 1, NULL)
or cb(b, BIO_CB_GETS, out, outl,    0, 1)

after the read operation:
cb_ex(b, BIO_CB_GETS|BIO_CB_RETURN, out, outl, 0, 0, ret, &bytes)
or cb(b, BIO_CB_GETS|BIO_CB_RETURN, out, outl,    0, ret)

In BIO_puts(BIO *b, const char *in):

before the write operation:
cb_ex(b, BIO_CB_PUTS, in, 0, 0, 0, 1, NULL)
or cb(b, BIO_CB_PUTS, in,    0, 0, 1)

after the write operation:
cb_ex(b, BIO_CB_PUTS|BIO_CB_RETURN, in, 0, 0, 0, ret, &bytes)
or cb(b, BIO_CB_PUTS|BIO_CB_RETURN, in,    0, 0, ret)

In BIO_ctrl(BIO *b, int cmd, long larg, void *parg):

before the control operation:
cb_ex(b, BIO_CB_CTRL, parg, 0, cmd, larg, 1, NULL)
or cb(b, BIO_CB_CTRL, parg,    cmd, larg, 1)

after the control operation:
cb_ex(b, BIO_CB_CTRL|BIO_CB_RETURN, parg, 0, cmd, larg, ret, NULL)
or cb(b, BIO_CB_CTRL|BIO_CB_RETURN, parg,    cmd, larg, ret)

In BIO_callback_ctrl(BIO *b, int cmd, BIO_info_cb *fp):

before the control operation:
cb_ex(b, BIO_CB_CTRL, fp, 0, cmd, 0, 1, NULL)
or cb(b, BIO_CB_CTRL, fp,    cmd, 0, 1)

after the control operation:
cb_ex(b, BIO_CB_CTRL|BIO_CB_RETURN, fp, 0, cmd, 0, ret, NULL)
or cb(b, BIO_CB_CTRL|BIO_CB_RETURN, fp,    cmd, 0, ret)

RETURN VALUES

BIO_get_callback_ex() returns a pointer to the function cb_ex previously installed with BIO_set_callback_cb(), or NULL if no such callback was installed.

BIO_get_callback() returns a pointer to the function cb previously installed with BIO_set_callback(), or NULL if no such callback was installed.

BIO_get_callback_arg() returns the pointer previously set with BIO_set_callback_arg(), or NULL if no such pointer was set.

BIO_debug_callback() returns ret if the bit BIO_CB_RETURN is set in cmd, or 1 otherwise.

EXAMPLES

The BIO_debug_callback() function is a good example. Its source is in the file crypto/bio/bio_cb.c.

SEE ALSO

BIO_new(3)

HISTORY

BIO_set_callback(), BIO_get_callback(), BIO_set_callback_arg(), and BIO_debug_callback() first appeared in SSLeay 0.6.0. BIO_get_callback_arg() first appeared in SSLeay 0.8.0. These functions have been available since OpenBSD 2.4.

BIO_callback_fn() first appeared in OpenSSL 1.1.0. BIO_callback_fn_ex(), BIO_set_callback_ex(), and BIO_get_callback_ex() first appeared in OpenSSL 1.1.1. These functions have been available since OpenBSD 7.1.