.\" $OpenBSD: BIO_push.3,v 1.14 2022/12/16 16:02:17 schwarze Exp $ .\" full merge up to: .\" OpenSSL doc/man3/BIO_push.pod 791bfd91 Nov 19 20:38:27 2021 +0100 .\" OpenSSL doc/man7/bio.pod 1cb7eff4 Sep 10 13:56:40 2019 +0100 .\" .\" This file is a derived work. .\" The changes are covered by the following Copyright and license: .\" .\" Copyright (c) 2022 Ingo Schwarze .\" .\" 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 . .\" Copyright (c) 2000, 2014 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: December 16 2022 $ .Dt BIO_PUSH 3 .Os .Sh NAME .Nm BIO_push , .Nm BIO_pop , .Nm BIO_set_next .Nd manipulate BIO chains .Sh SYNOPSIS .In openssl/bio.h .Ft BIO * .Fo BIO_push .Fa "BIO *b" .Fa "BIO *new_tail" .Fc .Ft BIO * .Fo BIO_pop .Fa "BIO *b" .Fc .Ft void .Fo BIO_set_next .Fa "BIO *b" .Fa "BIO *new_tail" .Fc .Sh DESCRIPTION BIOs can be joined together to form chains. A chain normally consists 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. .Pp Every BIO is a member of exactly one chain. It is either at the beginning of its chain or there is exactly one preceding BIO. It is either at the end of its chain or there is exactly one following BIO. If there is neither a preceding nor a following BIO, it can be regarded as a chain with one member. Every chain has exactly one beginning and exactly one end. .Pp .Fn BIO_push appends the chain starting at .Fa new_tail to the end of the chain that contains .Fa b . Unless .Fa b is .Dv NULL , it then calls .Xr BIO_ctrl 3 on .Fa b with an argument of .Dv BIO_CTRL_PUSH . If .Fa b or .Fa new_tail is .Dv NULL , nothing is appended. .Pp In LibreSSL, if .Fa new_tail is not at the beginning of its chain, the head of that chain up to but not including .Fa new_tail is cut off and becomes a separate chain. For portability, it is best to make sure that .Fa new_tail is at the beginning of its chain before calling .Fn BIO_push . .Pp .Fn BIO_pop removes the BIO .Fa b from its chain. Despite the word .Dq pop in the function name, .Fa b can be at the beginning, in the middle, or at the end of its chain. Before removal, .Xr BIO_ctrl 3 is called on .Fa b with an argument of .Dv BIO_CTRL_POP . The removed BIO .Fa b becomes the only member of its own chain and can thus be freed or attached to a different chain. If .Fa b is .Dv NULL , no action occurs. .Pp .Fn BIO_set_next appends the chain starting with .Fa new_tail to the chain ending with .Fa b . .Pp In LibreSSL, if .Fa new_tail is not at the beginning of its chain, the head of that chain up to but not including .Fa new_tail is cut off and becomes a separate chain, and if .Fa b is not at the end of its chain, the tail of that chain starting after .Fa b is cut off and becomes a separate chain. .Pp For portability, it is best to make sure that .Fa b is at the end of its chain and that .Fa new_tail is at the beginning of its chain before calling .Fn BIO_set_next and to avoid calling .Fn BIO_pop on .Fa new_tail afterwards. .Pp In LibreSSL, the only built-in BIO type for which .Xr BIO_ctrl 3 calls with an argument of .Dv BIO_CTRL_PUSH or .Dv BIO_CTRL_POP have any effect is .Xr BIO_f_ssl 3 . .Sh RETURN VALUES .Fn BIO_push returns .Fa b if it is not .Dv NULL or .Fa new_tail if it is. .Pp .Fn BIO_pop returns the BIO that followed .Fa b in its chain, or .Dv NULL if .Fa b is .Dv NULL or was at the end of its chain. .Sh EXAMPLES For these examples suppose .Sy md1 and .Sy md2 are digest BIOs, .Sy b64 is a Base64 BIO and .Sy f is a file BIO (see .Xr BIO_f_md 3 , .Xr BIO_f_base64 3 , and .Xr BIO_s_file 3 , respectively). .Pp If the call .Pp .Dl BIO_push(b64, f); .Pp is made then the new chain will be .Sy b64-f . After making the calls .Bd -literal -offset indent BIO_push(md2, b64); BIO_push(md1, md2); .Ed .Pp the new chain is .Sy md1-md2-b64-f . Data written to .Sy md1 will be digested by .Sy md1 and .Sy md2 , Base64-encoded and written to .Sy f . .Pp It should be noted that reading causes data to pass in the reverse direction. That is, data is read from .Sy f , Base64-decoded and digested by .Sy md1 and .Sy md2 . If this call is made: .Pp .Dl BIO_pop(md2); .Pp The call will return .Sy b64 and the new chain will be .Sy md1-b64-f ; data can be written to .Sy md1 as before. .Sh SEE ALSO .Xr BIO_find_type 3 , .Xr BIO_new 3 , .Xr BIO_read 3 .Sh HISTORY .Fn BIO_push first appeared in SSLeay 0.6.0. .Fn BIO_pop first appeared in SSLeay 0.6.4. Both functions have been available since .Ox 2.4 . .Pp .Fn BIO_set_next first appeared in OpenSSL 1.1.0 and has been available since .Ox 7.1 . .Sh CAVEATS Creating a cyclic chain results in undefined behavior. For example, infinite recursion or infinite loops may ensue. .Pp If it is unknown whether .Fa b and .Fa new_tail are already members of the same chain and whether joining them would create a cycle, the calling code can use the following safe idiom: .Bd -literal -offset indent BIO *btest; for (btest = new_tail; btest != NULL; btest = BIO_next(btest)) if (btest == b) /* Bail out because this would create a cycle. */ BIO_push(b, new_tail); /* This is now safe. */ .Ed .Pp The same idiom can be used with .Fn BIO_set_next instead of .Fn BIO_push . .Pp Often, the safe idiom is not needed because it is already known that .Fa b and .Fa new_tail are not members of the same chain, for example when .Fa b or .Fa new_tail was created right before.