]>
Commit | Line | Data |
---|---|---|
47770c4d DSH |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
53934822 | 5 | bio - Basic I/O abstraction |
47770c4d DSH |
6 | |
7 | =head1 SYNOPSIS | |
8 | ||
bb82531f | 9 | =for openssl generic |
a9c85cea | 10 | |
47770c4d DSH |
11 | #include <openssl/bio.h> |
12 | ||
47770c4d DSH |
13 | =head1 DESCRIPTION |
14 | ||
15 | A BIO is an I/O abstraction, it hides many of the underlying I/O | |
16 | details from an application. If an application uses a BIO for its | |
17 | I/O it can transparently handle SSL connections, unencrypted network | |
18 | connections and file I/O. | |
19 | ||
1ee1a169 | 20 | There are two types of BIO, a source/sink BIO and a filter BIO. |
47770c4d | 21 | |
1974a58f | 22 | As its name implies a source/sink BIO is a source and/or sink of data, |
47770c4d DSH |
23 | examples include a socket BIO and a file BIO. |
24 | ||
25 | A filter BIO takes data from one BIO and passes it through to | |
26 | another, or the application. The data may be left unmodified (for | |
27 | example a message digest BIO) or translated (for example an | |
28 | encryption BIO). The effect of a filter BIO may change according | |
29 | to the I/O operation it is performing: for example an encryption | |
30 | BIO will encrypt data if it is being written to and decrypt data | |
31 | if it is being read from. | |
32 | ||
33 | BIOs can be joined together to form a chain (a single BIO is a chain | |
1ee1a169 | 34 | with one component). A chain normally consists of one source/sink |
47770c4d | 35 | BIO and one or more filter BIOs. Data read from or written to the |
5fd0cd9a | 36 | first BIO then traverses the chain to the end (normally a source/sink |
47770c4d DSH |
37 | BIO). |
38 | ||
53934822 RS |
39 | Some BIOs (such as memory BIOs) can be used immediately after calling |
40 | BIO_new(). Others (such as file BIOs) need some additional initialization, | |
41 | and frequently a utility function exists to create and initialize such BIOs. | |
42 | ||
43 | If BIO_free() is called on a BIO chain it will only free one BIO resulting | |
44 | in a memory leak. | |
45 | ||
631c37be DB |
46 | Calling BIO_free_all() on a single BIO has the same effect as calling |
47 | BIO_free() on it other than the discarded return value. | |
53934822 | 48 | |
dfabee82 | 49 | Normally the I<type> argument is supplied by a function which returns a |
53934822 | 50 | pointer to a BIO_METHOD. There is a naming convention for such functions: |
57cd10dd | 51 | a source/sink BIO typically starts with I<BIO_s_> and |
e8769719 | 52 | a filter BIO with I<BIO_f_>. |
53934822 | 53 | |
a3e53d56 TS |
54 | =head2 TCP Fast Open |
55 | ||
56 | TCP Fast Open (RFC7413), abbreviated "TFO", is supported by the BIO | |
45ada6b9 | 57 | interface since OpenSSL 3.2. TFO is supported in the following operating systems: |
a3e53d56 TS |
58 | |
59 | =over 4 | |
60 | ||
61 | =item * Linux kernel 3.13 and later, where TFO is enabled by default. | |
62 | ||
63 | =item * Linux kernel 4.11 and later, using TCP_FASTOPEN_CONNECT. | |
64 | ||
65 | =item * FreeBSD 10.3 to 11.4, supports server TFO only. | |
66 | ||
67 | =item * FreeBSD 12.0 and later, supports both client and server TFO. | |
68 | ||
69 | =item * macOS 10.14 and later. | |
70 | ||
71 | =back | |
72 | ||
73 | Each operating system has a slightly different API for TFO. Please | |
74 | refer to the operating systems' API documentation when using | |
75 | sockets directly. | |
76 | ||
cda77422 | 77 | =head1 EXAMPLES |
53934822 RS |
78 | |
79 | Create a memory BIO: | |
80 | ||
81 | BIO *mem = BIO_new(BIO_s_mem()); | |
82 | ||
47770c4d DSH |
83 | =head1 SEE ALSO |
84 | ||
9b86974e RS |
85 | L<BIO_ctrl(3)>, |
86 | L<BIO_f_base64(3)>, L<BIO_f_buffer(3)>, | |
87 | L<BIO_f_cipher(3)>, L<BIO_f_md(3)>, | |
88 | L<BIO_f_null(3)>, L<BIO_f_ssl(3)>, | |
a30823c8 | 89 | L<BIO_f_readbuffer(3)>, |
a3e53d56 TS |
90 | L<BIO_find_type(3)>, |
91 | L<BIO_get_conn_mode(3)>, | |
92 | L<BIO_new(3)>, | |
9b86974e | 93 | L<BIO_new_bio_pair(3)>, |
b055fceb | 94 | L<BIO_push(3)>, L<BIO_read_ex(3)>, |
9b86974e RS |
95 | L<BIO_s_accept(3)>, L<BIO_s_bio(3)>, |
96 | L<BIO_s_connect(3)>, L<BIO_s_fd(3)>, | |
97 | L<BIO_s_file(3)>, L<BIO_s_mem(3)>, | |
9b86974e RS |
98 | L<BIO_s_null(3)>, L<BIO_s_socket(3)>, |
99 | L<BIO_set_callback(3)>, | |
a3e53d56 TS |
100 | L<BIO_set_conn_mode(3)>, |
101 | L<BIO_set_tfo(3)>, | |
102 | L<BIO_set_tfo_accept(3)>, | |
9b86974e | 103 | L<BIO_should_retry(3)> |
99ec4fdb | 104 | |
e2f92610 RS |
105 | =head1 COPYRIGHT |
106 | ||
fecb3aae | 107 | Copyright 2000-2022 The OpenSSL Project Authors. All Rights Reserved. |
e2f92610 | 108 | |
3187791e | 109 | Licensed under the Apache License 2.0 (the "License"). You may not use |
e2f92610 RS |
110 | this file except in compliance with the License. You can obtain a copy |
111 | in the file LICENSE in the source distribution or at | |
112 | L<https://www.openssl.org/source/license.html>. | |
113 | ||
114 | =cut |