1=pod 2 3=head1 NAME 4 5SSL_set_bio, SSL_set0_rbio, SSL_set0_wbio - connect the SSL object with a BIO 6 7=head1 SYNOPSIS 8 9 #include <openssl/ssl.h> 10 11 void SSL_set_bio(SSL *ssl, BIO *rbio, BIO *wbio); 12 void SSL_set0_rbio(SSL *s, BIO *rbio); 13 void SSL_set0_wbio(SSL *s, BIO *wbio); 14 15=head1 DESCRIPTION 16 17SSL_set0_rbio() connects the BIO B<rbio> for the read operations of the B<ssl> 18object. The SSL engine inherits the behaviour of B<rbio>. If the BIO is 19nonblocking then the B<ssl> object will also have nonblocking behaviour. This 20function transfers ownership of B<rbio> to B<ssl>. It will be automatically 21freed using L<BIO_free_all(3)> when the B<ssl> is freed. On calling this 22function, any existing B<rbio> that was previously set will also be freed via a 23call to L<BIO_free_all(3)> (this includes the case where the B<rbio> is set to 24the same value as previously). 25 26If using a custom BIO, B<rbio> must implement either 27L<BIO_meth_set_read_ex(3)> or L<BIO_meth_set_read(3)>. 28 29SSL_set0_wbio() works in the same as SSL_set0_rbio() except that it connects 30the BIO B<wbio> for the write operations of the B<ssl> object. Note that if the 31rbio and wbio are the same then SSL_set0_rbio() and SSL_set0_wbio() each take 32ownership of one reference. Therefore, it may be necessary to increment the 33number of references available using L<BIO_up_ref(3)> before calling the set0 34functions. 35 36If using a custom BIO, B<wbio> must implement 37L<BIO_meth_set_write_ex(3)> or L<BIO_meth_set_write(3)>. It additionally must 38implement L<BIO_flush(3)> using B<BIO_CTRL_FLUSH> and L<BIO_meth_set_ctrl(3)>. 39If flushing is unnecessary with B<wbio>, L<BIO_flush(3)> should return one and 40do nothing. 41 42SSL_set_bio() is similar to SSL_set0_rbio() and SSL_set0_wbio() except 43that it connects both the B<rbio> and the B<wbio> at the same time, and 44transfers the ownership of B<rbio> and B<wbio> to B<ssl> according to 45the following set of rules: 46 47=over 2 48 49=item * 50 51If neither the B<rbio> or B<wbio> have changed from their previous values 52then nothing is done. 53 54=item * 55 56If the B<rbio> and B<wbio> parameters are different and both are different 57to their 58previously set values then one reference is consumed for the rbio and one 59reference is consumed for the wbio. 60 61=item * 62 63If the B<rbio> and B<wbio> parameters are the same and the B<rbio> is not 64the same as the previously set value then one reference is consumed. 65 66=item * 67 68If the B<rbio> and B<wbio> parameters are the same and the B<rbio> is the 69same as the previously set value, then no additional references are consumed. 70 71=item * 72 73If the B<rbio> and B<wbio> parameters are different and the B<rbio> is the 74same as the 75previously set value then one reference is consumed for the B<wbio> and no 76references are consumed for the B<rbio>. 77 78=item * 79 80If the B<rbio> and B<wbio> parameters are different and the B<wbio> is the 81same as the previously set value and the old B<rbio> and B<wbio> values 82were the same as each other then one reference is consumed for the B<rbio> 83and no references are consumed for the B<wbio>. 84 85=item * 86 87If the B<rbio> and B<wbio> parameters are different and the B<wbio> 88is the same as the 89previously set value and the old B<rbio> and B<wbio> values were different 90to each other, then one reference is consumed for the B<rbio> and one 91reference is consumed for the B<wbio>. 92 93=back 94 95Because of this complexity, this function should be avoided; 96use SSL_set0_rbio() and SSL_set0_wbio() instead. 97 98Where a new BIO is set on a QUIC connection SSL object, blocking mode will be 99disabled on that SSL object if the BIO cannot support blocking mode. If another 100BIO is subsequently set on the SSL object which can support blocking mode, 101blocking mode will not be automatically re-enabled. For more information, see 102L<SSL_set_blocking_mode(3)>. 103 104=head1 RETURN VALUES 105 106SSL_set_bio(), SSL_set0_rbio() and SSL_set0_wbio() cannot fail. 107 108=head1 SEE ALSO 109 110L<SSL_get_rbio(3)>, 111L<SSL_connect(3)>, L<SSL_accept(3)>, 112L<SSL_shutdown(3)>, L<ssl(7)>, L<bio(7)> 113 114=head1 HISTORY 115 116SSL_set0_rbio() and SSL_set0_wbio() were added in OpenSSL 1.1.0. 117 118=head1 COPYRIGHT 119 120Copyright 2000-2023 The OpenSSL Project Authors. All Rights Reserved. 121 122Licensed under the Apache License 2.0 (the "License"). You may not use 123this file except in compliance with the License. You can obtain a copy 124in the file LICENSE in the source distribution or at 125L<https://www.openssl.org/source/license.html>. 126 127=cut 128
