.\" $OpenBSD: BIO_find_type.3,v 1.12 2023/07/26 20:01:04 tb Exp $ .\" full merge up to: OpenSSL 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) 2021, 2023 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, 2013, 2016 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: July 26 2023 $ .Dt BIO_FIND_TYPE 3 .Os .Sh NAME .Nm BIO_find_type , .Nm BIO_next , .Nm BIO_method_type , .Nm BIO_method_name .Nd BIO chain traversal .Sh SYNOPSIS .In openssl/bio.h .Ft BIO * .Fo BIO_find_type .Fa "BIO *bio" .Fa "int type" .Fc .Ft BIO * .Fo BIO_next .Fa "BIO *bio" .Fc .Ft int .Fo BIO_method_type .Fa "const BIO *bio" .Fc .Ft const char * .Fo BIO_method_name .Fa "const BIO *bio" .Fc .Fd #define BIO_TYPE_NONE 0 .Fd #define BIO_TYPE_START 128 .Sh DESCRIPTION .Fn BIO_find_type searches for a BIO matching the given .Fa type in the chain starting at .Fa bio . If the least significant byte of the .Fa type argument is non-zero, only exact matches of the .Fa type are accepted. Otherwise, a match only requires that any of the bits set in the .Fa type argument is also set in the candidate BIO. .Pp Types with a least significant byte in the range from 0 to .Dv BIO_TYPE_START , inclusive, are reserved for BIO types built into the library. Types with a least significant byte greater than .Dv BIO_TYPE_START are available for user-defined BIO types; see .Xr BIO_get_new_index 3 for details. .Pp .Fn BIO_next returns the next BIO in the chain after .Fa bio . This function can be used to traverse all BIOs in a chain or in conjunction with .Fn BIO_find_type to find all BIOs of a certain type. .Pp .Fn BIO_method_type returns the type of the given .Fa bio . .Pp .Fn BIO_method_name returns an ASCII string representing the type of the .Fa bio . .Pp The following are the built-in source/sink BIO types that operate on file descriptors. They all have both of the bits .Dv BIO_TYPE_SOURCE_SINK and .Dv BIO_TYPE_DESCRIPTOR but not the bit .Dv BIO_TYPE_FILTER set in their type constant. .Bl -column BIO_TYPE_NULL_FILTER "datagram socket" BIO_s_datagram(3) .It Fa type No constant Ta Em name No string Ta Vt BIO_METHOD .It Dv BIO_TYPE_ACCEPT Ta socket accept Ta Xr BIO_s_accept 3 .It Dv BIO_TYPE_CONNECT Ta socket connect Ta Xr BIO_s_connect 3 .It Dv BIO_TYPE_DGRAM Ta datagram socket Ta Xr BIO_s_datagram 3 .It Dv BIO_TYPE_FD Ta file descriptor Ta Xr BIO_s_fd 3 .It Dv BIO_TYPE_SOCKET Ta socket Ta Xr BIO_s_socket 3 .El .Pp The following are the built-in source/sink BIO types that do not directly operate on file descriptors. They all have the bit .Dv BIO_TYPE_SOURCE_SINK but not the bits .Dv BIO_TYPE_DESCRIPTOR and .Dv BIO_TYPE_FILTER set in their type constant. .Bl -column BIO_TYPE_NULL_FILTER "datagram socket" BIO_s_datagram(3) .It Fa type No constant Ta Em name No string Ta Vt BIO_METHOD .It Dv BIO_TYPE_BIO Ta BIO pair Ta Xr BIO_s_bio 3 .It Dv BIO_TYPE_FILE Ta FILE pointer Ta Xr BIO_s_file 3 .It Dv BIO_TYPE_MEM Ta memory buffer Ta Xr BIO_s_mem 3 .It Dv BIO_TYPE_NULL Ta NULL Ta Xr BIO_s_null 3 .El .Pp The following are the built-in filter BIO types. They all have the bit .Dv BIO_TYPE_FILTER but not the bits .Dv BIO_TYPE_SOURCE_SINK and .Dv BIO_TYPE_DESCRIPTOR set in their type constant. .Bl -column BIO_TYPE_NULL_FILTER "datagram socket" BIO_s_datagram(3) .It Fa type No constant Ta Em name No string Ta Vt BIO_METHOD .\" BIO_TYPE_ASN1 is intentionally undocumented because BIO_f_asn1 was .\" removed from the public API. .\" .It Dv BIO_TYPE_ASN1 Ta asn1 Ta Xr BIO_f_asn1 3 .It Dv BIO_TYPE_BASE64 Ta base64 encoding Ta Xr BIO_f_base64 3 .It Dv BIO_TYPE_BUFFER Ta buffer Ta Xr BIO_f_buffer 3 .It Dv BIO_TYPE_CIPHER Ta cipher Ta Xr BIO_f_cipher 3 .It Dv BIO_TYPE_MD Ta message digest Ta Xr BIO_f_md 3 .It Dv BIO_TYPE_NULL_FILTER Ta NULL filter Ta Xr BIO_f_null 3 .It Dv BIO_TYPE_SSL Ta ssl Ta Xr BIO_f_ssl 3 .El .Pp The constants .Dv BIO_TYPE_BER , .Dv BIO_TYPE_PROXY_CLIENT , and .Dv BIO_TYPE_PROXY_SERVER do not correspond to any BIO types implemented by the library and are not intended to be used for application-defined types, either. The constants .Dv BIO_TYPE_COMP , .Dv BIO_TYPE_LINEBUFFER , and .Dv BIO_TYPE_NBIO_TEST corresponds to a deprecated BIO types that are intentionally undocumented. .Pp If a variable in an application program is intended to store a BIO type but temporarily does not refer to any BIO or refers to a BIO of an unknown type, setting the variable to .Dv BIO_TYPE_NONE is recommended. .Sh RETURN VALUES .Fn BIO_find_type returns the next matching BIO or .Dv NULL if .Fa bio is a .Dv NULL pointer or if no matching BIO is found. .Pp .Fn BIO_next returns the next BIO or .Dv NULL if .Fa bio is a .Dv NULL pointer or points to the last BIO in a chain. .Pp .Fn BIO_method_type returns one of the .Dv BIO_TYPE_* constants. .Pp .Fn BIO_method_name returns an internal pointer to a string. .Sh EXAMPLES Traverse a chain looking for digest BIOs: .Bd -literal -offset 2n BIO *btmp; btmp = in_bio; /* in_bio is the chain to search through */ while (btmp != NULL) { btmp = BIO_find_type(btmp, BIO_TYPE_MD); if (btmp == NULL) break; /* Not found */ /* btmp is a digest BIO, do something with it ... */ ... btmp = BIO_next(btmp); } .Ed .Sh SEE ALSO .Xr BIO_meth_new 3 , .Xr BIO_new 3 .Sh HISTORY .Fn BIO_method_type and .Fn BIO_method_name first appeared in SSLeay 0.6.0. .Fn BIO_find_type first appeared in SSLeay 0.6.6. These functions have been available since .Ox 2.4 . .Pp .Fn BIO_next first appeared in OpenSSL 0.9.6 and has been available since .Ox 2.9 .