176866Skris=pod 276866Skris 376866Skris=head1 NAME 476866Skris 576866SkrisSSL_CTX_set_mode, SSL_set_mode, SSL_CTX_get_mode, SSL_get_mode - manipulate SSL engine mode 676866Skris 776866Skris=head1 SYNOPSIS 876866Skris 976866Skris #include <openssl/ssl.h> 1076866Skris 1176866Skris long SSL_CTX_set_mode(SSL_CTX *ctx, long mode); 1276866Skris long SSL_set_mode(SSL *ssl, long mode); 1376866Skris 1476866Skris long SSL_CTX_get_mode(SSL_CTX *ctx); 1576866Skris long SSL_get_mode(SSL *ssl); 1676866Skris 1776866Skris=head1 DESCRIPTION 1876866Skris 1976866SkrisSSL_CTX_set_mode() adds the mode set via bitmask in B<mode> to B<ctx>. 2076866SkrisOptions already set before are not cleared. 2176866Skris 2276866SkrisSSL_set_mode() adds the mode set via bitmask in B<mode> to B<ssl>. 2376866SkrisOptions already set before are not cleared. 2476866Skris 2576866SkrisSSL_CTX_get_mode() returns the mode set for B<ctx>. 2676866Skris 2776866SkrisSSL_get_mode() returns the mode set for B<ssl>. 2876866Skris 2976866Skris=head1 NOTES 3076866Skris 3176866SkrisThe following mode changes are available: 3276866Skris 3376866Skris=over 4 3476866Skris 3576866Skris=item SSL_MODE_ENABLE_PARTIAL_WRITE 3676866Skris 3776866SkrisAllow SSL_write(..., n) to return r with 0 < r < n (i.e. report success 3876866Skriswhen just a single record has been written). When not set (the default), 3976866SkrisSSL_write() will only report success once the complete chunk was written. 4089837SkrisOnce SSL_write() returns with r, r bytes have been successfully written 4189837Skrisand the next call to SSL_write() must only send the n-r bytes left, 4289837Skrisimitating the behaviour of write(). 4376866Skris 4476866Skris=item SSL_MODE_ACCEPT_MOVING_WRITE_BUFFER 4576866Skris 4676866SkrisMake it possible to retry SSL_write() with changed buffer location 4776866Skris(the buffer contents must stay the same). This is not the default to avoid 4876866Skristhe misconception that non-blocking SSL_write() behaves like 4976866Skrisnon-blocking write(). 5076866Skris 5176866Skris=item SSL_MODE_AUTO_RETRY 5276866Skris 5376866SkrisNever bother the application with retries if the transport is blocking. 5476866SkrisIf a renegotiation take place during normal operation, a 5576866SkrisL<SSL_read(3)|SSL_read(3)> or L<SSL_write(3)|SSL_write(3)> would return 5676866Skriswith -1 and indicate the need to retry with SSL_ERROR_WANT_READ. 5776866SkrisIn a non-blocking environment applications must be prepared to handle 5876866Skrisincomplete read/write operations. 5976866SkrisIn a blocking environment, applications are not always prepared to 6076866Skrisdeal with read/write operations returning without success report. The 6176866Skrisflag SSL_MODE_AUTO_RETRY will cause read/write operations to only 6276866Skrisreturn after the handshake and successful completion. 6376866Skris 64238405Sjkim=item SSL_MODE_RELEASE_BUFFERS 65238405Sjkim 66238405SjkimWhen we no longer need a read buffer or a write buffer for a given SSL, 67238405Sjkimthen release the memory we were using to hold it. Released memory is 68238405Sjkimeither appended to a list of unused RAM chunks on the SSL_CTX, or simply 69238405Sjkimfreed if the list of unused chunks would become longer than 70238405SjkimSSL_CTX->freelist_max_len, which defaults to 32. Using this flag can 71238405Sjkimsave around 34k per idle SSL connection. 72238405SjkimThis flag has no effect on SSL v2 connections, or on DTLS connections. 73238405Sjkim 74276861Sjkim=item SSL_MODE_SEND_FALLBACK_SCSV 75276861Sjkim 76276861SjkimSend TLS_FALLBACK_SCSV in the ClientHello. 77276861SjkimTo be set only by applications that reconnect with a downgraded protocol 78276861Sjkimversion; see draft-ietf-tls-downgrade-scsv-00 for details. 79276861Sjkim 80276861SjkimDO NOT ENABLE THIS if your application attempts a normal handshake. 81276861SjkimOnly use this in explicit fallback retries, following the guidance 82276861Sjkimin draft-ietf-tls-downgrade-scsv-00. 83276861Sjkim 8476866Skris=back 8576866Skris 8676866Skris=head1 RETURN VALUES 8776866Skris 8876866SkrisSSL_CTX_set_mode() and SSL_set_mode() return the new mode bitmask 8976866Skrisafter adding B<mode>. 9076866Skris 9176866SkrisSSL_CTX_get_mode() and SSL_get_mode() return the current bitmask. 9276866Skris 9376866Skris=head1 SEE ALSO 9476866Skris 9576866SkrisL<ssl(3)|ssl(3)>, L<SSL_read(3)|SSL_read(3)>, L<SSL_write(3)|SSL_write(3)> 9676866Skris 9776866Skris=head1 HISTORY 9876866Skris 9976866SkrisSSL_MODE_AUTO_RETRY as been added in OpenSSL 0.9.6. 10076866Skris 10176866Skris=cut 102