1.\" $OpenBSD: BIO_f_ssl.3,v 1.13 2022/12/18 20:24:52 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: December 18 2022 $ 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 308When a chain containing an SSL BIO is copied with 309.Xr BIO_dup_chain 3 , 310.Xr SSL_dup 3 311is called internally to copy the 312.Vt SSL 313object from the existing BIO object to the new BIO object, 314and the internal data related to 315.Fn BIO_set_ssl_renegotiate_bytes 316and 317.Fn BIO_set_ssl_renegotiate_timeout 318is also copied. 319.Pp 320.Vt SSL 321.Vt BIO Ns s 322are exceptional in that if the underlying transport is non-blocking they can 323still request a retry in exceptional circumstances. 324Specifically this will happen if a session renegotiation takes place during a 325.Xr BIO_read 3 326operation. 327One case where this happens is when step up occurs. 328.Pp 329In OpenSSL 0.9.6 and later the SSL flag 330.Dv SSL_AUTO_RETRY 331can be set to disable this behaviour. 332In other words, when this flag is set an 333.Vt SSL 334.Vt BIO 335using a blocking transport will never request a retry. 336.Pp 337Since unknown 338.Xr BIO_ctrl 3 339operations are sent through filter 340.Vt BIO Ns s , 341the server name and port can be set using 342.Xr BIO_set_conn_hostname 3 343and 344.Xr BIO_set_conn_port 3 345on the 346.Vt BIO 347returned by 348.Fn BIO_new_ssl_connect 349without having to locate the connect 350.Vt BIO 351first. 352.Pp 353Applications do not have to call 354.Fn BIO_do_handshake 355but may wish to do so to separate the handshake process from other I/O 356processing. 357.Pp 358.Fn BIO_set_ssl , 359.Fn BIO_get_ssl , 360.Fn BIO_set_ssl_mode , 361.Fn BIO_set_ssl_renegotiate_bytes , 362.Fn BIO_set_ssl_renegotiate_timeout , 363.Fn BIO_get_num_renegotiates , 364and 365.Fn BIO_do_handshake 366are implemented as macros. 367.Sh RETURN VALUES 368.Fn BIO_f_ssl 369returns a pointer to a static 370.Vt BIO_METHOD 371structure. 372.Pp 373.Fn BIO_set_ssl , 374.Fn BIO_get_ssl , 375.Fn BIO_set_ssl_mode , 376.Fn BIO_set_ssl_renegotiate_bytes , 377.Fn BIO_set_ssl_renegotiate_timeout , 378and 379.Fn BIO_get_num_renegotiates 380return 1 on success or a value less than or equal to 0 381if an error occurred. 382.Pp 383.Fn BIO_new_ssl , 384.Fn BIO_new_ssl_connect , 385and 386.Fn BIO_new_buffer_ssl_connect 387returns a pointer to a newly allocated 388.Vt BIO 389chain or 390.Dv NULL 391if an error occurred. 392.Pp 393.Fn BIO_ssl_copy_session_id 394returns 1 on success or 0 on error. 395.Pp 396.Fn BIO_do_handshake 397returns 1 if the connection was established successfully 398or a value less than or equal to 0 otherwise. 399.Sh EXAMPLES 400This SSL/TLS client example attempts to retrieve a page from an SSL/TLS web 401server. 402The I/O routines are identical to those of the unencrypted example in 403.Xr BIO_s_connect 3 . 404.Bd -literal 405BIO *sbio, *out; 406int len; 407char tmpbuf[1024]; 408SSL_CTX *ctx; 409SSL *ssl; 410 411ERR_load_crypto_strings(); 412ERR_load_SSL_strings(); 413OpenSSL_add_all_algorithms(); 414 415/* 416 * We would seed the PRNG here if the platform didn't do it automatically 417 */ 418 419ctx = SSL_CTX_new(SSLv23_client_method()); 420 421/* 422 * We'd normally set some stuff like the verify paths and mode here because 423 * as things stand this will connect to any server whose certificate is 424 * signed by any CA. 425 */ 426 427sbio = BIO_new_ssl_connect(ctx); 428 429BIO_get_ssl(sbio, &ssl); 430 431if (!ssl) { 432 fprintf(stderr, "Can't locate SSL pointer\en"); 433 /* whatever ... */ 434} 435 436/* Don't want any retries */ 437SSL_set_mode(ssl, SSL_MODE_AUTO_RETRY); 438 439/* We might want to do other things with ssl here */ 440 441BIO_set_conn_hostname(sbio, "localhost:https"); 442 443out = BIO_new_fp(stdout, BIO_NOCLOSE); 444if (BIO_do_connect(sbio) <= 0) { 445 fprintf(stderr, "Error connecting to server\en"); 446 ERR_print_errors_fp(stderr); 447 /* whatever ... */ 448} 449 450if (BIO_do_handshake(sbio) <= 0) { 451 fprintf(stderr, "Error establishing SSL connection\en"); 452 ERR_print_errors_fp(stderr); 453 /* whatever ... */ 454} 455 456/* Could examine ssl here to get connection info */ 457 458BIO_puts(sbio, "GET / HTTP/1.0\en\en"); 459for (;;) { 460 len = BIO_read(sbio, tmpbuf, 1024); 461 if(len <= 0) break; 462 BIO_write(out, tmpbuf, len); 463} 464BIO_free_all(sbio); 465BIO_free(out); 466.Ed 467.Pp 468Here is a simple server example. 469It makes use of a buffering 470.Vt BIO 471to allow lines to be read from the 472.Vt SSL 473.Vt BIO 474using 475.Xr BIO_gets 3 . 476It creates a pseudo web page containing the actual request from a client and 477also echoes the request to standard output. 478.Bd -literal 479BIO *sbio, *bbio, *acpt, *out; 480int len; 481char tmpbuf[1024]; 482SSL_CTX *ctx; 483SSL *ssl; 484 485ERR_load_crypto_strings(); 486ERR_load_SSL_strings(); 487OpenSSL_add_all_algorithms(); 488 489/* Might seed PRNG here */ 490 491ctx = SSL_CTX_new(SSLv23_server_method()); 492 493if (!SSL_CTX_use_certificate_file(ctx,"server.pem",SSL_FILETYPE_PEM) 494 || !SSL_CTX_use_PrivateKey_file(ctx,"server.pem",SSL_FILETYPE_PEM) 495 || !SSL_CTX_check_private_key(ctx)) { 496 fprintf(stderr, "Error setting up SSL_CTX\en"); 497 ERR_print_errors_fp(stderr); 498 return 0; 499} 500 501/* 502 * Might do other things here like setting verify locations and DH and/or 503 * RSA temporary key callbacks 504 */ 505 506/* New SSL BIO setup as server */ 507sbio = BIO_new_ssl(ctx,0); 508 509BIO_get_ssl(sbio, &ssl); 510 511if (!ssl) { 512 fprintf(stderr, "Can't locate SSL pointer\en"); 513 /* whatever ... */ 514} 515 516/* Don't want any retries */ 517SSL_set_mode(ssl, SSL_MODE_AUTO_RETRY); 518 519/* Create the buffering BIO */ 520 521bbio = BIO_new(BIO_f_buffer()); 522 523/* Add to chain */ 524sbio = BIO_push(bbio, sbio); 525 526acpt = BIO_new_accept("4433"); 527 528/* 529 * By doing this when a new connection is established we automatically 530 * have sbio inserted into it. The BIO chain is now 'swallowed' by the 531 * accept BIO and will be freed when the accept BIO is freed. 532 */ 533 534BIO_set_accept_bios(acpt,sbio); 535 536out = BIO_new_fp(stdout, BIO_NOCLOSE); 537 538/* Wait for incoming connection */ 539if (BIO_do_accept(acpt) <= 0) { 540 fprintf(stderr, "Error setting up accept BIO\en"); 541 ERR_print_errors_fp(stderr); 542 return 0; 543} 544 545/* We only want one connection so remove and free accept BIO */ 546 547sbio = BIO_pop(acpt); 548 549BIO_free_all(acpt); 550 551if (BIO_do_handshake(sbio) <= 0) { 552 fprintf(stderr, "Error in SSL handshake\en"); 553 ERR_print_errors_fp(stderr); 554 return 0; 555} 556 557BIO_puts(sbio, "HTTP/1.0 200 OK\er\enContent-type: text/plain\er\en\er\en"); 558BIO_puts(sbio, "\er\enConnection Established\er\enRequest headers:\er\en"); 559BIO_puts(sbio, "--------------------------------------------------\er\en"); 560 561for (;;) { 562 len = BIO_gets(sbio, tmpbuf, 1024); 563 if (len <= 0) 564 break; 565 BIO_write(sbio, tmpbuf, len); 566 BIO_write(out, tmpbuf, len); 567 /* Look for blank line signifying end of headers */ 568 if ((tmpbuf[0] == '\er') || (tmpbuf[0] == '\en')) 569 break; 570} 571 572BIO_puts(sbio, "--------------------------------------------------\er\en"); 573BIO_puts(sbio, "\er\en"); 574 575/* Since there is a buffering BIO present we had better flush it */ 576BIO_flush(sbio); 577 578BIO_free_all(sbio); 579.Ed 580.Sh SEE ALSO 581.Xr BIO_new 3 , 582.Xr ssl 3 583.Sh HISTORY 584.Fn BIO_f_ssl , 585.Fn BIO_set_ssl , 586and 587.Fn BIO_get_ssl 588first appeared in SSLeay 0.6.0. 589.Fn BIO_set_ssl_mode , 590.Fn BIO_new_ssl , 591and 592.Fn BIO_ssl_copy_session_id 593first appeared in SSLeay 0.8.0. 594.Fn BIO_ssl_shutdown 595and 596.Fn BIO_do_handshake 597first appeared in SSLeay 0.8.1. 598.Fn BIO_set_ssl_renegotiate_bytes , 599.Fn BIO_get_num_renegotiates , 600.Fn BIO_set_ssl_renegotiate_timeout , 601.Fn BIO_new_ssl_connect , 602and 603.Fn BIO_new_buffer_ssl_connect 604first appeared in SSLeay 0.9.0. 605All these functions have been available since 606.Ox 2.4 . 607.Pp 608In OpenSSL versions before 1.0.0 the 609.Xr BIO_pop 3 610call was handled incorrectly: 611the I/O BIO reference count was incorrectly incremented (instead of 612decremented) and dissociated with the 613.Vt SSL 614.Vt BIO 615even if the 616.Vt SSL 617.Vt BIO 618was not 619explicitly being popped (e.g., a pop higher up the chain). 620Applications which included workarounds for this bug (e.g., freeing BIOs more 621than once) should be modified to handle this fix or they may free up an already 622freed 623.Vt BIO . 624