SSL_CTX_set_mode.pod revision 302408
1=pod 2 3=head1 NAME 4 5SSL_CTX_set_mode, SSL_set_mode, SSL_CTX_get_mode, SSL_get_mode - manipulate SSL engine mode 6 7=head1 SYNOPSIS 8 9 #include <openssl/ssl.h> 10 11 long SSL_CTX_set_mode(SSL_CTX *ctx, long mode); 12 long SSL_set_mode(SSL *ssl, long mode); 13 14 long SSL_CTX_get_mode(SSL_CTX *ctx); 15 long SSL_get_mode(SSL *ssl); 16 17=head1 DESCRIPTION 18 19SSL_CTX_set_mode() adds the mode set via bitmask in B<mode> to B<ctx>. 20Options already set before are not cleared. 21 22SSL_set_mode() adds the mode set via bitmask in B<mode> to B<ssl>. 23Options already set before are not cleared. 24 25SSL_CTX_get_mode() returns the mode set for B<ctx>. 26 27SSL_get_mode() returns the mode set for B<ssl>. 28 29=head1 NOTES 30 31The following mode changes are available: 32 33=over 4 34 35=item SSL_MODE_ENABLE_PARTIAL_WRITE 36 37Allow SSL_write(..., n) to return r with 0 < r < n (i.e. report success 38when just a single record has been written). When not set (the default), 39SSL_write() will only report success once the complete chunk was written. 40Once SSL_write() returns with r, r bytes have been successfully written 41and the next call to SSL_write() must only send the n-r bytes left, 42imitating the behaviour of write(). 43 44=item SSL_MODE_ACCEPT_MOVING_WRITE_BUFFER 45 46Make it possible to retry SSL_write() with changed buffer location 47(the buffer contents must stay the same). This is not the default to avoid 48the misconception that non-blocking SSL_write() behaves like 49non-blocking write(). 50 51=item SSL_MODE_AUTO_RETRY 52 53Never bother the application with retries if the transport is blocking. 54If a renegotiation take place during normal operation, a 55L<SSL_read(3)|SSL_read(3)> or L<SSL_write(3)|SSL_write(3)> would return 56with -1 and indicate the need to retry with SSL_ERROR_WANT_READ. 57In a non-blocking environment applications must be prepared to handle 58incomplete read/write operations. 59In a blocking environment, applications are not always prepared to 60deal with read/write operations returning without success report. The 61flag SSL_MODE_AUTO_RETRY will cause read/write operations to only 62return after the handshake and successful completion. 63 64=item SSL_MODE_RELEASE_BUFFERS 65 66When we no longer need a read buffer or a write buffer for a given SSL, 67then release the memory we were using to hold it. Released memory is 68either appended to a list of unused RAM chunks on the SSL_CTX, or simply 69freed if the list of unused chunks would become longer than 70SSL_CTX->freelist_max_len, which defaults to 32. Using this flag can 71save around 34k per idle SSL connection. 72This flag has no effect on SSL v2 connections, or on DTLS connections. 73 74=item SSL_MODE_SEND_FALLBACK_SCSV 75 76Send TLS_FALLBACK_SCSV in the ClientHello. 77To be set only by applications that reconnect with a downgraded protocol 78version; see draft-ietf-tls-downgrade-scsv-00 for details. 79 80DO NOT ENABLE THIS if your application attempts a normal handshake. 81Only use this in explicit fallback retries, following the guidance 82in draft-ietf-tls-downgrade-scsv-00. 83 84=back 85 86=head1 RETURN VALUES 87 88SSL_CTX_set_mode() and SSL_set_mode() return the new mode bitmask 89after adding B<mode>. 90 91SSL_CTX_get_mode() and SSL_get_mode() return the current bitmask. 92 93=head1 SEE ALSO 94 95L<ssl(3)|ssl(3)>, L<SSL_read(3)|SSL_read(3)>, L<SSL_write(3)|SSL_write(3)> 96 97=head1 HISTORY 98 99SSL_MODE_AUTO_RETRY as been added in OpenSSL 0.9.6. 100 101=cut 102