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 14e71b7053SJung-uk Kim=for comment 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 57e71b7053SJung-uk KimBIO_set_ssl() sets the internal SSL pointer of BIO B<b> to B<ssl> using 58e71b7053SJung-uk Kimthe close flag B<c>. 59e71b7053SJung-uk Kim 60e71b7053SJung-uk KimBIO_get_ssl() retrieves the SSL pointer of 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 66e71b7053SJung-uk KimBIO_set_ssl_renegotiate_bytes() sets the renegotiate byte count 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 71e71b7053SJung-uk KimBIO_set_ssl_renegotiate_timeout() sets the renegotiate timeout to 72e71b7053SJung-uk KimB<seconds>. When the renegotiate timeout elapses the session is 73e71b7053SJung-uk Kimautomatically renegotiated. 74e71b7053SJung-uk Kim 75e71b7053SJung-uk KimBIO_get_num_renegotiates() returns the total number of session 76e71b7053SJung-uk Kimrenegotiations due to I/O or timeout. 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 85e71b7053SJung-uk Kimof a buffering BIO, an SSL BIO (using B<ctx>) and a connect 86e71b7053SJung-uk KimBIO. 87e71b7053SJung-uk Kim 88e71b7053SJung-uk KimBIO_ssl_copy_session_id() copies an SSL session id between 89e71b7053SJung-uk KimBIO chains B<from> and B<to>. It does this by locating the 90e71b7053SJung-uk KimSSL BIOs in each chain and calling SSL_copy_session_id() on 91e71b7053SJung-uk Kimthe internal SSL pointer. 92e71b7053SJung-uk Kim 93e71b7053SJung-uk KimBIO_ssl_shutdown() closes down an SSL connection on BIO 94e71b7053SJung-uk Kimchain B<bio>. It does this by locating the SSL BIO in the 95e71b7053SJung-uk Kimchain and calling SSL_shutdown() on its internal SSL 96e71b7053SJung-uk Kimpointer. 97e71b7053SJung-uk Kim 98e71b7053SJung-uk KimBIO_do_handshake() attempts to complete an SSL handshake on the 99e71b7053SJung-uk Kimsupplied BIO and establish the SSL connection. It returns 1 100e71b7053SJung-uk Kimif the connection was established successfully. A zero or negative 101e71b7053SJung-uk Kimvalue is returned if the connection could not be established, the 102e71b7053SJung-uk Kimcall BIO_should_retry() should be used for non blocking connect BIOs 103e71b7053SJung-uk Kimto determine if the call should be retried. If an SSL connection has 104e71b7053SJung-uk Kimalready been established this call has no effect. 105e71b7053SJung-uk Kim 106e71b7053SJung-uk Kim=head1 NOTES 107e71b7053SJung-uk Kim 108e71b7053SJung-uk KimSSL BIOs are exceptional in that if the underlying transport 109e71b7053SJung-uk Kimis non blocking they can still request a retry in exceptional 110e71b7053SJung-uk Kimcircumstances. Specifically this will happen if a session 111e71b7053SJung-uk Kimrenegotiation takes place during a BIO_read_ex() operation, one 112e71b7053SJung-uk Kimcase where this happens is when step up occurs. 113e71b7053SJung-uk Kim 114e71b7053SJung-uk KimThe SSL flag SSL_AUTO_RETRY can be 115e71b7053SJung-uk Kimset to disable this behaviour. That is when this flag is set 116e71b7053SJung-uk Kiman SSL BIO using a blocking transport will never request a 117e71b7053SJung-uk Kimretry. 118e71b7053SJung-uk Kim 119e71b7053SJung-uk KimSince unknown BIO_ctrl() operations are sent through filter 120e71b7053SJung-uk KimBIOs the servers name and port can be set using BIO_set_host() 121e71b7053SJung-uk Kimon the BIO returned by BIO_new_ssl_connect() without having 122e71b7053SJung-uk Kimto locate the connect BIO first. 123e71b7053SJung-uk Kim 124e71b7053SJung-uk KimApplications do not have to call BIO_do_handshake() but may wish 125e71b7053SJung-uk Kimto do so to separate the handshake process from other I/O 126e71b7053SJung-uk Kimprocessing. 127e71b7053SJung-uk Kim 128e71b7053SJung-uk KimBIO_set_ssl(), BIO_get_ssl(), BIO_set_ssl_mode(), 129e71b7053SJung-uk KimBIO_set_ssl_renegotiate_bytes(), BIO_set_ssl_renegotiate_timeout(), 130e71b7053SJung-uk KimBIO_get_num_renegotiates(), and BIO_do_handshake() are implemented as macros. 131e71b7053SJung-uk Kim 132e71b7053SJung-uk Kim=head1 EXAMPLE 133e71b7053SJung-uk Kim 134e71b7053SJung-uk KimThis SSL/TLS client example, attempts to retrieve a page from an 135e71b7053SJung-uk KimSSL/TLS web server. The I/O routines are identical to those of the 136e71b7053SJung-uk Kimunencrypted example in L<BIO_s_connect(3)>. 137e71b7053SJung-uk Kim 138e71b7053SJung-uk Kim BIO *sbio, *out; 139e71b7053SJung-uk Kim int len; 140e71b7053SJung-uk Kim char tmpbuf[1024]; 141e71b7053SJung-uk Kim SSL_CTX *ctx; 142e71b7053SJung-uk Kim SSL *ssl; 143e71b7053SJung-uk Kim 144e71b7053SJung-uk Kim /* XXX Seed the PRNG if needed. */ 145e71b7053SJung-uk Kim 146e71b7053SJung-uk Kim ctx = SSL_CTX_new(TLS_client_method()); 147e71b7053SJung-uk Kim 148e71b7053SJung-uk Kim /* XXX Set verify paths and mode here. */ 149e71b7053SJung-uk Kim 150e71b7053SJung-uk Kim sbio = BIO_new_ssl_connect(ctx); 151e71b7053SJung-uk Kim BIO_get_ssl(sbio, &ssl); 152e71b7053SJung-uk Kim if (ssl == NULL) { 153e71b7053SJung-uk Kim fprintf(stderr, "Can't locate SSL pointer\n"); 154e71b7053SJung-uk Kim ERR_print_errors_fp(stderr); 155e71b7053SJung-uk Kim exit(1); 156e71b7053SJung-uk Kim } 157e71b7053SJung-uk Kim 158e71b7053SJung-uk Kim /* Don't want any retries */ 159e71b7053SJung-uk Kim SSL_set_mode(ssl, SSL_MODE_AUTO_RETRY); 160e71b7053SJung-uk Kim 161e71b7053SJung-uk Kim /* XXX We might want to do other things with ssl here */ 162e71b7053SJung-uk Kim 163e71b7053SJung-uk Kim /* An empty host part means the loopback address */ 164e71b7053SJung-uk Kim BIO_set_conn_hostname(sbio, ":https"); 165e71b7053SJung-uk Kim 166e71b7053SJung-uk Kim out = BIO_new_fp(stdout, BIO_NOCLOSE); 167e71b7053SJung-uk Kim if (BIO_do_connect(sbio) <= 0) { 168e71b7053SJung-uk Kim fprintf(stderr, "Error connecting to server\n"); 169e71b7053SJung-uk Kim ERR_print_errors_fp(stderr); 170e71b7053SJung-uk Kim exit(1); 171e71b7053SJung-uk Kim } 172e71b7053SJung-uk Kim if (BIO_do_handshake(sbio) <= 0) { 173e71b7053SJung-uk Kim fprintf(stderr, "Error establishing SSL connection\n"); 174e71b7053SJung-uk Kim ERR_print_errors_fp(stderr); 175e71b7053SJung-uk Kim exit(1); 176e71b7053SJung-uk Kim } 177e71b7053SJung-uk Kim 178e71b7053SJung-uk Kim /* XXX Could examine ssl here to get connection info */ 179e71b7053SJung-uk Kim 180e71b7053SJung-uk Kim BIO_puts(sbio, "GET / HTTP/1.0\n\n"); 181e71b7053SJung-uk Kim for (;;) { 182e71b7053SJung-uk Kim len = BIO_read(sbio, tmpbuf, 1024); 183e71b7053SJung-uk Kim if (len <= 0) 184e71b7053SJung-uk Kim break; 185e71b7053SJung-uk Kim BIO_write(out, tmpbuf, len); 186e71b7053SJung-uk Kim } 187e71b7053SJung-uk Kim BIO_free_all(sbio); 188e71b7053SJung-uk Kim BIO_free(out); 189e71b7053SJung-uk Kim 190e71b7053SJung-uk KimHere is a simple server example. It makes use of a buffering 191e71b7053SJung-uk KimBIO to allow lines to be read from the SSL BIO using BIO_gets. 192e71b7053SJung-uk KimIt creates a pseudo web page containing the actual request from 193e71b7053SJung-uk Kima client and also echoes the request to standard output. 194e71b7053SJung-uk Kim 195e71b7053SJung-uk Kim BIO *sbio, *bbio, *acpt, *out; 196e71b7053SJung-uk Kim int len; 197e71b7053SJung-uk Kim char tmpbuf[1024]; 198e71b7053SJung-uk Kim SSL_CTX *ctx; 199e71b7053SJung-uk Kim SSL *ssl; 200e71b7053SJung-uk Kim 201e71b7053SJung-uk Kim /* XXX Seed the PRNG if needed. */ 202e71b7053SJung-uk Kim 203e71b7053SJung-uk Kim ctx = SSL_CTX_new(TLS_server_method()); 204e71b7053SJung-uk Kim if (!SSL_CTX_use_certificate_file(ctx, "server.pem", SSL_FILETYPE_PEM) 205e71b7053SJung-uk Kim || !SSL_CTX_use_PrivateKey_file(ctx, "server.pem", SSL_FILETYPE_PEM) 206e71b7053SJung-uk Kim || !SSL_CTX_check_private_key(ctx)) { 207e71b7053SJung-uk Kim fprintf(stderr, "Error setting up SSL_CTX\n"); 208e71b7053SJung-uk Kim ERR_print_errors_fp(stderr); 209e71b7053SJung-uk Kim exit(1); 210e71b7053SJung-uk Kim } 211e71b7053SJung-uk Kim 212e71b7053SJung-uk Kim /* XXX Other things like set verify locations, EDH temp callbacks. */ 213e71b7053SJung-uk Kim 214e71b7053SJung-uk Kim /* New SSL BIO setup as server */ 215e71b7053SJung-uk Kim sbio = BIO_new_ssl(ctx, 0); 216e71b7053SJung-uk Kim BIO_get_ssl(sbio, &ssl); 217e71b7053SJung-uk Kim if (ssl == NULL) { 218e71b7053SJung-uk Kim fprintf(stderr, "Can't locate SSL pointer\n"); 219e71b7053SJung-uk Kim ERR_print_errors_fp(stderr); 220e71b7053SJung-uk Kim exit(1); 221e71b7053SJung-uk Kim } 222e71b7053SJung-uk Kim 223e71b7053SJung-uk Kim SSL_set_mode(ssl, SSL_MODE_AUTO_RETRY); 224e71b7053SJung-uk Kim bbio = BIO_new(BIO_f_buffer()); 225e71b7053SJung-uk Kim sbio = BIO_push(bbio, sbio); 226e71b7053SJung-uk Kim acpt = BIO_new_accept("4433"); 227e71b7053SJung-uk Kim 228e71b7053SJung-uk Kim /* 229e71b7053SJung-uk Kim * By doing this when a new connection is established 230e71b7053SJung-uk Kim * we automatically have sbio inserted into it. The 231e71b7053SJung-uk Kim * BIO chain is now 'swallowed' by the accept BIO and 232e71b7053SJung-uk Kim * will be freed when the accept BIO is freed. 233e71b7053SJung-uk Kim */ 234e71b7053SJung-uk Kim BIO_set_accept_bios(acpt, sbio); 235e71b7053SJung-uk Kim out = BIO_new_fp(stdout, BIO_NOCLOSE); 236e71b7053SJung-uk Kim 237e71b7053SJung-uk Kim /* Setup accept BIO */ 238e71b7053SJung-uk Kim if (BIO_do_accept(acpt) <= 0) { 239e71b7053SJung-uk Kim fprintf(stderr, "Error setting up accept BIO\n"); 240e71b7053SJung-uk Kim ERR_print_errors_fp(stderr); 241e71b7053SJung-uk Kim exit(1); 242e71b7053SJung-uk Kim } 243e71b7053SJung-uk Kim 244e71b7053SJung-uk Kim /* We only want one connection so remove and free accept BIO */ 245e71b7053SJung-uk Kim sbio = BIO_pop(acpt); 246e71b7053SJung-uk Kim BIO_free_all(acpt); 247e71b7053SJung-uk Kim 248e71b7053SJung-uk Kim if (BIO_do_handshake(sbio) <= 0) { 249e71b7053SJung-uk Kim fprintf(stderr, "Error in SSL handshake\n"); 250e71b7053SJung-uk Kim ERR_print_errors_fp(stderr); 251e71b7053SJung-uk Kim exit(1); 252e71b7053SJung-uk Kim } 253e71b7053SJung-uk Kim 254e71b7053SJung-uk Kim BIO_puts(sbio, "HTTP/1.0 200 OK\r\nContent-type: text/plain\r\n\r\n"); 255e71b7053SJung-uk Kim BIO_puts(sbio, "\r\nConnection Established\r\nRequest headers:\r\n"); 256e71b7053SJung-uk Kim BIO_puts(sbio, "--------------------------------------------------\r\n"); 257e71b7053SJung-uk Kim 258e71b7053SJung-uk Kim for (;;) { 259e71b7053SJung-uk Kim len = BIO_gets(sbio, tmpbuf, 1024); 260e71b7053SJung-uk Kim if (len <= 0) 261e71b7053SJung-uk Kim break; 262e71b7053SJung-uk Kim BIO_write(sbio, tmpbuf, len); 263e71b7053SJung-uk Kim BIO_write(out, tmpbuf, len); 264e71b7053SJung-uk Kim /* Look for blank line signifying end of headers*/ 265e71b7053SJung-uk Kim if (tmpbuf[0] == '\r' || tmpbuf[0] == '\n') 266e71b7053SJung-uk Kim break; 267e71b7053SJung-uk Kim } 268e71b7053SJung-uk Kim 269e71b7053SJung-uk Kim BIO_puts(sbio, "--------------------------------------------------\r\n"); 270e71b7053SJung-uk Kim BIO_puts(sbio, "\r\n"); 271e71b7053SJung-uk Kim BIO_flush(sbio); 272e71b7053SJung-uk Kim BIO_free_all(sbio); 273e71b7053SJung-uk Kim 274e71b7053SJung-uk Kim=head1 RETURN VALUES 275e71b7053SJung-uk Kim 276e71b7053SJung-uk KimBIO_f_ssl() returns the SSL B<BIO_METHOD> structure. 277e71b7053SJung-uk Kim 278e71b7053SJung-uk KimBIO_set_ssl(), BIO_get_ssl(), BIO_set_ssl_mode(), BIO_set_ssl_renegotiate_bytes(), 279e71b7053SJung-uk KimBIO_set_ssl_renegotiate_timeout() and BIO_get_num_renegotiates() return 1 on 280e71b7053SJung-uk Kimsuccess or a value which is less than or equal to 0 if an error occurred. 281e71b7053SJung-uk Kim 282e71b7053SJung-uk KimBIO_new_ssl(), BIO_new_ssl_connect() and BIO_new_buffer_ssl_connect() return 283e71b7053SJung-uk Kima valid B<BIO> structure on success or B<NULL> if an error occurred. 284e71b7053SJung-uk Kim 285e71b7053SJung-uk KimBIO_ssl_copy_session_id() returns 1 on success or 0 on error. 286e71b7053SJung-uk Kim 287e71b7053SJung-uk KimBIO_do_handshake() returns 1 if the connection was established successfully. 288e71b7053SJung-uk KimA zero or negative value is returned if the connection could not be established. 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 301e71b7053SJung-uk KimCopyright 2000-2018 The OpenSSL Project Authors. All Rights Reserved. 302e71b7053SJung-uk Kim 303e71b7053SJung-uk KimLicensed under the OpenSSL license (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