Debian Codegraph @

upstream/debian-unstable/man3/BIO_f_ssl.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 "BIO_F_SSL 3SSL"
58 .TH BIO_F_SSL 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_do_handshake,
65 BIO_f_ssl, BIO_set_ssl, BIO_get_ssl, BIO_set_ssl_mode,
66 BIO_set_ssl_renegotiate_bytes,
67 BIO_get_num_renegotiates, BIO_set_ssl_renegotiate_timeout, BIO_new_ssl,
68 BIO_new_ssl_connect, BIO_new_buffer_ssl_connect, BIO_ssl_copy_session_id,
69 BIO_ssl_shutdown \- SSL BIO
70 .SH SYNOPSIS
71 .IX Header "SYNOPSIS"
72 .Vb 2
73 \& #include <openssl/bio.h>
74 \& #include <openssl/ssl.h>
75 \&
76 \& const BIO_METHOD *BIO_f_ssl(void);
77 \&
78 \& long BIO_set_ssl(BIO *b, SSL *ssl, long c);
79 \& long BIO_get_ssl(BIO *b, SSL **sslp);
80 \& long BIO_set_ssl_mode(BIO *b, long client);
81 \& long BIO_set_ssl_renegotiate_bytes(BIO *b, long num);
82 \& long BIO_set_ssl_renegotiate_timeout(BIO *b, long seconds);
83 \& long BIO_get_num_renegotiates(BIO *b);
84 \&
85 \& BIO *BIO_new_ssl(SSL_CTX *ctx, int client);
86 \& BIO *BIO_new_ssl_connect(SSL_CTX *ctx);
87 \& BIO *BIO_new_buffer_ssl_connect(SSL_CTX *ctx);
88 \& int BIO_ssl_copy_session_id(BIO *to, BIO *from);
89 \& void BIO_ssl_shutdown(BIO *bio);
90 \&
91 \& long BIO_do_handshake(BIO *b);
92 .Ve
93 .SH DESCRIPTION
94 .IX Header "DESCRIPTION"
95 \&\fBBIO_f_ssl()\fR returns the SSL BIO method. This is a filter BIO which
96 is a wrapper round the OpenSSL SSL routines adding a BIO "flavour" to
97 SSL I/O.
98 .PP
99 I/O performed on an SSL BIO communicates using the SSL protocol with
100 the SSLs read and write BIOs. If an SSL connection is not established
101 then an attempt is made to establish one on the first I/O call.
102 .PP
103 If a BIO is appended to an SSL BIO using \fBBIO_push()\fR it is automatically
104 used as the SSL BIOs read and write BIOs.
105 .PP
106 Calling \fBBIO_reset()\fR on an SSL BIO closes down any current SSL connection
107 by calling \fBSSL_shutdown()\fR. \fBBIO_reset()\fR is then sent to the next BIO in
108 the chain: this will typically disconnect the underlying transport.
109 The SSL BIO is then reset to the initial accept or connect state.
110 .PP
111 If the close flag is set when an SSL BIO is freed then the internal
112 SSL structure is also freed using \fBSSL_free()\fR.
113 .PP
114 \&\fBBIO_set_ssl()\fR sets the internal SSL pointer of SSL BIO \fBb\fR to \fBssl\fR using
115 the close flag \fBc\fR.
116 .PP
117 \&\fBBIO_get_ssl()\fR retrieves the SSL pointer of SSL BIO \fBb\fR, it can then be
118 manipulated using the standard SSL library functions.
119 .PP
120 \&\fBBIO_set_ssl_mode()\fR sets the SSL BIO mode to \fBclient\fR. If \fBclient\fR
121 is 1 client mode is set. If \fBclient\fR is 0 server mode is set.
122 .PP
123 \&\fBBIO_set_ssl_renegotiate_bytes()\fR sets the renegotiate byte count of SSL BIO \fBb\fR
124 to \fBnum\fR. When set after every \fBnum\fR bytes of I/O (read and write)
125 the SSL session is automatically renegotiated. \fBnum\fR must be at
126 least 512 bytes.
127 .PP
128 \&\fBBIO_set_ssl_renegotiate_timeout()\fR sets the renegotiate timeout of SSL BIO \fBb\fR
129 to \fBseconds\fR.
130 When the renegotiate timeout elapses the session is automatically renegotiated.
131 .PP
132 \&\fBBIO_get_num_renegotiates()\fR returns the total number of session
133 renegotiations due to I/O or timeout of SSL BIO \fBb\fR.
134 .PP
135 \&\fBBIO_new_ssl()\fR allocates an SSL BIO using SSL_CTX \fBctx\fR and using
136 client mode if \fBclient\fR is non zero.
137 .PP
138 \&\fBBIO_new_ssl_connect()\fR creates a new BIO chain consisting of an
139 SSL BIO (using \fBctx\fR) followed by a connect BIO.
140 .PP
141 \&\fBBIO_new_buffer_ssl_connect()\fR creates a new BIO chain consisting
142 of a buffering BIO, an SSL BIO (using \fBctx\fR), and a connect BIO.
143 .PP
144 \&\fBBIO_ssl_copy_session_id()\fR copies an SSL session id between
145 BIO chains \fBfrom\fR and \fBto\fR. It does this by locating the
146 SSL BIOs in each chain and calling \fBSSL_copy_session_id()\fR on
147 the internal SSL pointer.
148 .PP
149 \&\fBBIO_ssl_shutdown()\fR closes down an SSL connection on BIO
150 chain \fBbio\fR. It does this by locating the SSL BIO in the
151 chain and calling \fBSSL_shutdown()\fR on its internal SSL
152 pointer.
153 .PP
154 \&\fBBIO_do_handshake()\fR attempts to complete an SSL handshake on the
155 supplied BIO and establish the SSL connection.
156 For non-SSL BIOs the connection is done typically at TCP level.
157 If domain name resolution yields multiple IP addresses all of them are tried
158 after \fBconnect()\fR failures.
159 The function returns 1 if the connection was established successfully.
160 A zero or negative value is returned if the connection could not be established.
161 The call \fBBIO_should_retry()\fR should be used for nonblocking connect BIOs
162 to determine if the call should be retried.
163 If a connection has already been established this call has no effect.
164 .SH NOTES
165 .IX Header "NOTES"
166 SSL BIOs are exceptional in that if the underlying transport
167 is non blocking they can still request a retry in exceptional
168 circumstances. Specifically this will happen if a session
169 renegotiation takes place during a \fBBIO_read_ex()\fR operation, one
170 case where this happens is when step up occurs.
171 .PP
172 The SSL flag SSL_AUTO_RETRY can be
173 set to disable this behaviour. That is when this flag is set
174 an SSL BIO using a blocking transport will never request a
175 retry.
176 .PP
177 Since unknown \fBBIO_ctrl()\fR operations are sent through filter
178 BIOs the servers name and port can be set using \fBBIO_set_host()\fR
179 on the BIO returned by \fBBIO_new_ssl_connect()\fR without having
180 to locate the connect BIO first.
181 .PP
182 Applications do not have to call \fBBIO_do_handshake()\fR but may wish
183 to do so to separate the handshake process from other I/O
184 processing.
185 .PP
186 \&\fBBIO_set_ssl()\fR, \fBBIO_get_ssl()\fR, \fBBIO_set_ssl_mode()\fR,
187 \&\fBBIO_set_ssl_renegotiate_bytes()\fR, \fBBIO_set_ssl_renegotiate_timeout()\fR,
188 \&\fBBIO_get_num_renegotiates()\fR, and \fBBIO_do_handshake()\fR are implemented as macros.
189 .PP
190 \&\fBBIO_ssl_copy_session_id()\fR is not currently supported on QUIC SSL objects and
191 fails if called on such an object.
192 .SH "RETURN VALUES"
193 .IX Header "RETURN VALUES"
194 \&\fBBIO_f_ssl()\fR returns the SSL \fBBIO_METHOD\fR structure.
195 .PP
196 \&\fBBIO_set_ssl()\fR, \fBBIO_get_ssl()\fR, \fBBIO_set_ssl_mode()\fR, \fBBIO_set_ssl_renegotiate_bytes()\fR,
197 \&\fBBIO_set_ssl_renegotiate_timeout()\fR and \fBBIO_get_num_renegotiates()\fR return 1 on
198 success or a value which is less than or equal to 0 if an error occurred.
199 .PP
200 \&\fBBIO_new_ssl()\fR, \fBBIO_new_ssl_connect()\fR and \fBBIO_new_buffer_ssl_connect()\fR return
201 a valid \fBBIO\fR structure on success or \fBNULL\fR if an error occurred.
202 .PP
203 \&\fBBIO_ssl_copy_session_id()\fR returns 1 on success or 0 on error, or if called
204 on a QUIC SSL object.
205 .PP
206 \&\fBBIO_do_handshake()\fR returns 1 if the connection was established successfully.
207 A zero or negative value is returned if the connection could not be established.
208 .SH EXAMPLES
209 .IX Header "EXAMPLES"
210 This SSL/TLS client example attempts to retrieve a page from an
211 SSL/TLS web server. The I/O routines are identical to those of the
212 unencrypted example in \fBBIO_s_connect\fR\|(3).
213 .PP
214 .Vb 5
215 \& BIO *sbio, *out;
216 \& int len;
217 \& char tmpbuf[1024];
218 \& SSL_CTX *ctx;
219 \& SSL *ssl;
220 \&
221 \& /* XXX Seed the PRNG if needed. */
222 \&
223 \& ctx = SSL_CTX_new(TLS_client_method());
224 \&
225 \& /* XXX Set verify paths and mode here. */
226 \&
227 \& sbio = BIO_new_ssl_connect(ctx);
228 \& BIO_get_ssl(sbio, &ssl);
229 \& if (ssl == NULL) {
230 \& fprintf(stderr, "Can\*(Aqt locate SSL pointer\en");
231 \& ERR_print_errors_fp(stderr);
232 \& exit(1);
233 \& }
234 \&
235 \& /* XXX We might want to do other things with ssl here */
236 \&
237 \& /* An empty host part means the loopback address */
238 \& BIO_set_conn_hostname(sbio, ":https");
239 \&
240 \& out = BIO_new_fp(stdout, BIO_NOCLOSE);
241 \& if (BIO_do_connect(sbio) <= 0) {
242 \& fprintf(stderr, "Error connecting to server\en");
243 \& ERR_print_errors_fp(stderr);
244 \& exit(1);
245 \& }
246 \&
247 \& /* XXX Could examine ssl here to get connection info */
248 \&
249 \& BIO_puts(sbio, "GET / HTTP/1.0\en\en");
250 \& for (;;) {
251 \& len = BIO_read(sbio, tmpbuf, 1024);
252 \& if (len <= 0)
253 \& break;
254 \& BIO_write(out, tmpbuf, len);
255 \& }
256 \& BIO_free_all(sbio);
257 \& BIO_free(out);
258 .Ve
259 .PP
260 Here is a simple server example. It makes use of a buffering
261 BIO to allow lines to be read from the SSL BIO using BIO_gets.
262 It creates a pseudo web page containing the actual request from
263 a client and also echoes the request to standard output.
264 .PP
265 .Vb 5
266 \& BIO *sbio, *bbio, *acpt, *out;
267 \& int len;
268 \& char tmpbuf[1024];
269 \& SSL_CTX *ctx;
270 \& SSL *ssl;
271 \&
272 \& /* XXX Seed the PRNG if needed. */
273 \&
274 \& ctx = SSL_CTX_new(TLS_server_method());
275 \& if (!SSL_CTX_use_certificate_file(ctx, "server.pem", SSL_FILETYPE_PEM)
276 \& || !SSL_CTX_use_PrivateKey_file(ctx, "server.pem", SSL_FILETYPE_PEM)
277 \& || !SSL_CTX_check_private_key(ctx)) {
278 \& fprintf(stderr, "Error setting up SSL_CTX\en");
279 \& ERR_print_errors_fp(stderr);
280 \& exit(1);
281 \& }
282 \&
283 \& /* XXX Other things like set verify locations, EDH temp callbacks. */
284 \&
285 \& /* New SSL BIO setup as server */
286 \& sbio = BIO_new_ssl(ctx, 0);
287 \& BIO_get_ssl(sbio, &ssl);
288 \& if (ssl == NULL) {
289 \& fprintf(stderr, "Can\*(Aqt locate SSL pointer\en");
290 \& ERR_print_errors_fp(stderr);
291 \& exit(1);
292 \& }
293 \&
294 \& bbio = BIO_new(BIO_f_buffer());
295 \& sbio = BIO_push(bbio, sbio);
296 \& acpt = BIO_new_accept("4433");
297 \&
298 \& /*
299 \& * By doing this when a new connection is established
300 \& * we automatically have sbio inserted into it. The
301 \& * BIO chain is now \*(Aqswallowed\*(Aq by the accept BIO and
302 \& * will be freed when the accept BIO is freed.
303 \& */
304 \& BIO_set_accept_bios(acpt, sbio);
305 \& out = BIO_new_fp(stdout, BIO_NOCLOSE);
306 \&
307 \& /* First call to BIO_do_accept() sets up accept BIO */
308 \& if (BIO_do_accept(acpt) <= 0) {
309 \& fprintf(stderr, "Error setting up accept BIO\en");
310 \& ERR_print_errors_fp(stderr);
311 \& exit(1);
312 \& }
313 .Ve
314 .PP
315 /* Second call to \fBBIO_do_accept()\fR waits for incoming connection */
316 if (BIO_do_accept(acpt) <= 0) {
317 fprintf(stderr, "Error accepting connection\en");
318 ERR_print_errors_fp(stderr);
319 \fBexit\fR\|(1);
320 }
321 .PP
322 .Vb 3
323 \& /* We only want one connection so remove and free accept BIO */
324 \& sbio = BIO_pop(acpt);
325 \& BIO_free_all(acpt);
326 \&
327 \& if (BIO_do_handshake(sbio) <= 0) {
328 \& fprintf(stderr, "Error in SSL handshake\en");
329 \& ERR_print_errors_fp(stderr);
330 \& exit(1);
331 \& }
332 \&
333 \& BIO_puts(sbio, "HTTP/1.0 200 OK\er\enContent\-type: text/plain\er\en\er\en");
334 \& BIO_puts(sbio, "\er\enConnection Established\er\enRequest headers:\er\en");
335 \& BIO_puts(sbio, "\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\er\en");
336 \&
337 \& for (;;) {
338 \& len = BIO_gets(sbio, tmpbuf, 1024);
339 \& if (len <= 0)
340 \& break;
341 \& BIO_write(sbio, tmpbuf, len);
342 \& BIO_write(out, tmpbuf, len);
343 \& /* Look for blank line signifying end of headers*/
344 \& if (tmpbuf[0] == \*(Aq\er\*(Aq || tmpbuf[0] == \*(Aq\en\*(Aq)
345 \& break;
346 \& }
347 \&
348 \& BIO_puts(sbio, "\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\er\en");
349 \& BIO_puts(sbio, "\er\en");
350 \& BIO_flush(sbio);
351 \& BIO_free_all(sbio);
352 .Ve
353 .SH HISTORY
354 .IX Header "HISTORY"
355 In OpenSSL before 1.0.0 the \fBBIO_pop()\fR call was handled incorrectly,
356 the I/O BIO reference count was incorrectly incremented (instead of
357 decremented) and dissociated with the SSL BIO even if the SSL BIO was not
358 explicitly being popped (e.g. a pop higher up the chain). Applications which
359 included workarounds for this bug (e.g. freeing BIOs more than once) should
360 be modified to handle this fix or they may free up an already freed BIO.
361 .SH COPYRIGHT
362 .IX Header "COPYRIGHT"
363 Copyright 2000\-2023 The OpenSSL Project Authors. All Rights Reserved.
364 .PP
365 Licensed under the Apache License 2.0 (the "License"). You may not use
366 this file except in compliance with the License. You can obtain a copy
367 in the file LICENSE in the source distribution or at
368 <https://www.openssl.org/source/license.html>.