Merge from vendor branch OPENSSL:
[dragonfly.git] / secure / lib / libssl / man / SSL_CTX_set_options.3
CommitLineData
d3fa4948 1.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.14
e056f0e0
JR
2.\"
3.\" Standard preamble:
4.\" ========================================================================
5.de Sh \" Subsection heading
984263bc
MD
6.br
7.if t .Sp
8.ne 5
9.PP
10\fB\\$1\fR
11.PP
12..
e056f0e0 13.de Sp \" Vertical space (when we can't use .PP)
984263bc
MD
14.if t .sp .5v
15.if n .sp
16..
e056f0e0 17.de Vb \" Begin verbatim text
984263bc
MD
18.ft CW
19.nf
20.ne \\$1
21..
e056f0e0 22.de Ve \" End verbatim text
984263bc 23.ft R
984263bc
MD
24.fi
25..
e056f0e0
JR
26.\" Set up some character translations and predefined strings. \*(-- will
27.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
28.\" double quote, and \*(R" will give a right double quote. | will give a
29.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to
30.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C'
31.\" expand to `' in nroff, nothing in troff, for use with C<>.
984263bc 32.tr \(*W-|\(bv\*(Tr
e056f0e0 33.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
984263bc 34.ie n \{\
e056f0e0
JR
35. ds -- \(*W-
36. ds PI pi
37. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
38. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
39. ds L" ""
40. ds R" ""
41. ds C` ""
42. ds C' ""
984263bc
MD
43'br\}
44.el\{\
e056f0e0
JR
45. ds -- \|\(em\|
46. ds PI \(*p
47. ds L" ``
48. ds R" ''
984263bc 49'br\}
e056f0e0
JR
50.\"
51.\" If the F register is turned on, we'll generate index entries on stderr for
52.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
53.\" entries marked with X<> in POD. Of course, you'll have to process the
54.\" output yourself in some meaningful fashion.
55.if \nF \{\
56. de IX
57. tm Index:\\$1\t\\n%\t"\\$2"
984263bc 58..
e056f0e0
JR
59. nr % 0
60. rr F
984263bc 61.\}
e056f0e0
JR
62.\"
63.\" For nroff, turn off justification. Always turn off hyphenation; it makes
64.\" way too many mistakes in technical documents.
65.hy 0
984263bc 66.if n .na
e056f0e0
JR
67.\"
68.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
69.\" Fear. Run. Save yourself. No user-serviceable parts.
70. \" fudge factors for nroff and troff
984263bc 71.if n \{\
e056f0e0
JR
72. ds #H 0
73. ds #V .8m
74. ds #F .3m
75. ds #[ \f1
76. ds #] \fP
984263bc
MD
77.\}
78.if t \{\
e056f0e0
JR
79. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
80. ds #V .6m
81. ds #F 0
82. ds #[ \&
83. ds #] \&
984263bc 84.\}
e056f0e0 85. \" simple accents for nroff and troff
984263bc 86.if n \{\
e056f0e0
JR
87. ds ' \&
88. ds ` \&
89. ds ^ \&
90. ds , \&
91. ds ~ ~
92. ds /
984263bc
MD
93.\}
94.if t \{\
e056f0e0
JR
95. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
96. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
97. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
98. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
99. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
100. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
984263bc 101.\}
e056f0e0 102. \" troff and (daisy-wheel) nroff accents
984263bc
MD
103.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
104.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
105.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
106.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
107.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
108.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
109.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
110.ds ae a\h'-(\w'a'u*4/10)'e
111.ds Ae A\h'-(\w'A'u*4/10)'E
e056f0e0 112. \" corrections for vroff
984263bc
MD
113.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
114.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
e056f0e0 115. \" for low resolution devices (crt and lpr)
984263bc
MD
116.if \n(.H>23 .if \n(.V>19 \
117\{\
e056f0e0
JR
118. ds : e
119. ds 8 ss
120. ds o a
121. ds d- d\h'-1'\(ga
122. ds D- D\h'-1'\(hy
123. ds th \o'bp'
124. ds Th \o'LP'
125. ds ae ae
126. ds Ae AE
984263bc
MD
127.\}
128.rm #[ #] #H #V #F C
e056f0e0
JR
129.\" ========================================================================
130.\"
131.IX Title "SSL_CTX_set_options 3"
edae4a78 132.TH SSL_CTX_set_options 3 "2007-03-28" "0.9.8e" "OpenSSL"
984263bc 133.SH "NAME"
a7d27d5a 134SSL_CTX_set_options, SSL_set_options, SSL_CTX_get_options, SSL_get_options \- manipulate SSL engine options
984263bc 135.SH "SYNOPSIS"
e056f0e0 136.IX Header "SYNOPSIS"
984263bc
MD
137.Vb 1
138\& #include <openssl/ssl.h>
139.Ve
e056f0e0 140.PP
984263bc
MD
141.Vb 2
142\& long SSL_CTX_set_options(SSL_CTX *ctx, long options);
143\& long SSL_set_options(SSL *ssl, long options);
144.Ve
e056f0e0 145.PP
984263bc
MD
146.Vb 2
147\& long SSL_CTX_get_options(SSL_CTX *ctx);
148\& long SSL_get_options(SSL *ssl);
149.Ve
150.SH "DESCRIPTION"
e056f0e0
JR
151.IX Header "DESCRIPTION"
152\&\fISSL_CTX_set_options()\fR adds the options set via bitmask in \fBoptions\fR to \fBctx\fR.
984263bc
MD
153Options already set before are not cleared!
154.PP
e056f0e0 155\&\fISSL_set_options()\fR adds the options set via bitmask in \fBoptions\fR to \fBssl\fR.
984263bc
MD
156Options already set before are not cleared!
157.PP
e056f0e0 158\&\fISSL_CTX_get_options()\fR returns the options set for \fBctx\fR.
984263bc 159.PP
e056f0e0 160\&\fISSL_get_options()\fR returns the options set for \fBssl\fR.
984263bc 161.SH "NOTES"
e056f0e0
JR
162.IX Header "NOTES"
163The behaviour of the \s-1SSL\s0 library can be changed by setting several options.
984263bc
MD
164The options are coded as bitmasks and can be combined by a logical \fBor\fR
165operation (|). Options can only be added but can never be reset.
166.PP
e056f0e0
JR
167\&\fISSL_CTX_set_options()\fR and \fISSL_set_options()\fR affect the (external)
168protocol behaviour of the \s-1SSL\s0 library. The (internal) behaviour of
169the \s-1API\s0 can be changed by using the similar
170\&\fISSL_CTX_set_mode\fR\|(3) and \fISSL_set_mode()\fR functions.
984263bc 171.PP
e056f0e0
JR
172During a handshake, the option settings of the \s-1SSL\s0 object are used. When
173a new \s-1SSL\s0 object is created from a context using \fISSL_new()\fR, the current
984263bc 174option setting is copied. Changes to \fBctx\fR do not affect already created
e056f0e0 175\&\s-1SSL\s0 objects. \fISSL_clear()\fR does not affect the settings.
984263bc
MD
176.PP
177The following \fBbug workaround\fR options are available:
e056f0e0
JR
178.IP "\s-1SSL_OP_MICROSOFT_SESS_ID_BUG\s0" 4
179.IX Item "SSL_OP_MICROSOFT_SESS_ID_BUG"
984263bc
MD
180www.microsoft.com \- when talking SSLv2, if session-id reuse is
181performed, the session-id passed back in the server-finished message
182is different from the one decided upon.
e056f0e0
JR
183.IP "\s-1SSL_OP_NETSCAPE_CHALLENGE_BUG\s0" 4
184.IX Item "SSL_OP_NETSCAPE_CHALLENGE_BUG"
185Netscape\-Commerce/1.12, when talking SSLv2, accepts a 32 byte
984263bc
MD
186challenge but then appears to only use 16 bytes when generating the
187encryption keys. Using 16 bytes is ok but it should be ok to use 32.
188According to the SSLv3 spec, one should use 32 bytes for the challenge
189when operating in SSLv2/v3 compatibility mode, but as mentioned above,
190this breaks this server so 16 bytes is the way to go.
e056f0e0
JR
191.IP "\s-1SSL_OP_NETSCAPE_REUSE_CIPHER_CHANGE_BUG\s0" 4
192.IX Item "SSL_OP_NETSCAPE_REUSE_CIPHER_CHANGE_BUG"
193ssl3.netscape.com:443, first a connection is established with \s-1RC4\-MD5\s0.
194If it is then resumed, we end up using \s-1DES\-CBC3\-SHA\s0. It should be
195\&\s-1RC4\-MD5\s0 according to 7.6.1.3, 'cipher_suite'.
984263bc 196.Sp
e056f0e0 197Netscape\-Enterprise/2.01 (https://merchant.netscape.com) has this bug.
984263bc
MD
198It only really shows up when connecting via SSLv2/v3 then reconnecting
199via SSLv3. The cipher list changes....
200.Sp
e056f0e0
JR
201\&\s-1NEW\s0 \s-1INFORMATION\s0. Try connecting with a cipher list of just
202\&\s-1DES\-CBC\-SHA:RC4\-MD5\s0. For some weird reason, each new connection uses
203\&\s-1RC4\-MD5\s0, but a re-connect tries to use \s-1DES\-CBC\-SHA\s0. So netscape, when
204doing a re\-connect, always takes the first cipher in the cipher list.
205.IP "\s-1SSL_OP_SSLREF2_REUSE_CERT_TYPE_BUG\s0" 4
206.IX Item "SSL_OP_SSLREF2_REUSE_CERT_TYPE_BUG"
984263bc 207\&...
e056f0e0
JR
208.IP "\s-1SSL_OP_MICROSOFT_BIG_SSLV3_BUFFER\s0" 4
209.IX Item "SSL_OP_MICROSOFT_BIG_SSLV3_BUFFER"
984263bc 210\&...
e056f0e0
JR
211.IP "\s-1SSL_OP_MSIE_SSLV2_RSA_PADDING\s0" 4
212.IX Item "SSL_OP_MSIE_SSLV2_RSA_PADDING"
c6082640 213As of OpenSSL 0.9.7h and 0.9.8a, this option has no effect.
e056f0e0
JR
214.IP "\s-1SSL_OP_SSLEAY_080_CLIENT_DH_BUG\s0" 4
215.IX Item "SSL_OP_SSLEAY_080_CLIENT_DH_BUG"
984263bc 216\&...
e056f0e0
JR
217.IP "\s-1SSL_OP_TLS_D5_BUG\s0" 4
218.IX Item "SSL_OP_TLS_D5_BUG"
984263bc 219\&...
e056f0e0
JR
220.IP "\s-1SSL_OP_TLS_BLOCK_PADDING_BUG\s0" 4
221.IX Item "SSL_OP_TLS_BLOCK_PADDING_BUG"
984263bc 222\&...
e056f0e0
JR
223.IP "\s-1SSL_OP_DONT_INSERT_EMPTY_FRAGMENTS\s0" 4
224.IX Item "SSL_OP_DONT_INSERT_EMPTY_FRAGMENTS"
225Disables a countermeasure against a \s-1SSL\s0 3.0/TLS 1.0 protocol
984263bc
MD
226vulnerability affecting \s-1CBC\s0 ciphers, which cannot be handled by some
227broken \s-1SSL\s0 implementations. This option has no effect for connections
228using other ciphers.
e056f0e0
JR
229.IP "\s-1SSL_OP_ALL\s0" 4
230.IX Item "SSL_OP_ALL"
984263bc
MD
231All of the above bug workarounds.
232.PP
233It is usually safe to use \fB\s-1SSL_OP_ALL\s0\fR to enable the bug workaround
234options if compatibility with somewhat broken implementations is
235desired.
236.PP
237The following \fBmodifying\fR options are available:
e056f0e0
JR
238.IP "\s-1SSL_OP_TLS_ROLLBACK_BUG\s0" 4
239.IX Item "SSL_OP_TLS_ROLLBACK_BUG"
984263bc
MD
240Disable version rollback attack detection.
241.Sp
242During the client key exchange, the client must send the same information
243about acceptable \s-1SSL/TLS\s0 protocol levels as during the first hello. Some
244clients violate this rule by adapting to the server's answer. (Example:
245the client sends a SSLv2 hello and accepts up to SSLv3.1=TLSv1, the server
246only understands up to SSLv3. In this case the client must still use the
247same SSLv3.1=TLSv1 announcement. Some clients step down to SSLv3 with respect
248to the server's answer and violate the version rollback protection.)
e056f0e0
JR
249.IP "\s-1SSL_OP_SINGLE_DH_USE\s0" 4
250.IX Item "SSL_OP_SINGLE_DH_USE"
984263bc 251Always create a new key when using temporary/ephemeral \s-1DH\s0 parameters
e056f0e0 252(see \fISSL_CTX_set_tmp_dh_callback\fR\|(3)).
984263bc
MD
253This option must be used to prevent small subgroup attacks, when
254the \s-1DH\s0 parameters were not generated using \*(L"strong\*(R" primes
e056f0e0 255(e.g. when using DSA\-parameters, see \fIdhparam\fR\|(1)).
984263bc
MD
256If \*(L"strong\*(R" primes were used, it is not strictly necessary to generate
257a new \s-1DH\s0 key during each handshake but it is also recommended.
e056f0e0 258\&\fB\s-1SSL_OP_SINGLE_DH_USE\s0\fR should therefore be enabled whenever
984263bc 259temporary/ephemeral \s-1DH\s0 parameters are used.
e056f0e0
JR
260.IP "\s-1SSL_OP_EPHEMERAL_RSA\s0" 4
261.IX Item "SSL_OP_EPHEMERAL_RSA"
984263bc 262Always use ephemeral (temporary) \s-1RSA\s0 key when doing \s-1RSA\s0 operations
e056f0e0 263(see \fISSL_CTX_set_tmp_rsa_callback\fR\|(3)).
984263bc
MD
264According to the specifications this is only done, when a \s-1RSA\s0 key
265can only be used for signature operations (namely under export ciphers
266with restricted \s-1RSA\s0 keylength). By setting this option, ephemeral
e056f0e0
JR
267\&\s-1RSA\s0 keys are always used. This option breaks compatibility with the
268\&\s-1SSL/TLS\s0 specifications and may lead to interoperability problems with
984263bc 269clients and should therefore never be used. Ciphers with \s-1EDH\s0 (ephemeral
e056f0e0
JR
270Diffie\-Hellman) key exchange should be used instead.
271.IP "\s-1SSL_OP_CIPHER_SERVER_PREFERENCE\s0" 4
272.IX Item "SSL_OP_CIPHER_SERVER_PREFERENCE"
984263bc
MD
273When choosing a cipher, use the server's preferences instead of the client
274preferences. When not set, the \s-1SSL\s0 server will always follow the clients
275preferences. When set, the SSLv3/TLSv1 server will choose following its
276own preferences. Because of the different protocol, for SSLv2 the server
a561f9ff 277will send its list of preferences to the client and the client chooses.
e056f0e0
JR
278.IP "\s-1SSL_OP_PKCS1_CHECK_1\s0" 4
279.IX Item "SSL_OP_PKCS1_CHECK_1"
984263bc 280\&...
e056f0e0
JR
281.IP "\s-1SSL_OP_PKCS1_CHECK_2\s0" 4
282.IX Item "SSL_OP_PKCS1_CHECK_2"
984263bc 283\&...
e056f0e0
JR
284.IP "\s-1SSL_OP_NETSCAPE_CA_DN_BUG\s0" 4
285.IX Item "SSL_OP_NETSCAPE_CA_DN_BUG"
984263bc 286If we accept a netscape connection, demand a client cert, have a
a7d27d5a 287non-self-signed \s-1CA\s0 which does not have its \s-1CA\s0 in netscape, and the
984263bc 288browser has a cert, it will crash/hang. Works for 3.x and 4.xbeta
e056f0e0
JR
289.IP "\s-1SSL_OP_NETSCAPE_DEMO_CIPHER_CHANGE_BUG\s0" 4
290.IX Item "SSL_OP_NETSCAPE_DEMO_CIPHER_CHANGE_BUG"
984263bc 291\&...
e056f0e0
JR
292.IP "SSL_OP_NO_SSLv2" 4
293.IX Item "SSL_OP_NO_SSLv2"
984263bc 294Do not use the SSLv2 protocol.
e056f0e0
JR
295.IP "SSL_OP_NO_SSLv3" 4
296.IX Item "SSL_OP_NO_SSLv3"
984263bc 297Do not use the SSLv3 protocol.
e056f0e0
JR
298.IP "SSL_OP_NO_TLSv1" 4
299.IX Item "SSL_OP_NO_TLSv1"
984263bc 300Do not use the TLSv1 protocol.
e056f0e0
JR
301.IP "\s-1SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION\s0" 4
302.IX Item "SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION"
984263bc
MD
303When performing renegotiation as a server, always start a new session
304(i.e., session resumption requests are only accepted in the initial
305handshake). This option is not needed for clients.
306.SH "RETURN VALUES"
e056f0e0
JR
307.IX Header "RETURN VALUES"
308\&\fISSL_CTX_set_options()\fR and \fISSL_set_options()\fR return the new options bitmask
984263bc
MD
309after adding \fBoptions\fR.
310.PP
e056f0e0 311\&\fISSL_CTX_get_options()\fR and \fISSL_get_options()\fR return the current bitmask.
984263bc 312.SH "SEE ALSO"
e056f0e0
JR
313.IX Header "SEE ALSO"
314\&\fIssl\fR\|(3), \fISSL_new\fR\|(3), \fISSL_clear\fR\|(3),
315\&\fISSL_CTX_set_tmp_dh_callback\fR\|(3),
316\&\fISSL_CTX_set_tmp_rsa_callback\fR\|(3),
317\&\fIdhparam\fR\|(1)
984263bc 318.SH "HISTORY"
e056f0e0
JR
319.IX Header "HISTORY"
320\&\fB\s-1SSL_OP_CIPHER_SERVER_PREFERENCE\s0\fR and
321\&\fB\s-1SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION\s0\fR have been added in
984263bc
MD
322OpenSSL 0.9.7.
323.PP
e056f0e0
JR
324\&\fB\s-1SSL_OP_TLS_ROLLBACK_BUG\s0\fR has been added in OpenSSL 0.9.6 and was automatically
325enabled 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
326and must be explicitly set.
327.PP
e056f0e0 328\&\fB\s-1SSL_OP_DONT_INSERT_EMPTY_FRAGMENTS\s0\fR has been added in OpenSSL 0.9.6e.
984263bc
MD
329Versions up to OpenSSL 0.9.6c do not include the countermeasure that
330can be disabled with this option (in OpenSSL 0.9.6d, it was always
331enabled).