| blob | 5404b9c70fc5f7df1bc6f360fdc4e6c9cbce46ad |
1 .\" $OpenBSD: BIO_f_ssl.3,v 1.5 2017/08/20 17:35:18 schwarze Exp $
2 .\" OpenSSL BIO_f_ssl.pod e90fc053 Jul 15 09:39:45 2017 -0400
3 .\" OpenSSL BIO_f_ssl.pod f672aee4 Feb 9 11:52:40 2016 -0500
4 .\"
5 .\" This file was written by Dr. Stephen Henson <steve@openssl.org>.
6 .\" Copyright (c) 2000, 2003, 2009, 2014-2016 The OpenSSL Project.
7 .\" All rights reserved.
8 .\"
9 .\" Redistribution and use in source and binary forms, with or without
10 .\" modification, are permitted provided that the following conditions
11 .\" are met:
12 .\"
13 .\" 1. Redistributions of source code must retain the above copyright
14 .\" notice, this list of conditions and the following disclaimer.
15 .\"
16 .\" 2. Redistributions in binary form must reproduce the above copyright
17 .\" notice, this list of conditions and the following disclaimer in
18 .\" the documentation and/or other materials provided with the
19 .\" distribution.
20 .\"
21 .\" 3. All advertising materials mentioning features or use of this
22 .\" software must display the following acknowledgment:
23 .\" "This product includes software developed by the OpenSSL Project
24 .\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
25 .\"
26 .\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
27 .\" endorse or promote products derived from this software without
28 .\" prior written permission. For written permission, please contact
29 .\" openssl-core@openssl.org.
30 .\"
31 .\" 5. Products derived from this software may not be called "OpenSSL"
32 .\" nor may "OpenSSL" appear in their names without prior written
33 .\" permission of the OpenSSL Project.
34 .\"
35 .\" 6. Redistributions of any form whatsoever must retain the following
36 .\" acknowledgment:
37 .\" "This product includes software developed by the OpenSSL Project
38 .\" for use in the OpenSSL Toolkit (http://www.openssl.org/)"
39 .\"
40 .\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
41 .\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
42 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
43 .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR
44 .\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
45 .\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
46 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
47 .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
48 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
49 .\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
50 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
51 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
52 .\"
53 .Dd $Mdocdate: August 20 2017 $
54 .Dt BIO_F_SSL 3
55 .Os
56 .Sh NAME
57 .Nm BIO_f_ssl ,
58 .Nm BIO_set_ssl ,
59 .Nm BIO_get_ssl ,
60 .Nm BIO_set_ssl_mode ,
61 .Nm BIO_set_ssl_renegotiate_bytes ,
62 .Nm BIO_get_num_renegotiates ,
63 .Nm BIO_set_ssl_renegotiate_timeout ,
64 .Nm BIO_new_ssl ,
65 .Nm BIO_new_ssl_connect ,
66 .Nm BIO_new_buffer_ssl_connect ,
67 .Nm BIO_ssl_copy_session_id ,
68 .Nm BIO_ssl_shutdown ,
69 .Nm BIO_do_handshake
70 .Nd SSL BIO
71 .Sh SYNOPSIS
72 .In openssl/bio.h
73 .In openssl/ssl.h
74 .Ft BIO_METHOD *
75 .Fn BIO_f_ssl void
76 .Ft long
77 .Fo BIO_set_ssl
78 .Fa "BIO *b"
79 .Fa "SSL *ssl"
80 .Fa "long c"
81 .Fc
82 .Ft long
83 .Fo BIO_get_ssl
84 .Fa "BIO *b"
85 .Fa "SSL *sslp"
86 .Fc
87 .Ft long
88 .Fo BIO_set_ssl_mode
89 .Fa "BIO *b"
90 .Fa "long client"
91 .Fc
92 .Ft long
93 .Fo BIO_set_ssl_renegotiate_bytes
94 .Fa "BIO *b"
95 .Fa "long num"
96 .Fc
97 .Ft long
98 .Fo BIO_set_ssl_renegotiate_timeout
99 .Fa "BIO *b"
100 .Fa "long seconds"
101 .Fc
102 .Ft long
103 .Fo BIO_get_num_renegotiates
104 .Fa "BIO *b"
105 .Fc
106 .Ft BIO *
107 .Fn BIO_new_ssl "SSL_CTX *ctx" "int client"
108 .Ft BIO *
109 .Fn BIO_new_ssl_connect "SSL_CTX *ctx"
110 .Ft BIO *
111 .Fn BIO_new_buffer_ssl_connect "SSL_CTX *ctx"
112 .Ft int
113 .Fn BIO_ssl_copy_session_id "BIO *to" "BIO *from"
114 .Ft void
115 .Fn BIO_ssl_shutdown "BIO *bio"
116 .Ft long
117 .Fn BIO_do_handshake "BIO *b"
118 .Sh DESCRIPTION
119 .Fn BIO_f_ssl
120 returns the
121 .Vt SSL
122 .Vt BIO
123 method.
124 This is a filter
125 .Vt BIO
126 which is a wrapper around the OpenSSL
127 .Vt SSL
128 routines adding a
129 .Vt BIO
130 .Dq flavor
131 to SSL I/O.
132 .Pp
133 I/O performed on an
134 .Vt SSL
135 .Vt BIO
136 communicates using the SSL protocol with
137 the
138 .Vt SSL Ns 's
139 read and write
140 .Vt BIO Ns s .
141 If an SSL connection is not established then an attempt is made to establish
142 one on the first I/O call.
143 .Pp
144 If a
145 .Vt BIO
146 is appended to an
147 .Vt SSL
148 .Vt BIO
149 using
150 .Xr BIO_push 3
151 it is automatically used as the
152 .Vt SSL
153 .Vt BIO Ns 's read and write
154 .Vt BIO Ns s .
155 .Pp
156 Calling
157 .Xr BIO_reset 3
158 on an
159 .Vt SSL
160 .Vt BIO
161 closes down any current SSL connection by calling
162 .Xr SSL_shutdown 3 .
163 .Xr BIO_reset 3
164 is then sent to the next
165 .Vt BIO
166 in the chain; this will typically disconnect the underlying transport.
167 The
168 .Vt SSL
169 .Vt BIO
170 is then reset to the initial accept or connect state.
171 .Pp
172 If the close flag is set when an
173 .Vt SSL
174 .Vt BIO
175 is freed then the internal
176 .Vt SSL
177 structure is also freed using
178 .Xr SSL_free 3 .
179 .Pp
180 .Fn BIO_set_ssl
181 sets the internal
182 .Vt SSL
183 pointer of
184 .Vt BIO
185 .Fa b
186 to
187 .Fa ssl
188 using
189 the close flag
190 .Fa c .
191 .Pp
192 .Fn BIO_get_ssl
193 retrieves the
194 .Vt SSL
195 pointer of
196 .Vt BIO
197 .Fa b ;
198 it can then be manipulated using the standard SSL library functions.
199 .Pp
200 .Fn BIO_set_ssl_mode
201 sets the
202 .Vt SSL
203 .Vt BIO
204 mode to
205 .Fa client .
206 If
207 .Fa client
208 is 1, client mode is set.
209 If
210 .Fa client
211 is 0, server mode is set.
212 .Pp
213 .Fn BIO_set_ssl_renegotiate_bytes
214 sets the renegotiate byte count to
215 .Fa num .
216 When set after every
217 .Fa num
218 bytes of I/O (read and write) the SSL session is automatically renegotiated.
219 .Fa num
220 must be at least 512 bytes.
221 .Pp
222 .Fn BIO_set_ssl_renegotiate_timeout
223 sets the renegotiate timeout to
224 .Fa seconds .
225 When the renegotiate timeout elapses the session is automatically renegotiated.
226 .Pp
227 .Fn BIO_get_num_renegotiates
228 returns the total number of session renegotiations due to I/O or timeout.
229 .Pp
230 .Fn BIO_new_ssl
231 allocates an
232 .Vt SSL
233 .Vt BIO
234 using
235 .Vt SSL_CTX
236 .Va ctx
237 and using client mode if
238 .Fa client
239 is nonzero.
240 .Pp
241 .Fn BIO_new_ssl_connect
242 creates a new
243 .Vt BIO
244 chain consisting of an
245 .Vt SSL
246 .Vt BIO
247 (using
248 .Fa ctx )
249 followed by a connect BIO.
250 .Pp
251 .Fn BIO_new_buffer_ssl_connect
252 creates a new
253 .Vt BIO
254 chain consisting of a buffering
255 .Vt BIO ,
256 an
257 .Vt SSL
258 .Vt BIO
259 (using
260 .Fa ctx )
261 and a connect
262 .Vt BIO .
263 .Pp
264 .Fn BIO_ssl_copy_session_id
265 copies an SSL session id between
266 .Vt BIO
267 chains
268 .Fa from
269 and
270 .Fa to .
271 It does this by locating the
272 .Vt SSL
273 .Vt BIO Ns s
274 in each chain and calling
275 .Xr SSL_copy_session_id 3
276 on the internal
277 .Vt SSL
278 pointer.
279 .Pp
280 .Fn BIO_ssl_shutdown
281 closes down an SSL connection on
282 .Vt BIO
283 chain
284 .Fa bio .
285 It does this by locating the
286 .Vt SSL
287 .Vt BIO
288 in the
289 chain and calling
290 .Xr SSL_shutdown 3
291 on its internal
292 .Vt SSL
293 pointer.
294 .Pp
295 .Fn BIO_do_handshake
296 attempts to complete an SSL handshake on the supplied
297 .Vt BIO
298 and establish the SSL connection.
299 It returns 1 if the connection was established successfully.
300 A zero or negative value is returned if the connection could not be
301 established; the call
302 .Xr BIO_should_retry 3
303 should be used for non blocking connect
304 .Vt BIO Ns s
305 to determine if the call should be retried.
306 If an SSL connection has already been established this call has no effect.
307 .Pp
308 .Vt SSL
309 .Vt BIO Ns s
310 are exceptional in that if the underlying transport is non-blocking they can
311 still request a retry in exceptional circumstances.
312 Specifically this will happen if a session renegotiation takes place during a
313 .Xr BIO_read 3
314 operation.
315 One case where this happens is when step up occurs.
316 .Pp
317 In OpenSSL 0.9.6 and later the SSL flag
318 .Dv SSL_AUTO_RETRY
319 can be set to disable this behaviour.
320 In other words, when this flag is set an
321 .Vt SSL
322 .Vt BIO
323 using a blocking transport will never request a retry.
324 .Pp
325 Since unknown
326 .Xr BIO_ctrl 3
327 operations are sent through filter
328 .Vt BIO Ns s
329 the server name and port can be set using
330 .Xr BIO_set_conn_hostname 3
331 and
332 .Xr BIO_set_conn_port 3
333 on the
334 .Vt BIO
335 returned by
336 .Fn BIO_new_ssl_connect
337 without having to locate the connect
338 .Vt BIO
339 first.
340 .Pp
341 Applications do not have to call
342 .Fn BIO_do_handshake
343 but may wish to do so to separate the handshake process from other I/O
344 processing.
345 .Pp
346 .Fn BIO_set_ssl ,
347 .Fn BIO_get_ssl ,
348 .Fn BIO_set_ssl_mode ,
349 .Fn BIO_set_ssl_renegotiate_bytes ,
350 .Fn BIO_set_ssl_renegotiate_timeout ,
351 .Fn BIO_get_num_renegotiates ,
352 and
353 .Fn BIO_do_handshake
354 are implemented as macros.
355 .Sh RETURN VALUES
356 .\" XXX
357 This section is incomplete.
358 .Sh EXAMPLES
359 This SSL/TLS client example attempts to retrieve a page from an SSL/TLS web
360 server.
361 The I/O routines are identical to those of the unencrypted example in
362 .Xr BIO_s_connect 3 .
363 .Bd -literal
364 BIO *sbio, *out;
365 int len;
366 char tmpbuf[1024];
367 SSL_CTX *ctx;
368 SSL *ssl;
370 ERR_load_crypto_strings();
371 ERR_load_SSL_strings();
372 OpenSSL_add_all_algorithms();
374 /*
375 * We would seed the PRNG here if the platform didn't do it automatically
376 */
378 ctx = SSL_CTX_new(SSLv23_client_method());
380 /*
381 * We'd normally set some stuff like the verify paths and mode here because
382 * as things stand this will connect to any server whose certificate is
383 * signed by any CA.
384 */
386 sbio = BIO_new_ssl_connect(ctx);
388 BIO_get_ssl(sbio, &ssl);
390 if (!ssl) {
391 fprintf(stderr, "Can't locate SSL pointer\en");
392 /* whatever ... */
393 }
395 /* Don't want any retries */
396 SSL_set_mode(ssl, SSL_MODE_AUTO_RETRY);
398 /* We might want to do other things with ssl here */
400 BIO_set_conn_hostname(sbio, "localhost:https");
402 out = BIO_new_fp(stdout, BIO_NOCLOSE);
403 if (BIO_do_connect(sbio) <= 0) {
404 fprintf(stderr, "Error connecting to server\en");
405 ERR_print_errors_fp(stderr);
406 /* whatever ... */
407 }
409 if (BIO_do_handshake(sbio) <= 0) {
410 fprintf(stderr, "Error establishing SSL connection\en");
411 ERR_print_errors_fp(stderr);
412 /* whatever ... */
413 }
415 /* Could examine ssl here to get connection info */
417 BIO_puts(sbio, "GET / HTTP/1.0\en\en");
418 for (;;) {
419 len = BIO_read(sbio, tmpbuf, 1024);
420 if(len <= 0) break;
421 BIO_write(out, tmpbuf, len);
422 }
423 BIO_free_all(sbio);
424 BIO_free(out);
425 .Ed
426 .Pp
427 Here is a simple server example.
428 It makes use of a buffering
429 .Vt BIO
430 to allow lines to be read from the
431 .Vt SSL
432 .Vt BIO
433 using
434 .Xr BIO_gets 3 .
435 It creates a pseudo web page containing the actual request from a client and
436 also echoes the request to standard output.
437 .Bd -literal
438 BIO *sbio, *bbio, *acpt, *out;
439 int len;
440 char tmpbuf[1024];
441 SSL_CTX *ctx;
442 SSL *ssl;
444 ERR_load_crypto_strings();
445 ERR_load_SSL_strings();
446 OpenSSL_add_all_algorithms();
448 /* Might seed PRNG here */
450 ctx = SSL_CTX_new(SSLv23_server_method());
452 if (!SSL_CTX_use_certificate_file(ctx,"server.pem",SSL_FILETYPE_PEM)
453 || !SSL_CTX_use_PrivateKey_file(ctx,"server.pem",SSL_FILETYPE_PEM)
454 || !SSL_CTX_check_private_key(ctx)) {
455 fprintf(stderr, "Error setting up SSL_CTX\en");
456 ERR_print_errors_fp(stderr);
457 return 0;
458 }
460 /*
461 * Might do other things here like setting verify locations and DH and/or
462 * RSA temporary key callbacks
463 */
465 /* New SSL BIO setup as server */
466 sbio = BIO_new_ssl(ctx,0);
468 BIO_get_ssl(sbio, &ssl);
470 if (!ssl) {
471 fprintf(stderr, "Can't locate SSL pointer\en");
472 /* whatever ... */
473 }
475 /* Don't want any retries */
476 SSL_set_mode(ssl, SSL_MODE_AUTO_RETRY);
478 /* Create the buffering BIO */
480 bbio = BIO_new(BIO_f_buffer());
482 /* Add to chain */
483 sbio = BIO_push(bbio, sbio);
485 acpt = BIO_new_accept("4433");
487 /*
488 * By doing this when a new connection is established we automatically
489 * have sbio inserted into it. The BIO chain is now 'swallowed' by the
490 * accept BIO and will be freed when the accept BIO is freed.
491 */
493 BIO_set_accept_bios(acpt,sbio);
495 out = BIO_new_fp(stdout, BIO_NOCLOSE);
497 /* Wait for incoming connection */
498 if (BIO_do_accept(acpt) <= 0) {
499 fprintf(stderr, "Error setting up accept BIO\en");
500 ERR_print_errors_fp(stderr);
501 return 0;
502 }
504 /* We only want one connection so remove and free accept BIO */
506 sbio = BIO_pop(acpt);
508 BIO_free_all(acpt);
510 if (BIO_do_handshake(sbio) <= 0) {
511 fprintf(stderr, "Error in SSL handshake\en");
512 ERR_print_errors_fp(stderr);
513 return 0;
514 }
516 BIO_puts(sbio, "HTTP/1.0 200 OK\er\enContent-type: text/plain\er\en\er\en");
517 BIO_puts(sbio, "\er\enConnection Established\er\enRequest headers:\er\en");
518 BIO_puts(sbio, "--------------------------------------------------\er\en");
520 for (;;) {
521 len = BIO_gets(sbio, tmpbuf, 1024);
522 if (len <= 0)
523 break;
524 BIO_write(sbio, tmpbuf, len);
525 BIO_write(out, tmpbuf, len);
526 /* Look for blank line signifying end of headers */
527 if ((tmpbuf[0] == '\er') || (tmpbuf[0] == '\en'))
528 break;
529 }
531 BIO_puts(sbio, "--------------------------------------------------\er\en");
532 BIO_puts(sbio, "\er\en");
534 /* Since there is a buffering BIO present we had better flush it */
535 BIO_flush(sbio);
537 BIO_free_all(sbio);
538 .Ed
539 .Sh HISTORY
540 In OpenSSL versions before 1.0.0 the
541 .Xr BIO_pop 3
542 call was handled incorrectly:
543 the I/O BIO reference count was incorrectly incremented (instead of
544 decremented) and dissociated with the
545 .Vt SSL
546 .Vt BIO
547 even if the
548 .Vt SSL
549 .Vt BIO
550 was not
551 explicitly being popped (e.g., a pop higher up the chain).
552 Applications which included workarounds for this bug (e.g., freeing BIOs more
553 than once) should be modified to handle this fix or they may free up an already
554 freed
555 .Vt BIO .