1SSL_CTX_set_options(3) OpenSSL SSL_CTX_set_options(3)
2
6 SSL_CTX_set_options, SSL_set_options, SSL_CTX_get_options,
7 SSL_get_options - manipulate SSL engine options
8
10 #include <openssl/ssl.h>
11 long SSL_CTX_set_options(SSL_CTX *ctx, long options);
13 long SSL_set_options(SSL *ssl, long options);
14 long SSL_CTX_get_options(SSL_CTX *ctx);
16 long SSL_get_options(SSL *ssl);
17
19 SSL_CTX_set_options() adds the options set via bitmask in options to
20 ctx. Options already set before are not cleared!
21 SSL_set_options() adds the options set via bitmask in options to ssl.
23 Options already set before are not cleared!
24 SSL_CTX_get_options() returns the options set for ctx.
26 SSL_get_options() returns the options set for ssl.
28
30 The behaviour of the SSL library can be changed by setting several
31 options. The options are coded as bitmasks and can be combined by a
32 logical or operation (⎪). Options can only be added but can never be
33 reset.
34 SSL_CTX_set_options() and SSL_set_options() affect the (external) pro‐
36 tocol behaviour of the SSL library. The (internal) behaviour of the API
37 can be changed by using the similar SSL_CTX_set_mode(3) and
38 SSL_set_mode() functions.
39 During a handshake, the option settings of the SSL object are used.
41 When a new SSL object is created from a context using SSL_new(), the
42 current option setting is copied. Changes to ctx do not affect already
43 created SSL objects. SSL_clear() does not affect the settings.
44 The following bug workaround options are available:
46 SSL_OP_MICROSOFT_SESS_ID_BUG
48 www.microsoft.com - when talking SSLv2, if session-id reuse is per‐
49 formed, the session-id passed back in the server-finished message
50 is different from the one decided upon.
51 SSL_OP_NETSCAPE_CHALLENGE_BUG
53 Netscape-Commerce/1.12, when talking SSLv2, accepts a 32 byte chal‐
54 lenge but then appears to only use 16 bytes when generating the
55 encryption keys. Using 16 bytes is ok but it should be ok to use
56 32. According to the SSLv3 spec, one should use 32 bytes for the
57 challenge when operating in SSLv2/v3 compatibility mode, but as
58 mentioned above, this breaks this server so 16 bytes is the way to
59 go.
60 SSL_OP_NETSCAPE_REUSE_CIPHER_CHANGE_BUG
62 ssl3.netscape.com:443, first a connection is established with
63 RC4-MD5. If it is then resumed, we end up using DES-CBC3-SHA. It
64 should be RC4-MD5 according to 7.6.1.3, 'cipher_suite'.
65 Netscape-Enterprise/2.01 (https://merchant.netscape.com) has this
67 bug. It only really shows up when connecting via SSLv2/v3 then
68 reconnecting via SSLv3. The cipher list changes....
69 NEW INFORMATION. Try connecting with a cipher list of just
71 DES-CBC-SHA:RC4-MD5. For some weird reason, each new connection
72 uses RC4-MD5, but a re-connect tries to use DES-CBC-SHA. So net‐
73 scape, when doing a re-connect, always takes the first cipher in
74 the cipher list.
75 SSL_OP_SSLREF2_REUSE_CERT_TYPE_BUG
77 ...
78 SSL_OP_MICROSOFT_BIG_SSLV3_BUFFER
80 ...
81 SSL_OP_MSIE_SSLV2_RSA_PADDING
83 As of OpenSSL 0.9.7h and 0.9.8a, this option has no effect.
84 SSL_OP_SSLEAY_080_CLIENT_DH_BUG
86 ...
87 SSL_OP_TLS_D5_BUG
89 ...
90 SSL_OP_TLS_BLOCK_PADDING_BUG
92 ...
93 SSL_OP_DONT_INSERT_EMPTY_FRAGMENTS
95 Disables a countermeasure against a SSL 3.0/TLS 1.0 protocol vul‐
96 nerability affecting CBC ciphers, which cannot be handled by some
97 broken SSL implementations. This option has no effect for connec‐
98 tions using other ciphers.
99 SSL_OP_ALL
101 All of the above bug workarounds.
102 It is usually safe to use SSL_OP_ALL to enable the bug workaround
104 options if compatibility with somewhat broken implementations is
105 desired.
106 The following modifying options are available:
108 SSL_OP_TLS_ROLLBACK_BUG
110 Disable version rollback attack detection.
111 During the client key exchange, the client must send the same
113 information about acceptable SSL/TLS protocol levels as during the
114 first hello. Some clients violate this rule by adapting to the
115 server's answer. (Example: the client sends a SSLv2 hello and
116 accepts up to SSLv3.1=TLSv1, the server only understands up to
117 SSLv3. In this case the client must still use the same
118 SSLv3.1=TLSv1 announcement. Some clients step down to SSLv3 with
119 respect to the server's answer and violate the version rollback
120 protection.)
121 SSL_OP_SINGLE_DH_USE
123 Always create a new key when using temporary/ephemeral DH parame‐
124 ters (see SSL_CTX_set_tmp_dh_callback(3)). This option must be
125 used to prevent small subgroup attacks, when the DH parameters were
126 not generated using "strong" primes (e.g. when using DSA-parame‐
127 ters, see dhparam(1)). If "strong" primes were used, it is not
128 strictly necessary to generate a new DH key during each handshake
129 but it is also recommended. SSL_OP_SINGLE_DH_USE should therefore
130 be enabled whenever temporary/ephemeral DH parameters are used.
131 SSL_OP_EPHEMERAL_RSA
133 Always use ephemeral (temporary) RSA key when doing RSA operations
134 (see SSL_CTX_set_tmp_rsa_callback(3)). According to the specifica‐
135 tions this is only done, when a RSA key can only be used for signa‐
136 ture operations (namely under export ciphers with restricted RSA
137 keylength). By setting this option, ephemeral RSA keys are always
138 used. This option breaks compatibility with the SSL/TLS specifica‐
139 tions and may lead to interoperability problems with clients and
140 should therefore never be used. Ciphers with EDH (ephemeral
141 Diffie-Hellman) key exchange should be used instead.
142 SSL_OP_CIPHER_SERVER_PREFERENCE
144 When choosing a cipher, use the server's preferences instead of the
145 client preferences. When not set, the SSL server will always follow
146 the clients preferences. When set, the SSLv3/TLSv1 server will
147 choose following its own preferences. Because of the different pro‐
148 tocol, for SSLv2 the server will send its list of preferences to
149 the client and the client chooses.
150 SSL_OP_PKCS1_CHECK_1
152 ...
153 SSL_OP_PKCS1_CHECK_2
155 ...
156 SSL_OP_NETSCAPE_CA_DN_BUG
158 If we accept a netscape connection, demand a client cert, have a
159 non-self-signed CA which does not have its CA in netscape, and the
160 browser has a cert, it will crash/hang. Works for 3.x and 4.xbeta
161 SSL_OP_NETSCAPE_DEMO_CIPHER_CHANGE_BUG
163 ...
164 SSL_OP_NO_SSLv2
166 Do not use the SSLv2 protocol.
167 SSL_OP_NO_SSLv3
169 Do not use the SSLv3 protocol.
170 SSL_OP_NO_TLSv1
172 Do not use the TLSv1 protocol.
173 SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION
175 When performing renegotiation as a server, always start a new ses‐
176 sion (i.e., session resumption requests are only accepted in the
177 initial handshake). This option is not needed for clients.
178
180 SSL_CTX_set_options() and SSL_set_options() return the new options bit‐
181 mask after adding options.
182 SSL_CTX_get_options() and SSL_get_options() return the current bitmask.
184
186 ssl(3), SSL_new(3), SSL_clear(3), SSL_CTX_set_tmp_dh_callback(3),
187 SSL_CTX_set_tmp_rsa_callback(3), dhparam(1)
188
190 SSL_OP_CIPHER_SERVER_PREFERENCE and SSL_OP_NO_SESSION_RESUMP‐
191 TION_ON_RENEGOTIATION have been added in OpenSSL 0.9.7.
192 SSL_OP_TLS_ROLLBACK_BUG has been added in OpenSSL 0.9.6 and was auto‐
194 matically enabled with SSL_OP_ALL. As of 0.9.7, it is no longer
195 included in SSL_OP_ALL and must be explicitly set.
196 SSL_OP_DONT_INSERT_EMPTY_FRAGMENTS has been added in OpenSSL 0.9.6e.
198 Versions up to OpenSSL 0.9.6c do not include the countermeasure that
199 can be disabled with this option (in OpenSSL 0.9.6d, it was always
200 enabled).
2010.9.8b 2005-10-11 SSL_CTX_set_options(3)