1*1dcdf01fSchristos=pod 2*1dcdf01fSchristos 3*1dcdf01fSchristos=head1 NAME 4*1dcdf01fSchristos 5*1dcdf01fSchristosSSL_CTX_set_mode, SSL_CTX_clear_mode, SSL_set_mode, SSL_clear_mode, SSL_CTX_get_mode, SSL_get_mode - manipulate SSL engine mode 6*1dcdf01fSchristos 7*1dcdf01fSchristos=head1 SYNOPSIS 8*1dcdf01fSchristos 9*1dcdf01fSchristos #include <openssl/ssl.h> 10*1dcdf01fSchristos 11*1dcdf01fSchristos long SSL_CTX_set_mode(SSL_CTX *ctx, long mode); 12*1dcdf01fSchristos long SSL_CTX_clear_mode(SSL_CTX *ctx, long mode); 13*1dcdf01fSchristos long SSL_set_mode(SSL *ssl, long mode); 14*1dcdf01fSchristos long SSL_clear_mode(SSL *ssl, long mode); 15*1dcdf01fSchristos 16*1dcdf01fSchristos long SSL_CTX_get_mode(SSL_CTX *ctx); 17*1dcdf01fSchristos long SSL_get_mode(SSL *ssl); 18*1dcdf01fSchristos 19*1dcdf01fSchristos=head1 DESCRIPTION 20*1dcdf01fSchristos 21*1dcdf01fSchristosSSL_CTX_set_mode() adds the mode set via bit mask in B<mode> to B<ctx>. 22*1dcdf01fSchristosOptions already set before are not cleared. 23*1dcdf01fSchristosSSL_CTX_clear_mode() removes the mode set via bit mask in B<mode> from B<ctx>. 24*1dcdf01fSchristos 25*1dcdf01fSchristosSSL_set_mode() adds the mode set via bit mask in B<mode> to B<ssl>. 26*1dcdf01fSchristosOptions already set before are not cleared. 27*1dcdf01fSchristosSSL_clear_mode() removes the mode set via bit mask in B<mode> from B<ssl>. 28*1dcdf01fSchristos 29*1dcdf01fSchristosSSL_CTX_get_mode() returns the mode set for B<ctx>. 30*1dcdf01fSchristos 31*1dcdf01fSchristosSSL_get_mode() returns the mode set for B<ssl>. 32*1dcdf01fSchristos 33*1dcdf01fSchristos=head1 NOTES 34*1dcdf01fSchristos 35*1dcdf01fSchristosThe following mode changes are available: 36*1dcdf01fSchristos 37*1dcdf01fSchristos=over 4 38*1dcdf01fSchristos 39*1dcdf01fSchristos=item SSL_MODE_ENABLE_PARTIAL_WRITE 40*1dcdf01fSchristos 41*1dcdf01fSchristosAllow SSL_write_ex(..., n, &r) to return with 0 < r < n (i.e. report success 42*1dcdf01fSchristoswhen just a single record has been written). This works in a similar way for 43*1dcdf01fSchristosSSL_write(). When not set (the default), SSL_write_ex() or SSL_write() will only 44*1dcdf01fSchristosreport success once the complete chunk was written. Once SSL_write_ex() or 45*1dcdf01fSchristosSSL_write() returns successful, B<r> bytes have been written and the next call 46*1dcdf01fSchristosto SSL_write_ex() or SSL_write() must only send the n-r bytes left, imitating 47*1dcdf01fSchristosthe behaviour of write(). 48*1dcdf01fSchristos 49*1dcdf01fSchristos=item SSL_MODE_ACCEPT_MOVING_WRITE_BUFFER 50*1dcdf01fSchristos 51*1dcdf01fSchristosMake it possible to retry SSL_write_ex() or SSL_write() with changed buffer 52*1dcdf01fSchristoslocation (the buffer contents must stay the same). This is not the default to 53*1dcdf01fSchristosavoid the misconception that nonblocking SSL_write() behaves like 54*1dcdf01fSchristosnonblocking write(). 55*1dcdf01fSchristos 56*1dcdf01fSchristos=item SSL_MODE_AUTO_RETRY 57*1dcdf01fSchristos 58*1dcdf01fSchristosDuring normal operations, non-application data records might need to be sent or 59*1dcdf01fSchristosreceived that the application is not aware of. 60*1dcdf01fSchristosIf a non-application data record was processed, 61*1dcdf01fSchristosL<SSL_read_ex(3)> and L<SSL_read(3)> can return with a failure and indicate the 62*1dcdf01fSchristosneed to retry with B<SSL_ERROR_WANT_READ>. 63*1dcdf01fSchristosIf such a non-application data record was processed, the flag 64*1dcdf01fSchristosB<SSL_MODE_AUTO_RETRY> causes it to try to process the next record instead of 65*1dcdf01fSchristosreturning. 66*1dcdf01fSchristos 67*1dcdf01fSchristosIn a nonblocking environment applications must be prepared to handle 68*1dcdf01fSchristosincomplete read/write operations. 69*1dcdf01fSchristosSetting B<SSL_MODE_AUTO_RETRY> for a nonblocking B<BIO> will process 70*1dcdf01fSchristosnon-application data records until either no more data is available or 71*1dcdf01fSchristosan application data record has been processed. 72*1dcdf01fSchristos 73*1dcdf01fSchristosIn a blocking environment, applications are not always prepared to 74*1dcdf01fSchristosdeal with the functions returning intermediate reports such as retry 75*1dcdf01fSchristosrequests, and setting the B<SSL_MODE_AUTO_RETRY> flag will cause the functions 76*1dcdf01fSchristosto only return after successfully processing an application data record or a 77*1dcdf01fSchristosfailure. 78*1dcdf01fSchristos 79*1dcdf01fSchristosTurning off B<SSL_MODE_AUTO_RETRY> can be useful with blocking B<BIO>s in case 80*1dcdf01fSchristosthey are used in combination with something like select() or poll(). 81*1dcdf01fSchristosOtherwise the call to SSL_read() or SSL_read_ex() might hang when a 82*1dcdf01fSchristosnon-application record was sent and no application data was sent. 83*1dcdf01fSchristos 84*1dcdf01fSchristos=item SSL_MODE_RELEASE_BUFFERS 85*1dcdf01fSchristos 86*1dcdf01fSchristosWhen we no longer need a read buffer or a write buffer for a given SSL, 87*1dcdf01fSchristosthen release the memory we were using to hold it. 88*1dcdf01fSchristosUsing this flag can 89*1dcdf01fSchristossave around 34k per idle SSL connection. 90*1dcdf01fSchristosThis flag has no effect on SSL v2 connections, or on DTLS connections. 91*1dcdf01fSchristos 92*1dcdf01fSchristos=item SSL_MODE_SEND_FALLBACK_SCSV 93*1dcdf01fSchristos 94*1dcdf01fSchristosSend TLS_FALLBACK_SCSV in the ClientHello. 95*1dcdf01fSchristosTo be set only by applications that reconnect with a downgraded protocol 96*1dcdf01fSchristosversion; see draft-ietf-tls-downgrade-scsv-00 for details. 97*1dcdf01fSchristos 98*1dcdf01fSchristosDO NOT ENABLE THIS if your application attempts a normal handshake. 99*1dcdf01fSchristosOnly use this in explicit fallback retries, following the guidance 100*1dcdf01fSchristosin draft-ietf-tls-downgrade-scsv-00. 101*1dcdf01fSchristos 102*1dcdf01fSchristos=item SSL_MODE_ASYNC 103*1dcdf01fSchristos 104*1dcdf01fSchristosEnable asynchronous processing. TLS I/O operations may indicate a retry with 105*1dcdf01fSchristosSSL_ERROR_WANT_ASYNC with this mode set if an asynchronous capable engine is 106*1dcdf01fSchristosused to perform cryptographic operations. See L<SSL_get_error(3)>. 107*1dcdf01fSchristos 108*1dcdf01fSchristos=item SSL_MODE_DTLS_SCTP_LABEL_LENGTH_BUG 109*1dcdf01fSchristos 110*1dcdf01fSchristosOlder versions of OpenSSL had a bug in the computation of the label length 111*1dcdf01fSchristosused for computing the endpoint-pair shared secret. The bug was that the 112*1dcdf01fSchristosterminating zero was included in the length of the label. Setting this option 113*1dcdf01fSchristosenables this behaviour to allow interoperability with such broken 114*1dcdf01fSchristosimplementations. Please note that setting this option breaks interoperability 115*1dcdf01fSchristoswith correct implementations. This option only applies to DTLS over SCTP. 116*1dcdf01fSchristos 117*1dcdf01fSchristos=back 118*1dcdf01fSchristos 119*1dcdf01fSchristosAll modes are off by default except for SSL_MODE_AUTO_RETRY which is on by 120*1dcdf01fSchristosdefault since 1.1.1. 121*1dcdf01fSchristos 122*1dcdf01fSchristos=head1 RETURN VALUES 123*1dcdf01fSchristos 124*1dcdf01fSchristosSSL_CTX_set_mode() and SSL_set_mode() return the new mode bit mask 125*1dcdf01fSchristosafter adding B<mode>. 126*1dcdf01fSchristos 127*1dcdf01fSchristosSSL_CTX_get_mode() and SSL_get_mode() return the current bit mask. 128*1dcdf01fSchristos 129*1dcdf01fSchristos=head1 SEE ALSO 130*1dcdf01fSchristos 131*1dcdf01fSchristosL<ssl(7)>, L<SSL_read_ex(3)>, L<SSL_read(3)>, L<SSL_write_ex(3)> or 132*1dcdf01fSchristosL<SSL_write(3)>, L<SSL_get_error(3)> 133*1dcdf01fSchristos 134*1dcdf01fSchristos=head1 HISTORY 135*1dcdf01fSchristos 136*1dcdf01fSchristosSSL_MODE_ASYNC was added in OpenSSL 1.1.0. 137*1dcdf01fSchristos 138*1dcdf01fSchristos=head1 COPYRIGHT 139*1dcdf01fSchristos 140*1dcdf01fSchristosCopyright 2001-2020 The OpenSSL Project Authors. All Rights Reserved. 141*1dcdf01fSchristos 142*1dcdf01fSchristosLicensed under the OpenSSL license (the "License"). You may not use 143*1dcdf01fSchristosthis file except in compliance with the License. You can obtain a copy 144*1dcdf01fSchristosin the file LICENSE in the source distribution or at 145*1dcdf01fSchristosL<https://www.openssl.org/source/license.html>. 146*1dcdf01fSchristos 147*1dcdf01fSchristos=cut 148