]>
Commit | Line | Data |
---|---|---|
18f22594 DSH |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
1bc74519 | 5 | BIO_s_bio, BIO_make_bio_pair, BIO_destroy_bio_pair, BIO_shutdown_wr, |
2c281ebb DSH |
6 | BIO_set_write_buf_size, BIO_get_write_buf_size, BIO_new_bio_pair, |
7 | BIO_get_write_guarantee, BIO_ctrl_get_write_guarantee, BIO_get_read_request, | |
8 | BIO_ctrl_get_read_request, BIO_ctrl_reset_read_request - BIO pair BIO | |
18f22594 DSH |
9 | |
10 | =head1 SYNOPSIS | |
11 | ||
12 | #include <openssl/bio.h> | |
13 | ||
04f6b0fd | 14 | const BIO_METHOD *BIO_s_bio(void); |
18f22594 | 15 | |
91da5e77 RS |
16 | int BIO_make_bio_pair(BIO *b1, BIO *b2); |
17 | int BIO_destroy_bio_pair(BIO *b); | |
18 | int BIO_shutdown_wr(BIO *b); | |
18f22594 | 19 | |
91da5e77 RS |
20 | int BIO_set_write_buf_size(BIO *b, long size); |
21 | size_t BIO_get_write_buf_size(BIO *b, long size); | |
18f22594 DSH |
22 | |
23 | int BIO_new_bio_pair(BIO **bio1, size_t writebuf1, BIO **bio2, size_t writebuf2); | |
24 | ||
91da5e77 | 25 | int BIO_get_write_guarantee(BIO *b); |
18f22594 | 26 | size_t BIO_ctrl_get_write_guarantee(BIO *b); |
91da5e77 | 27 | int BIO_get_read_request(BIO *b); |
18f22594 | 28 | size_t BIO_ctrl_get_read_request(BIO *b); |
18f22594 DSH |
29 | int BIO_ctrl_reset_read_request(BIO *b); |
30 | ||
31 | =head1 DESCRIPTION | |
32 | ||
33 | BIO_s_bio() returns the method for a BIO pair. A BIO pair is a pair of source/sink | |
34 | BIOs where data written to either half of the pair is buffered and can be read from | |
e39c1943 BM |
35 | the other half. Both halves must usually by handled by the same application thread |
36 | since no locking is done on the internal data structures. | |
18f22594 DSH |
37 | |
38 | Since BIO chains typically end in a source/sink BIO it is possible to make this | |
39 | one half of a BIO pair and have all the data processed by the chain under application | |
40 | control. | |
41 | ||
e39c1943 BM |
42 | One typical use of BIO pairs is to place TLS/SSL I/O under application control, this |
43 | can be used when the application wishes to use a non standard transport for | |
44 | TLS/SSL or the normal socket routines are inappropriate. | |
18f22594 | 45 | |
b055fceb | 46 | Calls to BIO_read_ex() will read data from the buffer or request a retry if no |
18f22594 DSH |
47 | data is available. |
48 | ||
b055fceb | 49 | Calls to BIO_write_ex() will place data in the buffer or request a retry if the |
18f22594 DSH |
50 | buffer is full. |
51 | ||
52 | The standard calls BIO_ctrl_pending() and BIO_ctrl_wpending() can be used to | |
53 | determine the amount of pending data in the read or write buffer. | |
54 | ||
55 | BIO_reset() clears any data in the write buffer. | |
56 | ||
57 | BIO_make_bio_pair() joins two separate BIOs into a connected pair. | |
58 | ||
59 | BIO_destroy_pair() destroys the association between two connected BIOs. Freeing | |
e39c1943 | 60 | up any half of the pair will automatically destroy the association. |
18f22594 | 61 | |
07fcf422 | 62 | BIO_shutdown_wr() is used to close down a BIO B<b>. After this call no further |
2c281ebb DSH |
63 | writes on BIO B<b> are allowed (they will return an error). Reads on the other |
64 | half of the pair will return any pending data or EOF when all pending data has | |
1bc74519 | 65 | been read. |
2c281ebb | 66 | |
18f22594 | 67 | BIO_set_write_buf_size() sets the write buffer size of BIO B<b> to B<size>. |
1e4e5492 | 68 | If the size is not initialized a default value is used. This is currently |
18f22594 DSH |
69 | 17K, sufficient for a maximum size TLS record. |
70 | ||
71 | BIO_get_write_buf_size() returns the size of the write buffer. | |
72 | ||
73 | BIO_new_bio_pair() combines the calls to BIO_new(), BIO_make_bio_pair() and | |
74 | BIO_set_write_buf_size() to create a connected pair of BIOs B<bio1>, B<bio2> | |
75 | with write buffer sizes B<writebuf1> and B<writebuf2>. If either size is | |
18be6c41 RL |
76 | zero then the default size is used. BIO_new_bio_pair() does not check whether |
77 | B<bio1> or B<bio2> do point to some other BIO, the values are overwritten, | |
78 | BIO_free() is not called. | |
18f22594 | 79 | |
1e4e5492 | 80 | BIO_get_write_guarantee() and BIO_ctrl_get_write_guarantee() return the maximum |
18f22594 | 81 | length of data that can be currently written to the BIO. Writes larger than this |
b055fceb MC |
82 | value will return a value from BIO_write_ex() less than the amount requested or |
83 | if the buffer is full request a retry. BIO_ctrl_get_write_guarantee() is a | |
84 | function whereas BIO_get_write_guarantee() is a macro. | |
18f22594 | 85 | |
c1629c9e BM |
86 | BIO_get_read_request() and BIO_ctrl_get_read_request() return the |
87 | amount of data requested, or the buffer size if it is less, if the | |
88 | last read attempt at the other half of the BIO pair failed due to an | |
89 | empty buffer. This can be used to determine how much data should be | |
90 | written to the BIO so the next read will succeed: this is most useful | |
91 | in TLS/SSL applications where the amount of data read is usually | |
92 | meaningful rather than just a buffer size. After a successful read | |
93 | this call will return zero. It also will return zero once new data | |
94 | has been written satisfying the read request or part of it. | |
95 | Note that BIO_get_read_request() never returns an amount larger | |
96 | than that returned by BIO_get_write_guarantee(). | |
18f22594 DSH |
97 | |
98 | BIO_ctrl_reset_read_request() can also be used to reset the value returned by | |
99 | BIO_get_read_request() to zero. | |
100 | ||
101 | =head1 NOTES | |
102 | ||
1e4e5492 | 103 | Both halves of a BIO pair should be freed. That is even if one half is implicit |
18f22594 DSH |
104 | freed due to a BIO_free_all() or SSL_free() call the other half needs to be freed. |
105 | ||
e39c1943 | 106 | When used in bidirectional applications (such as TLS/SSL) care should be taken to |
18f22594 DSH |
107 | flush any data in the write buffer. This can be done by calling BIO_pending() |
108 | on the other half of the pair and, if any data is pending, reading it and sending | |
109 | it to the underlying transport. This must be done before any normal processing | |
110 | (such as calling select() ) due to a request and BIO_should_read() being true. | |
111 | ||
112 | To see why this is important consider a case where a request is sent using | |
b055fceb MC |
113 | BIO_write_ex() and a response read with BIO_read_ex(), this can occur during an |
114 | TLS/SSL handshake for example. BIO_write_ex() will succeed and place data in the | |
115 | write buffer. BIO_read_ex() will initially fail and BIO_should_read() will be | |
116 | true. If the application then waits for data to be available on the underlying | |
117 | transport before flushing the write buffer it will never succeed because the | |
118 | request was never sent! | |
18f22594 | 119 | |
3105d695 MC |
120 | BIO_eof() is true if no data is in the peer BIO and the peer BIO has been |
121 | shutdown. | |
122 | ||
91da5e77 RS |
123 | BIO_make_bio_pair(), BIO_destroy_bio_pair(), BIO_shutdown_wr(), |
124 | BIO_set_write_buf_size(), BIO_get_write_buf_size(), | |
125 | BIO_get_write_guarantee(), and BIO_get_read_request() are implemented | |
126 | as macros. | |
127 | ||
18be6c41 RL |
128 | =head1 RETURN VALUES |
129 | ||
130 | BIO_new_bio_pair() returns 1 on success, with the new BIOs available in | |
131 | B<bio1> and B<bio2>, or 0 on failure, with NULL pointers stored into the | |
132 | locations for B<bio1> and B<bio2>. Check the error stack for more information. | |
133 | ||
edd55d08 | 134 | [XXXXX: More return values need to be added here] |
18be6c41 | 135 | |
18f22594 DSH |
136 | =head1 EXAMPLE |
137 | ||
18be6c41 RL |
138 | The BIO pair can be used to have full control over the network access of an |
139 | application. The application can call select() on the socket as required | |
140 | without having to go through the SSL-interface. | |
141 | ||
142 | BIO *internal_bio, *network_bio; | |
e9b77246 | 143 | |
18be6c41 | 144 | ... |
c03726ca | 145 | BIO_new_bio_pair(&internal_bio, 0, &network_bio, 0); |
18be6c41 | 146 | SSL_set_bio(ssl, internal_bio, internal_bio); |
95dd5fb2 | 147 | SSL_operations(); /* e.g SSL_read and SSL_write */ |
18be6c41 RL |
148 | ... |
149 | ||
150 | application | TLS-engine | |
151 | | | | |
152 | +----------> SSL_operations() | |
153 | | /\ || | |
154 | | || \/ | |
155 | | BIO-pair (internal_bio) | |
c03726ca RS |
156 | | BIO-pair (network_bio) |
157 | | || /\ | |
158 | | \/ || | |
159 | +-----------< BIO_operations() | |
18be6c41 | 160 | | | |
c03726ca RS |
161 | | | |
162 | socket | |
18be6c41 RL |
163 | |
164 | ... | |
1bc74519 | 165 | SSL_free(ssl); /* implicitly frees internal_bio */ |
18be6c41 RL |
166 | BIO_free(network_bio); |
167 | ... | |
168 | ||
169 | As the BIO pair will only buffer the data and never directly access the | |
170 | connection, it behaves non-blocking and will return as soon as the write | |
171 | buffer is full or the read buffer is drained. Then the application has to | |
172 | flush the write buffer and/or fill the read buffer. | |
173 | ||
174 | Use the BIO_ctrl_pending(), to find out whether data is buffered in the BIO | |
186bb907 | 175 | and must be transferred to the network. Use BIO_ctrl_get_read_request() to |
18be6c41 RL |
176 | find out, how many bytes must be written into the buffer before the |
177 | SSL_operation() can successfully be continued. | |
178 | ||
179 | =head1 WARNING | |
180 | ||
b9b6a7e5 | 181 | As the data is buffered, SSL_operation() may return with an ERROR_SSL_WANT_READ |
18be6c41 RL |
182 | condition, but there is still data in the write buffer. An application must |
183 | not rely on the error value of SSL_operation() but must assure that the | |
184 | write buffer is always flushed first. Otherwise a deadlock may occur as | |
185 | the peer might be waiting for the data before being able to continue. | |
18f22594 DSH |
186 | |
187 | =head1 SEE ALSO | |
188 | ||
b97fdb57 | 189 | L<SSL_set_bio(3)>, L<ssl(7)>, L<bio(7)>, |
b055fceb | 190 | L<BIO_should_retry(3)>, L<BIO_read_ex(3)> |
18f22594 | 191 | |
e2f92610 RS |
192 | =head1 COPYRIGHT |
193 | ||
194 | Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. | |
195 | ||
4746f25a | 196 | Licensed under the Apache License 2.0 (the "License"). You may not use |
e2f92610 RS |
197 | this file except in compliance with the License. You can obtain a copy |
198 | in the file LICENSE in the source distribution or at | |
199 | L<https://www.openssl.org/source/license.html>. | |
200 | ||
201 | =cut |