1e71b7053SJung-uk Kim=pod 2e71b7053SJung-uk Kim 3e71b7053SJung-uk Kim=head1 NAME 4e71b7053SJung-uk Kim 5e71b7053SJung-uk KimSSL_CTX_set_mode, SSL_CTX_clear_mode, SSL_set_mode, SSL_clear_mode, SSL_CTX_get_mode, SSL_get_mode - manipulate SSL engine mode 6e71b7053SJung-uk Kim 7e71b7053SJung-uk Kim=head1 SYNOPSIS 8e71b7053SJung-uk Kim 9e71b7053SJung-uk Kim #include <openssl/ssl.h> 10e71b7053SJung-uk Kim 11e71b7053SJung-uk Kim long SSL_CTX_set_mode(SSL_CTX *ctx, long mode); 12e71b7053SJung-uk Kim long SSL_CTX_clear_mode(SSL_CTX *ctx, long mode); 13e71b7053SJung-uk Kim long SSL_set_mode(SSL *ssl, long mode); 14e71b7053SJung-uk Kim long SSL_clear_mode(SSL *ssl, long mode); 15e71b7053SJung-uk Kim 16e71b7053SJung-uk Kim long SSL_CTX_get_mode(SSL_CTX *ctx); 17e71b7053SJung-uk Kim long SSL_get_mode(SSL *ssl); 18e71b7053SJung-uk Kim 19e71b7053SJung-uk Kim=head1 DESCRIPTION 20e71b7053SJung-uk Kim 21b077aed3SPierre ProncherySSL_CTX_set_mode() adds the mode set via bit-mask in B<mode> to B<ctx>. 22e71b7053SJung-uk KimOptions already set before are not cleared. 23b077aed3SPierre ProncherySSL_CTX_clear_mode() removes the mode set via bit-mask in B<mode> from B<ctx>. 24e71b7053SJung-uk Kim 25b077aed3SPierre ProncherySSL_set_mode() adds the mode set via bit-mask in B<mode> to B<ssl>. 26e71b7053SJung-uk KimOptions already set before are not cleared. 27b077aed3SPierre ProncherySSL_clear_mode() removes the mode set via bit-mask in B<mode> from B<ssl>. 28e71b7053SJung-uk Kim 29e71b7053SJung-uk KimSSL_CTX_get_mode() returns the mode set for B<ctx>. 30e71b7053SJung-uk Kim 31e71b7053SJung-uk KimSSL_get_mode() returns the mode set for B<ssl>. 32e71b7053SJung-uk Kim 33e71b7053SJung-uk Kim=head1 NOTES 34e71b7053SJung-uk Kim 35e71b7053SJung-uk KimThe following mode changes are available: 36e71b7053SJung-uk Kim 37e71b7053SJung-uk Kim=over 4 38e71b7053SJung-uk Kim 39e71b7053SJung-uk Kim=item SSL_MODE_ENABLE_PARTIAL_WRITE 40e71b7053SJung-uk Kim 41e71b7053SJung-uk KimAllow SSL_write_ex(..., n, &r) to return with 0 < r < n (i.e. report success 42e71b7053SJung-uk Kimwhen just a single record has been written). This works in a similar way for 43e71b7053SJung-uk KimSSL_write(). When not set (the default), SSL_write_ex() or SSL_write() will only 44e71b7053SJung-uk Kimreport success once the complete chunk was written. Once SSL_write_ex() or 45e71b7053SJung-uk KimSSL_write() returns successful, B<r> bytes have been written and the next call 46e71b7053SJung-uk Kimto SSL_write_ex() or SSL_write() must only send the n-r bytes left, imitating 47e71b7053SJung-uk Kimthe behaviour of write(). 48e71b7053SJung-uk Kim 49e71b7053SJung-uk Kim=item SSL_MODE_ACCEPT_MOVING_WRITE_BUFFER 50e71b7053SJung-uk Kim 51e71b7053SJung-uk KimMake it possible to retry SSL_write_ex() or SSL_write() with changed buffer 52e71b7053SJung-uk Kimlocation (the buffer contents must stay the same). This is not the default to 5358f35182SJung-uk Kimavoid the misconception that nonblocking SSL_write() behaves like 5458f35182SJung-uk Kimnonblocking write(). 55e71b7053SJung-uk Kim 56e71b7053SJung-uk Kim=item SSL_MODE_AUTO_RETRY 57e71b7053SJung-uk Kim 58e71b7053SJung-uk KimDuring normal operations, non-application data records might need to be sent or 59e71b7053SJung-uk Kimreceived that the application is not aware of. 60e71b7053SJung-uk KimIf a non-application data record was processed, 61e71b7053SJung-uk KimL<SSL_read_ex(3)> and L<SSL_read(3)> can return with a failure and indicate the 62e71b7053SJung-uk Kimneed to retry with B<SSL_ERROR_WANT_READ>. 63e71b7053SJung-uk KimIf such a non-application data record was processed, the flag 64e71b7053SJung-uk KimB<SSL_MODE_AUTO_RETRY> causes it to try to process the next record instead of 65e71b7053SJung-uk Kimreturning. 66e71b7053SJung-uk Kim 6758f35182SJung-uk KimIn a nonblocking environment applications must be prepared to handle 68e71b7053SJung-uk Kimincomplete read/write operations. 6958f35182SJung-uk KimSetting B<SSL_MODE_AUTO_RETRY> for a nonblocking B<BIO> will process 70e71b7053SJung-uk Kimnon-application data records until either no more data is available or 71e71b7053SJung-uk Kiman application data record has been processed. 72e71b7053SJung-uk Kim 73e71b7053SJung-uk KimIn a blocking environment, applications are not always prepared to 74e71b7053SJung-uk Kimdeal with the functions returning intermediate reports such as retry 75e71b7053SJung-uk Kimrequests, and setting the B<SSL_MODE_AUTO_RETRY> flag will cause the functions 76e71b7053SJung-uk Kimto only return after successfully processing an application data record or a 77e71b7053SJung-uk Kimfailure. 78e71b7053SJung-uk Kim 79e71b7053SJung-uk KimTurning off B<SSL_MODE_AUTO_RETRY> can be useful with blocking B<BIO>s in case 80e71b7053SJung-uk Kimthey are used in combination with something like select() or poll(). 81e71b7053SJung-uk KimOtherwise the call to SSL_read() or SSL_read_ex() might hang when a 82e71b7053SJung-uk Kimnon-application record was sent and no application data was sent. 83e71b7053SJung-uk Kim 84e71b7053SJung-uk Kim=item SSL_MODE_RELEASE_BUFFERS 85e71b7053SJung-uk Kim 86e71b7053SJung-uk KimWhen we no longer need a read buffer or a write buffer for a given SSL, 87e71b7053SJung-uk Kimthen release the memory we were using to hold it. 88e71b7053SJung-uk KimUsing this flag can 89e71b7053SJung-uk Kimsave around 34k per idle SSL connection. 90e71b7053SJung-uk KimThis flag has no effect on SSL v2 connections, or on DTLS connections. 91e71b7053SJung-uk Kim 92e71b7053SJung-uk Kim=item SSL_MODE_SEND_FALLBACK_SCSV 93e71b7053SJung-uk Kim 94e71b7053SJung-uk KimSend TLS_FALLBACK_SCSV in the ClientHello. 95e71b7053SJung-uk KimTo be set only by applications that reconnect with a downgraded protocol 96e71b7053SJung-uk Kimversion; see draft-ietf-tls-downgrade-scsv-00 for details. 97e71b7053SJung-uk Kim 98e71b7053SJung-uk KimDO NOT ENABLE THIS if your application attempts a normal handshake. 99e71b7053SJung-uk KimOnly use this in explicit fallback retries, following the guidance 100e71b7053SJung-uk Kimin draft-ietf-tls-downgrade-scsv-00. 101e71b7053SJung-uk Kim 102e71b7053SJung-uk Kim=item SSL_MODE_ASYNC 103e71b7053SJung-uk Kim 104e71b7053SJung-uk KimEnable asynchronous processing. TLS I/O operations may indicate a retry with 105e71b7053SJung-uk KimSSL_ERROR_WANT_ASYNC with this mode set if an asynchronous capable engine is 106e71b7053SJung-uk Kimused to perform cryptographic operations. See L<SSL_get_error(3)>. 107e71b7053SJung-uk Kim 1086935a639SJung-uk Kim=item SSL_MODE_DTLS_SCTP_LABEL_LENGTH_BUG 1096935a639SJung-uk Kim 1106935a639SJung-uk KimOlder versions of OpenSSL had a bug in the computation of the label length 1116935a639SJung-uk Kimused for computing the endpoint-pair shared secret. The bug was that the 1126935a639SJung-uk Kimterminating zero was included in the length of the label. Setting this option 1136935a639SJung-uk Kimenables this behaviour to allow interoperability with such broken 1146935a639SJung-uk Kimimplementations. Please note that setting this option breaks interoperability 1156935a639SJung-uk Kimwith correct implementations. This option only applies to DTLS over SCTP. 1166935a639SJung-uk Kim 117e71b7053SJung-uk Kim=back 118e71b7053SJung-uk Kim 119e71b7053SJung-uk KimAll modes are off by default except for SSL_MODE_AUTO_RETRY which is on by 120e71b7053SJung-uk Kimdefault since 1.1.1. 121e71b7053SJung-uk Kim 122e71b7053SJung-uk Kim=head1 RETURN VALUES 123e71b7053SJung-uk Kim 124b077aed3SPierre ProncherySSL_CTX_set_mode() and SSL_set_mode() return the new mode bit-mask 125e71b7053SJung-uk Kimafter adding B<mode>. 126e71b7053SJung-uk Kim 127b077aed3SPierre ProncherySSL_CTX_get_mode() and SSL_get_mode() return the current bit-mask. 128e71b7053SJung-uk Kim 129e71b7053SJung-uk Kim=head1 SEE ALSO 130e71b7053SJung-uk Kim 131e71b7053SJung-uk KimL<ssl(7)>, L<SSL_read_ex(3)>, L<SSL_read(3)>, L<SSL_write_ex(3)> or 132e71b7053SJung-uk KimL<SSL_write(3)>, L<SSL_get_error(3)> 133e71b7053SJung-uk Kim 134e71b7053SJung-uk Kim=head1 HISTORY 135e71b7053SJung-uk Kim 1366935a639SJung-uk KimSSL_MODE_ASYNC was added in OpenSSL 1.1.0. 137e71b7053SJung-uk Kim 138e71b7053SJung-uk Kim=head1 COPYRIGHT 139e71b7053SJung-uk Kim 140b077aed3SPierre ProncheryCopyright 2001-2021 The OpenSSL Project Authors. All Rights Reserved. 141e71b7053SJung-uk Kim 142b077aed3SPierre ProncheryLicensed under the Apache License 2.0 (the "License"). You may not use 143e71b7053SJung-uk Kimthis file except in compliance with the License. You can obtain a copy 144e71b7053SJung-uk Kimin the file LICENSE in the source distribution or at 145e71b7053SJung-uk KimL<https://www.openssl.org/source/license.html>. 146e71b7053SJung-uk Kim 147e71b7053SJung-uk Kim=cut 148