1.\" $OpenBSD: BIO_f_ssl.3,v 1.16 2024/01/13 18:37:51 tb 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: January 13 2024 $ 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 373When called on an SSL BIO object, 374.Xr BIO_method_type 3 375returns the constant 376.Dv BIO_TYPE_SSL 377and 378.Xr BIO_method_name 3 379returns a pointer to the static string 380.Qq ssl . 381.Pp 382.Fn BIO_set_ssl , 383.Fn BIO_get_ssl , 384.Fn BIO_set_ssl_mode , 385.Fn BIO_set_ssl_renegotiate_bytes , 386.Fn BIO_set_ssl_renegotiate_timeout , 387and 388.Fn BIO_get_num_renegotiates 389return 1 on success or a value less than or equal to 0 390if an error occurred. 391.Pp 392.Fn BIO_new_ssl , 393.Fn BIO_new_ssl_connect , 394and 395.Fn BIO_new_buffer_ssl_connect 396returns a pointer to a newly allocated 397.Vt BIO 398chain or 399.Dv NULL 400if an error occurred. 401.Pp 402.Fn BIO_ssl_copy_session_id 403returns 1 on success or 0 on error. 404.Pp 405.Fn BIO_do_handshake 406returns 1 if the connection was established successfully 407or a value less than or equal to 0 otherwise. 408.Sh EXAMPLES 409This SSL/TLS client example attempts to retrieve a page from an SSL/TLS web 410server. 411The I/O routines are identical to those of the unencrypted example in 412.Xr BIO_s_connect 3 . 413.Bd -literal 414BIO *sbio, *out; 415int len; 416char tmpbuf[1024]; 417SSL_CTX *ctx; 418SSL *ssl; 419 420ERR_load_crypto_strings(); 421ERR_load_SSL_strings(); 422OpenSSL_add_all_algorithms(); 423 424/* 425 * We would seed the PRNG here if the platform didn't do it automatically 426 */ 427 428ctx = SSL_CTX_new(SSLv23_client_method()); 429 430/* 431 * We'd normally set some stuff like the verify paths and mode here because 432 * as things stand this will connect to any server whose certificate is 433 * signed by any CA. 434 */ 435 436sbio = BIO_new_ssl_connect(ctx); 437 438BIO_get_ssl(sbio, &ssl); 439 440if (!ssl) { 441 fprintf(stderr, "Can't locate SSL pointer\en"); 442 /* whatever ... */ 443} 444 445/* Don't want any retries */ 446SSL_set_mode(ssl, SSL_MODE_AUTO_RETRY); 447 448/* We might want to do other things with ssl here */ 449 450BIO_set_conn_hostname(sbio, "localhost:https"); 451 452out = BIO_new_fp(stdout, BIO_NOCLOSE); 453if (BIO_do_connect(sbio) <= 0) { 454 fprintf(stderr, "Error connecting to server\en"); 455 ERR_print_errors_fp(stderr); 456 /* whatever ... */ 457} 458 459if (BIO_do_handshake(sbio) <= 0) { 460 fprintf(stderr, "Error establishing SSL connection\en"); 461 ERR_print_errors_fp(stderr); 462 /* whatever ... */ 463} 464 465/* Could examine ssl here to get connection info */ 466 467BIO_puts(sbio, "GET / HTTP/1.0\en\en"); 468for (;;) { 469 len = BIO_read(sbio, tmpbuf, 1024); 470 if(len <= 0) break; 471 BIO_write(out, tmpbuf, len); 472} 473BIO_free_all(sbio); 474BIO_free(out); 475.Ed 476.Pp 477Here is a simple server example. 478It makes use of a buffering 479.Vt BIO 480to allow lines to be read from the 481.Vt SSL 482.Vt BIO 483using 484.Xr BIO_gets 3 . 485It creates a pseudo web page containing the actual request from a client and 486also echoes the request to standard output. 487.Bd -literal 488BIO *sbio, *bbio, *acpt, *out; 489int len; 490char tmpbuf[1024]; 491SSL_CTX *ctx; 492SSL *ssl; 493 494ctx = SSL_CTX_new(SSLv23_server_method()); 495 496if (!SSL_CTX_use_certificate_file(ctx,"server.pem",SSL_FILETYPE_PEM) 497 || !SSL_CTX_use_PrivateKey_file(ctx,"server.pem",SSL_FILETYPE_PEM) 498 || !SSL_CTX_check_private_key(ctx)) { 499 fprintf(stderr, "Error setting up SSL_CTX\en"); 500 ERR_print_errors_fp(stderr); 501 return 0; 502} 503 504/* 505 * Might do other things here like setting verify locations and DH and/or 506 * RSA temporary key callbacks 507 */ 508 509/* New SSL BIO setup as server */ 510sbio = BIO_new_ssl(ctx,0); 511 512BIO_get_ssl(sbio, &ssl); 513 514if (!ssl) { 515 fprintf(stderr, "Can't locate SSL pointer\en"); 516 /* whatever ... */ 517} 518 519/* Don't want any retries */ 520SSL_set_mode(ssl, SSL_MODE_AUTO_RETRY); 521 522/* Create the buffering BIO */ 523 524bbio = BIO_new(BIO_f_buffer()); 525 526/* Add to chain */ 527sbio = BIO_push(bbio, sbio); 528 529acpt = BIO_new_accept("4433"); 530 531/* 532 * By doing this when a new connection is established we automatically 533 * have sbio inserted into it. The BIO chain is now 'swallowed' by the 534 * accept BIO and will be freed when the accept BIO is freed. 535 */ 536 537BIO_set_accept_bios(acpt,sbio); 538 539out = BIO_new_fp(stdout, BIO_NOCLOSE); 540 541/* Wait for incoming connection */ 542if (BIO_do_accept(acpt) <= 0) { 543 fprintf(stderr, "Error setting up accept BIO\en"); 544 ERR_print_errors_fp(stderr); 545 return 0; 546} 547 548/* We only want one connection so remove and free accept BIO */ 549 550sbio = BIO_pop(acpt); 551 552BIO_free_all(acpt); 553 554if (BIO_do_handshake(sbio) <= 0) { 555 fprintf(stderr, "Error in SSL handshake\en"); 556 ERR_print_errors_fp(stderr); 557 return 0; 558} 559 560BIO_puts(sbio, "HTTP/1.0 200 OK\er\enContent-type: text/plain\er\en\er\en"); 561BIO_puts(sbio, "\er\enConnection Established\er\enRequest headers:\er\en"); 562BIO_puts(sbio, "--------------------------------------------------\er\en"); 563 564for (;;) { 565 len = BIO_gets(sbio, tmpbuf, 1024); 566 if (len <= 0) 567 break; 568 BIO_write(sbio, tmpbuf, len); 569 BIO_write(out, tmpbuf, len); 570 /* Look for blank line signifying end of headers */ 571 if ((tmpbuf[0] == '\er') || (tmpbuf[0] == '\en')) 572 break; 573} 574 575BIO_puts(sbio, "--------------------------------------------------\er\en"); 576BIO_puts(sbio, "\er\en"); 577 578/* Since there is a buffering BIO present we had better flush it */ 579BIO_flush(sbio); 580 581BIO_free_all(sbio); 582.Ed 583.Sh SEE ALSO 584.Xr BIO_new 3 , 585.Xr ssl 3 586.Sh HISTORY 587.Fn BIO_f_ssl , 588.Fn BIO_set_ssl , 589and 590.Fn BIO_get_ssl 591first appeared in SSLeay 0.6.0. 592.Fn BIO_set_ssl_mode , 593.Fn BIO_new_ssl , 594and 595.Fn BIO_ssl_copy_session_id 596first appeared in SSLeay 0.8.0. 597.Fn BIO_ssl_shutdown 598and 599.Fn BIO_do_handshake 600first appeared in SSLeay 0.8.1. 601.Fn BIO_set_ssl_renegotiate_bytes , 602.Fn BIO_get_num_renegotiates , 603.Fn BIO_set_ssl_renegotiate_timeout , 604.Fn BIO_new_ssl_connect , 605and 606.Fn BIO_new_buffer_ssl_connect 607first appeared in SSLeay 0.9.0. 608All these functions have been available since 609.Ox 2.4 . 610