Debian Codegraph @

upstream/debian-unstable/man3/SSL_set_bio.3ssl

raw
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 "SSL_SET_BIO 3SSL"
58 .TH SSL_SET_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 SSL_set_bio, SSL_set0_rbio, SSL_set0_wbio \- connect the SSL object with a BIO
65 .SH SYNOPSIS
66 .IX Header "SYNOPSIS"
67 .Vb 1
68 \& #include <openssl/ssl.h>
69 \&
70 \& void SSL_set_bio(SSL *ssl, BIO *rbio, BIO *wbio);
71 \& void SSL_set0_rbio(SSL *s, BIO *rbio);
72 \& void SSL_set0_wbio(SSL *s, BIO *wbio);
73 .Ve
74 .SH DESCRIPTION
75 .IX Header "DESCRIPTION"
76 \&\fBSSL_set0_rbio()\fR connects the BIO \fBrbio\fR for the read operations of the \fBssl\fR
77 object. The SSL engine inherits the behaviour of \fBrbio\fR. If the BIO is
78 nonblocking then the \fBssl\fR object will also have nonblocking behaviour. This
79 function transfers ownership of \fBrbio\fR to \fBssl\fR. It will be automatically
80 freed using \fBBIO_free_all\fR\|(3) when the \fBssl\fR is freed. On calling this
81 function, any existing \fBrbio\fR that was previously set will also be freed via a
82 call to \fBBIO_free_all\fR\|(3) (this includes the case where the \fBrbio\fR is set to
83 the same value as previously).
84 .PP
85 If using a custom BIO, \fBrbio\fR must implement either
86 \&\fBBIO_meth_set_read_ex\fR\|(3) or \fBBIO_meth_set_read\fR\|(3).
87 .PP
88 \&\fBSSL_set0_wbio()\fR works in the same as \fBSSL_set0_rbio()\fR except that it connects
89 the BIO \fBwbio\fR for the write operations of the \fBssl\fR object. Note that if the
90 rbio and wbio are the same then \fBSSL_set0_rbio()\fR and \fBSSL_set0_wbio()\fR each take
91 ownership of one reference. Therefore, it may be necessary to increment the
92 number of references available using \fBBIO_up_ref\fR\|(3) before calling the set0
93 functions.
94 .PP
95 If using a custom BIO, \fBwbio\fR must implement
96 \&\fBBIO_meth_set_write_ex\fR\|(3) or \fBBIO_meth_set_write\fR\|(3). It additionally must
97 implement \fBBIO_flush\fR\|(3) using \fBBIO_CTRL_FLUSH\fR and \fBBIO_meth_set_ctrl\fR\|(3).
98 If flushing is unnecessary with \fBwbio\fR, \fBBIO_flush\fR\|(3) should return one and
99 do nothing.
100 .PP
101 \&\fBSSL_set_bio()\fR is similar to \fBSSL_set0_rbio()\fR and \fBSSL_set0_wbio()\fR except
102 that it connects both the \fBrbio\fR and the \fBwbio\fR at the same time, and
103 transfers the ownership of \fBrbio\fR and \fBwbio\fR to \fBssl\fR according to
104 the following set of rules:
105 .IP \(bu 2
106 If neither the \fBrbio\fR or \fBwbio\fR have changed from their previous values
107 then nothing is done.
108 .IP \(bu 2
109 If the \fBrbio\fR and \fBwbio\fR parameters are different and both are different
110 to their
111 previously set values then one reference is consumed for the rbio and one
112 reference is consumed for the wbio.
113 .IP \(bu 2
114 If the \fBrbio\fR and \fBwbio\fR parameters are the same and the \fBrbio\fR is not
115 the same as the previously set value then one reference is consumed.
116 .IP \(bu 2
117 If the \fBrbio\fR and \fBwbio\fR parameters are the same and the \fBrbio\fR is the
118 same as the previously set value, then no additional references are consumed.
119 .IP \(bu 2
120 If the \fBrbio\fR and \fBwbio\fR parameters are different and the \fBrbio\fR is the
121 same as the
122 previously set value then one reference is consumed for the \fBwbio\fR and no
123 references are consumed for the \fBrbio\fR.
124 .IP \(bu 2
125 If the \fBrbio\fR and \fBwbio\fR parameters are different and the \fBwbio\fR is the
126 same as the previously set value and the old \fBrbio\fR and \fBwbio\fR values
127 were the same as each other then one reference is consumed for the \fBrbio\fR
128 and no references are consumed for the \fBwbio\fR.
129 .IP \(bu 2
130 If the \fBrbio\fR and \fBwbio\fR parameters are different and the \fBwbio\fR
131 is the same as the
132 previously set value and the old \fBrbio\fR and \fBwbio\fR values were different
133 to each other, then one reference is consumed for the \fBrbio\fR and one
134 reference is consumed for the \fBwbio\fR.
135 .PP
136 Because of this complexity, this function should be avoided;
137 use \fBSSL_set0_rbio()\fR and \fBSSL_set0_wbio()\fR instead.
138 .PP
139 Where a new BIO is set on a QUIC connection SSL object, blocking mode will be
140 disabled on that SSL object if the BIO cannot support blocking mode. If another
141 BIO is subsequently set on the SSL object which can support blocking mode,
142 blocking mode will not be automatically re-enabled. For more information, see
143 \&\fBSSL_set_blocking_mode\fR\|(3).
144 .SH "RETURN VALUES"
145 .IX Header "RETURN VALUES"
146 \&\fBSSL_set_bio()\fR, \fBSSL_set0_rbio()\fR and \fBSSL_set0_wbio()\fR cannot fail.
147 .SH "SEE ALSO"
148 .IX Header "SEE ALSO"
149 \&\fBSSL_get_rbio\fR\|(3),
150 \&\fBSSL_connect\fR\|(3), \fBSSL_accept\fR\|(3),
151 \&\fBSSL_shutdown\fR\|(3), \fBssl\fR\|(7), \fBbio\fR\|(7)
152 .SH HISTORY
153 .IX Header "HISTORY"
154 \&\fBSSL_set0_rbio()\fR and \fBSSL_set0_wbio()\fR were added in OpenSSL 1.1.0.
155 .SH COPYRIGHT
156 .IX Header "COPYRIGHT"
157 Copyright 2000\-2023 The OpenSSL Project Authors. All Rights Reserved.
158 .PP
159 Licensed under the Apache License 2.0 (the "License"). You may not use
160 this file except in compliance with the License. You can obtain a copy
161 in the file LICENSE in the source distribution or at
162 <https://www.openssl.org/source/license.html>.