397 lines
11 KiB
Groff
397 lines
11 KiB
Groff
.\" $OpenBSD: BIO_set_callback.3,v 1.12 2023/04/30 13:57:29 schwarze Exp $
|
|
.\" full merge up to: OpenSSL 24a535ea Sep 22 13:14:20 2020 +0100
|
|
.\"
|
|
.\" This file is a derived work.
|
|
.\" The changes are covered by the following Copyright and license:
|
|
.\"
|
|
.\" Copyright (c) 2018, 2022 Ingo Schwarze <schwarze@openbsd.org>
|
|
.\"
|
|
.\" Permission to use, copy, modify, and distribute this software for any
|
|
.\" purpose with or without fee is hereby granted, provided that the above
|
|
.\" copyright notice and this permission notice appear in all copies.
|
|
.\"
|
|
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
|
|
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
|
|
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
|
|
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
|
|
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
|
|
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
|
|
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
|
|
.\"
|
|
.\" The original file was written by Dr. Stephen Henson <steve@openssl.org>.
|
|
.\" Copyright (c) 2000, 2016, 2017 The OpenSSL Project. All rights reserved.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\"
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\"
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in
|
|
.\" the documentation and/or other materials provided with the
|
|
.\" distribution.
|
|
.\"
|
|
.\" 3. All advertising materials mentioning features or use of this
|
|
.\" software must display the following acknowledgment:
|
|
.\" "This product includes software developed by the OpenSSL Project
|
|
.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
|
|
.\"
|
|
.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
|
|
.\" endorse or promote products derived from this software without
|
|
.\" prior written permission. For written permission, please contact
|
|
.\" openssl-core@openssl.org.
|
|
.\"
|
|
.\" 5. Products derived from this software may not be called "OpenSSL"
|
|
.\" nor may "OpenSSL" appear in their names without prior written
|
|
.\" permission of the OpenSSL Project.
|
|
.\"
|
|
.\" 6. Redistributions of any form whatsoever must retain the following
|
|
.\" acknowledgment:
|
|
.\" "This product includes software developed by the OpenSSL Project
|
|
.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)"
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
|
|
.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
|
|
.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR
|
|
.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
|
|
.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
|
|
.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
|
|
.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
|
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
|
|
.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
|
|
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
|
|
.\" OF THE POSSIBILITY OF SUCH DAMAGE.
|
|
.\"
|
|
.Dd $Mdocdate: April 30 2023 $
|
|
.Dt BIO_SET_CALLBACK 3
|
|
.Os
|
|
.Sh NAME
|
|
.Nm BIO_callback_fn_ex ,
|
|
.Nm BIO_set_callback_ex ,
|
|
.Nm BIO_get_callback_ex ,
|
|
.Nm BIO_callback_fn ,
|
|
.Nm BIO_set_callback ,
|
|
.Nm BIO_get_callback ,
|
|
.Nm BIO_set_callback_arg ,
|
|
.Nm BIO_get_callback_arg ,
|
|
.Nm BIO_debug_callback
|
|
.\" The following three macros are intentionally undocumented because
|
|
.\" they are unused and would only cause obfuscation if they were used.
|
|
.\" .Nm BIO_CB_return
|
|
.\" .Nm BIO_cb_pre
|
|
.\" .Nm BIO_cb_post
|
|
.Nd BIO callback functions
|
|
.Sh SYNOPSIS
|
|
.In openssl/bio.h
|
|
.Ft typedef long
|
|
.Fo (*BIO_callback_fn_ex)
|
|
.Fa "BIO *b"
|
|
.Fa "int oper"
|
|
.Fa "const char *argp"
|
|
.Fa "size_t len"
|
|
.Fa "int argi"
|
|
.Fa "long argl"
|
|
.Fa "int ret"
|
|
.Fa "size_t *processed"
|
|
.Fc
|
|
.Ft void
|
|
.Fo BIO_set_callback_ex
|
|
.Fa "BIO *b"
|
|
.Fa "BIO_callback_fn_ex cb_ex"
|
|
.Fc
|
|
.Ft BIO_callback_fn_ex
|
|
.Fo BIO_get_callback_ex
|
|
.Fa "const BIO *b"
|
|
.Fc
|
|
.Ft typedef long
|
|
.Fo (*BIO_callback_fn)
|
|
.Fa "BIO *b"
|
|
.Fa "int oper"
|
|
.Fa "const char *argp"
|
|
.Fa "int argi"
|
|
.Fa "long argl"
|
|
.Fa "long ret"
|
|
.Fc
|
|
.Ft void
|
|
.Fo BIO_set_callback
|
|
.Fa "BIO *b"
|
|
.Fa "BIO_callback_fn cb"
|
|
.Fc
|
|
.Ft BIO_callback_fn
|
|
.Fo BIO_get_callback
|
|
.Fa "BIO *b"
|
|
.Fc
|
|
.Ft void
|
|
.Fo BIO_set_callback_arg
|
|
.Fa "BIO *b"
|
|
.Fa "char *pointer"
|
|
.Fc
|
|
.Ft char *
|
|
.Fo BIO_get_callback_arg
|
|
.Fa "const BIO *b"
|
|
.Fc
|
|
.Ft long
|
|
.Fo BIO_debug_callback
|
|
.Fa "BIO *bio"
|
|
.Fa "int oper"
|
|
.Fa "const char *argp"
|
|
.Fa "int argi"
|
|
.Fa "long argl"
|
|
.Fa "long ret"
|
|
.Fc
|
|
.Sh DESCRIPTION
|
|
.Fn BIO_set_callback_ex
|
|
and
|
|
.Fn 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.
|
|
.Pp
|
|
.Fn BIO_set_callback
|
|
and
|
|
.Fn 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
|
|
.Fn BIO_set_callback_ex .
|
|
.Pp
|
|
.Fn BIO_set_callback_arg
|
|
stores the
|
|
.Fa pointer
|
|
internally in
|
|
.Fa b
|
|
and
|
|
.Fn BIO_get_callback_arg
|
|
retrieves it from
|
|
.Fa b .
|
|
The name of these two functions is badly misleading: the
|
|
.Fa pointer
|
|
is never passed as an argument to any callback function.
|
|
But of course, callback functions can call
|
|
.Fn BIO_get_callback_arg
|
|
and access the pointer, just like any other code can.
|
|
.Pp
|
|
.Fn BIO_debug_callback
|
|
is a standard debugging callback which prints
|
|
out information related to each BIO operation.
|
|
If
|
|
.Fn BIO_set_callback_arg
|
|
was called with a
|
|
.Pf non- Dv NULL
|
|
argument, information is sent to the BIO pointed to by the
|
|
.Fa pointer ;
|
|
otherwise, standard error output is used.
|
|
.Pp
|
|
The arguments of the callback functions are as follows:
|
|
.Bl -tag -width Ds
|
|
.It Fa b
|
|
The BIO the callback is attached to.
|
|
.It Fa oper
|
|
The operation being performed, which is one of
|
|
.Dv BIO_CB_CTRL ,
|
|
.Dv BIO_CB_FREE ,
|
|
.Dv BIO_CB_GETS ,
|
|
.Dv BIO_CB_PUTS ,
|
|
.Dv BIO_CB_READ ,
|
|
or
|
|
.Dv BIO_CB_WRITE .
|
|
For some operations, the callback is called twice,
|
|
once before and once after the actual operation.
|
|
The latter case has
|
|
.Fa oper
|
|
OR'ed with
|
|
.Dv BIO_CB_RETURN .
|
|
.It Fa argp , argi , argl
|
|
The meaning of these three arguments depends on the value of
|
|
.Fa oper ,
|
|
that is on the operation being performed.
|
|
.It Fa len
|
|
The length of the data requested to be read or written.
|
|
This is only useful if
|
|
.Fa oper
|
|
is
|
|
.Dv BIO_CB_READ ,
|
|
.Dv BIO_CB_WRITE ,
|
|
or
|
|
.Dv BIO_CB_GETS .
|
|
.It Fa ret
|
|
When
|
|
.Fa oper
|
|
does not include
|
|
.Dv BIO_CB_RETURN ,
|
|
i.e. when the callback is invoked before an operation,
|
|
the value passed into the callback via
|
|
.Fa 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.
|
|
.Pp
|
|
When
|
|
.Fa oper
|
|
includes
|
|
.Dv BIO_CB_RETURN ,
|
|
i.e. when the callback is invoked after an operation,
|
|
the value passed into the callback via
|
|
.Fa 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.
|
|
.It Fa processed
|
|
The location pointed to is updated with the number of bytes
|
|
actually read or written.
|
|
Only used for
|
|
.Dv BIO_CB_READ ,
|
|
.Dv BIO_CB_WRITE ,
|
|
.Dv BIO_CB_GETS ,
|
|
and
|
|
.Dv BIO_CB_PUTS .
|
|
.El
|
|
.Pp
|
|
The callback should normally simply return
|
|
.Fa ret
|
|
when it has finished processing, unless it specifically wishes to
|
|
abort the operation or to modify the value returned to the application.
|
|
.Pp
|
|
The callbacks are called as follows:
|
|
.Bl -tag -width 1n
|
|
.It \&In Fn BIO_free "BIO *b" :
|
|
.Bd -literal
|
|
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)
|
|
.Ed
|
|
.It \&In Fn BIO_read "BIO *b" "void *out" "int outl" :
|
|
.Bd -literal
|
|
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)
|
|
.Ed
|
|
.It \&In Fn BIO_write "BIO *b" "const void *in" "int inl" :
|
|
.Bd -literal
|
|
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)
|
|
.Ed
|
|
.It \&In Fn BIO_gets "BIO *b" "char *out" "int outl" :
|
|
.Bd -literal
|
|
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)
|
|
.Ed
|
|
.It \&In Fn BIO_puts "BIO *b" "const char *in" :
|
|
.Bd -literal
|
|
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)
|
|
.Ed
|
|
.It \&In Fn BIO_ctrl "BIO *b" "int cmd" "long larg" "void *parg" :
|
|
.Bd -literal
|
|
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)
|
|
.Ed
|
|
.It \&In Fn BIO_callback_ctrl "BIO *b" "int cmd" "BIO_info_cb *fp" :
|
|
.Bd -literal
|
|
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)
|
|
.Ed
|
|
.El
|
|
.Sh RETURN VALUES
|
|
.Fn BIO_get_callback_ex
|
|
returns a pointer to the function
|
|
.Fa cb_ex
|
|
previously installed with
|
|
.Fn BIO_set_callback_cb ,
|
|
or
|
|
.Dv NULL
|
|
if no such callback was installed.
|
|
.Pp
|
|
.Fn BIO_get_callback
|
|
returns a pointer to the function
|
|
.Fa cb
|
|
previously installed with
|
|
.Fn BIO_set_callback ,
|
|
or
|
|
.Dv NULL
|
|
if no such callback was installed.
|
|
.Pp
|
|
.Fn BIO_get_callback_arg
|
|
returns the
|
|
.Fa pointer
|
|
previously set with
|
|
.Fn BIO_set_callback_arg ,
|
|
or
|
|
.Dv NULL
|
|
if no such pointer was set.
|
|
.Pp
|
|
.Fn BIO_debug_callback
|
|
returns
|
|
.Fa ret
|
|
if the bit
|
|
.Dv BIO_CB_RETURN
|
|
is set in
|
|
.Fa cmd ,
|
|
or 1 otherwise.
|
|
.Sh EXAMPLES
|
|
The
|
|
.Fn BIO_debug_callback
|
|
function is a good example.
|
|
Its source is in the file
|
|
.Pa crypto/bio/bio_cb.c .
|
|
.Sh SEE ALSO
|
|
.Xr BIO_new 3
|
|
.Sh HISTORY
|
|
.Fn BIO_set_callback ,
|
|
.Fn BIO_get_callback ,
|
|
.Fn BIO_set_callback_arg ,
|
|
and
|
|
.Fn BIO_debug_callback
|
|
first appeared in SSLeay 0.6.0.
|
|
.Fn BIO_get_callback_arg
|
|
first appeared in SSLeay 0.8.0.
|
|
These functions have been available since
|
|
.Ox 2.4 .
|
|
.Pp
|
|
.Fn BIO_callback_fn
|
|
first appeared in OpenSSL 1.1.0.
|
|
.Fn BIO_callback_fn_ex ,
|
|
.Fn BIO_set_callback_ex ,
|
|
and
|
|
.Fn BIO_get_callback_ex
|
|
first appeared in OpenSSL 1.1.1.
|
|
These functions have been available since
|
|
.Ox 7.1 .
|