]>
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 | |
2c281ebb | 20 | |
91da5e77 RS |
21 | int BIO_set_write_buf_size(BIO *b, long size); |
22 | size_t BIO_get_write_buf_size(BIO *b, long size); | |
18f22594 DSH |
23 | |
24 | int BIO_new_bio_pair(BIO **bio1, size_t writebuf1, BIO **bio2, size_t writebuf2); | |
25 | ||
91da5e77 | 26 | int BIO_get_write_guarantee(BIO *b); |
18f22594 | 27 | size_t BIO_ctrl_get_write_guarantee(BIO *b); |
91da5e77 | 28 | int BIO_get_read_request(BIO *b); |
18f22594 | 29 | size_t BIO_ctrl_get_read_request(BIO *b); |
18f22594 DSH |
30 | int BIO_ctrl_reset_read_request(BIO *b); |
31 | ||
32 | =head1 DESCRIPTION | |
33 | ||
34 | BIO_s_bio() returns the method for a BIO pair. A BIO pair is a pair of source/sink | |
35 | BIOs where data written to either half of the pair is buffered and can be read from | |
e39c1943 BM |
36 | the other half. Both halves must usually by handled by the same application thread |
37 | since no locking is done on the internal data structures. | |
18f22594 DSH |
38 | |
39 | Since BIO chains typically end in a source/sink BIO it is possible to make this | |
40 | one half of a BIO pair and have all the data processed by the chain under application | |
41 | control. | |
42 | ||
e39c1943 BM |
43 | One typical use of BIO pairs is to place TLS/SSL I/O under application control, this |
44 | can be used when the application wishes to use a non standard transport for | |
45 | TLS/SSL or the normal socket routines are inappropriate. | |
18f22594 DSH |
46 | |
47 | Calls to BIO_read() will read data from the buffer or request a retry if no | |
48 | data is available. | |
49 | ||
50 | Calls to BIO_write() will place data in the buffer or request a retry if the | |
51 | buffer is full. | |
52 | ||
53 | The standard calls BIO_ctrl_pending() and BIO_ctrl_wpending() can be used to | |
54 | determine the amount of pending data in the read or write buffer. | |
55 | ||
56 | BIO_reset() clears any data in the write buffer. | |
57 | ||
58 | BIO_make_bio_pair() joins two separate BIOs into a connected pair. | |
59 | ||
60 | BIO_destroy_pair() destroys the association between two connected BIOs. Freeing | |
e39c1943 | 61 | up any half of the pair will automatically destroy the association. |
18f22594 | 62 | |
07fcf422 | 63 | BIO_shutdown_wr() is used to close down a BIO B<b>. After this call no further |
2c281ebb DSH |
64 | writes on BIO B<b> are allowed (they will return an error). Reads on the other |
65 | half of the pair will return any pending data or EOF when all pending data has | |
1bc74519 | 66 | been read. |
2c281ebb | 67 | |
18f22594 | 68 | BIO_set_write_buf_size() sets the write buffer size of BIO B<b> to B<size>. |
1e4e5492 | 69 | If the size is not initialized a default value is used. This is currently |
18f22594 DSH |
70 | 17K, sufficient for a maximum size TLS record. |
71 | ||
72 | BIO_get_write_buf_size() returns the size of the write buffer. | |
73 | ||
74 | BIO_new_bio_pair() combines the calls to BIO_new(), BIO_make_bio_pair() and | |
75 | BIO_set_write_buf_size() to create a connected pair of BIOs B<bio1>, B<bio2> | |
76 | with write buffer sizes B<writebuf1> and B<writebuf2>. If either size is | |
18be6c41 RL |
77 | zero then the default size is used. BIO_new_bio_pair() does not check whether |
78 | B<bio1> or B<bio2> do point to some other BIO, the values are overwritten, | |
79 | BIO_free() is not called. | |
18f22594 | 80 | |
1e4e5492 | 81 | BIO_get_write_guarantee() and BIO_ctrl_get_write_guarantee() return the maximum |
18f22594 DSH |
82 | length of data that can be currently written to the BIO. Writes larger than this |
83 | value will return a value from BIO_write() less than the amount requested or if the | |
84 | buffer is full request a retry. BIO_ctrl_get_write_guarantee() is a function | |
85 | whereas BIO_get_write_guarantee() is a macro. | |
86 | ||
c1629c9e BM |
87 | BIO_get_read_request() and BIO_ctrl_get_read_request() return the |
88 | amount of data requested, or the buffer size if it is less, if the | |
89 | last read attempt at the other half of the BIO pair failed due to an | |
90 | empty buffer. This can be used to determine how much data should be | |
91 | written to the BIO so the next read will succeed: this is most useful | |
92 | in TLS/SSL applications where the amount of data read is usually | |
93 | meaningful rather than just a buffer size. After a successful read | |
94 | this call will return zero. It also will return zero once new data | |
95 | has been written satisfying the read request or part of it. | |
96 | Note that BIO_get_read_request() never returns an amount larger | |
97 | than that returned by BIO_get_write_guarantee(). | |
18f22594 DSH |
98 | |
99 | BIO_ctrl_reset_read_request() can also be used to reset the value returned by | |
100 | BIO_get_read_request() to zero. | |
101 | ||
102 | =head1 NOTES | |
103 | ||
1e4e5492 | 104 | Both halves of a BIO pair should be freed. That is even if one half is implicit |
18f22594 DSH |
105 | freed due to a BIO_free_all() or SSL_free() call the other half needs to be freed. |
106 | ||
e39c1943 | 107 | When used in bidirectional applications (such as TLS/SSL) care should be taken to |
18f22594 DSH |
108 | flush any data in the write buffer. This can be done by calling BIO_pending() |
109 | on the other half of the pair and, if any data is pending, reading it and sending | |
110 | it to the underlying transport. This must be done before any normal processing | |
111 | (such as calling select() ) due to a request and BIO_should_read() being true. | |
112 | ||
113 | To see why this is important consider a case where a request is sent using | |
114 | BIO_write() and a response read with BIO_read(), this can occur during an | |
e39c1943 | 115 | TLS/SSL handshake for example. BIO_write() will succeed and place data in the write |
18f22594 DSH |
116 | buffer. BIO_read() will initially fail and BIO_should_read() will be true. If |
117 | the application then waits for data to be available on the underlying transport | |
1e4e5492 | 118 | before flushing the write buffer it will never succeed because the request was |
18f22594 DSH |
119 | never sent! |
120 | ||
3105d695 MC |
121 | BIO_eof() is true if no data is in the peer BIO and the peer BIO has been |
122 | shutdown. | |
123 | ||
91da5e77 RS |
124 | BIO_make_bio_pair(), BIO_destroy_bio_pair(), BIO_shutdown_wr(), |
125 | BIO_set_write_buf_size(), BIO_get_write_buf_size(), | |
126 | BIO_get_write_guarantee(), and BIO_get_read_request() are implemented | |
127 | as macros. | |
128 | ||
18be6c41 RL |
129 | =head1 RETURN VALUES |
130 | ||
131 | BIO_new_bio_pair() returns 1 on success, with the new BIOs available in | |
132 | B<bio1> and B<bio2>, or 0 on failure, with NULL pointers stored into the | |
133 | locations for B<bio1> and B<bio2>. Check the error stack for more information. | |
134 | ||
edd55d08 | 135 | [XXXXX: More return values need to be added here] |
18be6c41 | 136 | |
18f22594 DSH |
137 | =head1 EXAMPLE |
138 | ||
18be6c41 RL |
139 | The BIO pair can be used to have full control over the network access of an |
140 | application. The application can call select() on the socket as required | |
141 | without having to go through the SSL-interface. | |
142 | ||
143 | BIO *internal_bio, *network_bio; | |
144 | ... | |
c03726ca | 145 | BIO_new_bio_pair(&internal_bio, 0, &network_bio, 0); |
18be6c41 | 146 | SSL_set_bio(ssl, internal_bio, internal_bio); |
c03726ca | 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 | ||
9b86974e RS |
189 | L<SSL_set_bio(3)>, L<ssl(3)>, L<bio(3)>, |
190 | L<BIO_should_retry(3)>, L<BIO_read(3)> | |
18f22594 | 191 | |
e2f92610 RS |
192 | =head1 COPYRIGHT |
193 | ||
194 | Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. | |
195 | ||
196 | Licensed under the OpenSSL license (the "License"). You may not use | |
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 |