1 =pod 2 3 =head1 NAME 4 5 BIO_s_bio, BIO_make_bio_pair, BIO_destroy_bio_pair, BIO_shutdown_wr, 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, 9 BIO_nread0, BIO_nread, BIO_nwrite0, BIO_nwrite - BIO pair BIO 10 11 =head1 SYNOPSIS 12 13 #include <openssl/bio.h> 14 15 const BIO_METHOD *BIO_s_bio(void); 16 17 int BIO_make_bio_pair(BIO *b1, BIO *b2); 18 int BIO_destroy_bio_pair(BIO *b); 19 int BIO_shutdown_wr(BIO *b); 20 21 int BIO_set_write_buf_size(BIO *b, long size); 22 size_t BIO_get_write_buf_size(BIO *b, long size); 23 24 int BIO_new_bio_pair(BIO **bio1, size_t writebuf1, BIO **bio2, size_t writebuf2); 25 26 int BIO_get_write_guarantee(BIO *b); 27 size_t BIO_ctrl_get_write_guarantee(BIO *b); 28 int BIO_get_read_request(BIO *b); 29 size_t BIO_ctrl_get_read_request(BIO *b); 30 int BIO_ctrl_reset_read_request(BIO *b); 31 32 int BIO_nread0(BIO *bio, char **buf); 33 int BIO_nread(BIO *bio, char **buf, int num); 34 int BIO_nwrite0(BIO *bio, char **buf); 35 int BIO_nwrite(BIO *bio, char **buf, int num); 36 37 =head1 DESCRIPTION 38 39 BIO_s_bio() returns the method for a BIO pair. A BIO pair is a pair of source/sink 40 BIOs where data written to either half of the pair is buffered and can be read from 41 the other half. Both halves must usually by handled by the same application thread 42 since no locking is done on the internal data structures. 43 44 Since BIO chains typically end in a source/sink BIO it is possible to make this 45 one half of a BIO pair and have all the data processed by the chain under application 46 control. 47 48 One typical use of BIO pairs is to place TLS/SSL I/O under application control, this 49 can be used when the application wishes to use a non standard transport for 50 TLS/SSL or the normal socket routines are inappropriate. 51 52 Calls to BIO_read_ex() will read data from the buffer or request a retry if no 53 data is available. 54 55 Calls to BIO_write_ex() will place data in the buffer or request a retry if the 56 buffer is full. 57 58 The standard calls BIO_ctrl_pending() and BIO_ctrl_wpending() can be used to 59 determine the amount of pending data in the read or write buffer. 60 61 BIO_reset() clears any data in the write buffer. 62 63 BIO_make_bio_pair() joins two separate BIOs into a connected pair. 64 65 BIO_destroy_pair() destroys the association between two connected BIOs. Freeing 66 up any half of the pair will automatically destroy the association. 67 68 BIO_shutdown_wr() is used to close down a BIO B<b>. After this call no further 69 writes on BIO B<b> are allowed (they will return an error). Reads on the other 70 half of the pair will return any pending data or EOF when all pending data has 71 been read. 72 73 BIO_set_write_buf_size() sets the write buffer size of BIO B<b> to B<size>. 74 If the size is not initialized a default value is used. This is currently 75 17K, sufficient for a maximum size TLS record. 76 77 BIO_get_write_buf_size() returns the size of the write buffer. 78 79 BIO_new_bio_pair() combines the calls to BIO_new(), BIO_make_bio_pair() and 80 BIO_set_write_buf_size() to create a connected pair of BIOs B<bio1>, B<bio2> 81 with write buffer sizes B<writebuf1> and B<writebuf2>. If either size is 82 zero then the default size is used. BIO_new_bio_pair() does not check whether 83 B<bio1> or B<bio2> do point to some other BIO, the values are overwritten, 84 BIO_free() is not called. 85 86 BIO_get_write_guarantee() and BIO_ctrl_get_write_guarantee() return the maximum 87 length of data that can be currently written to the BIO. Writes larger than this 88 value will return a value from BIO_write_ex() less than the amount requested or 89 if the buffer is full request a retry. BIO_ctrl_get_write_guarantee() is a 90 function whereas BIO_get_write_guarantee() is a macro. 91 92 BIO_get_read_request() and BIO_ctrl_get_read_request() return the 93 amount of data requested, or the buffer size if it is less, if the 94 last read attempt at the other half of the BIO pair failed due to an 95 empty buffer. This can be used to determine how much data should be 96 written to the BIO so the next read will succeed: this is most useful 97 in TLS/SSL applications where the amount of data read is usually 98 meaningful rather than just a buffer size. After a successful read 99 this call will return zero. It also will return zero once new data 100 has been written satisfying the read request or part of it. 101 Note that BIO_get_read_request() never returns an amount larger 102 than that returned by BIO_get_write_guarantee(). 103 104 BIO_ctrl_reset_read_request() can also be used to reset the value returned by 105 BIO_get_read_request() to zero. 106 107 =head2 Non-copying Interface 108 109 BIO_nread0(), BIO_nread(), BIO_nwrite0(), and BIO_nwrite() provide a non-copying 110 interface for reading from and writing to BIO pairs. These functions allow 111 direct access to the internal buffer, avoiding the overhead of copying data. 112 113 BIO_nread0() returns in B<*buf> a pointer to the start of the available data 114 in the peer's write buffer and returns the number of bytes available. 115 This allows reading directly from the buffer without copying. 116 It does not consume the data; a subsequent call to BIO_nread() is needed 117 to advance the buffer position. 118 119 BIO_nread() is similar to BIO_nread0() but also advances the read position 120 by up to B<num> bytes. The actual number of bytes consumed is returned. 121 The B<*buf> pointer is set to the start of the data that was consumed. 122 Since the data is considered consumed after this call, the pointer returned 123 by BIO_nread() should not be used afterwards unless the caller also 124 controls the writing side. The typical pattern is to call BIO_nread0() first, 125 use the data, and then call BIO_nread() to consume it. 126 127 BIO_nwrite0() returns in B<*buf> a pointer to the start of the available 128 space in the write buffer and returns the number of bytes that can be written. 129 This allows writing directly to the buffer without copying. 130 It does not commit the data; a subsequent call to BIO_nwrite() is needed 131 to update the buffer length. 132 133 BIO_nwrite() is similar to BIO_nwrite0() but also commits up to B<num> bytes 134 as written. The actual number of bytes committed is returned. 135 The B<*buf> pointer is set to the start of the region that was committed. 136 BIO_nwrite() should only be called after the data has actually been written 137 to the buffer obtained from BIO_nwrite0(), since committing signals data 138 availability to the reading side. 139 140 Note that due to the ring buffer implementation, if wrapping around would be 141 required, BIO_nread0() and BIO_nwrite0() may return less than the total 142 available space. In such cases, a second call may be needed to access the 143 remaining data or space. 144 145 =head1 NOTES 146 147 Both halves of a BIO pair should be freed. That is even if one half is implicit 148 freed due to a BIO_free_all() or SSL_free() call the other half needs to be freed. 149 150 When used in bidirectional applications (such as TLS/SSL) care should be taken to 151 flush any data in the write buffer. This can be done by calling BIO_pending() 152 on the other half of the pair and, if any data is pending, reading it and sending 153 it to the underlying transport. This must be done before any normal processing 154 (such as calling select() ) due to a request and BIO_should_read() being true. 155 156 To see why this is important consider a case where a request is sent using 157 BIO_write_ex() and a response read with BIO_read_ex(), this can occur during an 158 TLS/SSL handshake for example. BIO_write_ex() will succeed and place data in the 159 write buffer. BIO_read_ex() will initially fail and BIO_should_read() will be 160 true. If the application then waits for data to be available on the underlying 161 transport before flushing the write buffer it will never succeed because the 162 request was never sent! 163 164 BIO_eof() is true if no data is in the peer BIO and the peer BIO has been 165 shutdown. 166 167 BIO_make_bio_pair(), BIO_destroy_bio_pair(), BIO_shutdown_wr(), 168 BIO_set_write_buf_size(), BIO_get_write_buf_size(), 169 BIO_get_write_guarantee(), and BIO_get_read_request() are implemented 170 as macros. 171 172 =head1 RETURN VALUES 173 174 BIO_new_bio_pair() returns 1 on success, with the new BIOs available in 175 B<bio1> and B<bio2>, or 0 on failure, with NULL pointers stored into the 176 locations for B<bio1> and B<bio2>. Check the error stack for more information. 177 178 [XXXXX: More return values need to be added here] 179 180 BIO_nread0() returns the number of bytes available for reading, 0 if the peer 181 has closed and no data remains (EOF), or -1 if no data is currently available 182 (retry may be appropriate). If the BIO is not initialized, -2 is returned. 183 184 BIO_nwrite0() returns the number of bytes of space available for writing, or -1 185 if no space is currently available (retry may be appropriate) or the BIO has 186 been closed. If the BIO is not initialized, -2 is returned. 187 188 BIO_nread() and BIO_nwrite() return the number of bytes consumed or committed 189 respectively, or the same error values as BIO_nread0() and BIO_nwrite0(). 190 191 =head1 EXAMPLES 192 193 The BIO pair can be used to have full control over the network access of an 194 application. The application can call select() on the socket as required 195 without having to go through the SSL-interface. 196 197 BIO *internal_bio, *network_bio; 198 199 ... 200 BIO_new_bio_pair(&internal_bio, 0, &network_bio, 0); 201 SSL_set_bio(ssl, internal_bio, internal_bio); 202 SSL_operations(); /* e.g. SSL_read and SSL_write */ 203 ... 204 205 application | TLS-engine 206 | | 207 +----------> SSL_operations() 208 | /\ || 209 | || \/ 210 | BIO-pair (internal_bio) 211 | BIO-pair (network_bio) 212 | || /\ 213 | \/ || 214 +-----------< BIO_operations() 215 | | 216 | | 217 socket 218 219 ... 220 SSL_free(ssl); /* implicitly frees internal_bio */ 221 BIO_free(network_bio); 222 ... 223 224 As the BIO pair will only buffer the data and never directly access the 225 connection, it behaves nonblocking and will return as soon as the write 226 buffer is full or the read buffer is drained. Then the application has to 227 flush the write buffer and/or fill the read buffer. 228 229 Use the BIO_ctrl_pending(), to find out whether data is buffered in the BIO 230 and must be transferred to the network. Use BIO_ctrl_get_read_request() to 231 find out, how many bytes must be written into the buffer before the 232 SSL_operation() can successfully be continued. 233 234 A typical usage pattern for the non-copying write interface is: 235 236 int ret; 237 char *buf; 238 239 ret = BIO_nwrite0(bio, &buf); 240 if (ret > 0) { 241 /* write up to 'ret' bytes directly to 'buf' */ 242 memcpy(buf, data, len); 243 BIO_nwrite(bio, &buf, len); /* commit the write */ 244 } 245 246 A typical usage pattern for the non-copying read interface is: 247 248 int ret; 249 char *buf; 250 251 ret = BIO_nread0(bio, &buf); 252 if (ret > 0) { 253 /* read up to 'ret' bytes directly from 'buf' */ 254 process_data(buf, ret); 255 BIO_nread(bio, &buf, ret); /* consume the data */ 256 } 257 258 =head1 WARNINGS 259 260 As the data is buffered, SSL_operation() may return with an ERROR_SSL_WANT_READ 261 condition, but there is still data in the write buffer. An application must 262 not rely on the error value of SSL_operation() but must assure that the 263 write buffer is always flushed first. Otherwise a deadlock may occur as 264 the peer might be waiting for the data before being able to continue. 265 266 =head1 SEE ALSO 267 268 L<SSL_set_bio(3)>, L<ssl(7)>, L<bio(7)>, 269 L<BIO_should_retry(3)>, L<BIO_read_ex(3)> 270 271 =head1 COPYRIGHT 272 273 Copyright 2000-2026 The OpenSSL Project Authors. All Rights Reserved. 274 275 Licensed under the Apache License 2.0 (the "License"). You may not use 276 this file except in compliance with the License. You can obtain a copy 277 in the file LICENSE in the source distribution or at 278 L<https://www.openssl.org/source/license.html>. 279 280 =cut 281
Indexes created Sat Jun 27 00:24:51 UTC 2026