diff options
author | Dr. Stephen Henson <steve@openssl.org> | 2009-12-09 17:59:29 +0000 |
---|---|---|
committer | Dr. Stephen Henson <steve@openssl.org> | 2009-12-09 17:59:29 +0000 |
commit | 4db82571ba7849b7865a237c85cb9107ef2d51a9 (patch) | |
tree | c101cf50b0449337d3835cc22c674e73025da615 /doc | |
parent | 89408580eddad47a231c458e19b6fc4d0af3df8c (diff) | |
download | openssl-4db82571ba7849b7865a237c85cb9107ef2d51a9.tar.gz |
Document option clearning functions.
Initial secure renegotiation documentation.
Diffstat (limited to 'doc')
-rw-r--r-- | doc/ssl/SSL_CTX_set_options.pod | 74 |
1 files 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<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 @@ -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<SECURE RENEGOTIATION> 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<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 +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<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)>, @@ -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<SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION> was first added in OpenSSL +0.9.8m. + =cut |