From d93eb21c7c1e39db098a7f1331a75cc95a783c2a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lutz=20J=C3=A4nicke?= Date: Mon, 20 Aug 2001 14:34:16 +0000 Subject: [PATCH 1/3] More interdependencies with respect to shutdown behaviour. --- doc/ssl/SSL_read.pod | 16 +++++++++++++--- doc/ssl/SSL_set_shutdown.pod | 5 ++++- doc/ssl/SSL_shutdown.pod | 9 ++++++--- doc/ssl/SSL_write.pod | 14 ++++++++++++-- 4 files changed, 35 insertions(+), 9 deletions(-) diff --git a/doc/ssl/SSL_read.pod b/doc/ssl/SSL_read.pod index e9557ba1a..6b47f2fbd 100644 --- a/doc/ssl/SSL_read.pod +++ b/doc/ssl/SSL_read.pod @@ -83,9 +83,18 @@ bytes actually read from the TLS/SSL connection. =item 0 -The read operation was not successful, probably because no data was -available. Call SSL_get_error() with the return value B to find out, -whether an error occurred. +The read operation was not successful, the SSL connection was closed by the +peer by sending a "close notify" alert. The SSL_RECEIVED_SHUTDOWN flag in +the ssl shutdown state is set (see L, +L). +Call SSL_get_error() with the return value B to find out, +whether an error occurred or the connection was shut down cleanly +(SSL_ERROR_ZERO_RETURN). + +SSLv2 (deprecated) does not support a shutdown alert protocol, so it can +only be detected, whether the underlying connection was closed. It cannot +be checked, whether the closure was initiated by the peer or by something +else. =item E0 @@ -101,6 +110,7 @@ L, L, L, L, L, L L, +L, L, L, L =cut diff --git a/doc/ssl/SSL_set_shutdown.pod b/doc/ssl/SSL_set_shutdown.pod index 119bb83c5..6289e635d 100644 --- a/doc/ssl/SSL_set_shutdown.pod +++ b/doc/ssl/SSL_set_shutdown.pod @@ -46,7 +46,10 @@ The shutdown state of the connection is used to determine the state of the ssl session. If the session is still open, when L or L is called, it is considered bad and removed according to RFC2246. -The actual condition for a correctly closed session is SSL_SENT_SHUTDOWN. +The actual condition for a correctly closed session is SSL_SENT_SHUTDOWN +(according to the TLS RFC, it is acceptable to only send the "close notify" +alert but to not wait for the peer's answer, when the underlying connection +is closed). SSL_set_shutdown() can be used to set this state without sending a close alert to the peer (see L). diff --git a/doc/ssl/SSL_shutdown.pod b/doc/ssl/SSL_shutdown.pod index e205eac30..6b5012be7 100644 --- a/doc/ssl/SSL_shutdown.pod +++ b/doc/ssl/SSL_shutdown.pod @@ -49,9 +49,12 @@ shutdown alert. On success, the second call to SSL_shutdown() will return with 1. =item If the peer already sent the "close notify" alert B it was -already processed implicitly inside another call of e.g. -B, SSL_shutdown() will send the "close notify" -alert, set the SSL_SENT_SHUTDOWN flag and will immediately return with 1. +already processed implicitly inside another function +(L), the SSL_RECEIVED_SHUTDOWN flag is set. +SSL_shutdown() will send the "close notify" alert, set the SSL_SENT_SHUTDOWN +flag and will immediately return with 1. +Whether SSL_RECEIVED_SHUTDOWN is already set can be checked using the +SSL_get_shutdown() (see also L call. =back diff --git a/doc/ssl/SSL_write.pod b/doc/ssl/SSL_write.pod index da66f0f05..7299f6e2e 100644 --- a/doc/ssl/SSL_write.pod +++ b/doc/ssl/SSL_write.pod @@ -78,8 +78,18 @@ bytes actually written to the TLS/SSL connection. =item 0 -The write operation was not successful. Call SSL_get_error() with the return -value B to find out, whether an error occurred. +The write operation was not successful, because the write side of the +SSL connection was shut down (the SSL_SENT_SHUTDOWN flag in the shutdown +state is set) by calling L or +L. It is also possible, that the +underlying connection was closed. +Call SSL_get_error() with the return value B to find out, +whether an error occurred or the connection was shut down cleanly +(SSL_ERROR_ZERO_RETURN). + +SSLv2 (deprecated) does not support a shutdown alert protocol, so it can +only be detected, whether the underlying connection was closed. It cannot +be checked, why the closure happened. =item E0 From df7cb13525f49fc3d004405d34cbe321cd42a7d8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lutz=20J=C3=A4nicke?= Date: Tue, 21 Aug 2001 07:27:02 +0000 Subject: [PATCH 2/3] Checked in from the wrong !@#$%&*() copy... --- ssl/ssl_stat.c | 48 ++++++++++++++++++++++++------------------------ 1 file changed, 24 insertions(+), 24 deletions(-) diff --git a/ssl/ssl_stat.c b/ssl/ssl_stat.c index e8b4f56aa..8e2b874f6 100644 --- a/ssl/ssl_stat.c +++ b/ssl/ssl_stat.c @@ -387,18 +387,18 @@ char *SSL_alert_desc_string(int value) case SSL3_AD_CERTIFICATE_EXPIRED: str="CE"; break; case SSL3_AD_CERTIFICATE_UNKNOWN: str="CU"; break; case SSL3_AD_ILLEGAL_PARAMETER: str="IP"; break; - case TLS1_AD_DECRYPTION_FAILED str="DC"; break; - case TLS1_AD_RECORD_OVERFLOW str="RO"; break; - case TLS1_AD_UNKNOWN_CA str="CA"; break; - case TLS1_AD_ACCESS_DENIED str="AD"; break; - case TLS1_AD_DECODE_ERROR str="DE"; break; - case TLS1_AD_DECRYPT_ERROR str="CY"; break; - case TLS1_AD_EXPORT_RESTRICTION str="ER"; break; - case TLS1_AD_PROTOCOL_VERSION str="PV"; break; - case TLS1_AD_INSUFFICIENT_SECURITY str="IS"; break; - case TLS1_AD_INTERNAL_ERROR str="IE"; break; - case TLS1_AD_USER_CANCELLED str="US"; break; - case TLS1_AD_NO_RENEGOTIATION str="NR"; break; + case TLS1_AD_DECRYPTION_FAILED: str="DC"; break; + case TLS1_AD_RECORD_OVERFLOW: str="RO"; break; + case TLS1_AD_UNKNOWN_CA: str="CA"; break; + case TLS1_AD_ACCESS_DENIED: str="AD"; break; + case TLS1_AD_DECODE_ERROR: str="DE"; break; + case TLS1_AD_DECRYPT_ERROR: str="CY"; break; + case TLS1_AD_EXPORT_RESTRICTION: str="ER"; break; + case TLS1_AD_PROTOCOL_VERSION: str="PV"; break; + case TLS1_AD_INSUFFICIENT_SECURITY: str="IS"; break; + case TLS1_AD_INTERNAL_ERROR: str="IE"; break; + case TLS1_AD_USER_CANCELLED: str="US"; break; + case TLS1_AD_NO_RENEGOTIATION: str="NR"; break; default: str="UK"; break; } return(str); @@ -446,40 +446,40 @@ char *SSL_alert_desc_string_long(int value) case SSL3_AD_ILLEGAL_PARAMETER: str="illegal parameter"; break; - case TLS1_AD_DECRYPTION_FAILED + case TLS1_AD_DECRYPTION_FAILED: str="decryption failed"; break; - case TLS1_AD_RECORD_OVERFLOW + case TLS1_AD_RECORD_OVERFLOW: str="record overflow"; break; - case TLS1_AD_UNKNOWN_CA + case TLS1_AD_UNKNOWN_CA: str="unknown CA"; break; - case TLS1_AD_ACCESS_DENIED + case TLS1_AD_ACCESS_DENIED: str="access denied"; break; - case TLS1_AD_DECODE_ERROR + case TLS1_AD_DECODE_ERROR: str="decode error"; break; - case TLS1_AD_DECRYPT_ERROR + case TLS1_AD_DECRYPT_ERROR: str="decrypt error"; break; - case TLS1_AD_EXPORT_RESTRICTION + case TLS1_AD_EXPORT_RESTRICTION: str="export restriction"; break; - case TLS1_AD_PROTOCOL_VERSION + case TLS1_AD_PROTOCOL_VERSION: str="protocol version"; break; - case TLS1_AD_INSUFFICIENT_SECURITY + case TLS1_AD_INSUFFICIENT_SECURITY: str="insufficient security"; break; - case TLS1_AD_INTERNAL_ERROR + case TLS1_AD_INTERNAL_ERROR: str="internal error"; break; - case TLS1_AD_USER_CANCELLED + case TLS1_AD_USER_CANCELLED: str="user canceled"; break; - case TLS1_AD_NO_RENEGOTIATION + case TLS1_AD_NO_RENEGOTIATION: str="no renegotiation"; break; default: str="unknown"; break; From 336736ef35471888c266336ac2fb17e740979955 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lutz=20J=C3=A4nicke?= Date: Tue, 21 Aug 2001 13:02:58 +0000 Subject: [PATCH 3/3] Documentation on how to handle compression methods. Hopefully it is clear enough, that it is currently not recommended. --- doc/ssl/SSL_COMP_add_compression_method.pod | 64 +++++++++++++++++++++ doc/ssl/ssl.pod | 1 + 2 files changed, 65 insertions(+) create mode 100644 doc/ssl/SSL_COMP_add_compression_method.pod diff --git a/doc/ssl/SSL_COMP_add_compression_method.pod b/doc/ssl/SSL_COMP_add_compression_method.pod new file mode 100644 index 000000000..9e970044a --- /dev/null +++ b/doc/ssl/SSL_COMP_add_compression_method.pod @@ -0,0 +1,64 @@ +=pod + +=head1 NAME + +SSL_COMP_add_compression_method - handle SSL/TLS integrated compression methods + +=head1 SYNOPSIS + + #include + + int SSL_COMP_add_compression_method(int id, COMP_METHOD *cm); + +=head1 DESCRIPTION + +SSL_COMP_add_compression_method() adds the compression method B with +the identifier B to the list of available compression methods. This +list is globally maintained for all SSL operations within this application. +It cannot be set for specific SSL_CTX or SSL objects. + +=head1 NOTES + +The TLS standard (or SSLv3) allows the integration of compression methods +into the communication. The TLS RFC does however not specify compression +methods or their corresponding identifiers, so there is currently no compatible +way to integrate compression with unknown peers. It is therefore currently not +recommended to integrate compression into applications. Applications for +non-public use may agree on certain compression methods. Using different +compression methods with the same identifier will lead to connection failure. + +An OpenSSL client speaking a protocol that allows compression (SSLv3, TLSv1) +will unconditionally send the list of all compression methods enabled with +SSL_COMP_add_compression_method() to the server during the handshake. +Unlike the mechanisms to set a cipher list, there is no method available to +restrict the list of compression method on a per connection basis. + +An OpenSSL server will match the identifiers listed by a client against +its own compression methods and will unconditionally activate compression +when a matching identifier is found. There is no way to restrict the list +of compression methods supported on a per connection basis. + +The OpenSSL library has the compression methods B and (when +especially enabled during compilation) B available. + +=head1 RETURN VALUES + +SSL_COMP_add_compression_method() may return the following values: + +=over 4 + +=item 1 + +The operation succeeded. + +=item 0 + +The operation failed. Check the error queue to find out the reason. + +=back + +=head1 SEE ALSO + +L + +=cut diff --git a/doc/ssl/ssl.pod b/doc/ssl/ssl.pod index bee252aa8..cb4260ee8 100644 --- a/doc/ssl/ssl.pod +++ b/doc/ssl/ssl.pod @@ -650,6 +650,7 @@ L, L, L, L, L, L, +L, L, L, L,