From 4db82571ba7849b7865a237c85cb9107ef2d51a9 Mon Sep 17 00:00:00 2001 From: "Dr. Stephen Henson" Date: Wed, 9 Dec 2009 17:59:29 +0000 Subject: [PATCH] Document option clearning functions. Initial secure renegotiation documentation. --- doc/ssl/SSL_CTX_set_options.pod | 74 +++++++++++++++++++++++++++++++-- 1 file changed, 71 insertions(+), 3 deletions(-) diff --git a/doc/ssl/SSL_CTX_set_options.pod b/doc/ssl/SSL_CTX_set_options.pod index 81ee82c04c..e5837819dc 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_get_options, SSL_get_options - 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 to B. Options already set before are not cleared! SSL_set_options() adds the options set via bitmask in B to B. Options already set before are not cleared! +SSL_CTX_clear_options() clears the options set via bitmask in B +to B. + +SSL_clear_options() clears the options set via bitmask in B to B. + SSL_CTX_get_options() returns the options set for B. SSL_get_options() returns the options set for B. +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 -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 @@ -199,7 +214,7 @@ 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 @@ -209,15 +224,62 @@ 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 section for a discussion of the purpose of +this option + =back +=head1 SECURE RENEGOTIATION + +OpenSSL by 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. A server not supporting secure +renegotiation is referred to as I. + +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 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 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 is set then the +renegotiation between unpatched clients and patched servers is permitted as +well as initial connections and renegotiation between patched clients and +unpatched servers. 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 simply refusing to connect to unpatched +servers may well be considered unacceptable. So applications may be forced to +use this option 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. +SSL_CTX_clear_options() and SSL_clear_options() return the new options bitmask +after clearing B. + 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, L, L, @@ -240,4 +302,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 was first added in OpenSSL +0.9.8m. + =cut -- 2.25.1