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