1e71b7053SJung-uk Kim=pod 2e71b7053SJung-uk Kim 3e71b7053SJung-uk Kim=head1 NAME 4e71b7053SJung-uk Kim 5e71b7053SJung-uk KimBIO_do_handshake, 6e71b7053SJung-uk KimBIO_f_ssl, BIO_set_ssl, BIO_get_ssl, BIO_set_ssl_mode, 7e71b7053SJung-uk KimBIO_set_ssl_renegotiate_bytes, 8e71b7053SJung-uk KimBIO_get_num_renegotiates, BIO_set_ssl_renegotiate_timeout, BIO_new_ssl, 9e71b7053SJung-uk KimBIO_new_ssl_connect, BIO_new_buffer_ssl_connect, BIO_ssl_copy_session_id, 10e71b7053SJung-uk KimBIO_ssl_shutdown - SSL BIO 11e71b7053SJung-uk Kim 12e71b7053SJung-uk Kim=head1 SYNOPSIS 13e71b7053SJung-uk Kim 14b077aed3SPierre Pronchery=for openssl multiple includes 15e71b7053SJung-uk Kim 16e71b7053SJung-uk Kim #include <openssl/bio.h> 17e71b7053SJung-uk Kim #include <openssl/ssl.h> 18e71b7053SJung-uk Kim 19e71b7053SJung-uk Kim const BIO_METHOD *BIO_f_ssl(void); 20e71b7053SJung-uk Kim 21e71b7053SJung-uk Kim long BIO_set_ssl(BIO *b, SSL *ssl, long c); 22e71b7053SJung-uk Kim long BIO_get_ssl(BIO *b, SSL **sslp); 23e71b7053SJung-uk Kim long BIO_set_ssl_mode(BIO *b, long client); 24e71b7053SJung-uk Kim long BIO_set_ssl_renegotiate_bytes(BIO *b, long num); 25e71b7053SJung-uk Kim long BIO_set_ssl_renegotiate_timeout(BIO *b, long seconds); 26e71b7053SJung-uk Kim long BIO_get_num_renegotiates(BIO *b); 27e71b7053SJung-uk Kim 28e71b7053SJung-uk Kim BIO *BIO_new_ssl(SSL_CTX *ctx, int client); 29e71b7053SJung-uk Kim BIO *BIO_new_ssl_connect(SSL_CTX *ctx); 30e71b7053SJung-uk Kim BIO *BIO_new_buffer_ssl_connect(SSL_CTX *ctx); 31e71b7053SJung-uk Kim int BIO_ssl_copy_session_id(BIO *to, BIO *from); 32e71b7053SJung-uk Kim void BIO_ssl_shutdown(BIO *bio); 33e71b7053SJung-uk Kim 34e71b7053SJung-uk Kim long BIO_do_handshake(BIO *b); 35e71b7053SJung-uk Kim 36e71b7053SJung-uk Kim=head1 DESCRIPTION 37e71b7053SJung-uk Kim 38e71b7053SJung-uk KimBIO_f_ssl() returns the SSL BIO method. This is a filter BIO which 39e71b7053SJung-uk Kimis a wrapper round the OpenSSL SSL routines adding a BIO "flavour" to 40e71b7053SJung-uk KimSSL I/O. 41e71b7053SJung-uk Kim 42e71b7053SJung-uk KimI/O performed on an SSL BIO communicates using the SSL protocol with 43e71b7053SJung-uk Kimthe SSLs read and write BIOs. If an SSL connection is not established 44e71b7053SJung-uk Kimthen an attempt is made to establish one on the first I/O call. 45e71b7053SJung-uk Kim 46e71b7053SJung-uk KimIf a BIO is appended to an SSL BIO using BIO_push() it is automatically 47e71b7053SJung-uk Kimused as the SSL BIOs read and write BIOs. 48e71b7053SJung-uk Kim 49e71b7053SJung-uk KimCalling BIO_reset() on an SSL BIO closes down any current SSL connection 50e71b7053SJung-uk Kimby calling SSL_shutdown(). BIO_reset() is then sent to the next BIO in 51e71b7053SJung-uk Kimthe chain: this will typically disconnect the underlying transport. 52e71b7053SJung-uk KimThe SSL BIO is then reset to the initial accept or connect state. 53e71b7053SJung-uk Kim 54e71b7053SJung-uk KimIf the close flag is set when an SSL BIO is freed then the internal 55e71b7053SJung-uk KimSSL structure is also freed using SSL_free(). 56e71b7053SJung-uk Kim 57b2bf0c7eSJung-uk KimBIO_set_ssl() sets the internal SSL pointer of SSL BIO B<b> to B<ssl> using 58e71b7053SJung-uk Kimthe close flag B<c>. 59e71b7053SJung-uk Kim 60b2bf0c7eSJung-uk KimBIO_get_ssl() retrieves the SSL pointer of SSL BIO B<b>, it can then be 61e71b7053SJung-uk Kimmanipulated using the standard SSL library functions. 62e71b7053SJung-uk Kim 63e71b7053SJung-uk KimBIO_set_ssl_mode() sets the SSL BIO mode to B<client>. If B<client> 64e71b7053SJung-uk Kimis 1 client mode is set. If B<client> is 0 server mode is set. 65e71b7053SJung-uk Kim 66b2bf0c7eSJung-uk KimBIO_set_ssl_renegotiate_bytes() sets the renegotiate byte count of SSL BIO B<b> 67e71b7053SJung-uk Kimto B<num>. When set after every B<num> bytes of I/O (read and write) 68e71b7053SJung-uk Kimthe SSL session is automatically renegotiated. B<num> must be at 69e71b7053SJung-uk Kimleast 512 bytes. 70e71b7053SJung-uk Kim 71b2bf0c7eSJung-uk KimBIO_set_ssl_renegotiate_timeout() sets the renegotiate timeout of SSL BIO B<b> 72b2bf0c7eSJung-uk Kimto B<seconds>. 73b2bf0c7eSJung-uk KimWhen the renegotiate timeout elapses the session is automatically renegotiated. 74e71b7053SJung-uk Kim 75e71b7053SJung-uk KimBIO_get_num_renegotiates() returns the total number of session 76b2bf0c7eSJung-uk Kimrenegotiations due to I/O or timeout of SSL BIO B<b>. 77e71b7053SJung-uk Kim 78e71b7053SJung-uk KimBIO_new_ssl() allocates an SSL BIO using SSL_CTX B<ctx> and using 79e71b7053SJung-uk Kimclient mode if B<client> is non zero. 80e71b7053SJung-uk Kim 81e71b7053SJung-uk KimBIO_new_ssl_connect() creates a new BIO chain consisting of an 82e71b7053SJung-uk KimSSL BIO (using B<ctx>) followed by a connect BIO. 83e71b7053SJung-uk Kim 84e71b7053SJung-uk KimBIO_new_buffer_ssl_connect() creates a new BIO chain consisting 85b2bf0c7eSJung-uk Kimof a buffering BIO, an SSL BIO (using B<ctx>), and a connect BIO. 86e71b7053SJung-uk Kim 87e71b7053SJung-uk KimBIO_ssl_copy_session_id() copies an SSL session id between 88e71b7053SJung-uk KimBIO chains B<from> and B<to>. It does this by locating the 89e71b7053SJung-uk KimSSL BIOs in each chain and calling SSL_copy_session_id() on 90e71b7053SJung-uk Kimthe internal SSL pointer. 91e71b7053SJung-uk Kim 92e71b7053SJung-uk KimBIO_ssl_shutdown() closes down an SSL connection on BIO 93e71b7053SJung-uk Kimchain B<bio>. It does this by locating the SSL BIO in the 94e71b7053SJung-uk Kimchain and calling SSL_shutdown() on its internal SSL 95e71b7053SJung-uk Kimpointer. 96e71b7053SJung-uk Kim 97e71b7053SJung-uk KimBIO_do_handshake() attempts to complete an SSL handshake on the 98b077aed3SPierre Proncherysupplied BIO and establish the SSL connection. 99b077aed3SPierre ProncheryFor non-SSL BIOs the connection is done typically at TCP level. 100b077aed3SPierre ProncheryIf domain name resolution yields multiple IP addresses all of them are tried 101b077aed3SPierre Proncheryafter connect() failures. 102b077aed3SPierre ProncheryThe function returns 1 if the connection was established successfully. 103b077aed3SPierre ProncheryA zero or negative value is returned if the connection could not be established. 104b077aed3SPierre ProncheryThe call BIO_should_retry() should be used for nonblocking connect BIOs 105b077aed3SPierre Proncheryto determine if the call should be retried. 106b077aed3SPierre ProncheryIf a connection has already been established this call has no effect. 107e71b7053SJung-uk Kim 108e71b7053SJung-uk Kim=head1 NOTES 109e71b7053SJung-uk Kim 110e71b7053SJung-uk KimSSL BIOs are exceptional in that if the underlying transport 111e71b7053SJung-uk Kimis non blocking they can still request a retry in exceptional 112e71b7053SJung-uk Kimcircumstances. Specifically this will happen if a session 113e71b7053SJung-uk Kimrenegotiation takes place during a BIO_read_ex() operation, one 114e71b7053SJung-uk Kimcase where this happens is when step up occurs. 115e71b7053SJung-uk Kim 116e71b7053SJung-uk KimThe SSL flag SSL_AUTO_RETRY can be 117e71b7053SJung-uk Kimset to disable this behaviour. That is when this flag is set 118e71b7053SJung-uk Kiman SSL BIO using a blocking transport will never request a 119e71b7053SJung-uk Kimretry. 120e71b7053SJung-uk Kim 121e71b7053SJung-uk KimSince unknown BIO_ctrl() operations are sent through filter 122e71b7053SJung-uk KimBIOs the servers name and port can be set using BIO_set_host() 123e71b7053SJung-uk Kimon the BIO returned by BIO_new_ssl_connect() without having 124e71b7053SJung-uk Kimto locate the connect BIO first. 125e71b7053SJung-uk Kim 126e71b7053SJung-uk KimApplications do not have to call BIO_do_handshake() but may wish 127e71b7053SJung-uk Kimto do so to separate the handshake process from other I/O 128e71b7053SJung-uk Kimprocessing. 129e71b7053SJung-uk Kim 130e71b7053SJung-uk KimBIO_set_ssl(), BIO_get_ssl(), BIO_set_ssl_mode(), 131e71b7053SJung-uk KimBIO_set_ssl_renegotiate_bytes(), BIO_set_ssl_renegotiate_timeout(), 132e71b7053SJung-uk KimBIO_get_num_renegotiates(), and BIO_do_handshake() are implemented as macros. 133e71b7053SJung-uk Kim 134da327cd2SJung-uk Kim=head1 RETURN VALUES 135e71b7053SJung-uk Kim 136da327cd2SJung-uk KimBIO_f_ssl() returns the SSL B<BIO_METHOD> structure. 137da327cd2SJung-uk Kim 138da327cd2SJung-uk KimBIO_set_ssl(), BIO_get_ssl(), BIO_set_ssl_mode(), BIO_set_ssl_renegotiate_bytes(), 139da327cd2SJung-uk KimBIO_set_ssl_renegotiate_timeout() and BIO_get_num_renegotiates() return 1 on 140da327cd2SJung-uk Kimsuccess or a value which is less than or equal to 0 if an error occurred. 141da327cd2SJung-uk Kim 142da327cd2SJung-uk KimBIO_new_ssl(), BIO_new_ssl_connect() and BIO_new_buffer_ssl_connect() return 143da327cd2SJung-uk Kima valid B<BIO> structure on success or B<NULL> if an error occurred. 144da327cd2SJung-uk Kim 145da327cd2SJung-uk KimBIO_ssl_copy_session_id() returns 1 on success or 0 on error. 146da327cd2SJung-uk Kim 147da327cd2SJung-uk KimBIO_do_handshake() returns 1 if the connection was established successfully. 148da327cd2SJung-uk KimA zero or negative value is returned if the connection could not be established. 149da327cd2SJung-uk Kim 150da327cd2SJung-uk Kim=head1 EXAMPLES 151da327cd2SJung-uk Kim 152da327cd2SJung-uk KimThis SSL/TLS client example attempts to retrieve a page from an 153e71b7053SJung-uk KimSSL/TLS web server. The I/O routines are identical to those of the 154e71b7053SJung-uk Kimunencrypted example in L<BIO_s_connect(3)>. 155e71b7053SJung-uk Kim 156e71b7053SJung-uk Kim BIO *sbio, *out; 157e71b7053SJung-uk Kim int len; 158e71b7053SJung-uk Kim char tmpbuf[1024]; 159e71b7053SJung-uk Kim SSL_CTX *ctx; 160e71b7053SJung-uk Kim SSL *ssl; 161e71b7053SJung-uk Kim 162e71b7053SJung-uk Kim /* XXX Seed the PRNG if needed. */ 163e71b7053SJung-uk Kim 164e71b7053SJung-uk Kim ctx = SSL_CTX_new(TLS_client_method()); 165e71b7053SJung-uk Kim 166e71b7053SJung-uk Kim /* XXX Set verify paths and mode here. */ 167e71b7053SJung-uk Kim 168e71b7053SJung-uk Kim sbio = BIO_new_ssl_connect(ctx); 169e71b7053SJung-uk Kim BIO_get_ssl(sbio, &ssl); 170e71b7053SJung-uk Kim if (ssl == NULL) { 171e71b7053SJung-uk Kim fprintf(stderr, "Can't locate SSL pointer\n"); 172e71b7053SJung-uk Kim ERR_print_errors_fp(stderr); 173e71b7053SJung-uk Kim exit(1); 174e71b7053SJung-uk Kim } 175e71b7053SJung-uk Kim 176e71b7053SJung-uk Kim /* XXX We might want to do other things with ssl here */ 177e71b7053SJung-uk Kim 178e71b7053SJung-uk Kim /* An empty host part means the loopback address */ 179e71b7053SJung-uk Kim BIO_set_conn_hostname(sbio, ":https"); 180e71b7053SJung-uk Kim 181e71b7053SJung-uk Kim out = BIO_new_fp(stdout, BIO_NOCLOSE); 182e71b7053SJung-uk Kim if (BIO_do_connect(sbio) <= 0) { 183e71b7053SJung-uk Kim fprintf(stderr, "Error connecting to server\n"); 184e71b7053SJung-uk Kim ERR_print_errors_fp(stderr); 185e71b7053SJung-uk Kim exit(1); 186e71b7053SJung-uk Kim } 187e71b7053SJung-uk Kim 188e71b7053SJung-uk Kim /* XXX Could examine ssl here to get connection info */ 189e71b7053SJung-uk Kim 190e71b7053SJung-uk Kim BIO_puts(sbio, "GET / HTTP/1.0\n\n"); 191e71b7053SJung-uk Kim for (;;) { 192e71b7053SJung-uk Kim len = BIO_read(sbio, tmpbuf, 1024); 193e71b7053SJung-uk Kim if (len <= 0) 194e71b7053SJung-uk Kim break; 195e71b7053SJung-uk Kim BIO_write(out, tmpbuf, len); 196e71b7053SJung-uk Kim } 197e71b7053SJung-uk Kim BIO_free_all(sbio); 198e71b7053SJung-uk Kim BIO_free(out); 199e71b7053SJung-uk Kim 200e71b7053SJung-uk KimHere is a simple server example. It makes use of a buffering 201e71b7053SJung-uk KimBIO to allow lines to be read from the SSL BIO using BIO_gets. 202e71b7053SJung-uk KimIt creates a pseudo web page containing the actual request from 203e71b7053SJung-uk Kima client and also echoes the request to standard output. 204e71b7053SJung-uk Kim 205e71b7053SJung-uk Kim BIO *sbio, *bbio, *acpt, *out; 206e71b7053SJung-uk Kim int len; 207e71b7053SJung-uk Kim char tmpbuf[1024]; 208e71b7053SJung-uk Kim SSL_CTX *ctx; 209e71b7053SJung-uk Kim SSL *ssl; 210e71b7053SJung-uk Kim 211e71b7053SJung-uk Kim /* XXX Seed the PRNG if needed. */ 212e71b7053SJung-uk Kim 213e71b7053SJung-uk Kim ctx = SSL_CTX_new(TLS_server_method()); 214e71b7053SJung-uk Kim if (!SSL_CTX_use_certificate_file(ctx, "server.pem", SSL_FILETYPE_PEM) 215e71b7053SJung-uk Kim || !SSL_CTX_use_PrivateKey_file(ctx, "server.pem", SSL_FILETYPE_PEM) 216e71b7053SJung-uk Kim || !SSL_CTX_check_private_key(ctx)) { 217e71b7053SJung-uk Kim fprintf(stderr, "Error setting up SSL_CTX\n"); 218e71b7053SJung-uk Kim ERR_print_errors_fp(stderr); 219e71b7053SJung-uk Kim exit(1); 220e71b7053SJung-uk Kim } 221e71b7053SJung-uk Kim 222e71b7053SJung-uk Kim /* XXX Other things like set verify locations, EDH temp callbacks. */ 223e71b7053SJung-uk Kim 224e71b7053SJung-uk Kim /* New SSL BIO setup as server */ 225e71b7053SJung-uk Kim sbio = BIO_new_ssl(ctx, 0); 226e71b7053SJung-uk Kim BIO_get_ssl(sbio, &ssl); 227e71b7053SJung-uk Kim if (ssl == NULL) { 228e71b7053SJung-uk Kim fprintf(stderr, "Can't locate SSL pointer\n"); 229e71b7053SJung-uk Kim ERR_print_errors_fp(stderr); 230e71b7053SJung-uk Kim exit(1); 231e71b7053SJung-uk Kim } 232e71b7053SJung-uk Kim 233e71b7053SJung-uk Kim bbio = BIO_new(BIO_f_buffer()); 234e71b7053SJung-uk Kim sbio = BIO_push(bbio, sbio); 235e71b7053SJung-uk Kim acpt = BIO_new_accept("4433"); 236e71b7053SJung-uk Kim 237e71b7053SJung-uk Kim /* 238e71b7053SJung-uk Kim * By doing this when a new connection is established 239e71b7053SJung-uk Kim * we automatically have sbio inserted into it. The 240e71b7053SJung-uk Kim * BIO chain is now 'swallowed' by the accept BIO and 241e71b7053SJung-uk Kim * will be freed when the accept BIO is freed. 242e71b7053SJung-uk Kim */ 243e71b7053SJung-uk Kim BIO_set_accept_bios(acpt, sbio); 244e71b7053SJung-uk Kim out = BIO_new_fp(stdout, BIO_NOCLOSE); 245e71b7053SJung-uk Kim 246b077aed3SPierre Pronchery /* First call to BIO_do_accept() sets up accept BIO */ 247e71b7053SJung-uk Kim if (BIO_do_accept(acpt) <= 0) { 248e71b7053SJung-uk Kim fprintf(stderr, "Error setting up accept BIO\n"); 249e71b7053SJung-uk Kim ERR_print_errors_fp(stderr); 250e71b7053SJung-uk Kim exit(1); 251e71b7053SJung-uk Kim } 252e71b7053SJung-uk Kim 253b077aed3SPierre Pronchery/* Second call to BIO_do_accept() waits for incoming connection */ 254b077aed3SPierre Pronchery if (BIO_do_accept(acpt) <= 0) { 255b077aed3SPierre Pronchery fprintf(stderr, "Error accepting connection\n"); 256b077aed3SPierre Pronchery ERR_print_errors_fp(stderr); 257b077aed3SPierre Pronchery exit(1); 258b077aed3SPierre Pronchery } 259b077aed3SPierre Pronchery 260e71b7053SJung-uk Kim /* We only want one connection so remove and free accept BIO */ 261e71b7053SJung-uk Kim sbio = BIO_pop(acpt); 262e71b7053SJung-uk Kim BIO_free_all(acpt); 263e71b7053SJung-uk Kim 264e71b7053SJung-uk Kim if (BIO_do_handshake(sbio) <= 0) { 265e71b7053SJung-uk Kim fprintf(stderr, "Error in SSL handshake\n"); 266e71b7053SJung-uk Kim ERR_print_errors_fp(stderr); 267e71b7053SJung-uk Kim exit(1); 268e71b7053SJung-uk Kim } 269e71b7053SJung-uk Kim 270e71b7053SJung-uk Kim BIO_puts(sbio, "HTTP/1.0 200 OK\r\nContent-type: text/plain\r\n\r\n"); 271e71b7053SJung-uk Kim BIO_puts(sbio, "\r\nConnection Established\r\nRequest headers:\r\n"); 272e71b7053SJung-uk Kim BIO_puts(sbio, "--------------------------------------------------\r\n"); 273e71b7053SJung-uk Kim 274e71b7053SJung-uk Kim for (;;) { 275e71b7053SJung-uk Kim len = BIO_gets(sbio, tmpbuf, 1024); 276e71b7053SJung-uk Kim if (len <= 0) 277e71b7053SJung-uk Kim break; 278e71b7053SJung-uk Kim BIO_write(sbio, tmpbuf, len); 279e71b7053SJung-uk Kim BIO_write(out, tmpbuf, len); 280e71b7053SJung-uk Kim /* Look for blank line signifying end of headers*/ 281e71b7053SJung-uk Kim if (tmpbuf[0] == '\r' || tmpbuf[0] == '\n') 282e71b7053SJung-uk Kim break; 283e71b7053SJung-uk Kim } 284e71b7053SJung-uk Kim 285e71b7053SJung-uk Kim BIO_puts(sbio, "--------------------------------------------------\r\n"); 286e71b7053SJung-uk Kim BIO_puts(sbio, "\r\n"); 287e71b7053SJung-uk Kim BIO_flush(sbio); 288e71b7053SJung-uk Kim BIO_free_all(sbio); 289e71b7053SJung-uk Kim 290e71b7053SJung-uk Kim=head1 HISTORY 291e71b7053SJung-uk Kim 292e71b7053SJung-uk KimIn OpenSSL before 1.0.0 the BIO_pop() call was handled incorrectly, 293e71b7053SJung-uk Kimthe I/O BIO reference count was incorrectly incremented (instead of 294e71b7053SJung-uk Kimdecremented) and dissociated with the SSL BIO even if the SSL BIO was not 295e71b7053SJung-uk Kimexplicitly being popped (e.g. a pop higher up the chain). Applications which 296e71b7053SJung-uk Kimincluded workarounds for this bug (e.g. freeing BIOs more than once) should 297e71b7053SJung-uk Kimbe modified to handle this fix or they may free up an already freed BIO. 298e71b7053SJung-uk Kim 299e71b7053SJung-uk Kim=head1 COPYRIGHT 300e71b7053SJung-uk Kim 301b077aed3SPierre ProncheryCopyright 2000-2022 The OpenSSL Project Authors. All Rights Reserved. 302e71b7053SJung-uk Kim 303b077aed3SPierre ProncheryLicensed under the Apache License 2.0 (the "License"). You may not use 304e71b7053SJung-uk Kimthis file except in compliance with the License. You can obtain a copy 305e71b7053SJung-uk Kimin the file LICENSE in the source distribution or at 306e71b7053SJung-uk KimL<https://www.openssl.org/source/license.html>. 307e71b7053SJung-uk Kim 308e71b7053SJung-uk Kim=cut 309