Commit | Line | Data |
---|---|---|
5a44c043 | 1 | .\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28) |
e056f0e0 JR |
2 | .\" |
3 | .\" Standard preamble: | |
4 | .\" ======================================================================== | |
e056f0e0 | 5 | .de Sp \" Vertical space (when we can't use .PP) |
984263bc MD |
6 | .if t .sp .5v |
7 | .if n .sp | |
8 | .. | |
e056f0e0 | 9 | .de Vb \" Begin verbatim text |
984263bc MD |
10 | .ft CW |
11 | .nf | |
12 | .ne \\$1 | |
13 | .. | |
e056f0e0 | 14 | .de Ve \" End verbatim text |
984263bc | 15 | .ft R |
984263bc MD |
16 | .fi |
17 | .. | |
e056f0e0 JR |
18 | .\" Set up some character translations and predefined strings. \*(-- will |
19 | .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left | |
e257b235 PA |
20 | .\" double quote, and \*(R" will give a right double quote. \*(C+ will |
21 | .\" give a nicer C++. Capital omega is used to do unbreakable dashes and | |
22 | .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, | |
23 | .\" nothing in troff, for use with C<>. | |
24 | .tr \(*W- | |
e056f0e0 | 25 | .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' |
984263bc | 26 | .ie n \{\ |
e056f0e0 JR |
27 | . ds -- \(*W- |
28 | . ds PI pi | |
29 | . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch | |
30 | . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch | |
31 | . ds L" "" | |
32 | . ds R" "" | |
33 | . ds C` "" | |
34 | . ds C' "" | |
984263bc MD |
35 | 'br\} |
36 | .el\{\ | |
e056f0e0 JR |
37 | . ds -- \|\(em\| |
38 | . ds PI \(*p | |
39 | . ds L" `` | |
40 | . ds R" '' | |
5a44c043 SW |
41 | . ds C` |
42 | . ds C' | |
984263bc | 43 | 'br\} |
e056f0e0 | 44 | .\" |
e257b235 PA |
45 | .\" Escape single quotes in literal strings from groff's Unicode transform. |
46 | .ie \n(.g .ds Aq \(aq | |
47 | .el .ds Aq ' | |
48 | .\" | |
e056f0e0 | 49 | .\" If the F register is turned on, we'll generate index entries on stderr for |
01185282 | 50 | .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index |
e056f0e0 JR |
51 | .\" entries marked with X<> in POD. Of course, you'll have to process the |
52 | .\" output yourself in some meaningful fashion. | |
5a44c043 SW |
53 | .\" |
54 | .\" Avoid warning from groff about undefined register 'F'. | |
55 | .de IX | |
984263bc | 56 | .. |
5a44c043 SW |
57 | .nr rF 0 |
58 | .if \n(.g .if rF .nr rF 1 | |
59 | .if (\n(rF:(\n(.g==0)) \{ | |
60 | . if \nF \{ | |
61 | . de IX | |
62 | . tm Index:\\$1\t\\n%\t"\\$2" | |
e257b235 | 63 | .. |
5a44c043 SW |
64 | . if !\nF==2 \{ |
65 | . nr % 0 | |
66 | . nr F 2 | |
67 | . \} | |
68 | . \} | |
e257b235 | 69 | .\} |
5a44c043 | 70 | .rr rF |
aac4ff6f | 71 | .\" |
e056f0e0 JR |
72 | .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). |
73 | .\" Fear. Run. Save yourself. No user-serviceable parts. | |
74 | . \" fudge factors for nroff and troff | |
984263bc | 75 | .if n \{\ |
e056f0e0 JR |
76 | . ds #H 0 |
77 | . ds #V .8m | |
78 | . ds #F .3m | |
79 | . ds #[ \f1 | |
80 | . ds #] \fP | |
984263bc MD |
81 | .\} |
82 | .if t \{\ | |
e056f0e0 JR |
83 | . ds #H ((1u-(\\\\n(.fu%2u))*.13m) |
84 | . ds #V .6m | |
85 | . ds #F 0 | |
86 | . ds #[ \& | |
87 | . ds #] \& | |
984263bc | 88 | .\} |
e056f0e0 | 89 | . \" simple accents for nroff and troff |
984263bc | 90 | .if n \{\ |
e056f0e0 JR |
91 | . ds ' \& |
92 | . ds ` \& | |
93 | . ds ^ \& | |
94 | . ds , \& | |
95 | . ds ~ ~ | |
96 | . ds / | |
984263bc MD |
97 | .\} |
98 | .if t \{\ | |
e056f0e0 JR |
99 | . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" |
100 | . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' | |
101 | . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' | |
102 | . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' | |
103 | . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' | |
104 | . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' | |
984263bc | 105 | .\} |
e056f0e0 | 106 | . \" troff and (daisy-wheel) nroff accents |
984263bc MD |
107 | .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' |
108 | .ds 8 \h'\*(#H'\(*b\h'-\*(#H' | |
109 | .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] | |
110 | .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' | |
111 | .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' | |
112 | .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] | |
113 | .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] | |
114 | .ds ae a\h'-(\w'a'u*4/10)'e | |
115 | .ds Ae A\h'-(\w'A'u*4/10)'E | |
e056f0e0 | 116 | . \" corrections for vroff |
984263bc MD |
117 | .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' |
118 | .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' | |
e056f0e0 | 119 | . \" for low resolution devices (crt and lpr) |
984263bc MD |
120 | .if \n(.H>23 .if \n(.V>19 \ |
121 | \{\ | |
e056f0e0 JR |
122 | . ds : e |
123 | . ds 8 ss | |
124 | . ds o a | |
125 | . ds d- d\h'-1'\(ga | |
126 | . ds D- D\h'-1'\(hy | |
127 | . ds th \o'bp' | |
128 | . ds Th \o'LP' | |
129 | . ds ae ae | |
130 | . ds Ae AE | |
984263bc MD |
131 | .\} |
132 | .rm #[ #] #H #V #F C | |
e056f0e0 JR |
133 | .\" ======================================================================== |
134 | .\" | |
135 | .IX Title "SSL_CTX_set_options 3" | |
7dc78669 | 136 | .TH SSL_CTX_set_options 3 "2015-07-09" "1.0.1p" "OpenSSL" |
e257b235 PA |
137 | .\" For nroff, turn off justification. Always turn off hyphenation; it makes |
138 | .\" way too many mistakes in technical documents. | |
139 | .if n .ad l | |
140 | .nh | |
984263bc | 141 | .SH "NAME" |
01185282 | 142 | SSL_CTX_set_options, SSL_set_options, SSL_CTX_clear_options, SSL_clear_options, SSL_CTX_get_options, SSL_get_options, SSL_get_secure_renegotiation_support \- manipulate SSL options |
984263bc | 143 | .SH "SYNOPSIS" |
e056f0e0 | 144 | .IX Header "SYNOPSIS" |
984263bc MD |
145 | .Vb 1 |
146 | \& #include <openssl/ssl.h> | |
e257b235 | 147 | \& |
984263bc MD |
148 | \& long SSL_CTX_set_options(SSL_CTX *ctx, long options); |
149 | \& long SSL_set_options(SSL *ssl, long options); | |
e257b235 | 150 | \& |
01185282 PA |
151 | \& long SSL_CTX_clear_options(SSL_CTX *ctx, long options); |
152 | \& long SSL_clear_options(SSL *ssl, long options); | |
153 | \& | |
984263bc MD |
154 | \& long SSL_CTX_get_options(SSL_CTX *ctx); |
155 | \& long SSL_get_options(SSL *ssl); | |
01185282 PA |
156 | \& |
157 | \& long SSL_get_secure_renegotiation_support(SSL *ssl); | |
984263bc MD |
158 | .Ve |
159 | .SH "DESCRIPTION" | |
e056f0e0 | 160 | .IX Header "DESCRIPTION" |
01185282 PA |
161 | Note: all these functions are implemented using macros. |
162 | .PP | |
e056f0e0 | 163 | \&\fISSL_CTX_set_options()\fR adds the options set via bitmask in \fBoptions\fR to \fBctx\fR. |
984263bc MD |
164 | Options already set before are not cleared! |
165 | .PP | |
e056f0e0 | 166 | \&\fISSL_set_options()\fR adds the options set via bitmask in \fBoptions\fR to \fBssl\fR. |
984263bc MD |
167 | Options already set before are not cleared! |
168 | .PP | |
01185282 PA |
169 | \&\fISSL_CTX_clear_options()\fR clears the options set via bitmask in \fBoptions\fR |
170 | to \fBctx\fR. | |
171 | .PP | |
172 | \&\fISSL_clear_options()\fR clears the options set via bitmask in \fBoptions\fR to \fBssl\fR. | |
173 | .PP | |
e056f0e0 | 174 | \&\fISSL_CTX_get_options()\fR returns the options set for \fBctx\fR. |
984263bc | 175 | .PP |
e056f0e0 | 176 | \&\fISSL_get_options()\fR returns the options set for \fBssl\fR. |
01185282 PA |
177 | .PP |
178 | \&\fISSL_get_secure_renegotiation_support()\fR indicates whether the peer supports | |
179 | secure renegotiation. | |
984263bc | 180 | .SH "NOTES" |
e056f0e0 JR |
181 | .IX Header "NOTES" |
182 | The behaviour of the \s-1SSL\s0 library can be changed by setting several options. | |
984263bc | 183 | The options are coded as bitmasks and can be combined by a logical \fBor\fR |
01185282 | 184 | operation (|). |
984263bc | 185 | .PP |
e056f0e0 JR |
186 | \&\fISSL_CTX_set_options()\fR and \fISSL_set_options()\fR affect the (external) |
187 | protocol behaviour of the \s-1SSL\s0 library. The (internal) behaviour of | |
188 | the \s-1API\s0 can be changed by using the similar | |
189 | \&\fISSL_CTX_set_mode\fR\|(3) and \fISSL_set_mode()\fR functions. | |
984263bc | 190 | .PP |
e056f0e0 JR |
191 | During a handshake, the option settings of the \s-1SSL\s0 object are used. When |
192 | a new \s-1SSL\s0 object is created from a context using \fISSL_new()\fR, the current | |
984263bc | 193 | option setting is copied. Changes to \fBctx\fR do not affect already created |
e056f0e0 | 194 | \&\s-1SSL\s0 objects. \fISSL_clear()\fR does not affect the settings. |
984263bc MD |
195 | .PP |
196 | The following \fBbug workaround\fR options are available: | |
e056f0e0 JR |
197 | .IP "\s-1SSL_OP_MICROSOFT_SESS_ID_BUG\s0" 4 |
198 | .IX Item "SSL_OP_MICROSOFT_SESS_ID_BUG" | |
984263bc MD |
199 | www.microsoft.com \- when talking SSLv2, if session-id reuse is |
200 | performed, the session-id passed back in the server-finished message | |
201 | is different from the one decided upon. | |
e056f0e0 JR |
202 | .IP "\s-1SSL_OP_NETSCAPE_CHALLENGE_BUG\s0" 4 |
203 | .IX Item "SSL_OP_NETSCAPE_CHALLENGE_BUG" | |
204 | Netscape\-Commerce/1.12, when talking SSLv2, accepts a 32 byte | |
984263bc MD |
205 | challenge but then appears to only use 16 bytes when generating the |
206 | encryption keys. Using 16 bytes is ok but it should be ok to use 32. | |
207 | According to the SSLv3 spec, one should use 32 bytes for the challenge | |
208 | when operating in SSLv2/v3 compatibility mode, but as mentioned above, | |
209 | this breaks this server so 16 bytes is the way to go. | |
e056f0e0 JR |
210 | .IP "\s-1SSL_OP_NETSCAPE_REUSE_CIPHER_CHANGE_BUG\s0" 4 |
211 | .IX Item "SSL_OP_NETSCAPE_REUSE_CIPHER_CHANGE_BUG" | |
b911043f | 212 | As of OpenSSL 0.9.8q and 1.0.0c, this option has no effect. |
e056f0e0 JR |
213 | .IP "\s-1SSL_OP_SSLREF2_REUSE_CERT_TYPE_BUG\s0" 4 |
214 | .IX Item "SSL_OP_SSLREF2_REUSE_CERT_TYPE_BUG" | |
984263bc | 215 | \&... |
e056f0e0 JR |
216 | .IP "\s-1SSL_OP_MICROSOFT_BIG_SSLV3_BUFFER\s0" 4 |
217 | .IX Item "SSL_OP_MICROSOFT_BIG_SSLV3_BUFFER" | |
984263bc | 218 | \&... |
11c7e1cd PA |
219 | .IP "\s-1SSL_OP_SAFARI_ECDHE_ECDSA_BUG\s0" 4 |
220 | .IX Item "SSL_OP_SAFARI_ECDHE_ECDSA_BUG" | |
5a44c043 SW |
221 | Don't prefer ECDHE-ECDSA ciphers when the client appears to be Safari on \s-1OS X. |
222 | OS X 10.8..10.8.3\s0 has broken support for ECDHE-ECDSA ciphers. | |
e056f0e0 JR |
223 | .IP "\s-1SSL_OP_SSLEAY_080_CLIENT_DH_BUG\s0" 4 |
224 | .IX Item "SSL_OP_SSLEAY_080_CLIENT_DH_BUG" | |
984263bc | 225 | \&... |
e056f0e0 JR |
226 | .IP "\s-1SSL_OP_TLS_D5_BUG\s0" 4 |
227 | .IX Item "SSL_OP_TLS_D5_BUG" | |
984263bc | 228 | \&... |
e056f0e0 JR |
229 | .IP "\s-1SSL_OP_TLS_BLOCK_PADDING_BUG\s0" 4 |
230 | .IX Item "SSL_OP_TLS_BLOCK_PADDING_BUG" | |
984263bc | 231 | \&... |
e056f0e0 JR |
232 | .IP "\s-1SSL_OP_DONT_INSERT_EMPTY_FRAGMENTS\s0" 4 |
233 | .IX Item "SSL_OP_DONT_INSERT_EMPTY_FRAGMENTS" | |
5a44c043 | 234 | Disables a countermeasure against a \s-1SSL 3.0/TLS 1.0\s0 protocol |
984263bc MD |
235 | vulnerability affecting \s-1CBC\s0 ciphers, which cannot be handled by some |
236 | broken \s-1SSL\s0 implementations. This option has no effect for connections | |
237 | using other ciphers. | |
34240b21 SW |
238 | .IP "\s-1SSL_OP_TLSEXT_PADDING\s0" 4 |
239 | .IX Item "SSL_OP_TLSEXT_PADDING" | |
240 | Adds a padding extension to ensure the ClientHello size is never between | |
241 | 256 and 511 bytes in length. This is needed as a workaround for some | |
242 | implementations. | |
e056f0e0 JR |
243 | .IP "\s-1SSL_OP_ALL\s0" 4 |
244 | .IX Item "SSL_OP_ALL" | |
984263bc MD |
245 | All of the above bug workarounds. |
246 | .PP | |
247 | It is usually safe to use \fB\s-1SSL_OP_ALL\s0\fR to enable the bug workaround | |
248 | options if compatibility with somewhat broken implementations is | |
249 | desired. | |
250 | .PP | |
251 | The following \fBmodifying\fR options are available: | |
e056f0e0 JR |
252 | .IP "\s-1SSL_OP_TLS_ROLLBACK_BUG\s0" 4 |
253 | .IX Item "SSL_OP_TLS_ROLLBACK_BUG" | |
984263bc MD |
254 | Disable version rollback attack detection. |
255 | .Sp | |
256 | During the client key exchange, the client must send the same information | |
257 | about acceptable \s-1SSL/TLS\s0 protocol levels as during the first hello. Some | |
258 | clients violate this rule by adapting to the server's answer. (Example: | |
259 | the client sends a SSLv2 hello and accepts up to SSLv3.1=TLSv1, the server | |
260 | only understands up to SSLv3. In this case the client must still use the | |
261 | same SSLv3.1=TLSv1 announcement. Some clients step down to SSLv3 with respect | |
262 | to the server's answer and violate the version rollback protection.) | |
e056f0e0 JR |
263 | .IP "\s-1SSL_OP_SINGLE_DH_USE\s0" 4 |
264 | .IX Item "SSL_OP_SINGLE_DH_USE" | |
984263bc | 265 | Always create a new key when using temporary/ephemeral \s-1DH\s0 parameters |
e056f0e0 | 266 | (see \fISSL_CTX_set_tmp_dh_callback\fR\|(3)). |
984263bc MD |
267 | This option must be used to prevent small subgroup attacks, when |
268 | the \s-1DH\s0 parameters were not generated using \*(L"strong\*(R" primes | |
e257b235 | 269 | (e.g. when using DSA-parameters, see \fIdhparam\fR\|(1)). |
984263bc MD |
270 | If \*(L"strong\*(R" primes were used, it is not strictly necessary to generate |
271 | a new \s-1DH\s0 key during each handshake but it is also recommended. | |
e056f0e0 | 272 | \&\fB\s-1SSL_OP_SINGLE_DH_USE\s0\fR should therefore be enabled whenever |
984263bc | 273 | temporary/ephemeral \s-1DH\s0 parameters are used. |
e056f0e0 JR |
274 | .IP "\s-1SSL_OP_EPHEMERAL_RSA\s0" 4 |
275 | .IX Item "SSL_OP_EPHEMERAL_RSA" | |
ca2244c8 | 276 | This option is no longer implemented and is treated as no op. |
e056f0e0 JR |
277 | .IP "\s-1SSL_OP_CIPHER_SERVER_PREFERENCE\s0" 4 |
278 | .IX Item "SSL_OP_CIPHER_SERVER_PREFERENCE" | |
984263bc MD |
279 | When choosing a cipher, use the server's preferences instead of the client |
280 | preferences. When not set, the \s-1SSL\s0 server will always follow the clients | |
281 | preferences. When set, the SSLv3/TLSv1 server will choose following its | |
282 | own preferences. Because of the different protocol, for SSLv2 the server | |
a561f9ff | 283 | will send its list of preferences to the client and the client chooses. |
e056f0e0 JR |
284 | .IP "\s-1SSL_OP_PKCS1_CHECK_1\s0" 4 |
285 | .IX Item "SSL_OP_PKCS1_CHECK_1" | |
984263bc | 286 | \&... |
e056f0e0 JR |
287 | .IP "\s-1SSL_OP_PKCS1_CHECK_2\s0" 4 |
288 | .IX Item "SSL_OP_PKCS1_CHECK_2" | |
984263bc | 289 | \&... |
e056f0e0 JR |
290 | .IP "\s-1SSL_OP_NETSCAPE_CA_DN_BUG\s0" 4 |
291 | .IX Item "SSL_OP_NETSCAPE_CA_DN_BUG" | |
984263bc | 292 | If we accept a netscape connection, demand a client cert, have a |
a7d27d5a | 293 | non-self-signed \s-1CA\s0 which does not have its \s-1CA\s0 in netscape, and the |
e257b235 | 294 | browser has a cert, it will crash/hang. Works for 3.x and 4.xbeta |
e056f0e0 JR |
295 | .IP "\s-1SSL_OP_NETSCAPE_DEMO_CIPHER_CHANGE_BUG\s0" 4 |
296 | .IX Item "SSL_OP_NETSCAPE_DEMO_CIPHER_CHANGE_BUG" | |
984263bc | 297 | \&... |
e056f0e0 JR |
298 | .IP "SSL_OP_NO_SSLv2" 4 |
299 | .IX Item "SSL_OP_NO_SSLv2" | |
984263bc | 300 | Do not use the SSLv2 protocol. |
e056f0e0 JR |
301 | .IP "SSL_OP_NO_SSLv3" 4 |
302 | .IX Item "SSL_OP_NO_SSLv3" | |
984263bc | 303 | Do not use the SSLv3 protocol. |
e056f0e0 JR |
304 | .IP "SSL_OP_NO_TLSv1" 4 |
305 | .IX Item "SSL_OP_NO_TLSv1" | |
984263bc | 306 | Do not use the TLSv1 protocol. |
e056f0e0 JR |
307 | .IP "\s-1SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION\s0" 4 |
308 | .IX Item "SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION" | |
984263bc MD |
309 | When performing renegotiation as a server, always start a new session |
310 | (i.e., session resumption requests are only accepted in the initial | |
01185282 | 311 | handshake). This option is not needed for clients. |
2c0715f4 PA |
312 | .IP "\s-1SSL_OP_NO_TICKET\s0" 4 |
313 | .IX Item "SSL_OP_NO_TICKET" | |
314 | Normally clients and servers will, where possible, transparently make use | |
01185282 | 315 | of RFC4507bis tickets for stateless session resumption. |
2c0715f4 PA |
316 | .Sp |
317 | If this option is set this functionality is disabled and tickets will | |
318 | not be used by clients or servers. | |
01185282 PA |
319 | .IP "\s-1SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION\s0" 4 |
320 | .IX Item "SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION" | |
321 | Allow legacy insecure renegotiation between OpenSSL and unpatched clients or | |
5a44c043 | 322 | servers. See the \fB\s-1SECURE RENEGOTIATION\s0\fR section for more details. |
01185282 PA |
323 | .IP "\s-1SSL_OP_LEGACY_SERVER_CONNECT\s0" 4 |
324 | .IX Item "SSL_OP_LEGACY_SERVER_CONNECT" | |
325 | Allow legacy insecure renegotiation between OpenSSL and unpatched servers | |
326 | \&\fBonly\fR: this option is currently set by default. See the | |
5a44c043 | 327 | \&\fB\s-1SECURE RENEGOTIATION\s0\fR section for more details. |
01185282 PA |
328 | .SH "SECURE RENEGOTIATION" |
329 | .IX Header "SECURE RENEGOTIATION" | |
330 | OpenSSL 0.9.8m and later always attempts to use secure renegotiation as | |
5a44c043 | 331 | described in \s-1RFC5746.\s0 This counters the prefix attack described in |
01185282 PA |
332 | \&\s-1CVE\-2009\-3555\s0 and elsewhere. |
333 | .PP | |
334 | The deprecated and highly broken SSLv2 protocol does not support | |
335 | renegotiation at all: its use is \fBstrongly\fR discouraged. | |
336 | .PP | |
337 | This attack has far reaching consequences which application writers should be | |
338 | aware of. In the description below an implementation supporting secure | |
339 | renegotiation is referred to as \fIpatched\fR. A server not supporting secure | |
340 | renegotiation is referred to as \fIunpatched\fR. | |
341 | .PP | |
342 | The following sections describe the operations permitted by OpenSSL's secure | |
343 | renegotiation implementation. | |
344 | .SS "Patched client and server" | |
345 | .IX Subsection "Patched client and server" | |
346 | Connections and renegotiation are always permitted by OpenSSL implementations. | |
347 | .SS "Unpatched client and patched OpenSSL server" | |
348 | .IX Subsection "Unpatched client and patched OpenSSL server" | |
ecf90583 | 349 | The initial connection succeeds but client renegotiation is denied by the |
01185282 PA |
350 | server with a \fBno_renegotiation\fR warning alert if \s-1TLS\s0 v1.0 is used or a fatal |
351 | \&\fBhandshake_failure\fR alert in \s-1SSL\s0 v3.0. | |
352 | .PP | |
353 | If the patched OpenSSL server attempts to renegotiate a fatal | |
354 | \&\fBhandshake_failure\fR alert is sent. This is because the server code may be | |
355 | unaware of the unpatched nature of the client. | |
356 | .PP | |
357 | If the option \fB\s-1SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION\s0\fR is set then | |
358 | renegotiation \fBalways\fR succeeds. | |
359 | .PP | |
360 | \&\fB\s-1NB:\s0\fR a bug in OpenSSL clients earlier than 0.9.8m (all of which are | |
361 | unpatched) will result in the connection hanging if it receives a | |
362 | \&\fBno_renegotiation\fR alert. OpenSSL versions 0.9.8m and later will regard | |
363 | a \fBno_renegotiation\fR alert as fatal and respond with a fatal | |
364 | \&\fBhandshake_failure\fR alert. This is because the OpenSSL \s-1API\s0 currently has | |
365 | no provision to indicate to an application that a renegotiation attempt | |
366 | was refused. | |
367 | .SS "Patched OpenSSL client and unpatched server." | |
368 | .IX Subsection "Patched OpenSSL client and unpatched server." | |
369 | If the option \fB\s-1SSL_OP_LEGACY_SERVER_CONNECT\s0\fR or | |
370 | \&\fB\s-1SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION\s0\fR is set then initial connections | |
371 | and renegotiation between patched OpenSSL clients and unpatched servers | |
372 | succeeds. If neither option is set then initial connections to unpatched | |
373 | servers will fail. | |
374 | .PP | |
375 | The option \fB\s-1SSL_OP_LEGACY_SERVER_CONNECT\s0\fR is currently set by default even | |
376 | though it has security implications: otherwise it would be impossible to | |
377 | connect to unpatched servers (i.e. all of them initially) and this is clearly | |
378 | not acceptable. Renegotiation is permitted because this does not add any | |
379 | additional security issues: during an attack clients do not see any | |
380 | renegotiations anyway. | |
381 | .PP | |
382 | As more servers become patched the option \fB\s-1SSL_OP_LEGACY_SERVER_CONNECT\s0\fR will | |
383 | \&\fBnot\fR be set by default in a future version of OpenSSL. | |
384 | .PP | |
385 | OpenSSL client applications wishing to ensure they can connect to unpatched | |
386 | servers should always \fBset\fR \fB\s-1SSL_OP_LEGACY_SERVER_CONNECT\s0\fR | |
387 | .PP | |
388 | OpenSSL client applications that want to ensure they can \fBnot\fR connect to | |
389 | unpatched servers (and thus avoid any security issues) should always \fBclear\fR | |
390 | \&\fB\s-1SSL_OP_LEGACY_SERVER_CONNECT\s0\fR using \fISSL_CTX_clear_options()\fR or | |
391 | \&\fISSL_clear_options()\fR. | |
392 | .PP | |
393 | The difference between the \fB\s-1SSL_OP_LEGACY_SERVER_CONNECT\s0\fR and | |
394 | \&\fB\s-1SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION\s0\fR options is that | |
395 | \&\fB\s-1SSL_OP_LEGACY_SERVER_CONNECT\s0\fR enables initial connections and secure | |
396 | renegotiation between OpenSSL clients and unpatched servers \fBonly\fR, while | |
397 | \&\fB\s-1SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION\s0\fR allows initial connections | |
398 | and renegotiation between OpenSSL and unpatched clients or servers. | |
984263bc | 399 | .SH "RETURN VALUES" |
e056f0e0 JR |
400 | .IX Header "RETURN VALUES" |
401 | \&\fISSL_CTX_set_options()\fR and \fISSL_set_options()\fR return the new options bitmask | |
984263bc MD |
402 | after adding \fBoptions\fR. |
403 | .PP | |
01185282 PA |
404 | \&\fISSL_CTX_clear_options()\fR and \fISSL_clear_options()\fR return the new options bitmask |
405 | after clearing \fBoptions\fR. | |
406 | .PP | |
e056f0e0 | 407 | \&\fISSL_CTX_get_options()\fR and \fISSL_get_options()\fR return the current bitmask. |
01185282 PA |
408 | .PP |
409 | \&\fISSL_get_secure_renegotiation_support()\fR returns 1 is the peer supports | |
410 | secure renegotiation and 0 if it does not. | |
984263bc | 411 | .SH "SEE ALSO" |
e056f0e0 JR |
412 | .IX Header "SEE ALSO" |
413 | \&\fIssl\fR\|(3), \fISSL_new\fR\|(3), \fISSL_clear\fR\|(3), | |
414 | \&\fISSL_CTX_set_tmp_dh_callback\fR\|(3), | |
415 | \&\fISSL_CTX_set_tmp_rsa_callback\fR\|(3), | |
416 | \&\fIdhparam\fR\|(1) | |
984263bc | 417 | .SH "HISTORY" |
e056f0e0 JR |
418 | .IX Header "HISTORY" |
419 | \&\fB\s-1SSL_OP_CIPHER_SERVER_PREFERENCE\s0\fR and | |
420 | \&\fB\s-1SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION\s0\fR have been added in | |
984263bc MD |
421 | OpenSSL 0.9.7. |
422 | .PP | |
e056f0e0 JR |
423 | \&\fB\s-1SSL_OP_TLS_ROLLBACK_BUG\s0\fR has been added in OpenSSL 0.9.6 and was automatically |
424 | enabled with \fB\s-1SSL_OP_ALL\s0\fR. As of 0.9.7, it is no longer included in \fB\s-1SSL_OP_ALL\s0\fR | |
984263bc MD |
425 | and must be explicitly set. |
426 | .PP | |
e056f0e0 | 427 | \&\fB\s-1SSL_OP_DONT_INSERT_EMPTY_FRAGMENTS\s0\fR has been added in OpenSSL 0.9.6e. |
984263bc MD |
428 | Versions up to OpenSSL 0.9.6c do not include the countermeasure that |
429 | can be disabled with this option (in OpenSSL 0.9.6d, it was always | |
430 | enabled). | |
01185282 PA |
431 | .PP |
432 | \&\fISSL_CTX_clear_options()\fR and \fISSL_clear_options()\fR were first added in OpenSSL | |
433 | 0.9.8m. | |
434 | .PP | |
435 | \&\fB\s-1SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION\s0\fR, \fB\s-1SSL_OP_LEGACY_SERVER_CONNECT\s0\fR | |
436 | and the function \fISSL_get_secure_renegotiation_support()\fR were first added in | |
437 | OpenSSL 0.9.8m. |