diff options
Diffstat (limited to 'doc/ssl/SSL_CTX_set_options.pod')
| -rw-r--r-- | doc/ssl/SSL_CTX_set_options.pod | 87 |
1 files changed, 82 insertions, 5 deletions
diff --git a/doc/ssl/SSL_CTX_set_options.pod b/doc/ssl/SSL_CTX_set_options.pod index 766f0c9200..9331e67153 100644 --- a/doc/ssl/SSL_CTX_set_options.pod +++ b/doc/ssl/SSL_CTX_set_options.pod @@ -2,7 +2,7 @@ =head1 NAME -SSL_CTX_set_options, SSL_set_options, SSL_CTX_get_options, SSL_get_options - manipulate SSL engine options +SSL_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 =head1 SYNOPSIS @@ -11,26 +11,41 @@ SSL_CTX_set_options, SSL_set_options, SSL_CTX_get_options, SSL_get_options - man long SSL_CTX_set_options(SSL_CTX *ctx, long options); long SSL_set_options(SSL *ssl, long options); + long SSL_CTX_clear_options(SSL_CTX *ctx, long options); + long SSL_clear_options(SSL *ssl, long options); + long SSL_CTX_get_options(SSL_CTX *ctx); long SSL_get_options(SSL *ssl); + long SSL_get_secure_renegotiation_support(SSL *ssl); + =head1 DESCRIPTION +Note: all these functions are implemented using macros. + SSL_CTX_set_options() adds the options set via bitmask in B<options> to B<ctx>. Options already set before are not cleared! SSL_set_options() adds the options set via bitmask in B<options> to B<ssl>. Options already set before are not cleared! +SSL_CTX_clear_options() clears the options set via bitmask in B<options> +to B<ctx>. + +SSL_clear_options() clears the options set via bitmask in B<options> to B<ssl>. + SSL_CTX_get_options() returns the options set for B<ctx>. SSL_get_options() returns the options set for B<ssl>. +SSL_get_secure_renegotiation_support() indicates whether the peer supports +secure renegotiation. + =head1 NOTES The behaviour of the SSL library can be changed by setting several options. The options are coded as bitmasks and can be combined by a logical B<or> -operation (|). Options can only be added but can never be reset. +operation (|). SSL_CTX_set_options() and SSL_set_options() affect the (external) protocol behaviour of the SSL library. The (internal) behaviour of @@ -86,7 +101,7 @@ doing a re-connect, always takes the first cipher in the cipher list. =item SSL_OP_MSIE_SSLV2_RSA_PADDING -... +As of OpenSSL 0.9.7h and 0.9.8a, this option has no effect. =item SSL_OP_SSLEAY_080_CLIENT_DH_BUG @@ -163,7 +178,7 @@ When choosing a cipher, use the server's preferences instead of the client preferences. When not set, the SSL server will always follow the clients preferences. When set, the SSLv3/TLSv1 server will choose following its own preferences. Because of the different protocol, for SSLv2 the server -will send his list of preferences to the client and the client chooses. +will send its list of preferences to the client and the client chooses. =item SSL_OP_PKCS1_CHECK_1 @@ -199,17 +214,73 @@ Do not use the TLSv1 protocol. When performing renegotiation as a server, always start a new session (i.e., session resumption requests are only accepted in the initial -handshake). This option is not needed for clients. +handshake). This option is not needed for clients. + +=item SSL_OP_NO_TICKET + +Normally clients and servers will, where possible, transparently make use +of RFC4507bis tickets for stateless session resumption. + +If this option is set this functionality is disabled and tickets will +not be used by clients or servers. + +=item SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION + +See the B<SECURE RENEGOTIATION> section for a discussion of the purpose of +this option =back +=head1 SECURE RENEGOTIATION + +OpenSSL 0.9.8m and later always attempts to use secure renegotiation as +described in draft-ietf-tls-renegotiation (FIXME: replace by RFC). This +counters a prefix attack described in the draft and elsewhere (FIXME: need full +reference). + +This attack has far reaching consequences which application writers should be +aware of. In the description below an implementation supporting secure +renegotiation is referred to as I<patched>. A server not supporting secure +renegotiation is referred to as I<unpatched>. + +If an unpatched client attempts to connect to a patched OpenSSL server then +the attempt will succeed but renegotiation is not permitted. As required +by the standard a B<no_renegotiation> alert is sent back to the client if +the TLS v1.0 protocol is used. If SSLv3.0 is used then renegotiation results +in a fatal B<handshake_failed> alert. + +If a patched OpenSSL client attempts to connect to an unpatched server +then the connection will fail because it is not possible to determine +whether an attack is taking place. + +If the option B<SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION> is set then the +above restrictions are relaxed. Renegotiation is permissible and initial +connections to unpatched servers will succeed. + +This option should be used with caution because it leaves both clients and +servers vulnerable. However unpatched servers and clients are likely to be +around for some time and refusing to connect to unpatched servers or denying +renegotion altogether may be unacceptable. So applications may be forced to +tolerate unsafe renegotiation for the immediate future. + +The function SSL_get_secure_renegotiation_support() indicates whether the peer +supports secure renegotiation. + +The deprecated SSLv2 protocol does not support secure renegotiation at all. + =head1 RETURN VALUES SSL_CTX_set_options() and SSL_set_options() return the new options bitmask after adding B<options>. +SSL_CTX_clear_options() and SSL_clear_options() return the new options bitmask +after clearing B<options>. + SSL_CTX_get_options() and SSL_get_options() return the current bitmask. +SSL_get_secure_renegotiation_support() returns 1 is the peer supports +secure renegotiation and 0 if it does not. + =head1 SEE ALSO L<ssl(3)|ssl(3)>, L<SSL_new(3)|SSL_new(3)>, L<SSL_clear(3)|SSL_clear(3)>, @@ -232,4 +303,10 @@ Versions up to OpenSSL 0.9.6c do not include the countermeasure that can be disabled with this option (in OpenSSL 0.9.6d, it was always enabled). +SSL_CTX_clear_options() and SSL_clear_options() were first added in OpenSSL +0.9.8m. + +B<SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION> was first added in OpenSSL +0.9.8m. + =cut |