]>
Commit | Line | Data |
---|---|---|
f282ca74 LJ |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
57fd5170 | 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 |
f282ca74 LJ |
6 | |
7 | =head1 SYNOPSIS | |
8 | ||
9 | #include <openssl/ssl.h> | |
10 | ||
11 | long SSL_CTX_set_mode(SSL_CTX *ctx, long mode); | |
57fd5170 | 12 | long SSL_CTX_clear_mode(SSL_CTX *ctx, long mode); |
f282ca74 | 13 | long SSL_set_mode(SSL *ssl, long mode); |
57fd5170 | 14 | long SSL_clear_mode(SSL *ssl, long mode); |
f282ca74 LJ |
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 bitmask in B<mode> to B<ctx>. | |
22 | Options already set before are not cleared. | |
57fd5170 | 23 | SSL_CTX_clear_mode() removes the mode set via bitmask in B<mode> from B<ctx>. |
f282ca74 LJ |
24 | |
25 | SSL_set_mode() adds the mode set via bitmask in B<mode> to B<ssl>. | |
26 | Options already set before are not cleared. | |
57fd5170 | 27 | SSL_clear_mode() removes the mode set via bitmask in B<mode> from B<ssl>. |
f282ca74 LJ |
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 | ||
7714dc5e MC |
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 | |
6782e5fd MC |
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(). | |
f282ca74 LJ |
48 | |
49 | =item SSL_MODE_ACCEPT_MOVING_WRITE_BUFFER | |
50 | ||
7714dc5e MC |
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 non-blocking SSL_write() behaves like | |
f282ca74 LJ |
54 | non-blocking write(). |
55 | ||
56 | =item SSL_MODE_AUTO_RETRY | |
57 | ||
57fd5170 KR |
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 | ||
f282ca74 LJ |
67 | In a non-blocking environment applications must be prepared to handle |
68 | incomplete read/write operations. | |
57fd5170 KR |
69 | Setting B<SSL_MODE_AUTO_RETRY> for a non-blocking 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 | ||
f282ca74 | 73 | In a blocking environment, applications are not always prepared to |
57fd5170 KR |
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. | |
f282ca74 | 83 | |
8671b898 BL |
84 | =item SSL_MODE_RELEASE_BUFFERS |
85 | ||
86 | When we no longer need a read buffer or a write buffer for a given SSL, | |
63c574f6 RS |
87 | then release the memory we were using to hold it. |
88 | Using this flag can | |
8671b898 BL |
89 | save around 34k per idle SSL connection. |
90 | This flag has no effect on SSL v2 connections, or on DTLS connections. | |
91 | ||
98f1ac7d | 92 | =item SSL_MODE_SEND_FALLBACK_SCSV |
fb0e87fb BM |
93 | |
94 | Send TLS_FALLBACK_SCSV in the ClientHello. | |
98f1ac7d | 95 | To be set only by applications that reconnect with a downgraded protocol |
fb0e87fb BM |
96 | version; see draft-ietf-tls-downgrade-scsv-00 for details. |
97 | ||
98f1ac7d BM |
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 | ||
bc8857bf MC |
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 | ||
50ec7505 BP |
108 | =item SSL_MODE_NO_KTLS_TX |
109 | ||
110 | Disable the use of the kernel TLS egress data-path. | |
111 | By default kernel TLS is enabled if it is supported by the negotiated ciphersuites | |
112 | and extensions and OpenSSL has been compiled with support for it. | |
113 | The kernel TLS data-path implements the record layer, | |
114 | and the crypto algorithm. The kernel will utilize the best hardware | |
115 | available for crypto. Using the kernel data-path should reduce the memory | |
116 | footprint of OpenSSL because no buffering is required. Also, the throughput | |
117 | should improve because data copy is avoided when user data is encrypted into | |
118 | kernel memory instead of the usual encrypt than copy to kernel. | |
119 | ||
120 | Kernel TLS might not support all the features of OpenSSL. For instance, | |
121 | renegotiation, and setting the maximum fragment size is not possible as of | |
122 | Linux 4.20. | |
123 | ||
09d62b33 MT |
124 | =item SSL_MODE_DTLS_SCTP_LABEL_LENGTH_BUG |
125 | ||
126 | Older versions of OpenSSL had a bug in the computation of the label length | |
127 | used for computing the endpoint-pair shared secret. The bug was that the | |
128 | terminating zero was included in the length of the label. Setting this option | |
129 | enables this behaviour to allow interoperability with such broken | |
130 | implementations. Please note that setting this option breaks interoperability | |
131 | with correct implementations. This option only applies to DTLS over SCTP. | |
132 | ||
f282ca74 LJ |
133 | =back |
134 | ||
57fd5170 KR |
135 | All modes are off by default except for SSL_MODE_AUTO_RETRY which is on by |
136 | default since 1.1.1. | |
137 | ||
f282ca74 LJ |
138 | =head1 RETURN VALUES |
139 | ||
140 | SSL_CTX_set_mode() and SSL_set_mode() return the new mode bitmask | |
141 | after adding B<mode>. | |
142 | ||
143 | SSL_CTX_get_mode() and SSL_get_mode() return the current bitmask. | |
144 | ||
145 | =head1 SEE ALSO | |
146 | ||
b97fdb57 | 147 | L<ssl(7)>, L<SSL_read_ex(3)>, L<SSL_read(3)>, L<SSL_write_ex(3)> or |
7714dc5e | 148 | L<SSL_write(3)>, L<SSL_get_error(3)> |
bc8857bf | 149 | |
bc8857bf MC |
150 | =head1 HISTORY |
151 | ||
fc5ecadd DMSP |
152 | SSL_MODE_ASYNC was added in OpenSSL 1.1.0. |
153 | SSL_MODE_NO_KTLS_TX was added in OpenSSL 3.0.0. | |
f282ca74 | 154 | |
e2f92610 RS |
155 | =head1 COPYRIGHT |
156 | ||
1212818e | 157 | Copyright 2001-2018 The OpenSSL Project Authors. All Rights Reserved. |
e2f92610 | 158 | |
4746f25a | 159 | Licensed under the Apache License 2.0 (the "License"). You may not use |
e2f92610 RS |
160 | this file except in compliance with the License. You can obtain a copy |
161 | in the file LICENSE in the source distribution or at | |
162 | L<https://www.openssl.org/source/license.html>. | |
163 | ||
164 | =cut |