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