Update per latest manual pages after running 'man-update'.
[dragonfly.git] / secure / lib / libssl / man / SSL_CTX_set_options.3
CommitLineData
a7d27d5a
JR
1.rn '' }`
2''' $RCSfile$$Revision$$Date$
3'''
4''' $Log$
5'''
6.de Sh
984263bc
MD
7.br
8.if t .Sp
9.ne 5
10.PP
11\fB\\$1\fR
12.PP
13..
a7d27d5a 14.de Sp
984263bc
MD
15.if t .sp .5v
16.if n .sp
17..
a7d27d5a 18.de Ip
984263bc
MD
19.br
20.ie \\n(.$>=3 .ne \\$3
21.el .ne 3
22.IP "\\$1" \\$2
23..
a7d27d5a 24.de Vb
984263bc
MD
25.ft CW
26.nf
27.ne \\$1
28..
a7d27d5a 29.de Ve
984263bc
MD
30.ft R
31
32.fi
33..
a7d27d5a
JR
34'''
35'''
36''' Set up \*(-- to give an unbreakable dash;
37''' string Tr holds user defined translation string.
38''' Bell System Logo is used as a dummy character.
39'''
984263bc 40.tr \(*W-|\(bv\*(Tr
984263bc 41.ie n \{\
a7d27d5a
JR
42.ds -- \(*W-
43.ds PI pi
44.if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
45.if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
46.ds L" ""
47.ds R" ""
48''' \*(M", \*(S", \*(N" and \*(T" are the equivalent of
49''' \*(L" and \*(R", except that they are used on ".xx" lines,
50''' such as .IP and .SH, which do another additional levels of
51''' double-quote interpretation
52.ds M" """
53.ds S" """
54.ds N" """""
55.ds T" """""
56.ds L' '
57.ds R' '
58.ds M' '
59.ds S' '
60.ds N' '
61.ds T' '
984263bc
MD
62'br\}
63.el\{\
a7d27d5a
JR
64.ds -- \(em\|
65.tr \*(Tr
66.ds L" ``
67.ds R" ''
68.ds M" ``
69.ds S" ''
70.ds N" ``
71.ds T" ''
72.ds L' `
73.ds R' '
74.ds M' `
75.ds S' '
76.ds N' `
77.ds T' '
78.ds PI \(*p
984263bc 79'br\}
a7d27d5a
JR
80.\" If the F register is turned on, we'll generate
81.\" index entries out stderr for the following things:
82.\" TH Title
83.\" SH Header
84.\" Sh Subsection
85.\" Ip Item
86.\" X<> Xref (embedded
87.\" Of course, you have to process the output yourself
88.\" in some meaninful fashion.
89.if \nF \{
90.de IX
91.tm Index:\\$1\t\\n%\t"\\$2"
984263bc 92..
a7d27d5a
JR
93.nr % 0
94.rr F
984263bc 95.\}
a7d27d5a
JR
96.TH SSL_CTX_set_options 3 "0.9.7d" "2/Sep/2004" "OpenSSL"
97.UC
98.if n .hy 0
984263bc 99.if n .na
a7d27d5a
JR
100.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
101.de CQ \" put $1 in typewriter font
102.ft CW
103'if n "\c
104'if t \\&\\$1\c
105'if n \\&\\$1\c
106'if n \&"
107\\&\\$2 \\$3 \\$4 \\$5 \\$6 \\$7
108'.ft R
109..
110.\" @(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2
111. \" AM - accent mark definitions
984263bc 112.bd B 3
a7d27d5a 113. \" fudge factors for nroff and troff
984263bc 114.if n \{\
a7d27d5a
JR
115. ds #H 0
116. ds #V .8m
117. ds #F .3m
118. ds #[ \f1
119. ds #] \fP
984263bc
MD
120.\}
121.if t \{\
a7d27d5a
JR
122. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
123. ds #V .6m
124. ds #F 0
125. ds #[ \&
126. ds #] \&
984263bc 127.\}
a7d27d5a 128. \" simple accents for nroff and troff
984263bc 129.if n \{\
a7d27d5a
JR
130. ds ' \&
131. ds ` \&
132. ds ^ \&
133. ds , \&
134. ds ~ ~
135. ds ? ?
136. ds ! !
137. ds /
138. ds q
984263bc
MD
139.\}
140.if t \{\
a7d27d5a
JR
141. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
142. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
143. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
144. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
145. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
146. ds ? \s-2c\h'-\w'c'u*7/10'\u\h'\*(#H'\zi\d\s+2\h'\w'c'u*8/10'
147. ds ! \s-2\(or\s+2\h'-\w'\(or'u'\v'-.8m'.\v'.8m'
148. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
149. ds q o\h'-\w'o'u*8/10'\s-4\v'.4m'\z\(*i\v'-.4m'\s+4\h'\w'o'u*8/10'
984263bc 150.\}
a7d27d5a 151. \" troff and (daisy-wheel) nroff accents
984263bc
MD
152.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
153.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
a7d27d5a
JR
154.ds v \\k:\h'-(\\n(.wu*9/10-\*(#H)'\v'-\*(#V'\*(#[\s-4v\s0\v'\*(#V'\h'|\\n:u'\*(#]
155.ds _ \\k:\h'-(\\n(.wu*9/10-\*(#H+(\*(#F*2/3))'\v'-.4m'\z\(hy\v'.4m'\h'|\\n:u'
156.ds . \\k:\h'-(\\n(.wu*8/10)'\v'\*(#V*4/10'\z.\v'-\*(#V*4/10'\h'|\\n:u'
157.ds 3 \*(#[\v'.2m'\s-2\&3\s0\v'-.2m'\*(#]
984263bc
MD
158.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
159.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
160.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
161.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
162.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
163.ds ae a\h'-(\w'a'u*4/10)'e
164.ds Ae A\h'-(\w'A'u*4/10)'E
a7d27d5a
JR
165.ds oe o\h'-(\w'o'u*4/10)'e
166.ds Oe O\h'-(\w'O'u*4/10)'E
167. \" corrections for vroff
984263bc
MD
168.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
169.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
a7d27d5a 170. \" for low resolution devices (crt and lpr)
984263bc
MD
171.if \n(.H>23 .if \n(.V>19 \
172\{\
a7d27d5a
JR
173. ds : e
174. ds 8 ss
175. ds v \h'-1'\o'\(aa\(ga'
176. ds _ \h'-1'^
177. ds . \h'-1'.
178. ds 3 3
179. ds o a
180. ds d- d\h'-1'\(ga
181. ds D- D\h'-1'\(hy
182. ds th \o'bp'
183. ds Th \o'LP'
184. ds ae ae
185. ds Ae AE
186. ds oe oe
187. ds Oe OE
984263bc
MD
188.\}
189.rm #[ #] #H #V #F C
984263bc 190.SH "NAME"
a7d27d5a 191SSL_CTX_set_options, SSL_set_options, SSL_CTX_get_options, SSL_get_options \- manipulate SSL engine options
984263bc 192.SH "SYNOPSIS"
a7d27d5a 193.PP
984263bc
MD
194.Vb 1
195\& #include <openssl/ssl.h>
196.Ve
197.Vb 2
198\& long SSL_CTX_set_options(SSL_CTX *ctx, long options);
199\& long SSL_set_options(SSL *ssl, long options);
200.Ve
201.Vb 2
202\& long SSL_CTX_get_options(SSL_CTX *ctx);
203\& long SSL_get_options(SSL *ssl);
204.Ve
205.SH "DESCRIPTION"
a7d27d5a 206\fISSL_CTX_set_options()\fR adds the options set via bitmask in \fBoptions\fR to \fBctx\fR.
984263bc
MD
207Options already set before are not cleared!
208.PP
a7d27d5a 209\fISSL_set_options()\fR adds the options set via bitmask in \fBoptions\fR to \fBssl\fR.
984263bc
MD
210Options already set before are not cleared!
211.PP
a7d27d5a 212\fISSL_CTX_get_options()\fR returns the options set for \fBctx\fR.
984263bc 213.PP
a7d27d5a 214\fISSL_get_options()\fR returns the options set for \fBssl\fR.
984263bc 215.SH "NOTES"
a7d27d5a 216The behaviour of the SSL library can be changed by setting several options.
984263bc
MD
217The options are coded as bitmasks and can be combined by a logical \fBor\fR
218operation (|). Options can only be added but can never be reset.
219.PP
a7d27d5a
JR
220\fISSL_CTX_set_options()\fR and \fISSL_set_options()\fR affect the (external)
221protocol behaviour of the SSL library. The (internal) behaviour of
222the API can be changed by using the similar
984263bc
MD
223SSL_CTX_set_mode(3) and \fISSL_set_mode()\fR functions.
224.PP
a7d27d5a
JR
225During a handshake, the option settings of the SSL object are used. When
226a new SSL object is created from a context using \fISSL_new()\fR, the current
984263bc 227option setting is copied. Changes to \fBctx\fR do not affect already created
a7d27d5a 228SSL objects. \fISSL_clear()\fR does not affect the settings.
984263bc
MD
229.PP
230The following \fBbug workaround\fR options are available:
231.Ip "\s-1SSL_OP_MICROSOFT_SESS_ID_BUG\s0" 4
984263bc
MD
232www.microsoft.com \- when talking SSLv2, if session-id reuse is
233performed, the session-id passed back in the server-finished message
234is different from the one decided upon.
235.Ip "\s-1SSL_OP_NETSCAPE_CHALLENGE_BUG\s0" 4
984263bc
MD
236Netscape-Commerce/1.12, when talking SSLv2, accepts a 32 byte
237challenge but then appears to only use 16 bytes when generating the
238encryption keys. Using 16 bytes is ok but it should be ok to use 32.
239According to the SSLv3 spec, one should use 32 bytes for the challenge
240when operating in SSLv2/v3 compatibility mode, but as mentioned above,
241this breaks this server so 16 bytes is the way to go.
242.Ip "\s-1SSL_OP_NETSCAPE_REUSE_CIPHER_CHANGE_BUG\s0" 4
a7d27d5a
JR
243ssl3.netscape.com:443, first a connection is established with \s-1RC4-MD5\s0.
244If it is then resumed, we end up using \s-1DES\s0\-\s-1CBC3-SHA\s0. It should be
245\s-1RC4-MD5\s0 according to 7.6.1.3, \*(L'cipher_suite\*(R'.
984263bc
MD
246.Sp
247Netscape-Enterprise/2.01 (https://merchant.netscape.com) has this bug.
248It only really shows up when connecting via SSLv2/v3 then reconnecting
249via SSLv3. The cipher list changes....
250.Sp
a7d27d5a
JR
251\s-1NEW\s0 \s-1INFORMATION\s0. Try connecting with a cipher list of just
252\s-1DES\s0\-\s-1CBC\s0\-\s-1SHA:RC4-MD5\s0. For some weird reason, each new connection uses
253\s-1RC4-MD5\s0, but a re-connect tries to use \s-1DES\s0\-\s-1CBC\s0\-\s-1SHA\s0. So netscape, when
984263bc
MD
254doing a re-connect, always takes the first cipher in the cipher list.
255.Ip "\s-1SSL_OP_SSLREF2_REUSE_CERT_TYPE_BUG\s0" 4
984263bc
MD
256\&...
257.Ip "\s-1SSL_OP_MICROSOFT_BIG_SSLV3_BUFFER\s0" 4
984263bc
MD
258\&...
259.Ip "\s-1SSL_OP_MSIE_SSLV2_RSA_PADDING\s0" 4
984263bc
MD
260\&...
261.Ip "\s-1SSL_OP_SSLEAY_080_CLIENT_DH_BUG\s0" 4
984263bc
MD
262\&...
263.Ip "\s-1SSL_OP_TLS_D5_BUG\s0" 4
984263bc
MD
264\&...
265.Ip "\s-1SSL_OP_TLS_BLOCK_PADDING_BUG\s0" 4
984263bc
MD
266\&...
267.Ip "\s-1SSL_OP_DONT_INSERT_EMPTY_FRAGMENTS\s0" 4
a7d27d5a 268Disables a countermeasure against a \s-1SSL\s0 3.0/\s-1TLS\s0 1.0 protocol
984263bc
MD
269vulnerability affecting \s-1CBC\s0 ciphers, which cannot be handled by some
270broken \s-1SSL\s0 implementations. This option has no effect for connections
271using other ciphers.
272.Ip "\s-1SSL_OP_ALL\s0" 4
984263bc
MD
273All of the above bug workarounds.
274.PP
275It is usually safe to use \fB\s-1SSL_OP_ALL\s0\fR to enable the bug workaround
276options if compatibility with somewhat broken implementations is
277desired.
278.PP
279The following \fBmodifying\fR options are available:
280.Ip "\s-1SSL_OP_TLS_ROLLBACK_BUG\s0" 4
984263bc
MD
281Disable version rollback attack detection.
282.Sp
283During the client key exchange, the client must send the same information
284about acceptable \s-1SSL/TLS\s0 protocol levels as during the first hello. Some
285clients violate this rule by adapting to the server's answer. (Example:
286the client sends a SSLv2 hello and accepts up to SSLv3.1=TLSv1, the server
287only understands up to SSLv3. In this case the client must still use the
288same SSLv3.1=TLSv1 announcement. Some clients step down to SSLv3 with respect
289to the server's answer and violate the version rollback protection.)
290.Ip "\s-1SSL_OP_SINGLE_DH_USE\s0" 4
984263bc
MD
291Always create a new key when using temporary/ephemeral \s-1DH\s0 parameters
292(see SSL_CTX_set_tmp_dh_callback(3)).
293This option must be used to prevent small subgroup attacks, when
294the \s-1DH\s0 parameters were not generated using \*(L"strong\*(R" primes
a7d27d5a 295(e.g. when using \s-1DSA\s0\-parameters, see dhparam(1)).
984263bc
MD
296If \*(L"strong\*(R" primes were used, it is not strictly necessary to generate
297a new \s-1DH\s0 key during each handshake but it is also recommended.
a7d27d5a 298\fB\s-1SSL_OP_SINGLE_DH_USE\s0\fR should therefore be enabled whenever
984263bc
MD
299temporary/ephemeral \s-1DH\s0 parameters are used.
300.Ip "\s-1SSL_OP_EPHEMERAL_RSA\s0" 4
984263bc
MD
301Always use ephemeral (temporary) \s-1RSA\s0 key when doing \s-1RSA\s0 operations
302(see SSL_CTX_set_tmp_rsa_callback(3)).
303According to the specifications this is only done, when a \s-1RSA\s0 key
304can only be used for signature operations (namely under export ciphers
305with restricted \s-1RSA\s0 keylength). By setting this option, ephemeral
a7d27d5a
JR
306\s-1RSA\s0 keys are always used. This option breaks compatibility with the
307\s-1SSL/TLS\s0 specifications and may lead to interoperability problems with
984263bc
MD
308clients and should therefore never be used. Ciphers with \s-1EDH\s0 (ephemeral
309Diffie-Hellman) key exchange should be used instead.
310.Ip "\s-1SSL_OP_CIPHER_SERVER_PREFERENCE\s0" 4
984263bc
MD
311When choosing a cipher, use the server's preferences instead of the client
312preferences. When not set, the \s-1SSL\s0 server will always follow the clients
313preferences. When set, the SSLv3/TLSv1 server will choose following its
314own preferences. Because of the different protocol, for SSLv2 the server
315will send his list of preferences to the client and the client chooses.
316.Ip "\s-1SSL_OP_PKCS1_CHECK_1\s0" 4
984263bc
MD
317\&...
318.Ip "\s-1SSL_OP_PKCS1_CHECK_2\s0" 4
984263bc
MD
319\&...
320.Ip "\s-1SSL_OP_NETSCAPE_CA_DN_BUG\s0" 4
984263bc 321If we accept a netscape connection, demand a client cert, have a
a7d27d5a 322non-self-signed \s-1CA\s0 which does not have its \s-1CA\s0 in netscape, and the
984263bc
MD
323browser has a cert, it will crash/hang. Works for 3.x and 4.xbeta
324.Ip "\s-1SSL_OP_NETSCAPE_DEMO_CIPHER_CHANGE_BUG\s0" 4
984263bc
MD
325\&...
326.Ip "SSL_OP_NO_SSLv2" 4
984263bc
MD
327Do not use the SSLv2 protocol.
328.Ip "SSL_OP_NO_SSLv3" 4
984263bc
MD
329Do not use the SSLv3 protocol.
330.Ip "SSL_OP_NO_TLSv1" 4
984263bc
MD
331Do not use the TLSv1 protocol.
332.Ip "\s-1SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION\s0" 4
984263bc
MD
333When performing renegotiation as a server, always start a new session
334(i.e., session resumption requests are only accepted in the initial
335handshake). This option is not needed for clients.
336.SH "RETURN VALUES"
a7d27d5a 337\fISSL_CTX_set_options()\fR and \fISSL_set_options()\fR return the new options bitmask
984263bc
MD
338after adding \fBoptions\fR.
339.PP
a7d27d5a 340\fISSL_CTX_get_options()\fR and \fISSL_get_options()\fR return the current bitmask.
984263bc 341.SH "SEE ALSO"
984263bc
MD
342ssl(3), SSL_new(3), SSL_clear(3),
343SSL_CTX_set_tmp_dh_callback(3),
344SSL_CTX_set_tmp_rsa_callback(3),
345dhparam(1)
346.SH "HISTORY"
a7d27d5a
JR
347\fBSSL_OP_CIPHER_SERVER_PREFERENCE\fR and
348\fBSSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION\fR have been added in
984263bc
MD
349OpenSSL 0.9.7.
350.PP
a7d27d5a
JR
351\fBSSL_OP_TLS_ROLLBACK_BUG\fR has been added in OpenSSL 0.9.6 and was automatically
352enabled with \fBSSL_OP_ALL\fR. As of 0.9.7, it is no longer included in \fBSSL_OP_ALL\fR
984263bc
MD
353and must be explicitly set.
354.PP
a7d27d5a 355\fBSSL_OP_DONT_INSERT_EMPTY_FRAGMENTS\fR has been added in OpenSSL 0.9.6e.
984263bc
MD
356Versions up to OpenSSL 0.9.6c do not include the countermeasure that
357can be disabled with this option (in OpenSSL 0.9.6d, it was always
358enabled).
a7d27d5a
JR
359
360.rn }` ''
361.IX Title "SSL_CTX_set_options 3"
362.IX Name "SSL_CTX_set_options, SSL_set_options, SSL_CTX_get_options, SSL_get_options - manipulate SSL engine options"
363
364.IX Header "NAME"
365
366.IX Header "SYNOPSIS"
367
368.IX Header "DESCRIPTION"
369
370.IX Header "NOTES"
371
372.IX Item "\s-1SSL_OP_MICROSOFT_SESS_ID_BUG\s0"
373
374.IX Item "\s-1SSL_OP_NETSCAPE_CHALLENGE_BUG\s0"
375
376.IX Item "\s-1SSL_OP_NETSCAPE_REUSE_CIPHER_CHANGE_BUG\s0"
377
378.IX Item "\s-1SSL_OP_SSLREF2_REUSE_CERT_TYPE_BUG\s0"
379
380.IX Item "\s-1SSL_OP_MICROSOFT_BIG_SSLV3_BUFFER\s0"
381
382.IX Item "\s-1SSL_OP_MSIE_SSLV2_RSA_PADDING\s0"
383
384.IX Item "\s-1SSL_OP_SSLEAY_080_CLIENT_DH_BUG\s0"
385
386.IX Item "\s-1SSL_OP_TLS_D5_BUG\s0"
387
388.IX Item "\s-1SSL_OP_TLS_BLOCK_PADDING_BUG\s0"
389
390.IX Item "\s-1SSL_OP_DONT_INSERT_EMPTY_FRAGMENTS\s0"
391
392.IX Item "\s-1SSL_OP_ALL\s0"
393
394.IX Item "\s-1SSL_OP_TLS_ROLLBACK_BUG\s0"
395
396.IX Item "\s-1SSL_OP_SINGLE_DH_USE\s0"
397
398.IX Item "\s-1SSL_OP_EPHEMERAL_RSA\s0"
399
400.IX Item "\s-1SSL_OP_CIPHER_SERVER_PREFERENCE\s0"
401
402.IX Item "\s-1SSL_OP_PKCS1_CHECK_1\s0"
403
404.IX Item "\s-1SSL_OP_PKCS1_CHECK_2\s0"
405
406.IX Item "\s-1SSL_OP_NETSCAPE_CA_DN_BUG\s0"
407
408.IX Item "\s-1SSL_OP_NETSCAPE_DEMO_CIPHER_CHANGE_BUG\s0"
409
410.IX Item "SSL_OP_NO_SSLv2"
411
412.IX Item "SSL_OP_NO_SSLv3"
413
414.IX Item "SSL_OP_NO_TLSv1"
415
416.IX Item "\s-1SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION\s0"
417
418.IX Header "RETURN VALUES"
419
420.IX Header "SEE ALSO"
421
422.IX Header "HISTORY"
423