1.\" $OpenBSD: BIO_set_callback.3,v 1.12 2023/04/30 13:57:29 schwarze Exp $ 2.\" full merge up to: OpenSSL 24a535ea Sep 22 13:14:20 2020 +0100 3.\" 4.\" This file is a derived work. 5.\" The changes are covered by the following Copyright and license: 6.\" 7.\" Copyright (c) 2018, 2022 Ingo Schwarze <schwarze@openbsd.org> 8.\" 9.\" Permission to use, copy, modify, and distribute this software for any 10.\" purpose with or without fee is hereby granted, provided that the above 11.\" copyright notice and this permission notice appear in all copies. 12.\" 13.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 14.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 15.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 16.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 17.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 18.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 19.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 20.\" 21.\" The original file was written by Dr. Stephen Henson <steve@openssl.org>. 22.\" Copyright (c) 2000, 2016, 2017 The OpenSSL Project. All rights reserved. 23.\" 24.\" Redistribution and use in source and binary forms, with or without 25.\" modification, are permitted provided that the following conditions 26.\" are met: 27.\" 28.\" 1. Redistributions of source code must retain the above copyright 29.\" notice, this list of conditions and the following disclaimer. 30.\" 31.\" 2. Redistributions in binary form must reproduce the above copyright 32.\" notice, this list of conditions and the following disclaimer in 33.\" the documentation and/or other materials provided with the 34.\" distribution. 35.\" 36.\" 3. All advertising materials mentioning features or use of this 37.\" software must display the following acknowledgment: 38.\" "This product includes software developed by the OpenSSL Project 39.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" 40.\" 41.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to 42.\" endorse or promote products derived from this software without 43.\" prior written permission. For written permission, please contact 44.\" openssl-core@openssl.org. 45.\" 46.\" 5. Products derived from this software may not be called "OpenSSL" 47.\" nor may "OpenSSL" appear in their names without prior written 48.\" permission of the OpenSSL Project. 49.\" 50.\" 6. Redistributions of any form whatsoever must retain the following 51.\" acknowledgment: 52.\" "This product includes software developed by the OpenSSL Project 53.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" 54.\" 55.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY 56.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 57.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 58.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR 59.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 60.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 61.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 62.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 63.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 64.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 65.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED 66.\" OF THE POSSIBILITY OF SUCH DAMAGE. 67.\" 68.Dd $Mdocdate: April 30 2023 $ 69.Dt BIO_SET_CALLBACK 3 70.Os 71.Sh NAME 72.Nm BIO_callback_fn_ex , 73.Nm BIO_set_callback_ex , 74.Nm BIO_get_callback_ex , 75.Nm BIO_callback_fn , 76.Nm BIO_set_callback , 77.Nm BIO_get_callback , 78.Nm BIO_set_callback_arg , 79.Nm BIO_get_callback_arg , 80.Nm BIO_debug_callback 81.\" The following three macros are intentionally undocumented because 82.\" they are unused and would only cause obfuscation if they were used. 83.\" .Nm BIO_CB_return 84.\" .Nm BIO_cb_pre 85.\" .Nm BIO_cb_post 86.Nd BIO callback functions 87.Sh SYNOPSIS 88.In openssl/bio.h 89.Ft typedef long 90.Fo (*BIO_callback_fn_ex) 91.Fa "BIO *b" 92.Fa "int oper" 93.Fa "const char *argp" 94.Fa "size_t len" 95.Fa "int argi" 96.Fa "long argl" 97.Fa "int ret" 98.Fa "size_t *processed" 99.Fc 100.Ft void 101.Fo BIO_set_callback_ex 102.Fa "BIO *b" 103.Fa "BIO_callback_fn_ex cb_ex" 104.Fc 105.Ft BIO_callback_fn_ex 106.Fo BIO_get_callback_ex 107.Fa "const BIO *b" 108.Fc 109.Ft typedef long 110.Fo (*BIO_callback_fn) 111.Fa "BIO *b" 112.Fa "int oper" 113.Fa "const char *argp" 114.Fa "int argi" 115.Fa "long argl" 116.Fa "long ret" 117.Fc 118.Ft void 119.Fo BIO_set_callback 120.Fa "BIO *b" 121.Fa "BIO_callback_fn cb" 122.Fc 123.Ft BIO_callback_fn 124.Fo BIO_get_callback 125.Fa "BIO *b" 126.Fc 127.Ft void 128.Fo BIO_set_callback_arg 129.Fa "BIO *b" 130.Fa "char *pointer" 131.Fc 132.Ft char * 133.Fo BIO_get_callback_arg 134.Fa "const BIO *b" 135.Fc 136.Ft long 137.Fo BIO_debug_callback 138.Fa "BIO *bio" 139.Fa "int oper" 140.Fa "const char *argp" 141.Fa "int argi" 142.Fa "long argl" 143.Fa "long ret" 144.Fc 145.Sh DESCRIPTION 146.Fn BIO_set_callback_ex 147and 148.Fn BIO_get_callback_ex 149set and retrieve the BIO callback. 150The callback is called during most high-level BIO operations. 151It can be used for debugging purposes to trace operations on a BIO 152or to modify its operation. 153.Pp 154.Fn BIO_set_callback 155and 156.Fn BIO_get_callback 157are deprecated functions that set and retrieve the old-style BIO callback, 158which is only used if no new-style callback is set with 159.Fn BIO_set_callback_ex . 160.Pp 161.Fn BIO_set_callback_arg 162stores the 163.Fa pointer 164internally in 165.Fa b 166and 167.Fn BIO_get_callback_arg 168retrieves it from 169.Fa b . 170The name of these two functions is badly misleading: the 171.Fa pointer 172is never passed as an argument to any callback function. 173But of course, callback functions can call 174.Fn BIO_get_callback_arg 175and access the pointer, just like any other code can. 176.Pp 177.Fn BIO_debug_callback 178is a standard debugging callback which prints 179out information related to each BIO operation. 180If 181.Fn BIO_set_callback_arg 182was called with a 183.Pf non- Dv NULL 184argument, information is sent to the BIO pointed to by the 185.Fa pointer ; 186otherwise, standard error output is used. 187.Pp 188The arguments of the callback functions are as follows: 189.Bl -tag -width Ds 190.It Fa b 191The BIO the callback is attached to. 192.It Fa oper 193The operation being performed, which is one of 194.Dv BIO_CB_CTRL , 195.Dv BIO_CB_FREE , 196.Dv BIO_CB_GETS , 197.Dv BIO_CB_PUTS , 198.Dv BIO_CB_READ , 199or 200.Dv BIO_CB_WRITE . 201For some operations, the callback is called twice, 202once before and once after the actual operation. 203The latter case has 204.Fa oper 205OR'ed with 206.Dv BIO_CB_RETURN . 207.It Fa argp , argi , argl 208The meaning of these three arguments depends on the value of 209.Fa oper , 210that is on the operation being performed. 211.It Fa len 212The length of the data requested to be read or written. 213This is only useful if 214.Fa oper 215is 216.Dv BIO_CB_READ , 217.Dv BIO_CB_WRITE , 218or 219.Dv BIO_CB_GETS . 220.It Fa ret 221When 222.Fa oper 223does not include 224.Dv BIO_CB_RETURN , 225i.e. when the callback is invoked before an operation, 226the value passed into the callback via 227.Fa ret 228is always 1. 229In this case, if the callback returns a negative value, the library 230aborts the requested operation and instead returns the negative 231return value from the callback to the application. 232If the callback returns a non-negative value, that return value is 233ignored by the library, and the operation is performed normally. 234.Pp 235When 236.Fa oper 237includes 238.Dv BIO_CB_RETURN , 239i.e. when the callback is invoked after an operation, 240the value passed into the callback via 241.Fa ret 242is the return value that the operation would return to the application 243if no callback were present. 244When a callback is present, the operation only passes this value 245to the callback and instead of it returns the return value of the 246callback to the application. 247.It Fa processed 248The location pointed to is updated with the number of bytes 249actually read or written. 250Only used for 251.Dv BIO_CB_READ , 252.Dv BIO_CB_WRITE , 253.Dv BIO_CB_GETS , 254and 255.Dv BIO_CB_PUTS . 256.El 257.Pp 258The callback should normally simply return 259.Fa ret 260when it has finished processing, unless it specifically wishes to 261abort the operation or to modify the value returned to the application. 262.Pp 263The callbacks are called as follows: 264.Bl -tag -width 1n 265.It \&In Fn BIO_free "BIO *b" : 266.Bd -literal 267before the free operation: 268cb_ex(b, BIO_CB_FREE, NULL, 0, 0, 0, 1, NULL) 269or cb(b, BIO_CB_FREE, NULL, 0, 0, 1) 270.Ed 271.It \&In Fn BIO_read "BIO *b" "void *out" "int outl" : 272.Bd -literal 273before the read operation: 274cb_ex(b, BIO_CB_READ, out, outl, 0, 0, 1, NULL) 275or cb(b, BIO_CB_READ, out, outl, 0, 1) 276 277after the read operation: 278cb_ex(b, BIO_CB_READ|BIO_CB_RETURN, out, outl, 0, 0, ret, &bytes) 279or cb(b, BIO_CB_READ|BIO_CB_RETURN, out, outl, 0, ret) 280.Ed 281.It \&In Fn BIO_write "BIO *b" "const void *in" "int inl" : 282.Bd -literal 283before the write operation: 284cb_ex(b, BIO_CB_WRITE, in, inl, 0, 0, 1, NULL) 285or cb(b, BIO_CB_WRITE, in, inl, 0, 1) 286 287after the write operation: 288cb_ex(b, BIO_CB_WRITE|BIO_CB_RETURN, in, inl, 0, 0, ret, &bytes) 289or cb(b, BIO_CB_WRITE|BIO_CB_RETURN, in, inl, 0, ret) 290.Ed 291.It \&In Fn BIO_gets "BIO *b" "char *out" "int outl" : 292.Bd -literal 293before the read operation: 294cb_ex(b, BIO_CB_GETS, out, outl, 0, 0, 1, NULL) 295or cb(b, BIO_CB_GETS, out, outl, 0, 1) 296 297after the read operation: 298cb_ex(b, BIO_CB_GETS|BIO_CB_RETURN, out, outl, 0, 0, ret, &bytes) 299or cb(b, BIO_CB_GETS|BIO_CB_RETURN, out, outl, 0, ret) 300.Ed 301.It \&In Fn BIO_puts "BIO *b" "const char *in" : 302.Bd -literal 303before the write operation: 304cb_ex(b, BIO_CB_PUTS, in, 0, 0, 0, 1, NULL) 305or cb(b, BIO_CB_PUTS, in, 0, 0, 1) 306 307after the write operation: 308cb_ex(b, BIO_CB_PUTS|BIO_CB_RETURN, in, 0, 0, 0, ret, &bytes) 309or cb(b, BIO_CB_PUTS|BIO_CB_RETURN, in, 0, 0, ret) 310.Ed 311.It \&In Fn BIO_ctrl "BIO *b" "int cmd" "long larg" "void *parg" : 312.Bd -literal 313before the control operation: 314cb_ex(b, BIO_CB_CTRL, parg, 0, cmd, larg, 1, NULL) 315or cb(b, BIO_CB_CTRL, parg, cmd, larg, 1) 316 317after the control operation: 318cb_ex(b, BIO_CB_CTRL|BIO_CB_RETURN, parg, 0, cmd, larg, ret, NULL) 319or cb(b, BIO_CB_CTRL|BIO_CB_RETURN, parg, cmd, larg, ret) 320.Ed 321.It \&In Fn BIO_callback_ctrl "BIO *b" "int cmd" "BIO_info_cb *fp" : 322.Bd -literal 323before the control operation: 324cb_ex(b, BIO_CB_CTRL, fp, 0, cmd, 0, 1, NULL) 325or cb(b, BIO_CB_CTRL, fp, cmd, 0, 1) 326 327after the control operation: 328cb_ex(b, BIO_CB_CTRL|BIO_CB_RETURN, fp, 0, cmd, 0, ret, NULL) 329or cb(b, BIO_CB_CTRL|BIO_CB_RETURN, fp, cmd, 0, ret) 330.Ed 331.El 332.Sh RETURN VALUES 333.Fn BIO_get_callback_ex 334returns a pointer to the function 335.Fa cb_ex 336previously installed with 337.Fn BIO_set_callback_cb , 338or 339.Dv NULL 340if no such callback was installed. 341.Pp 342.Fn BIO_get_callback 343returns a pointer to the function 344.Fa cb 345previously installed with 346.Fn BIO_set_callback , 347or 348.Dv NULL 349if no such callback was installed. 350.Pp 351.Fn BIO_get_callback_arg 352returns the 353.Fa pointer 354previously set with 355.Fn BIO_set_callback_arg , 356or 357.Dv NULL 358if no such pointer was set. 359.Pp 360.Fn BIO_debug_callback 361returns 362.Fa ret 363if the bit 364.Dv BIO_CB_RETURN 365is set in 366.Fa cmd , 367or 1 otherwise. 368.Sh EXAMPLES 369The 370.Fn BIO_debug_callback 371function is a good example. 372Its source is in the file 373.Pa crypto/bio/bio_cb.c . 374.Sh SEE ALSO 375.Xr BIO_new 3 376.Sh HISTORY 377.Fn BIO_set_callback , 378.Fn BIO_get_callback , 379.Fn BIO_set_callback_arg , 380and 381.Fn BIO_debug_callback 382first appeared in SSLeay 0.6.0. 383.Fn BIO_get_callback_arg 384first appeared in SSLeay 0.8.0. 385These functions have been available since 386.Ox 2.4 . 387.Pp 388.Fn BIO_callback_fn 389first appeared in OpenSSL 1.1.0. 390.Fn BIO_callback_fn_ex , 391.Fn BIO_set_callback_ex , 392and 393.Fn BIO_get_callback_ex 394first appeared in OpenSSL 1.1.1. 395These functions have been available since 396.Ox 7.1 . 397