| SSL_CTX_set_options.3 (206048) | SSL_CTX_set_options.3 (215698) |
|---|---|
| 1.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.37 | 1.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.07) |
| 2.\" 3.\" Standard preamble: 4.\" ======================================================================== | 2.\" 3.\" Standard preamble: 4.\" ======================================================================== |
| 5.de Sh \" Subsection heading 6.br 7.if t .Sp 8.ne 5 9.PP 10\fB\\$1\fR 11.PP 12.. | |
| 13.de Sp \" Vertical space (when we can't use .PP) 14.if t .sp .5v 15.if n .sp 16.. 17.de Vb \" Begin verbatim text 18.ft CW 19.nf 20.ne \\$1 21.. 22.de Ve \" End verbatim text 23.ft R 24.fi 25.. 26.\" Set up some character translations and predefined strings. \*(-- will 27.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left | 5.de Sp \" Vertical space (when we can't use .PP) 6.if t .sp .5v 7.if n .sp 8.. 9.de Vb \" Begin verbatim text 10.ft CW 11.nf 12.ne \\$1 13.. 14.de Ve \" End verbatim text 15.ft R 16.fi 17.. 18.\" Set up some character translations and predefined strings. \*(-- will 19.\" 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<>. 32.tr \(*W-|\(bv\*(Tr | 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- |
| 33.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' 34.ie n \{\ 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' "" 43'br\} 44.el\{\ 45. ds -- \|\(em\| 46. ds PI \(*p 47. ds L" `` 48. ds R" '' 49'br\} 50.\" | 25.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' 26.ie n \{\ 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' "" 35'br\} 36.el\{\ 37. ds -- \|\(em\| 38. ds PI \(*p 39. ds L" `` 40. ds R" '' 41'br\} 42.\" |
| 43.\" Escape single quotes in literal strings from groff's Unicode transform. 44.ie \n(.g .ds Aq \(aq 45.el .ds Aq ' 46.\" |
|
| 51.\" If the F register is turned on, we'll generate index entries on stderr for | 47.\" 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 | 48.\" titles (.TH), headers (.SH), subsections (.SS), 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. | 49.\" entries marked with X<> in POD. Of course, you'll have to process the 50.\" output yourself in some meaningful fashion. |
| 55.if \nF \{\ | 51.ie \nF \{\ |
| 56. de IX 57. tm Index:\\$1\t\\n%\t"\\$2" 58.. 59. nr % 0 60. rr F 61.\} | 52. de IX 53. tm Index:\\$1\t\\n%\t"\\$2" 54.. 55. nr % 0 56. rr F 57.\} |
| 58.el \{\ 59. de IX 60.. 61.\} |
|
| 62.\" | 62.\" |
| 63.\" For nroff, turn off justification. Always turn off hyphenation; it makes 64.\" way too many mistakes in technical documents. 65.hy 0 66.if n .na 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 71.if n \{\ 72. ds #H 0 73. ds #V .8m 74. ds #F .3m 75. ds #[ \f1 --- 48 unchanged lines hidden (view full) --- 124. ds Th \o'LP' 125. ds ae ae 126. ds Ae AE 127.\} 128.rm #[ #] #H #V #F C 129.\" ======================================================================== 130.\" 131.IX Title "SSL_CTX_set_options 3" | 63.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). 64.\" Fear. Run. Save yourself. No user-serviceable parts. 65. \" fudge factors for nroff and troff 66.if n \{\ 67. ds #H 0 68. ds #V .8m 69. ds #F .3m 70. ds #[ \f1 --- 48 unchanged lines hidden (view full) --- 119. ds Th \o'LP' 120. ds ae ae 121. ds Ae AE 122.\} 123.rm #[ #] #H #V #F C 124.\" ======================================================================== 125.\" 126.IX Title "SSL_CTX_set_options 3" |
| 132.TH SSL_CTX_set_options 3 "2010-03-24" "0.9.8n" "OpenSSL" | 127.TH SSL_CTX_set_options 3 "2010-11-16" "0.9.8p" "OpenSSL" 128.\" For nroff, turn off justification. Always turn off hyphenation; it makes 129.\" way too many mistakes in technical documents. 130.if n .ad l 131.nh |
| 133.SH "NAME" 134SSL_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 135.SH "SYNOPSIS" 136.IX Header "SYNOPSIS" 137.Vb 1 138\& #include <openssl/ssl.h> | 132.SH "NAME" 133SSL_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 134.SH "SYNOPSIS" 135.IX Header "SYNOPSIS" 136.Vb 1 137\& #include <openssl/ssl.h> |
| 139.Ve 140.PP 141.Vb 2 | 138\& |
| 142\& long SSL_CTX_set_options(SSL_CTX *ctx, long options); 143\& long SSL_set_options(SSL *ssl, long options); | 139\& long SSL_CTX_set_options(SSL_CTX *ctx, long options); 140\& long SSL_set_options(SSL *ssl, long options); |
| 144.Ve 145.PP 146.Vb 2 | 141\& |
| 147\& long SSL_CTX_clear_options(SSL_CTX *ctx, long options); 148\& long SSL_clear_options(SSL *ssl, long options); | 142\& long SSL_CTX_clear_options(SSL_CTX *ctx, long options); 143\& long SSL_clear_options(SSL *ssl, long options); |
| 149.Ve 150.PP 151.Vb 2 | 144\& |
| 152\& long SSL_CTX_get_options(SSL_CTX *ctx); 153\& long SSL_get_options(SSL *ssl); | 145\& long SSL_CTX_get_options(SSL_CTX *ctx); 146\& long SSL_get_options(SSL *ssl); |
| 154.Ve 155.PP 156.Vb 1 | 147\& |
| 157\& long SSL_get_secure_renegotiation_support(SSL *ssl); 158.Ve 159.SH "DESCRIPTION" 160.IX Header "DESCRIPTION" 161Note: all these functions are implemented using macros. 162.PP 163\&\fISSL_CTX_set_options()\fR adds the options set via bitmask in \fBoptions\fR to \fBctx\fR. 164Options already set before are not cleared! --- 49 unchanged lines hidden (view full) --- 214\&\s-1RC4\-MD5\s0 according to 7.6.1.3, 'cipher_suite'. 215.Sp 216Netscape\-Enterprise/2.01 (https://merchant.netscape.com) has this bug. 217It only really shows up when connecting via SSLv2/v3 then reconnecting 218via SSLv3. The cipher list changes.... 219.Sp 220\&\s-1NEW\s0 \s-1INFORMATION\s0. Try connecting with a cipher list of just 221\&\s-1DES\-CBC\-SHA:RC4\-MD5\s0. For some weird reason, each new connection uses | 148\& long SSL_get_secure_renegotiation_support(SSL *ssl); 149.Ve 150.SH "DESCRIPTION" 151.IX Header "DESCRIPTION" 152Note: all these functions are implemented using macros. 153.PP 154\&\fISSL_CTX_set_options()\fR adds the options set via bitmask in \fBoptions\fR to \fBctx\fR. 155Options already set before are not cleared! --- 49 unchanged lines hidden (view full) --- 205\&\s-1RC4\-MD5\s0 according to 7.6.1.3, 'cipher_suite'. 206.Sp 207Netscape\-Enterprise/2.01 (https://merchant.netscape.com) has this bug. 208It only really shows up when connecting via SSLv2/v3 then reconnecting 209via SSLv3. The cipher list changes.... 210.Sp 211\&\s-1NEW\s0 \s-1INFORMATION\s0. Try connecting with a cipher list of just 212\&\s-1DES\-CBC\-SHA:RC4\-MD5\s0. For some weird reason, each new connection uses |
| 222\&\s-1RC4\-MD5\s0, but a re-connect tries to use \s-1DES\-CBC\-SHA\s0. So netscape, when 223doing a re\-connect, always takes the first cipher in the cipher list. | 213\&\s-1RC4\-MD5\s0, but a re-connect tries to use DES-CBC-SHA. So netscape, when 214doing a re-connect, always takes the first cipher in the cipher list. |
| 224.IP "\s-1SSL_OP_SSLREF2_REUSE_CERT_TYPE_BUG\s0" 4 225.IX Item "SSL_OP_SSLREF2_REUSE_CERT_TYPE_BUG" 226\&... 227.IP "\s-1SSL_OP_MICROSOFT_BIG_SSLV3_BUFFER\s0" 4 228.IX Item "SSL_OP_MICROSOFT_BIG_SSLV3_BUFFER" 229\&... 230.IP "\s-1SSL_OP_MSIE_SSLV2_RSA_PADDING\s0" 4 231.IX Item "SSL_OP_MSIE_SSLV2_RSA_PADDING" --- 34 unchanged lines hidden (view full) --- 266same SSLv3.1=TLSv1 announcement. Some clients step down to SSLv3 with respect 267to the server's answer and violate the version rollback protection.) 268.IP "\s-1SSL_OP_SINGLE_DH_USE\s0" 4 269.IX Item "SSL_OP_SINGLE_DH_USE" 270Always create a new key when using temporary/ephemeral \s-1DH\s0 parameters 271(see \fISSL_CTX_set_tmp_dh_callback\fR\|(3)). 272This option must be used to prevent small subgroup attacks, when 273the \s-1DH\s0 parameters were not generated using \*(L"strong\*(R" primes | 215.IP "\s-1SSL_OP_SSLREF2_REUSE_CERT_TYPE_BUG\s0" 4 216.IX Item "SSL_OP_SSLREF2_REUSE_CERT_TYPE_BUG" 217\&... 218.IP "\s-1SSL_OP_MICROSOFT_BIG_SSLV3_BUFFER\s0" 4 219.IX Item "SSL_OP_MICROSOFT_BIG_SSLV3_BUFFER" 220\&... 221.IP "\s-1SSL_OP_MSIE_SSLV2_RSA_PADDING\s0" 4 222.IX Item "SSL_OP_MSIE_SSLV2_RSA_PADDING" --- 34 unchanged lines hidden (view full) --- 257same SSLv3.1=TLSv1 announcement. Some clients step down to SSLv3 with respect 258to the server's answer and violate the version rollback protection.) 259.IP "\s-1SSL_OP_SINGLE_DH_USE\s0" 4 260.IX Item "SSL_OP_SINGLE_DH_USE" 261Always create a new key when using temporary/ephemeral \s-1DH\s0 parameters 262(see \fISSL_CTX_set_tmp_dh_callback\fR\|(3)). 263This option must be used to prevent small subgroup attacks, when 264the \s-1DH\s0 parameters were not generated using \*(L"strong\*(R" primes |
| 274(e.g. when using DSA\-parameters, see \fIdhparam\fR\|(1)). | 265(e.g. when using DSA-parameters, see \fIdhparam\fR\|(1)). |
| 275If \*(L"strong\*(R" primes were used, it is not strictly necessary to generate 276a new \s-1DH\s0 key during each handshake but it is also recommended. 277\&\fB\s-1SSL_OP_SINGLE_DH_USE\s0\fR should therefore be enabled whenever 278temporary/ephemeral \s-1DH\s0 parameters are used. 279.IP "\s-1SSL_OP_EPHEMERAL_RSA\s0" 4 280.IX Item "SSL_OP_EPHEMERAL_RSA" 281Always use ephemeral (temporary) \s-1RSA\s0 key when doing \s-1RSA\s0 operations 282(see \fISSL_CTX_set_tmp_rsa_callback\fR\|(3)). 283According to the specifications this is only done, when a \s-1RSA\s0 key 284can only be used for signature operations (namely under export ciphers 285with restricted \s-1RSA\s0 keylength). By setting this option, ephemeral 286\&\s-1RSA\s0 keys are always used. This option breaks compatibility with the 287\&\s-1SSL/TLS\s0 specifications and may lead to interoperability problems with 288clients and should therefore never be used. Ciphers with \s-1EDH\s0 (ephemeral | 266If \*(L"strong\*(R" primes were used, it is not strictly necessary to generate 267a new \s-1DH\s0 key during each handshake but it is also recommended. 268\&\fB\s-1SSL_OP_SINGLE_DH_USE\s0\fR should therefore be enabled whenever 269temporary/ephemeral \s-1DH\s0 parameters are used. 270.IP "\s-1SSL_OP_EPHEMERAL_RSA\s0" 4 271.IX Item "SSL_OP_EPHEMERAL_RSA" 272Always use ephemeral (temporary) \s-1RSA\s0 key when doing \s-1RSA\s0 operations 273(see \fISSL_CTX_set_tmp_rsa_callback\fR\|(3)). 274According to the specifications this is only done, when a \s-1RSA\s0 key 275can only be used for signature operations (namely under export ciphers 276with restricted \s-1RSA\s0 keylength). By setting this option, ephemeral 277\&\s-1RSA\s0 keys are always used. This option breaks compatibility with the 278\&\s-1SSL/TLS\s0 specifications and may lead to interoperability problems with 279clients and should therefore never be used. Ciphers with \s-1EDH\s0 (ephemeral |
| 289Diffie\-Hellman) key exchange should be used instead. | 280Diffie-Hellman) key exchange should be used instead. |
| 290.IP "\s-1SSL_OP_CIPHER_SERVER_PREFERENCE\s0" 4 291.IX Item "SSL_OP_CIPHER_SERVER_PREFERENCE" 292When choosing a cipher, use the server's preferences instead of the client 293preferences. When not set, the \s-1SSL\s0 server will always follow the clients 294preferences. When set, the SSLv3/TLSv1 server will choose following its 295own preferences. Because of the different protocol, for SSLv2 the server 296will send its list of preferences to the client and the client chooses. 297.IP "\s-1SSL_OP_PKCS1_CHECK_1\s0" 4 298.IX Item "SSL_OP_PKCS1_CHECK_1" 299\&... 300.IP "\s-1SSL_OP_PKCS1_CHECK_2\s0" 4 301.IX Item "SSL_OP_PKCS1_CHECK_2" 302\&... 303.IP "\s-1SSL_OP_NETSCAPE_CA_DN_BUG\s0" 4 304.IX Item "SSL_OP_NETSCAPE_CA_DN_BUG" 305If we accept a netscape connection, demand a client cert, have a 306non-self-signed \s-1CA\s0 which does not have its \s-1CA\s0 in netscape, and the | 281.IP "\s-1SSL_OP_CIPHER_SERVER_PREFERENCE\s0" 4 282.IX Item "SSL_OP_CIPHER_SERVER_PREFERENCE" 283When choosing a cipher, use the server's preferences instead of the client 284preferences. When not set, the \s-1SSL\s0 server will always follow the clients 285preferences. When set, the SSLv3/TLSv1 server will choose following its 286own preferences. Because of the different protocol, for SSLv2 the server 287will send its list of preferences to the client and the client chooses. 288.IP "\s-1SSL_OP_PKCS1_CHECK_1\s0" 4 289.IX Item "SSL_OP_PKCS1_CHECK_1" 290\&... 291.IP "\s-1SSL_OP_PKCS1_CHECK_2\s0" 4 292.IX Item "SSL_OP_PKCS1_CHECK_2" 293\&... 294.IP "\s-1SSL_OP_NETSCAPE_CA_DN_BUG\s0" 4 295.IX Item "SSL_OP_NETSCAPE_CA_DN_BUG" 296If we accept a netscape connection, demand a client cert, have a 297non-self-signed \s-1CA\s0 which does not have its \s-1CA\s0 in netscape, and the |
| 307browser has a cert, it will crash/hang. Works for 3.x and 4.xbeta | 298browser has a cert, it will crash/hang. Works for 3.x and 4.xbeta |
| 308.IP "\s-1SSL_OP_NETSCAPE_DEMO_CIPHER_CHANGE_BUG\s0" 4 309.IX Item "SSL_OP_NETSCAPE_DEMO_CIPHER_CHANGE_BUG" 310\&... 311.IP "SSL_OP_NO_SSLv2" 4 312.IX Item "SSL_OP_NO_SSLv2" 313Do not use the SSLv2 protocol. 314.IP "SSL_OP_NO_SSLv3" 4 315.IX Item "SSL_OP_NO_SSLv3" --- 34 unchanged lines hidden (view full) --- 350.PP 351This attack has far reaching consequences which application writers should be 352aware of. In the description below an implementation supporting secure 353renegotiation is referred to as \fIpatched\fR. A server not supporting secure 354renegotiation is referred to as \fIunpatched\fR. 355.PP 356The following sections describe the operations permitted by OpenSSL's secure 357renegotiation implementation. | 299.IP "\s-1SSL_OP_NETSCAPE_DEMO_CIPHER_CHANGE_BUG\s0" 4 300.IX Item "SSL_OP_NETSCAPE_DEMO_CIPHER_CHANGE_BUG" 301\&... 302.IP "SSL_OP_NO_SSLv2" 4 303.IX Item "SSL_OP_NO_SSLv2" 304Do not use the SSLv2 protocol. 305.IP "SSL_OP_NO_SSLv3" 4 306.IX Item "SSL_OP_NO_SSLv3" --- 34 unchanged lines hidden (view full) --- 341.PP 342This attack has far reaching consequences which application writers should be 343aware of. In the description below an implementation supporting secure 344renegotiation is referred to as \fIpatched\fR. A server not supporting secure 345renegotiation is referred to as \fIunpatched\fR. 346.PP 347The following sections describe the operations permitted by OpenSSL's secure 348renegotiation implementation. |
| 358.Sh "Patched client and server" | 349.SS "Patched client and server" |
| 359.IX Subsection "Patched client and server" 360Connections and renegotiation are always permitted by OpenSSL implementations. | 350.IX Subsection "Patched client and server" 351Connections and renegotiation are always permitted by OpenSSL implementations. |
| 361.Sh "Unpatched client and patched OpenSSL server" | 352.SS "Unpatched client and patched OpenSSL server" |
| 362.IX Subsection "Unpatched client and patched OpenSSL server" 363The initial connection suceeds but client renegotiation is denied by the 364server with a \fBno_renegotiation\fR warning alert if \s-1TLS\s0 v1.0 is used or a fatal 365\&\fBhandshake_failure\fR alert in \s-1SSL\s0 v3.0. 366.PP 367If the patched OpenSSL server attempts to renegotiate a fatal 368\&\fBhandshake_failure\fR alert is sent. This is because the server code may be 369unaware of the unpatched nature of the client. 370.PP 371If the option \fB\s-1SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION\s0\fR is set then 372renegotiation \fBalways\fR succeeds. 373.PP 374\&\fB\s-1NB:\s0\fR a bug in OpenSSL clients earlier than 0.9.8m (all of which are 375unpatched) will result in the connection hanging if it receives a 376\&\fBno_renegotiation\fR alert. OpenSSL versions 0.9.8m and later will regard 377a \fBno_renegotiation\fR alert as fatal and respond with a fatal 378\&\fBhandshake_failure\fR alert. This is because the OpenSSL \s-1API\s0 currently has 379no provision to indicate to an application that a renegotiation attempt 380was refused. | 353.IX Subsection "Unpatched client and patched OpenSSL server" 354The initial connection suceeds but client renegotiation is denied by the 355server with a \fBno_renegotiation\fR warning alert if \s-1TLS\s0 v1.0 is used or a fatal 356\&\fBhandshake_failure\fR alert in \s-1SSL\s0 v3.0. 357.PP 358If the patched OpenSSL server attempts to renegotiate a fatal 359\&\fBhandshake_failure\fR alert is sent. This is because the server code may be 360unaware of the unpatched nature of the client. 361.PP 362If the option \fB\s-1SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION\s0\fR is set then 363renegotiation \fBalways\fR succeeds. 364.PP 365\&\fB\s-1NB:\s0\fR a bug in OpenSSL clients earlier than 0.9.8m (all of which are 366unpatched) will result in the connection hanging if it receives a 367\&\fBno_renegotiation\fR alert. OpenSSL versions 0.9.8m and later will regard 368a \fBno_renegotiation\fR alert as fatal and respond with a fatal 369\&\fBhandshake_failure\fR alert. This is because the OpenSSL \s-1API\s0 currently has 370no provision to indicate to an application that a renegotiation attempt 371was refused. |
| 381.Sh "Patched OpenSSL client and unpatched server." | 372.SS "Patched OpenSSL client and unpatched server." |
| 382.IX Subsection "Patched OpenSSL client and unpatched server." 383If the option \fB\s-1SSL_OP_LEGACY_SERVER_CONNECT\s0\fR or 384\&\fB\s-1SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION\s0\fR is set then initial connections 385and renegotiation between patched OpenSSL clients and unpatched servers 386succeeds. If neither option is set then initial connections to unpatched 387servers will fail. 388.PP 389The option \fB\s-1SSL_OP_LEGACY_SERVER_CONNECT\s0\fR is currently set by default even --- 62 unchanged lines hidden --- | 373.IX Subsection "Patched OpenSSL client and unpatched server." 374If the option \fB\s-1SSL_OP_LEGACY_SERVER_CONNECT\s0\fR or 375\&\fB\s-1SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION\s0\fR is set then initial connections 376and renegotiation between patched OpenSSL clients and unpatched servers 377succeeds. If neither option is set then initial connections to unpatched 378servers will fail. 379.PP 380The option \fB\s-1SSL_OP_LEGACY_SERVER_CONNECT\s0\fR is currently set by default even --- 62 unchanged lines hidden --- |