1.\" $OpenBSD: BIO_push.3,v 1.14 2022/12/16 16:02:17 schwarze Exp $ 2.\" full merge up to: 3.\" OpenSSL doc/man3/BIO_push.pod 791bfd91 Nov 19 20:38:27 2021 +0100 4.\" OpenSSL doc/man7/bio.pod 1cb7eff4 Sep 10 13:56:40 2019 +0100 5.\" 6.\" This file is a derived work. 7.\" The changes are covered by the following Copyright and license: 8.\" 9.\" Copyright (c) 2022 Ingo Schwarze <schwarze@openbsd.org> 10.\" 11.\" Permission to use, copy, modify, and distribute this software for any 12.\" purpose with or without fee is hereby granted, provided that the above 13.\" copyright notice and this permission notice appear in all copies. 14.\" 15.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 16.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 17.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 18.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 19.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 20.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 21.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 22.\" 23.\" The original file was written by Dr. Stephen Henson <steve@openssl.org>. 24.\" Copyright (c) 2000, 2014 The OpenSSL Project. All rights reserved. 25.\" 26.\" Redistribution and use in source and binary forms, with or without 27.\" modification, are permitted provided that the following conditions 28.\" are met: 29.\" 30.\" 1. Redistributions of source code must retain the above copyright 31.\" notice, this list of conditions and the following disclaimer. 32.\" 33.\" 2. Redistributions in binary form must reproduce the above copyright 34.\" notice, this list of conditions and the following disclaimer in 35.\" the documentation and/or other materials provided with the 36.\" distribution. 37.\" 38.\" 3. All advertising materials mentioning features or use of this 39.\" software must display the following acknowledgment: 40.\" "This product includes software developed by the OpenSSL Project 41.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" 42.\" 43.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to 44.\" endorse or promote products derived from this software without 45.\" prior written permission. For written permission, please contact 46.\" openssl-core@openssl.org. 47.\" 48.\" 5. Products derived from this software may not be called "OpenSSL" 49.\" nor may "OpenSSL" appear in their names without prior written 50.\" permission of the OpenSSL Project. 51.\" 52.\" 6. Redistributions of any form whatsoever must retain the following 53.\" acknowledgment: 54.\" "This product includes software developed by the OpenSSL Project 55.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" 56.\" 57.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY 58.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 59.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 60.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR 61.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 62.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 63.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 64.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 65.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 66.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 67.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED 68.\" OF THE POSSIBILITY OF SUCH DAMAGE. 69.\" 70.Dd $Mdocdate: December 16 2022 $ 71.Dt BIO_PUSH 3 72.Os 73.Sh NAME 74.Nm BIO_push , 75.Nm BIO_pop , 76.Nm BIO_set_next 77.Nd manipulate BIO chains 78.Sh SYNOPSIS 79.In openssl/bio.h 80.Ft BIO * 81.Fo BIO_push 82.Fa "BIO *b" 83.Fa "BIO *new_tail" 84.Fc 85.Ft BIO * 86.Fo BIO_pop 87.Fa "BIO *b" 88.Fc 89.Ft void 90.Fo BIO_set_next 91.Fa "BIO *b" 92.Fa "BIO *new_tail" 93.Fc 94.Sh DESCRIPTION 95BIOs can be joined together to form chains. 96A chain normally consists of one or more filter BIOs 97and one source/sink BIO at the end. 98Data read from or written to the first BIO traverses the chain 99to the end. 100.Pp 101Every BIO is a member of exactly one chain. 102It is either at the beginning of its chain 103or there is exactly one preceding BIO. 104It is either at the end of its chain 105or there is exactly one following BIO. 106If there is neither a preceding nor a following BIO, 107it can be regarded as a chain with one member. 108Every chain has exactly one beginning and exactly one end. 109.Pp 110.Fn BIO_push 111appends the chain starting at 112.Fa new_tail 113to the end of the chain that contains 114.Fa b . 115Unless 116.Fa b 117is 118.Dv NULL , 119it then calls 120.Xr BIO_ctrl 3 121on 122.Fa b 123with an argument of 124.Dv BIO_CTRL_PUSH . 125If 126.Fa b 127or 128.Fa new_tail 129is 130.Dv NULL , 131nothing is appended. 132.Pp 133In LibreSSL, if 134.Fa new_tail 135is not at the beginning of its chain, 136the head of that chain up to but not including 137.Fa new_tail 138is cut off and becomes a separate chain. 139For portability, it is best to make sure that 140.Fa new_tail 141is at the beginning of its chain before calling 142.Fn BIO_push . 143.Pp 144.Fn BIO_pop 145removes the BIO 146.Fa b 147from its chain. 148Despite the word 149.Dq pop 150in the function name, 151.Fa b 152can be at the beginning, in the middle, or at the end of its chain. 153Before removal, 154.Xr BIO_ctrl 3 155is called on 156.Fa b 157with an argument of 158.Dv BIO_CTRL_POP . 159The removed BIO 160.Fa b 161becomes the only member of its own chain and can thus be freed 162or attached to a different chain. 163If 164.Fa b 165is 166.Dv NULL , 167no action occurs. 168.Pp 169.Fn BIO_set_next 170appends the chain starting with 171.Fa new_tail 172to the chain ending with 173.Fa b . 174.Pp 175In LibreSSL, if 176.Fa new_tail 177is not at the beginning of its chain, 178the head of that chain up to but not including 179.Fa new_tail 180is cut off and becomes a separate chain, 181and if 182.Fa b 183is not at the end of its chain, 184the tail of that chain starting after 185.Fa b 186is cut off and becomes a separate chain. 187.Pp 188For portability, it is best to make sure that 189.Fa b 190is at the end of its chain and that 191.Fa new_tail 192is at the beginning of its chain before calling 193.Fn BIO_set_next 194and to avoid calling 195.Fn BIO_pop 196on 197.Fa new_tail 198afterwards. 199.Pp 200In LibreSSL, the only built-in BIO type for which 201.Xr BIO_ctrl 3 202calls with an argument of 203.Dv BIO_CTRL_PUSH 204or 205.Dv BIO_CTRL_POP 206have any effect is 207.Xr BIO_f_ssl 3 . 208.Sh RETURN VALUES 209.Fn BIO_push 210returns 211.Fa b 212if it is not 213.Dv NULL 214or 215.Fa new_tail 216if it is. 217.Pp 218.Fn BIO_pop 219returns the BIO that followed 220.Fa b 221in its chain, or 222.Dv NULL 223if 224.Fa b 225is 226.Dv NULL 227or was at the end of its chain. 228.Sh EXAMPLES 229For these examples suppose 230.Sy md1 231and 232.Sy md2 233are digest BIOs, 234.Sy b64 235is a Base64 BIO and 236.Sy f 237is a file BIO (see 238.Xr BIO_f_md 3 , 239.Xr BIO_f_base64 3 , 240and 241.Xr BIO_s_file 3 , 242respectively). 243.Pp 244If the call 245.Pp 246.Dl BIO_push(b64, f); 247.Pp 248is made then the new chain will be 249.Sy b64-f . 250After making the calls 251.Bd -literal -offset indent 252BIO_push(md2, b64); 253BIO_push(md1, md2); 254.Ed 255.Pp 256the new chain is 257.Sy md1-md2-b64-f . 258Data written to 259.Sy md1 260will be digested 261by 262.Sy md1 263and 264.Sy md2 , 265Base64-encoded and written to 266.Sy f . 267.Pp 268It should be noted that reading causes data to pass 269in the reverse direction. 270That is, data is read from 271.Sy f , 272Base64-decoded and digested by 273.Sy md1 274and 275.Sy md2 . 276If this call is made: 277.Pp 278.Dl BIO_pop(md2); 279.Pp 280The call will return 281.Sy b64 282and the new chain will be 283.Sy md1-b64-f ; 284data can be written to 285.Sy md1 286as before. 287.Sh SEE ALSO 288.Xr BIO_find_type 3 , 289.Xr BIO_new 3 , 290.Xr BIO_read 3 291.Sh HISTORY 292.Fn BIO_push 293first appeared in SSLeay 0.6.0. 294.Fn BIO_pop 295first appeared in SSLeay 0.6.4. 296Both functions have been available since 297.Ox 2.4 . 298.Pp 299.Fn BIO_set_next 300first appeared in OpenSSL 1.1.0 301and has been available since 302.Ox 7.1 . 303.Sh CAVEATS 304Creating a cyclic chain results in undefined behavior. 305For example, infinite recursion or infinite loops may ensue. 306.Pp 307If it is unknown whether 308.Fa b 309and 310.Fa new_tail 311are already members of the same chain and whether joining them would 312create a cycle, the calling code can use the following safe idiom: 313.Bd -literal -offset indent 314BIO *btest; 315 316for (btest = new_tail; btest != NULL; btest = BIO_next(btest)) 317 if (btest == b) 318 /* Bail out because this would create a cycle. */ 319BIO_push(b, new_tail); /* This is now safe. */ 320.Ed 321.Pp 322The same idiom can be used with 323.Fn BIO_set_next 324instead of 325.Fn BIO_push . 326.Pp 327Often, the safe idiom is not needed because it is already known that 328.Fa b 329and 330.Fa new_tail 331are not members of the same chain, for example when 332.Fa b 333or 334.Fa new_tail 335was created right before. 336