]>
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 | ||
9c0586d5 | 21 | SSL_CTX_set_mode() adds the mode set via bit-mask in B<mode> to B<ctx>. |
f282ca74 | 22 | Options already set before are not cleared. |
9c0586d5 | 23 | SSL_CTX_clear_mode() removes the mode set via bit-mask in B<mode> from B<ctx>. |
f282ca74 | 24 | |
9c0586d5 | 25 | SSL_set_mode() adds the mode set via bit-mask in B<mode> to B<ssl>. |
f282ca74 | 26 | Options already set before are not cleared. |
9c0586d5 | 27 | SSL_clear_mode() removes the mode set via bit-mask 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 | |
490c8711 GN |
53 | avoid the misconception that nonblocking SSL_write() behaves like |
54 | nonblocking write(). | |
f282ca74 LJ |
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 | ||
490c8711 | 67 | In a nonblocking environment applications must be prepared to handle |
f282ca74 | 68 | incomplete read/write operations. |
490c8711 | 69 | Setting B<SSL_MODE_AUTO_RETRY> for a nonblocking B<BIO> will process |
57fd5170 KR |
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 | ||
09d62b33 MT |
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 | ||
f282ca74 LJ |
117 | =back |
118 | ||
57fd5170 KR |
119 | All modes are off by default except for SSL_MODE_AUTO_RETRY which is on by |
120 | default since 1.1.1. | |
121 | ||
f282ca74 LJ |
122 | =head1 RETURN VALUES |
123 | ||
9c0586d5 | 124 | SSL_CTX_set_mode() and SSL_set_mode() return the new mode bit-mask |
f282ca74 LJ |
125 | after adding B<mode>. |
126 | ||
9c0586d5 | 127 | SSL_CTX_get_mode() and SSL_get_mode() return the current bit-mask. |
f282ca74 LJ |
128 | |
129 | =head1 SEE ALSO | |
130 | ||
b97fdb57 | 131 | L<ssl(7)>, L<SSL_read_ex(3)>, L<SSL_read(3)>, L<SSL_write_ex(3)> or |
7714dc5e | 132 | L<SSL_write(3)>, L<SSL_get_error(3)> |
bc8857bf | 133 | |
bc8857bf MC |
134 | =head1 HISTORY |
135 | ||
fc5ecadd | 136 | SSL_MODE_ASYNC was added in OpenSSL 1.1.0. |
f282ca74 | 137 | |
e2f92610 RS |
138 | =head1 COPYRIGHT |
139 | ||
0f84cbc3 | 140 | Copyright 2001-2020 The OpenSSL Project Authors. All Rights Reserved. |
e2f92610 | 141 | |
4746f25a | 142 | Licensed under the Apache License 2.0 (the "License"). You may not use |
e2f92610 RS |
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 |