1.\" $OpenBSD: BIO_f_ssl.3,v 1.11 2019/06/12 09:36:30 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: June 12 2019 $ 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 const 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 120returns the 121.Vt SSL 122.Vt BIO 123method. 124This is a filter 125.Vt BIO 126which is a wrapper around the OpenSSL 127.Vt SSL 128routines adding a 129.Vt BIO 130.Dq flavor 131to SSL I/O. 132.Pp 133I/O performed on an 134.Vt SSL 135.Vt BIO 136communicates using the SSL protocol with 137the 138.Vt SSL Ns 's 139read and write 140.Vt BIO Ns s . 141If an SSL connection is not established then an attempt is made to establish 142one on the first I/O call. 143.Pp 144If a 145.Vt BIO 146is appended to an 147.Vt SSL 148.Vt BIO 149using 150.Xr BIO_push 3 151it is automatically used as the 152.Vt SSL 153.Vt BIO Ns 's read and write 154.Vt BIO Ns s . 155.Pp 156Calling 157.Xr BIO_reset 3 158on an 159.Vt SSL 160.Vt BIO 161closes down any current SSL connection by calling 162.Xr SSL_shutdown 3 . 163.Xr BIO_reset 3 164is then sent to the next 165.Vt BIO 166in the chain; this will typically disconnect the underlying transport. 167The 168.Vt SSL 169.Vt BIO 170is then reset to the initial accept or connect state. 171.Pp 172If the close flag is set when an 173.Vt SSL 174.Vt BIO 175is freed then the internal 176.Vt SSL 177structure is also freed using 178.Xr SSL_free 3 . 179.Pp 180.Fn BIO_set_ssl 181sets the internal 182.Vt SSL 183pointer of 184.Vt BIO 185.Fa b 186to 187.Fa ssl 188using 189the close flag 190.Fa c . 191.Pp 192.Fn BIO_get_ssl 193retrieves the 194.Vt SSL 195pointer of 196.Vt BIO 197.Fa b ; 198it can then be manipulated using the standard SSL library functions. 199.Pp 200.Fn BIO_set_ssl_mode 201sets the 202.Vt SSL 203.Vt BIO 204mode to 205.Fa client . 206If 207.Fa client 208is 1, client mode is set. 209If 210.Fa client 211is 0, server mode is set. 212.Pp 213.Fn BIO_set_ssl_renegotiate_bytes 214sets the renegotiate byte count to 215.Fa num . 216When set after every 217.Fa num 218bytes of I/O (read and write) the SSL session is automatically renegotiated. 219.Fa num 220must be at least 512 bytes. 221.Pp 222.Fn BIO_set_ssl_renegotiate_timeout 223sets the renegotiate timeout to 224.Fa seconds . 225When the renegotiate timeout elapses the session is automatically renegotiated. 226.Pp 227.Fn BIO_get_num_renegotiates 228returns the total number of session renegotiations due to I/O or timeout. 229.Pp 230.Fn BIO_new_ssl 231allocates an 232.Vt SSL 233.Vt BIO 234using 235.Vt SSL_CTX 236.Va ctx 237and using client mode if 238.Fa client 239is nonzero. 240.Pp 241.Fn BIO_new_ssl_connect 242creates a new 243.Vt BIO 244chain consisting of an 245.Vt SSL 246.Vt BIO 247(using 248.Fa ctx ) 249followed by a connect BIO. 250.Pp 251.Fn BIO_new_buffer_ssl_connect 252creates a new 253.Vt BIO 254chain consisting of a buffering 255.Vt BIO , 256an 257.Vt SSL 258.Vt BIO 259(using 260.Fa ctx ) 261and a connect 262.Vt BIO . 263.Pp 264.Fn BIO_ssl_copy_session_id 265copies an SSL session id between 266.Vt BIO 267chains 268.Fa from 269and 270.Fa to . 271It does this by locating the 272.Vt SSL 273.Vt BIO Ns s 274in each chain and calling 275.Xr SSL_copy_session_id 3 276on the internal 277.Vt SSL 278pointer. 279.Pp 280.Fn BIO_ssl_shutdown 281closes down an SSL connection on 282.Vt BIO 283chain 284.Fa bio . 285It does this by locating the 286.Vt SSL 287.Vt BIO 288in the 289chain and calling 290.Xr SSL_shutdown 3 291on its internal 292.Vt SSL 293pointer. 294.Pp 295.Fn BIO_do_handshake 296attempts to complete an SSL handshake on the supplied 297.Vt BIO 298and establish the SSL connection. 299It returns 1 if the connection was established successfully. 300A zero or negative value is returned if the connection could not be 301established; the call 302.Xr BIO_should_retry 3 303should be used for non blocking connect 304.Vt BIO Ns s 305to determine if the call should be retried. 306If an SSL connection has already been established this call has no effect. 307.Pp 308.Vt SSL 309.Vt BIO Ns s 310are exceptional in that if the underlying transport is non-blocking they can 311still request a retry in exceptional circumstances. 312Specifically this will happen if a session renegotiation takes place during a 313.Xr BIO_read 3 314operation. 315One case where this happens is when step up occurs. 316.Pp 317In OpenSSL 0.9.6 and later the SSL flag 318.Dv SSL_AUTO_RETRY 319can be set to disable this behaviour. 320In other words, when this flag is set an 321.Vt SSL 322.Vt BIO 323using a blocking transport will never request a retry. 324.Pp 325Since unknown 326.Xr BIO_ctrl 3 327operations are sent through filter 328.Vt BIO Ns s 329the server name and port can be set using 330.Xr BIO_set_conn_hostname 3 331and 332.Xr BIO_set_conn_port 3 333on the 334.Vt BIO 335returned by 336.Fn BIO_new_ssl_connect 337without having to locate the connect 338.Vt BIO 339first. 340.Pp 341Applications do not have to call 342.Fn BIO_do_handshake 343but may wish to do so to separate the handshake process from other I/O 344processing. 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 , 352and 353.Fn BIO_do_handshake 354are implemented as macros. 355.Sh RETURN VALUES 356.Fn BIO_f_ssl 357returns a pointer to a static 358.Vt BIO_METHOD 359structure. 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 , 366and 367.Fn BIO_get_num_renegotiates 368return 1 on success or a value less than or equal to 0 369if an error occurred. 370.Pp 371.Fn BIO_new_ssl , 372.Fn BIO_new_ssl_connect , 373and 374.Fn BIO_new_buffer_ssl_connect 375returns a pointer to a newly allocated 376.Vt BIO 377chain or 378.Dv NULL 379if an error occurred. 380.Pp 381.Fn BIO_ssl_copy_session_id 382returns 1 on success or 0 on error. 383.Pp 384.Fn BIO_do_handshake 385returns 1 if the connection was established successfully 386or a value less than or equal to 0 otherwise. 387.Sh EXAMPLES 388This SSL/TLS client example attempts to retrieve a page from an SSL/TLS web 389server. 390The I/O routines are identical to those of the unencrypted example in 391.Xr BIO_s_connect 3 . 392.Bd -literal 393BIO *sbio, *out; 394int len; 395char tmpbuf[1024]; 396SSL_CTX *ctx; 397SSL *ssl; 398 399ERR_load_crypto_strings(); 400ERR_load_SSL_strings(); 401OpenSSL_add_all_algorithms(); 402 403/* 404 * We would seed the PRNG here if the platform didn't do it automatically 405 */ 406 407ctx = SSL_CTX_new(SSLv23_client_method()); 408 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 */ 414 415sbio = BIO_new_ssl_connect(ctx); 416 417BIO_get_ssl(sbio, &ssl); 418 419if (!ssl) { 420 fprintf(stderr, "Can't locate SSL pointer\en"); 421 /* whatever ... */ 422} 423 424/* Don't want any retries */ 425SSL_set_mode(ssl, SSL_MODE_AUTO_RETRY); 426 427/* We might want to do other things with ssl here */ 428 429BIO_set_conn_hostname(sbio, "localhost:https"); 430 431out = BIO_new_fp(stdout, BIO_NOCLOSE); 432if (BIO_do_connect(sbio) <= 0) { 433 fprintf(stderr, "Error connecting to server\en"); 434 ERR_print_errors_fp(stderr); 435 /* whatever ... */ 436} 437 438if (BIO_do_handshake(sbio) <= 0) { 439 fprintf(stderr, "Error establishing SSL connection\en"); 440 ERR_print_errors_fp(stderr); 441 /* whatever ... */ 442} 443 444/* Could examine ssl here to get connection info */ 445 446BIO_puts(sbio, "GET / HTTP/1.0\en\en"); 447for (;;) { 448 len = BIO_read(sbio, tmpbuf, 1024); 449 if(len <= 0) break; 450 BIO_write(out, tmpbuf, len); 451} 452BIO_free_all(sbio); 453BIO_free(out); 454.Ed 455.Pp 456Here is a simple server example. 457It makes use of a buffering 458.Vt BIO 459to allow lines to be read from the 460.Vt SSL 461.Vt BIO 462using 463.Xr BIO_gets 3 . 464It creates a pseudo web page containing the actual request from a client and 465also echoes the request to standard output. 466.Bd -literal 467BIO *sbio, *bbio, *acpt, *out; 468int len; 469char tmpbuf[1024]; 470SSL_CTX *ctx; 471SSL *ssl; 472 473ERR_load_crypto_strings(); 474ERR_load_SSL_strings(); 475OpenSSL_add_all_algorithms(); 476 477/* Might seed PRNG here */ 478 479ctx = SSL_CTX_new(SSLv23_server_method()); 480 481if (!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} 488 489/* 490 * Might do other things here like setting verify locations and DH and/or 491 * RSA temporary key callbacks 492 */ 493 494/* New SSL BIO setup as server */ 495sbio = BIO_new_ssl(ctx,0); 496 497BIO_get_ssl(sbio, &ssl); 498 499if (!ssl) { 500 fprintf(stderr, "Can't locate SSL pointer\en"); 501 /* whatever ... */ 502} 503 504/* Don't want any retries */ 505SSL_set_mode(ssl, SSL_MODE_AUTO_RETRY); 506 507/* Create the buffering BIO */ 508 509bbio = BIO_new(BIO_f_buffer()); 510 511/* Add to chain */ 512sbio = BIO_push(bbio, sbio); 513 514acpt = BIO_new_accept("4433"); 515 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 */ 521 522BIO_set_accept_bios(acpt,sbio); 523 524out = BIO_new_fp(stdout, BIO_NOCLOSE); 525 526/* Wait for incoming connection */ 527if (BIO_do_accept(acpt) <= 0) { 528 fprintf(stderr, "Error setting up accept BIO\en"); 529 ERR_print_errors_fp(stderr); 530 return 0; 531} 532 533/* We only want one connection so remove and free accept BIO */ 534 535sbio = BIO_pop(acpt); 536 537BIO_free_all(acpt); 538 539if (BIO_do_handshake(sbio) <= 0) { 540 fprintf(stderr, "Error in SSL handshake\en"); 541 ERR_print_errors_fp(stderr); 542 return 0; 543} 544 545BIO_puts(sbio, "HTTP/1.0 200 OK\er\enContent-type: text/plain\er\en\er\en"); 546BIO_puts(sbio, "\er\enConnection Established\er\enRequest headers:\er\en"); 547BIO_puts(sbio, "--------------------------------------------------\er\en"); 548 549for (;;) { 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} 559 560BIO_puts(sbio, "--------------------------------------------------\er\en"); 561BIO_puts(sbio, "\er\en"); 562 563/* Since there is a buffering BIO present we had better flush it */ 564BIO_flush(sbio); 565 566BIO_free_all(sbio); 567.Ed 568.Sh SEE ALSO 569.Xr BIO_new 3 , 570.Xr ssl 3 571.Sh HISTORY 572.Fn BIO_f_ssl , 573.Fn BIO_set_ssl , 574and 575.Fn BIO_get_ssl 576first appeared in SSLeay 0.6.0. 577.Fn BIO_set_ssl_mode , 578.Fn BIO_new_ssl , 579and 580.Fn BIO_ssl_copy_session_id 581first appeared in SSLeay 0.8.0. 582.Fn BIO_ssl_shutdown 583and 584.Fn BIO_do_handshake 585first appeared in SSLeay 0.8.1. 586.Fn BIO_set_ssl_renegotiate_bytes , 587.Fn BIO_get_num_renegotiates , 588.Fn BIO_set_ssl_renegotiate_timeout , 589.Fn BIO_new_ssl_connect , 590and 591.Fn BIO_new_buffer_ssl_connect 592first appeared in SSLeay 0.9.0. 593All these functions have been available since 594.Ox 2.4 . 595.Pp 596In OpenSSL versions before 1.0.0 the 597.Xr BIO_pop 3 598call was handled incorrectly: 599the I/O BIO reference count was incorrectly incremented (instead of 600decremented) and dissociated with the 601.Vt SSL 602.Vt BIO 603even if the 604.Vt SSL 605.Vt BIO 606was not 607explicitly being popped (e.g., a pop higher up the chain). 608Applications which included workarounds for this bug (e.g., freeing BIOs more 609than once) should be modified to handle this fix or they may free up an already 610freed 611.Vt BIO . 612