| blob | 6826441e81485207dbccad59a7e9ee680a8c0f20 |
1 .\" $OpenBSD: BIO_f_ssl.3,v 1.8 2018/03/21 08:06:34 schwarze Exp $
2 .\" full merge up to: OpenSSL f672aee4 Feb 9 11:52:40 2016 -0500
3 .\" selective merge up to: OpenSSL 61f805c1 Jan 16 01:01:46 2018 +0800
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: March 21 2018 $
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 .Fn BIO_f_ssl
357 returns a pointer to a static
358 .Vt BIO_METHOD
359 structure.
360 .Pp
361 .Fn BIO_set_ssl ,
362 .Fn BIO_get_ssl ,
363 .Fn BIO_set_ssl_mode ,
364 .Fn BIO_set_ssl_renegotiate_bytes ,
365 .Fn BIO_set_ssl_renegotiate_timeout ,
366 and
367 .Fn BIO_get_num_renegotiates
368 return 1 on success or a value less than or equal to 0
369 if an error occurred.
370 .Pp
371 .Fn BIO_new_ssl ,
372 .Fn BIO_new_ssl_connect ,
373 and
374 .Fn BIO_new_buffer_ssl_connect
375 returns a pointer to a newly allocated
376 .Vt BIO
377 chain or
378 .Dv NULL
379 if an error occurred.
380 .Pp
381 .Fn BIO_ssl_copy_session_id
382 returns 1 on success or 0 on error.
383 .Pp
384 .Fn BIO_do_handshake
385 returns 1 if the connection was established successfully
386 or a value less than or equal to 0 otherwise.
387 .Sh EXAMPLES
388 This SSL/TLS client example attempts to retrieve a page from an SSL/TLS web
389 server.
390 The I/O routines are identical to those of the unencrypted example in
391 .Xr BIO_s_connect 3 .
392 .Bd -literal
393 BIO *sbio, *out;
394 int len;
395 char tmpbuf[1024];
396 SSL_CTX *ctx;
397 SSL *ssl;
399 ERR_load_crypto_strings();
400 ERR_load_SSL_strings();
401 OpenSSL_add_all_algorithms();
403 /*
404 * We would seed the PRNG here if the platform didn't do it automatically
405 */
407 ctx = SSL_CTX_new(SSLv23_client_method());
409 /*
410 * We'd normally set some stuff like the verify paths and mode here because
411 * as things stand this will connect to any server whose certificate is
412 * signed by any CA.
413 */
415 sbio = BIO_new_ssl_connect(ctx);
417 BIO_get_ssl(sbio, &ssl);
419 if (!ssl) {
420 fprintf(stderr, "Can't locate SSL pointer\en");
421 /* whatever ... */
422 }
424 /* Don't want any retries */
425 SSL_set_mode(ssl, SSL_MODE_AUTO_RETRY);
427 /* We might want to do other things with ssl here */
429 BIO_set_conn_hostname(sbio, "localhost:https");
431 out = BIO_new_fp(stdout, BIO_NOCLOSE);
432 if (BIO_do_connect(sbio) <= 0) {
433 fprintf(stderr, "Error connecting to server\en");
434 ERR_print_errors_fp(stderr);
435 /* whatever ... */
436 }
438 if (BIO_do_handshake(sbio) <= 0) {
439 fprintf(stderr, "Error establishing SSL connection\en");
440 ERR_print_errors_fp(stderr);
441 /* whatever ... */
442 }
444 /* Could examine ssl here to get connection info */
446 BIO_puts(sbio, "GET / HTTP/1.0\en\en");
447 for (;;) {
448 len = BIO_read(sbio, tmpbuf, 1024);
449 if(len <= 0) break;
450 BIO_write(out, tmpbuf, len);
451 }
452 BIO_free_all(sbio);
453 BIO_free(out);
454 .Ed
455 .Pp
456 Here is a simple server example.
457 It makes use of a buffering
458 .Vt BIO
459 to allow lines to be read from the
460 .Vt SSL
461 .Vt BIO
462 using
463 .Xr BIO_gets 3 .
464 It creates a pseudo web page containing the actual request from a client and
465 also echoes the request to standard output.
466 .Bd -literal
467 BIO *sbio, *bbio, *acpt, *out;
468 int len;
469 char tmpbuf[1024];
470 SSL_CTX *ctx;
471 SSL *ssl;
473 ERR_load_crypto_strings();
474 ERR_load_SSL_strings();
475 OpenSSL_add_all_algorithms();
477 /* Might seed PRNG here */
479 ctx = SSL_CTX_new(SSLv23_server_method());
481 if (!SSL_CTX_use_certificate_file(ctx,"server.pem",SSL_FILETYPE_PEM)
482 || !SSL_CTX_use_PrivateKey_file(ctx,"server.pem",SSL_FILETYPE_PEM)
483 || !SSL_CTX_check_private_key(ctx)) {
484 fprintf(stderr, "Error setting up SSL_CTX\en");
485 ERR_print_errors_fp(stderr);
486 return 0;
487 }
489 /*
490 * Might do other things here like setting verify locations and DH and/or
491 * RSA temporary key callbacks
492 */
494 /* New SSL BIO setup as server */
495 sbio = BIO_new_ssl(ctx,0);
497 BIO_get_ssl(sbio, &ssl);
499 if (!ssl) {
500 fprintf(stderr, "Can't locate SSL pointer\en");
501 /* whatever ... */
502 }
504 /* Don't want any retries */
505 SSL_set_mode(ssl, SSL_MODE_AUTO_RETRY);
507 /* Create the buffering BIO */
509 bbio = BIO_new(BIO_f_buffer());
511 /* Add to chain */
512 sbio = BIO_push(bbio, sbio);
514 acpt = BIO_new_accept("4433");
516 /*
517 * By doing this when a new connection is established we automatically
518 * have sbio inserted into it. The BIO chain is now 'swallowed' by the
519 * accept BIO and will be freed when the accept BIO is freed.
520 */
522 BIO_set_accept_bios(acpt,sbio);
524 out = BIO_new_fp(stdout, BIO_NOCLOSE);
526 /* Wait for incoming connection */
527 if (BIO_do_accept(acpt) <= 0) {
528 fprintf(stderr, "Error setting up accept BIO\en");
529 ERR_print_errors_fp(stderr);
530 return 0;
531 }
533 /* We only want one connection so remove and free accept BIO */
535 sbio = BIO_pop(acpt);
537 BIO_free_all(acpt);
539 if (BIO_do_handshake(sbio) <= 0) {
540 fprintf(stderr, "Error in SSL handshake\en");
541 ERR_print_errors_fp(stderr);
542 return 0;
543 }
545 BIO_puts(sbio, "HTTP/1.0 200 OK\er\enContent-type: text/plain\er\en\er\en");
546 BIO_puts(sbio, "\er\enConnection Established\er\enRequest headers:\er\en");
547 BIO_puts(sbio, "--------------------------------------------------\er\en");
549 for (;;) {
550 len = BIO_gets(sbio, tmpbuf, 1024);
551 if (len <= 0)
552 break;
553 BIO_write(sbio, tmpbuf, len);
554 BIO_write(out, tmpbuf, len);
555 /* Look for blank line signifying end of headers */
556 if ((tmpbuf[0] == '\er') || (tmpbuf[0] == '\en'))
557 break;
558 }
560 BIO_puts(sbio, "--------------------------------------------------\er\en");
561 BIO_puts(sbio, "\er\en");
563 /* Since there is a buffering BIO present we had better flush it */
564 BIO_flush(sbio);
566 BIO_free_all(sbio);
567 .Ed
568 .Sh HISTORY
569 .Fn BIO_f_ssl ,
570 .Fn BIO_set_ssl ,
571 .Fn BIO_get_ssl ,
572 .Fn BIO_set_ssl_mode ,
573 .Fn BIO_new_ssl ,
574 .Fn BIO_ssl_copy_session_id ,
575 .Fn BIO_ssl_shutdown ,
576 and
577 .Fn BIO_do_handshake
578 appeared before SSLeay 0.8.
579 .Fn BIO_set_ssl_renegotiate_bytes ,
580 .Fn BIO_get_num_renegotiates ,
581 .Fn BIO_set_ssl_renegotiate_timeout ,
582 .Fn BIO_new_ssl_connect ,
583 and
584 .Fn BIO_new_buffer_ssl_connect
585 first appeared in SSLeay 0.9.0.
586 All these functions have been available since
587 .Ox 2.4 .
588 .Pp
589 In OpenSSL versions before 1.0.0 the
590 .Xr BIO_pop 3
591 call was handled incorrectly:
592 the I/O BIO reference count was incorrectly incremented (instead of
593 decremented) and dissociated with the
594 .Vt SSL
595 .Vt BIO
596 even if the
597 .Vt SSL
598 .Vt BIO
599 was not
600 explicitly being popped (e.g., a pop higher up the chain).
601 Applications which included workarounds for this bug (e.g., freeing BIOs more
602 than once) should be modified to handle this fix or they may free up an already
603 freed
604 .Vt BIO .