| 1 |
.\" -*- mode: troff; coding: utf-8 -*- |
| 2 |
.\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45) |
| 3 |
.\" |
| 4 |
.\" Standard preamble: |
| 5 |
.\" ======================================================================== |
| 6 |
.de Sp \" Vertical space (when we can't use .PP) |
| 7 |
.if t .sp .5v |
| 8 |
.if n .sp |
| 9 |
.. |
| 10 |
.de Vb \" Begin verbatim text |
| 11 |
.ft CW |
| 12 |
.nf |
| 13 |
.ne \\$1 |
| 14 |
.. |
| 15 |
.de Ve \" End verbatim text |
| 16 |
.ft R |
| 17 |
.fi |
| 18 |
.. |
| 19 |
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. |
| 20 |
.ie n \{\ |
| 21 |
. ds C` "" |
| 22 |
. ds C' "" |
| 23 |
'br\} |
| 24 |
.el\{\ |
| 25 |
. ds C` |
| 26 |
. ds C' |
| 27 |
'br\} |
| 28 |
.\" |
| 29 |
.\" Escape single quotes in literal strings from groff's Unicode transform. |
| 30 |
.ie \n(.g .ds Aq \(aq |
| 31 |
.el .ds Aq ' |
| 32 |
.\" |
| 33 |
.\" If the F register is >0, we'll generate index entries on stderr for |
| 34 |
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index |
| 35 |
.\" entries marked with X<> in POD. Of course, you'll have to process the |
| 36 |
.\" output yourself in some meaningful fashion. |
| 37 |
.\" |
| 38 |
.\" Avoid warning from groff about undefined register 'F'. |
| 39 |
.de IX |
| 40 |
.. |
| 41 |
.nr rF 0 |
| 42 |
.if \n(.g .if rF .nr rF 1 |
| 43 |
.if (\n(rF:(\n(.g==0)) \{\ |
| 44 |
. if \nF \{\ |
| 45 |
. de IX |
| 46 |
. tm Index:\\$1\t\\n%\t"\\$2" |
| 47 |
.. |
| 48 |
. if !\nF==2 \{\ |
| 49 |
. nr % 0 |
| 50 |
. nr F 2 |
| 51 |
. \} |
| 52 |
. \} |
| 53 |
.\} |
| 54 |
.rr rF |
| 55 |
.\" ======================================================================== |
| 56 |
.\" |
| 57 |
.IX Title "BIO_S_BIO 3SSL" |
| 58 |
.TH BIO_S_BIO 3SSL 2026-04-07 3.6.2 OpenSSL |
| 59 |
.\" For nroff, turn off justification. Always turn off hyphenation; it makes |
| 60 |
.\" way too many mistakes in technical documents. |
| 61 |
.if n .ad l |
| 62 |
.nh |
| 63 |
.SH NAME |
| 64 |
BIO_s_bio, BIO_make_bio_pair, BIO_destroy_bio_pair, BIO_shutdown_wr, |
| 65 |
BIO_set_write_buf_size, BIO_get_write_buf_size, BIO_new_bio_pair, |
| 66 |
BIO_get_write_guarantee, BIO_ctrl_get_write_guarantee, BIO_get_read_request, |
| 67 |
BIO_ctrl_get_read_request, BIO_ctrl_reset_read_request \- BIO pair BIO |
| 68 |
.SH SYNOPSIS |
| 69 |
.IX Header "SYNOPSIS" |
| 70 |
.Vb 1 |
| 71 |
\& #include <openssl/bio.h> |
| 72 |
\& |
| 73 |
\& const BIO_METHOD *BIO_s_bio(void); |
| 74 |
\& |
| 75 |
\& int BIO_make_bio_pair(BIO *b1, BIO *b2); |
| 76 |
\& int BIO_destroy_bio_pair(BIO *b); |
| 77 |
\& int BIO_shutdown_wr(BIO *b); |
| 78 |
\& |
| 79 |
\& int BIO_set_write_buf_size(BIO *b, long size); |
| 80 |
\& size_t BIO_get_write_buf_size(BIO *b, long size); |
| 81 |
\& |
| 82 |
\& int BIO_new_bio_pair(BIO **bio1, size_t writebuf1, BIO **bio2, size_t writebuf2); |
| 83 |
\& |
| 84 |
\& int BIO_get_write_guarantee(BIO *b); |
| 85 |
\& size_t BIO_ctrl_get_write_guarantee(BIO *b); |
| 86 |
\& int BIO_get_read_request(BIO *b); |
| 87 |
\& size_t BIO_ctrl_get_read_request(BIO *b); |
| 88 |
\& int BIO_ctrl_reset_read_request(BIO *b); |
| 89 |
.Ve |
| 90 |
.SH DESCRIPTION |
| 91 |
.IX Header "DESCRIPTION" |
| 92 |
\&\fBBIO_s_bio()\fR returns the method for a BIO pair. A BIO pair is a pair of source/sink |
| 93 |
BIOs where data written to either half of the pair is buffered and can be read from |
| 94 |
the other half. Both halves must usually by handled by the same application thread |
| 95 |
since no locking is done on the internal data structures. |
| 96 |
.PP |
| 97 |
Since BIO chains typically end in a source/sink BIO it is possible to make this |
| 98 |
one half of a BIO pair and have all the data processed by the chain under application |
| 99 |
control. |
| 100 |
.PP |
| 101 |
One typical use of BIO pairs is to place TLS/SSL I/O under application control, this |
| 102 |
can be used when the application wishes to use a non standard transport for |
| 103 |
TLS/SSL or the normal socket routines are inappropriate. |
| 104 |
.PP |
| 105 |
Calls to \fBBIO_read_ex()\fR will read data from the buffer or request a retry if no |
| 106 |
data is available. |
| 107 |
.PP |
| 108 |
Calls to \fBBIO_write_ex()\fR will place data in the buffer or request a retry if the |
| 109 |
buffer is full. |
| 110 |
.PP |
| 111 |
The standard calls \fBBIO_ctrl_pending()\fR and \fBBIO_ctrl_wpending()\fR can be used to |
| 112 |
determine the amount of pending data in the read or write buffer. |
| 113 |
.PP |
| 114 |
\&\fBBIO_reset()\fR clears any data in the write buffer. |
| 115 |
.PP |
| 116 |
\&\fBBIO_make_bio_pair()\fR joins two separate BIOs into a connected pair. |
| 117 |
.PP |
| 118 |
\&\fBBIO_destroy_pair()\fR destroys the association between two connected BIOs. Freeing |
| 119 |
up any half of the pair will automatically destroy the association. |
| 120 |
.PP |
| 121 |
\&\fBBIO_shutdown_wr()\fR is used to close down a BIO \fBb\fR. After this call no further |
| 122 |
writes on BIO \fBb\fR are allowed (they will return an error). Reads on the other |
| 123 |
half of the pair will return any pending data or EOF when all pending data has |
| 124 |
been read. |
| 125 |
.PP |
| 126 |
\&\fBBIO_set_write_buf_size()\fR sets the write buffer size of BIO \fBb\fR to \fBsize\fR. |
| 127 |
If the size is not initialized a default value is used. This is currently |
| 128 |
17K, sufficient for a maximum size TLS record. |
| 129 |
.PP |
| 130 |
\&\fBBIO_get_write_buf_size()\fR returns the size of the write buffer. |
| 131 |
.PP |
| 132 |
\&\fBBIO_new_bio_pair()\fR combines the calls to \fBBIO_new()\fR, \fBBIO_make_bio_pair()\fR and |
| 133 |
\&\fBBIO_set_write_buf_size()\fR to create a connected pair of BIOs \fBbio1\fR, \fBbio2\fR |
| 134 |
with write buffer sizes \fBwritebuf1\fR and \fBwritebuf2\fR. If either size is |
| 135 |
zero then the default size is used. \fBBIO_new_bio_pair()\fR does not check whether |
| 136 |
\&\fBbio1\fR or \fBbio2\fR do point to some other BIO, the values are overwritten, |
| 137 |
\&\fBBIO_free()\fR is not called. |
| 138 |
.PP |
| 139 |
\&\fBBIO_get_write_guarantee()\fR and \fBBIO_ctrl_get_write_guarantee()\fR return the maximum |
| 140 |
length of data that can be currently written to the BIO. Writes larger than this |
| 141 |
value will return a value from \fBBIO_write_ex()\fR less than the amount requested or |
| 142 |
if the buffer is full request a retry. \fBBIO_ctrl_get_write_guarantee()\fR is a |
| 143 |
function whereas \fBBIO_get_write_guarantee()\fR is a macro. |
| 144 |
.PP |
| 145 |
\&\fBBIO_get_read_request()\fR and \fBBIO_ctrl_get_read_request()\fR return the |
| 146 |
amount of data requested, or the buffer size if it is less, if the |
| 147 |
last read attempt at the other half of the BIO pair failed due to an |
| 148 |
empty buffer. This can be used to determine how much data should be |
| 149 |
written to the BIO so the next read will succeed: this is most useful |
| 150 |
in TLS/SSL applications where the amount of data read is usually |
| 151 |
meaningful rather than just a buffer size. After a successful read |
| 152 |
this call will return zero. It also will return zero once new data |
| 153 |
has been written satisfying the read request or part of it. |
| 154 |
Note that \fBBIO_get_read_request()\fR never returns an amount larger |
| 155 |
than that returned by \fBBIO_get_write_guarantee()\fR. |
| 156 |
.PP |
| 157 |
\&\fBBIO_ctrl_reset_read_request()\fR can also be used to reset the value returned by |
| 158 |
\&\fBBIO_get_read_request()\fR to zero. |
| 159 |
.SH NOTES |
| 160 |
.IX Header "NOTES" |
| 161 |
Both halves of a BIO pair should be freed. That is even if one half is implicit |
| 162 |
freed due to a \fBBIO_free_all()\fR or \fBSSL_free()\fR call the other half needs to be freed. |
| 163 |
.PP |
| 164 |
When used in bidirectional applications (such as TLS/SSL) care should be taken to |
| 165 |
flush any data in the write buffer. This can be done by calling \fBBIO_pending()\fR |
| 166 |
on the other half of the pair and, if any data is pending, reading it and sending |
| 167 |
it to the underlying transport. This must be done before any normal processing |
| 168 |
(such as calling \fBselect()\fR ) due to a request and \fBBIO_should_read()\fR being true. |
| 169 |
.PP |
| 170 |
To see why this is important consider a case where a request is sent using |
| 171 |
\&\fBBIO_write_ex()\fR and a response read with \fBBIO_read_ex()\fR, this can occur during an |
| 172 |
TLS/SSL handshake for example. \fBBIO_write_ex()\fR will succeed and place data in the |
| 173 |
write buffer. \fBBIO_read_ex()\fR will initially fail and \fBBIO_should_read()\fR will be |
| 174 |
true. If the application then waits for data to be available on the underlying |
| 175 |
transport before flushing the write buffer it will never succeed because the |
| 176 |
request was never sent! |
| 177 |
.PP |
| 178 |
\&\fBBIO_eof()\fR is true if no data is in the peer BIO and the peer BIO has been |
| 179 |
shutdown. |
| 180 |
.PP |
| 181 |
\&\fBBIO_make_bio_pair()\fR, \fBBIO_destroy_bio_pair()\fR, \fBBIO_shutdown_wr()\fR, |
| 182 |
\&\fBBIO_set_write_buf_size()\fR, \fBBIO_get_write_buf_size()\fR, |
| 183 |
\&\fBBIO_get_write_guarantee()\fR, and \fBBIO_get_read_request()\fR are implemented |
| 184 |
as macros. |
| 185 |
.SH "RETURN VALUES" |
| 186 |
.IX Header "RETURN VALUES" |
| 187 |
\&\fBBIO_new_bio_pair()\fR returns 1 on success, with the new BIOs available in |
| 188 |
\&\fBbio1\fR and \fBbio2\fR, or 0 on failure, with NULL pointers stored into the |
| 189 |
locations for \fBbio1\fR and \fBbio2\fR. Check the error stack for more information. |
| 190 |
.PP |
| 191 |
[XXXXX: More return values need to be added here] |
| 192 |
.SH EXAMPLES |
| 193 |
.IX Header "EXAMPLES" |
| 194 |
The BIO pair can be used to have full control over the network access of an |
| 195 |
application. The application can call \fBselect()\fR on the socket as required |
| 196 |
without having to go through the SSL-interface. |
| 197 |
.PP |
| 198 |
.Vb 1 |
| 199 |
\& BIO *internal_bio, *network_bio; |
| 200 |
\& |
| 201 |
\& ... |
| 202 |
\& BIO_new_bio_pair(&internal_bio, 0, &network_bio, 0); |
| 203 |
\& SSL_set_bio(ssl, internal_bio, internal_bio); |
| 204 |
\& SSL_operations(); /* e.g. SSL_read and SSL_write */ |
| 205 |
\& ... |
| 206 |
\& |
| 207 |
\& application | TLS\-engine |
| 208 |
\& | | |
| 209 |
\& +\-\-\-\-\-\-\-\-\-\-> SSL_operations() |
| 210 |
\& | /\e || |
| 211 |
\& | || \e/ |
| 212 |
\& | BIO\-pair (internal_bio) |
| 213 |
\& | BIO\-pair (network_bio) |
| 214 |
\& | || /\e |
| 215 |
\& | \e/ || |
| 216 |
\& +\-\-\-\-\-\-\-\-\-\-\-< BIO_operations() |
| 217 |
\& | | |
| 218 |
\& | | |
| 219 |
\& socket |
| 220 |
\& |
| 221 |
\& ... |
| 222 |
\& SSL_free(ssl); /* implicitly frees internal_bio */ |
| 223 |
\& BIO_free(network_bio); |
| 224 |
\& ... |
| 225 |
.Ve |
| 226 |
.PP |
| 227 |
As the BIO pair will only buffer the data and never directly access the |
| 228 |
connection, it behaves nonblocking and will return as soon as the write |
| 229 |
buffer is full or the read buffer is drained. Then the application has to |
| 230 |
flush the write buffer and/or fill the read buffer. |
| 231 |
.PP |
| 232 |
Use the \fBBIO_ctrl_pending()\fR, to find out whether data is buffered in the BIO |
| 233 |
and must be transferred to the network. Use \fBBIO_ctrl_get_read_request()\fR to |
| 234 |
find out, how many bytes must be written into the buffer before the |
| 235 |
\&\fBSSL_operation()\fR can successfully be continued. |
| 236 |
.SH WARNINGS |
| 237 |
.IX Header "WARNINGS" |
| 238 |
As the data is buffered, \fBSSL_operation()\fR may return with an ERROR_SSL_WANT_READ |
| 239 |
condition, but there is still data in the write buffer. An application must |
| 240 |
not rely on the error value of \fBSSL_operation()\fR but must assure that the |
| 241 |
write buffer is always flushed first. Otherwise a deadlock may occur as |
| 242 |
the peer might be waiting for the data before being able to continue. |
| 243 |
.SH "SEE ALSO" |
| 244 |
.IX Header "SEE ALSO" |
| 245 |
\&\fBSSL_set_bio\fR\|(3), \fBssl\fR\|(7), \fBbio\fR\|(7), |
| 246 |
\&\fBBIO_should_retry\fR\|(3), \fBBIO_read_ex\fR\|(3) |
| 247 |
.SH COPYRIGHT |
| 248 |
.IX Header "COPYRIGHT" |
| 249 |
Copyright 2000\-2020 The OpenSSL Project Authors. All Rights Reserved. |
| 250 |
.PP |
| 251 |
Licensed under the Apache License 2.0 (the "License"). You may not use |
| 252 |
this file except in compliance with the License. You can obtain a copy |
| 253 |
in the file LICENSE in the source distribution or at |
| 254 |
<https://www.openssl.org/source/license.html>. |