1.\" $OpenBSD: BIO_find_type.3,v 1.12 2023/07/26 20:01:04 tb Exp $ 2.\" full merge up to: OpenSSL 1cb7eff4 Sep 10 13:56:40 2019 +0100 3.\" 4.\" This file is a derived work. 5.\" The changes are covered by the following Copyright and license: 6.\" 7.\" Copyright (c) 2021, 2023 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, 2013, 2016 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: July 26 2023 $ 69.Dt BIO_FIND_TYPE 3 70.Os 71.Sh NAME 72.Nm BIO_find_type , 73.Nm BIO_next , 74.Nm BIO_method_type , 75.Nm BIO_method_name 76.Nd BIO chain traversal 77.Sh SYNOPSIS 78.In openssl/bio.h 79.Ft BIO * 80.Fo BIO_find_type 81.Fa "BIO *bio" 82.Fa "int type" 83.Fc 84.Ft BIO * 85.Fo BIO_next 86.Fa "BIO *bio" 87.Fc 88.Ft int 89.Fo BIO_method_type 90.Fa "const BIO *bio" 91.Fc 92.Ft const char * 93.Fo BIO_method_name 94.Fa "const BIO *bio" 95.Fc 96.Fd #define BIO_TYPE_NONE 0 97.Fd #define BIO_TYPE_START 128 98.Sh DESCRIPTION 99.Fn BIO_find_type 100searches for a BIO matching the given 101.Fa type 102in the chain starting at 103.Fa bio . 104If the least significant byte of the 105.Fa type 106argument is non-zero, only exact matches of the 107.Fa type 108are accepted. 109Otherwise, a match only requires that any of the bits set in the 110.Fa type 111argument is also set in the candidate BIO. 112.Pp 113Types with a least significant byte in the range from 0 to 114.Dv BIO_TYPE_START , 115inclusive, are reserved for BIO types built into the library. 116Types with a least significant byte greater than 117.Dv BIO_TYPE_START 118are available for user-defined BIO types; see 119.Xr BIO_get_new_index 3 120for details. 121.Pp 122.Fn BIO_next 123returns the next BIO in the chain after 124.Fa bio . 125This function can be used to traverse all BIOs in a chain 126or in conjunction with 127.Fn BIO_find_type 128to find all BIOs of a certain type. 129.Pp 130.Fn BIO_method_type 131returns the type of the given 132.Fa bio . 133.Pp 134.Fn BIO_method_name 135returns an ASCII string representing the type of the 136.Fa bio . 137.Pp 138The following are the built-in source/sink BIO types 139that operate on file descriptors. 140They all have both of the bits 141.Dv BIO_TYPE_SOURCE_SINK 142and 143.Dv BIO_TYPE_DESCRIPTOR 144but not the bit 145.Dv BIO_TYPE_FILTER 146set in their type constant. 147.Bl -column BIO_TYPE_NULL_FILTER "datagram socket" BIO_s_datagram(3) 148.It Fa type No constant Ta Em name No string Ta Vt BIO_METHOD 149.It Dv BIO_TYPE_ACCEPT Ta socket accept Ta Xr BIO_s_accept 3 150.It Dv BIO_TYPE_CONNECT Ta socket connect Ta Xr BIO_s_connect 3 151.It Dv BIO_TYPE_DGRAM Ta datagram socket Ta Xr BIO_s_datagram 3 152.It Dv BIO_TYPE_FD Ta file descriptor Ta Xr BIO_s_fd 3 153.It Dv BIO_TYPE_SOCKET Ta socket Ta Xr BIO_s_socket 3 154.El 155.Pp 156The following are the built-in source/sink BIO types 157that do not directly operate on file descriptors. 158They all have the bit 159.Dv BIO_TYPE_SOURCE_SINK 160but not the bits 161.Dv BIO_TYPE_DESCRIPTOR 162and 163.Dv BIO_TYPE_FILTER 164set in their type constant. 165.Bl -column BIO_TYPE_NULL_FILTER "datagram socket" BIO_s_datagram(3) 166.It Fa type No constant Ta Em name No string Ta Vt BIO_METHOD 167.It Dv BIO_TYPE_BIO Ta BIO pair Ta Xr BIO_s_bio 3 168.It Dv BIO_TYPE_FILE Ta FILE pointer Ta Xr BIO_s_file 3 169.It Dv BIO_TYPE_MEM Ta memory buffer Ta Xr BIO_s_mem 3 170.It Dv BIO_TYPE_NULL Ta NULL Ta Xr BIO_s_null 3 171.El 172.Pp 173The following are the built-in filter BIO types. 174They all have the bit 175.Dv BIO_TYPE_FILTER 176but not the bits 177.Dv BIO_TYPE_SOURCE_SINK 178and 179.Dv BIO_TYPE_DESCRIPTOR 180set in their type constant. 181.Bl -column BIO_TYPE_NULL_FILTER "datagram socket" BIO_s_datagram(3) 182.It Fa type No constant Ta Em name No string Ta Vt BIO_METHOD 183.\" BIO_TYPE_ASN1 is intentionally undocumented because BIO_f_asn1 was 184.\" removed from the public API. 185.\" .It Dv BIO_TYPE_ASN1 Ta asn1 Ta Xr BIO_f_asn1 3 186.It Dv BIO_TYPE_BASE64 Ta base64 encoding Ta Xr BIO_f_base64 3 187.It Dv BIO_TYPE_BUFFER Ta buffer Ta Xr BIO_f_buffer 3 188.It Dv BIO_TYPE_CIPHER Ta cipher Ta Xr BIO_f_cipher 3 189.It Dv BIO_TYPE_MD Ta message digest Ta Xr BIO_f_md 3 190.It Dv BIO_TYPE_NULL_FILTER Ta NULL filter Ta Xr BIO_f_null 3 191.It Dv BIO_TYPE_SSL Ta ssl Ta Xr BIO_f_ssl 3 192.El 193.Pp 194The constants 195.Dv BIO_TYPE_BER , 196.Dv BIO_TYPE_PROXY_CLIENT , 197and 198.Dv BIO_TYPE_PROXY_SERVER 199do not correspond to any BIO types implemented by the library and are 200not intended to be used for application-defined types, either. 201The constants 202.Dv BIO_TYPE_COMP , 203.Dv BIO_TYPE_LINEBUFFER , 204and 205.Dv BIO_TYPE_NBIO_TEST 206corresponds to a deprecated BIO types that are intentionally undocumented. 207.Pp 208If a variable in an application program is intended 209to store a BIO type but temporarily does not refer to any BIO 210or refers to a BIO of an unknown type, setting the variable to 211.Dv BIO_TYPE_NONE 212is recommended. 213.Sh RETURN VALUES 214.Fn BIO_find_type 215returns the next matching BIO or 216.Dv NULL 217if 218.Fa bio 219is a 220.Dv NULL 221pointer or if no matching BIO is found. 222.Pp 223.Fn BIO_next 224returns the next BIO or 225.Dv NULL 226if 227.Fa bio 228is a 229.Dv NULL 230pointer or points to the last BIO in a chain. 231.Pp 232.Fn BIO_method_type 233returns one of the 234.Dv BIO_TYPE_* 235constants. 236.Pp 237.Fn BIO_method_name 238returns an internal pointer to a string. 239.Sh EXAMPLES 240Traverse a chain looking for digest BIOs: 241.Bd -literal -offset 2n 242BIO *btmp; 243 244btmp = in_bio; /* in_bio is the chain to search through */ 245while (btmp != NULL) { 246 btmp = BIO_find_type(btmp, BIO_TYPE_MD); 247 if (btmp == NULL) 248 break; /* Not found */ 249 250 /* btmp is a digest BIO, do something with it ... */ 251 ... 252 253 btmp = BIO_next(btmp); 254} 255.Ed 256.Sh SEE ALSO 257.Xr BIO_meth_new 3 , 258.Xr BIO_new 3 259.Sh HISTORY 260.Fn BIO_method_type 261and 262.Fn BIO_method_name 263first appeared in SSLeay 0.6.0. 264.Fn BIO_find_type 265first appeared in SSLeay 0.6.6. 266These functions have been available since 267.Ox 2.4 . 268.Pp 269.Fn BIO_next 270first appeared in OpenSSL 0.9.6 and has been available since 271.Ox 2.9 . 272