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