| blob | 065a8bae08e146abdc9d68050b3798133c38c97e |
1 .\" $OpenBSD: BIO_s_bio.3,v 1.9 2017/01/06 02:29:18 schwarze Exp $
2 .\" OpenSSL c03726ca Aug 27 12:28:08 2015 -0400
3 .\"
4 .\" This file was written by
5 .\" Lutz Jaenicke <Lutz.Jaenicke@aet.TU-Cottbus.DE>,
6 .\" Dr. Stephen Henson <steve@openssl.org>,
7 .\" Bodo Moeller <bodo@openssl.org>,
8 .\" and Richard Levitte <levitte@openssl.org>.
9 .\" Copyright (c) 2000, 2002, 2015, 2016 The OpenSSL Project.
10 .\" All rights reserved.
11 .\"
12 .\" Redistribution and use in source and binary forms, with or without
13 .\" modification, are permitted provided that the following conditions
14 .\" are met:
15 .\"
16 .\" 1. Redistributions of source code must retain the above copyright
17 .\" notice, this list of conditions and the following disclaimer.
18 .\"
19 .\" 2. Redistributions in binary form must reproduce the above copyright
20 .\" notice, this list of conditions and the following disclaimer in
21 .\" the documentation and/or other materials provided with the
22 .\" distribution.
23 .\"
24 .\" 3. All advertising materials mentioning features or use of this
25 .\" software must display the following acknowledgment:
26 .\" "This product includes software developed by the OpenSSL Project
27 .\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
28 .\"
29 .\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
30 .\" endorse or promote products derived from this software without
31 .\" prior written permission. For written permission, please contact
32 .\" openssl-core@openssl.org.
33 .\"
34 .\" 5. Products derived from this software may not be called "OpenSSL"
35 .\" nor may "OpenSSL" appear in their names without prior written
36 .\" permission of the OpenSSL Project.
37 .\"
38 .\" 6. Redistributions of any form whatsoever must retain the following
39 .\" acknowledgment:
40 .\" "This product includes software developed by the OpenSSL Project
41 .\" for use in the OpenSSL Toolkit (http://www.openssl.org/)"
42 .\"
43 .\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
44 .\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
45 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
46 .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR
47 .\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
48 .\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
49 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
50 .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
51 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
52 .\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
53 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
54 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
55 .\"
56 .Dd $Mdocdate: January 6 2017 $
57 .Dt BIO_S_BIO 3
58 .Os
59 .Sh NAME
60 .Nm BIO_s_bio ,
61 .Nm BIO_make_bio_pair ,
62 .Nm BIO_destroy_bio_pair ,
63 .Nm BIO_shutdown_wr ,
64 .Nm BIO_set_write_buf_size ,
65 .Nm BIO_get_write_buf_size ,
66 .Nm BIO_new_bio_pair ,
67 .Nm BIO_get_write_guarantee ,
68 .Nm BIO_ctrl_get_write_guarantee ,
69 .Nm BIO_get_read_request ,
70 .Nm BIO_ctrl_get_read_request ,
71 .Nm BIO_ctrl_reset_read_request
72 .Nd BIO pair BIO
73 .Sh SYNOPSIS
74 .In openssl/bio.h
75 .Ft BIO_METHOD *
76 .Fo BIO_s_bio
77 .Fa void
78 .Fc
79 .Ft int
80 .Fo BIO_make_bio_pair
81 .Fa "BIO *b1"
82 .Fa "BIO *b2"
83 .Fc
84 .Ft int
85 .Fo BIO_destroy_bio_pair
86 .Fa "BIO *b"
87 .Fc
88 .Ft int
89 .Fo BIO_shutdown_wr
90 .Fa "BIO *b"
91 .Fc
92 .Ft int
93 .Fo BIO_set_write_buf_size
94 .Fa "BIO *b"
95 .Fa "long size"
96 .Fc
97 .Ft size_t
98 .Fo BIO_get_write_buf_size
99 .Fa "BIO *b"
100 .Fa "long size"
101 .Fc
102 .Ft int
103 .Fo BIO_new_bio_pair
104 .Fa "BIO **bio1"
105 .Fa "size_t writebuf1"
106 .Fa "BIO **bio2"
107 .Fa "size_t writebuf2"
108 .Fc
109 .Ft size_t
110 .Fo BIO_get_write_guarantee
111 .Fa "BIO *b"
112 .Fc
113 .Ft size_t
114 .Fo BIO_ctrl_get_write_guarantee
115 .Fa "BIO *b"
116 .Fc
117 .Ft int
118 .Fo BIO_get_read_request
119 .Fa "BIO *b"
120 .Fc
121 .Ft size_t
122 .Fo BIO_ctrl_get_read_request
123 .Fa "BIO *b"
124 .Fc
125 .Ft int
126 .Fo BIO_ctrl_reset_read_request
127 .Fa "BIO *b"
128 .Fc
129 .Sh DESCRIPTION
130 .Fn BIO_s_bio
131 returns the method for a BIO pair.
132 A BIO pair is a pair of source/sink BIOs where data written to either
133 half of the pair is buffered and can be read from the other half.
134 Both halves must usually be handled by the same application thread
135 since no locking is done on the internal data structures.
136 .Pp
137 Since BIO chains typically end in a source/sink BIO,
138 it is possible to make this one half of a BIO pair and
139 have all the data processed by the chain under application control.
140 .Pp
141 One typical use of BIO pairs is
142 to place TLS/SSL I/O under application control.
143 This can be used when the application wishes to use a non-standard
144 transport for TLS/SSL or the normal socket routines are inappropriate.
145 .Pp
146 Calls to
147 .Xr BIO_read 3
148 will read data from the buffer or request a retry if no data is available.
149 .Pp
150 Calls to
151 .Xr BIO_write 3
152 will place data in the buffer or request a retry if the buffer is full.
153 .Pp
154 The standard calls
155 .Xr BIO_ctrl_pending 3
156 and
157 .Xr BIO_ctrl_wpending 3
158 can be used to determine the amount of pending data
159 in the read or write buffer.
160 .Pp
161 .Xr BIO_reset 3
162 clears any data in the write buffer.
163 .Pp
164 .Fn BIO_make_bio_pair
165 joins two separate BIOs into a connected pair.
166 .Pp
167 .Fn BIO_destroy_pair
168 destroys the association between two connected BIOs.
169 Freeing up any half of the pair will automatically destroy the association.
170 .Pp
171 .Fn BIO_shutdown_wr
172 is used to close down a BIO
173 .Fa b .
174 After this call no further writes on BIO
175 .Fa b
176 are allowed; they will return an error.
177 Reads on the other half of the pair will return any pending data
178 or EOF when all pending data has been read.
179 .Pp
180 .Fn BIO_set_write_buf_size
181 sets the write buffer size of BIO
182 .Fa b
183 to
184 .Fa size .
185 If the size is not initialized a default value is used.
186 This is currently 17K, sufficient for a maximum size TLS record.
187 .Pp
188 .Fn BIO_get_write_buf_size
189 returns the size of the write buffer.
190 .Pp
191 .Fn BIO_new_bio_pair
192 combines the calls to
193 .Xr BIO_new 3 ,
194 .Fn BIO_make_bio_pair
195 and
196 .Fn BIO_set_write_buf_size
197 to create a connected pair of BIOs
198 .Fa bio1
199 and
200 .Fa bio2
201 with write buffer sizes
202 .Fa writebuf1
203 and
204 .Fa writebuf2 .
205 If either size is zero, then the default size is used.
206 .Fn BIO_new_bio_pair
207 does not check whether
208 .Fa bio1
209 or
210 .Fa bio2
211 point to some other BIO; the values are overwritten and
212 .Xr BIO_free 3
213 is not called.
214 .Pp
215 .Fn BIO_get_write_guarantee
216 and
217 .Fn BIO_ctrl_get_write_guarantee
218 return the maximum length of data
219 that can be currently written to the BIO.
220 Writes larger than this value will return a value from
221 .Xr BIO_write 3
222 less than the amount requested or if the buffer is full request a retry.
223 .Fn BIO_ctrl_get_write_guarantee
224 is a function whereas
225 .Fn BIO_get_write_guarantee
226 is a macro.
227 .Pp
228 .Fn BIO_get_read_request
229 and
230 .Fn BIO_ctrl_get_read_request
231 return the amount of data requested, or the buffer size if it is less,
232 if the last read attempt at the other half of the BIO pair failed
233 due to an empty buffer.
234 This can be used to determine how much data should be
235 written to the BIO so the next read will succeed:
236 this is most useful in TLS/SSL applications where the amount of
237 data read is usually meaningful rather than just a buffer size.
238 After a successful read this call will return zero.
239 It also will return zero once new data has been written
240 satisfying the read request or part of it.
241 Note that
242 .Fn BIO_get_read_request
243 never returns an amount larger than that returned by
244 .Fn BIO_get_write_guarantee .
245 .Pp
246 .Fn BIO_ctrl_reset_read_request
247 can also be used to reset the value returned by
248 .Fn BIO_get_read_request
249 to zero.
250 .Pp
251 Both halves of a BIO pair should be freed.
252 Even if one half is implicitly freed due to a
253 .Xr BIO_free_all 3
254 or
255 .Xr SSL_free 3
256 call, the other half still needs to be freed.
257 .Pp
258 When used in bidirectional applications (such as TLS/SSL)
259 care should be taken to flush any data in the write buffer.
260 This can be done by calling
261 .Xr BIO_pending 3
262 on the other half of the pair and, if any data is pending,
263 reading it and sending it to the underlying transport.
264 This must be done before any normal processing (such as calling
265 .Xr select 2 )
266 due to a request and
267 .Xr BIO_should_read 3
268 being true.
269 .Pp
270 To see why this is important,
271 consider a case where a request is sent using
272 .Xr BIO_write 3
273 and a response read with
274 .Xr BIO_read 3 ,
275 this can occur during a TLS/SSL handshake for example.
276 .Xr BIO_write 3
277 will succeed and place data in the write buffer.
278 .Xr BIO_read 3
279 will initially fail and
280 .Xr BIO_should_read 3
281 will be true.
282 If the application then waits for data to become available
283 on the underlying transport before flushing the write buffer,
284 it will never succeed because the request was never sent.
285 .Pp
286 .Xr BIO_eof 3
287 is true if no data is in the peer BIO and the peer BIO has been shutdown.
288 .Pp
289 .Fn BIO_make_bio_pair ,
290 .Fn BIO_destroy_bio_pair ,
291 .Fn BIO_shutdown_wr ,
292 .Fn BIO_set_write_buf_size ,
293 .Fn BIO_get_write_buf_size ,
294 .Fn BIO_get_write_guarantee ,
295 and
296 .Fn BIO_get_read_request
297 are implemented as macros.
298 .Sh RETURN VALUES
299 .Fn BIO_new_bio_pair
300 returns 1 on success, with the new BIOs available in
301 .Fa bio1
302 and
303 .Fa bio2 ,
304 or 0 on failure, with NULL pointers stored into the locations for
305 .Fa bio1
306 and
307 .Fa bio2 .
308 Check the error stack for more information.
309 .\" XXX More return values need to be added here.
310 .Sh EXAMPLES
311 The BIO pair can be used to have full control
312 over the network access of an application.
313 The application can call
314 .Xr select 2
315 on the socket as required without having to go through the SSL interface.
316 .Bd -literal -offset 2n
317 BIO *internal_bio, *network_bio;
318 \&...
319 BIO_new_bio_pair(&internal_bio, 0, &network_bio, 0);
320 SSL_set_bio(ssl, internal_bio, internal_bio);
321 SSL_operations(); /* e.g. SSL_read() and SSL_write() */
322 \&...
324 application | TLS-engine
325 | |
326 +----------> SSL_operations()
327 | /\e ||
328 | || \e/
329 | BIO-pair (internal_bio)
330 | BIO-pair (network_bio)
331 | || /\e
332 | \e/ ||
333 +-----------< BIO_operations()
334 | |
335 socket |
337 \&...
338 SSL_free(ssl); /* implicitly frees internal_bio */
339 BIO_free(network_bio);
340 \&...
341 .Ed
342 .Pp
343 As the BIO pair will only buffer the data and never directly access
344 the connection, it behaves non-blocking and will return as soon as
345 the write buffer is full or the read buffer is drained.
346 Then the application has to flush the write buffer
347 and/or fill the read buffer.
348 .Pp
349 Use
350 .Xr BIO_ctrl_pending 3
351 to find out whether data is buffered in the BIO
352 and must be transferred to the network.
353 Use
354 .Fn BIO_ctrl_get_read_request
355 to find out how many bytes must be written into the buffer before the
356 SSL operations can successfully be continued.
357 .Sh SEE ALSO
358 .Xr BIO_new 3 ,
359 .Xr BIO_read 3 ,
360 .Xr BIO_should_retry 3 ,
361 .Xr ssl 3 ,
362 .Xr SSL_set_bio 3
363 .Sh CAVEATS
364 As the data is buffered, SSL operations may return with an
365 .Dv ERROR_SSL_WANT_READ
366 condition, but there is still data in the write buffer.
367 An application must not rely on the error value of the SSL operation
368 but must assure that the write buffer is always flushed first.
369 Otherwise a deadlock may occur as the peer might be waiting
370 for the data before being able to continue.