From 8e495e4ac7caa585fe28d3e7c2fe32dd1d3e94a8 Mon Sep 17 00:00:00 2001 From: Lutz Jänicke Date: Tue, 13 Feb 2001 14:00:09 +0000 Subject: Finish first round of session cache documentation. --- doc/ssl/SSL_clear.pod | 14 +++++++-- doc/ssl/SSL_free.pod | 13 ++++++++- doc/ssl/SSL_get_session.pod | 21 ++++++++++++-- doc/ssl/SSL_set_shutdown.pod | 68 ++++++++++++++++++++++++++++++++++++++++++++ doc/ssl/SSL_shutdown.pod | 18 +++++++++--- doc/ssl/ssl.pod | 1 + 6 files changed, 126 insertions(+), 9 deletions(-) create mode 100644 doc/ssl/SSL_set_shutdown.pod diff --git a/doc/ssl/SSL_clear.pod b/doc/ssl/SSL_clear.pod index aeb0b5c7a2..8b735d81dc 100644 --- a/doc/ssl/SSL_clear.pod +++ b/doc/ssl/SSL_clear.pod @@ -13,8 +13,17 @@ SSL_clear - reset SSL object to allow another connection =head1 DESCRIPTION Reset B to allow another connection. All settings (method, ciphers, -BIOs) are kept. A completely negotiated B is not freed but left -untouched for the underlying B. +BIOs) are kept. + +=head1 NOTES + +SSL_clear is used to prepare an SSL object for a new connection. While all +settings are kept, a side effect is the handling of the current SSL session. +If a session is still B, it is considered bad and will be removed +from the session cache, as required by RFC2246. A session is considered open, +if L was not called for the connection +or at least L was used to +set the SSL_SENT_SHUTDOWN state. =head1 RETURN VALUES @@ -34,6 +43,7 @@ The SSL_clear() operation was successful. =back L, L, +L, L, L, L =cut diff --git a/doc/ssl/SSL_free.pod b/doc/ssl/SSL_free.pod index f3f0c345f8..2d4f8b6168 100644 --- a/doc/ssl/SSL_free.pod +++ b/doc/ssl/SSL_free.pod @@ -16,18 +16,29 @@ SSL_free() decrements the reference count of B, and removes the SSL structure pointed to by B and frees up the allocated memory if the the reference count has reached 0. -It also calls the free()ing procedures for indirectly affected items, if +=head1 NOTES + +SSL_free() also calls the free()ing procedures for indirectly affected items, if applicable: the buffering BIO, the read and write BIOs, cipher lists specially created for this B, the B. Do not explicitly free these indirectly freed up items before or after calling SSL_free(), as trying to free things twice may lead to program failure. +The ssl session has reference counts from two users: the SSL object, for +which the reference count is removed by SSL_free() and the internal +session cache. If the session is considered bad, because +L was not called for the connection +and L was not used to set the +SSL_SENT_SHUTDOWN state, the session will also be removed +from the session cache as required by RFC2246. + =head1 RETURN VALUES SSL_free() does not provide diagnostic information. L, L, +L, L, L =cut diff --git a/doc/ssl/SSL_get_session.pod b/doc/ssl/SSL_get_session.pod index aff41fb9cf..a0266e2ac6 100644 --- a/doc/ssl/SSL_get_session.pod +++ b/doc/ssl/SSL_get_session.pod @@ -16,14 +16,30 @@ SSL_get_session - retrieve TLS/SSL session data SSL_get_session() returns a pointer to the B actually used in B. The reference count of the B is not incremented, so -that the pointer can become invalid when the B is freed and -SSL_SESSION_free() is implicitly called. +that the pointer can become invalid by other operations. SSL_get0_session() is the same as SSL_get_session(). SSL_get1_session() is the same as SSL_get_session(), but the reference count of the B is incremented by one. +=head1 NOTES + +The ssl session contains all information required to re-establish the +connection without a new handshake. + +SSL_get0_session() returns a pointer to the actual session. As the +reference counter is not incremented, the pointer is only valid while +the connection is in use. If L or +L is called, the session may be removed completely +(if considered bad), and the pointer obtained will become invalid. Even +if the session is valid, it can be removed at any time due to timeout +during L. + +If the data is to be kept, SSL_get1_session() will increment the reference +count and the session will stay in memory until explicitly freed with +L, regardless of its state. + =head1 RETURN VALUES The following return values can occur: @@ -43,6 +59,7 @@ The return value points to the data of an SSL session. =head1 SEE ALSO L, L, +L, L =cut diff --git a/doc/ssl/SSL_set_shutdown.pod b/doc/ssl/SSL_set_shutdown.pod new file mode 100644 index 0000000000..6b196c1f15 --- /dev/null +++ b/doc/ssl/SSL_set_shutdown.pod @@ -0,0 +1,68 @@ +=pod + +=head1 NAME + +SSL_set_shutdown, SSL_get_shutdown - manipulate shutdown state of an SSL connection + +=head1 SYNOPSIS + + #include + + void SSL_set_shutdown(SSL *ssl, int mode); + + int SSL_get_shutdown(SSL *ssl); + +=head1 DESCRIPTION + +SSL_set_shutdown() sets the shutdown state of B to B. + +SSL_get_shutdown() returns the shutdown mode of B. + +=head1 NOTES + +The shutdown state of an ssl connection is a bitmask of: + +=over 4 + +=item 0 + +No shutdown setting, yet. + +=item SSL_SENT_SHUTDOWN + +A "close notify" shutdown alert was sent to the peer, the connection is being +considered closed and the session is closed and correct. + +=item SSL_RECEIVED_SHUTDOWN + +A shutdown alert was received form the peer, either a normal "close notify" +or a fatal error. + +=back + +SSL_SENT_SHUTDOWN and SSL_RECEIVED_SHUTDOWN can be set at the same time. + +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. +SSL_set_shutdown() can be used to set this state without sending a +close alert to the peer (see L). + +If a "close notify" was received, SSL_RECEIVED_SHUTDOWN will be set, +for setting SSL_SENT_SHUTDOWN the application must however still call +L or SSL_set_shutdown() itself. + +=head1 RETURN VALUES + +SSL_set_shutdown() does not return diagnostic information. + +SSL_get_shutdown() returns the current setting. + +=head1 SEE ALSO + +L, L, +L, L + +=cut diff --git a/doc/ssl/SSL_shutdown.pod b/doc/ssl/SSL_shutdown.pod index 20e273bd4d..7988dd3c90 100644 --- a/doc/ssl/SSL_shutdown.pod +++ b/doc/ssl/SSL_shutdown.pod @@ -12,9 +12,17 @@ SSL_shutdown - shut down a TLS/SSL connection =head1 DESCRIPTION -SSL_shutdown() shuts down an active TLS/SSL connection. It sends the shutdown -alert to the peer. The behaviour of SSL_shutdown() depends on the underlying -BIO. +SSL_shutdown() shuts down an active TLS/SSL connection. It sends the +"close notify" shutdown alert to the peer. + +=head1 NOTES + +SSL_shutdown() tries to send the "close notify" shutdown alert to the peer. +Whether the operation succeeds or not, the SSL_SENT_SHUTDOWN flag is set and +a currently open session is considered closed and good and will be kept in the +session cache for further reuse. + +The behaviour of SSL_shutdown() depends on the underlying BIO. If the underlying BIO is B, SSL_shutdown() will only return once the handshake has been finished or an error occurred. @@ -57,6 +65,8 @@ Call SSL_get_error() with the return value B to find out the reason. =head1 SEE ALSO L, L, -L, L, L +L, L, +L, +L, L =cut diff --git a/doc/ssl/ssl.pod b/doc/ssl/ssl.pod index 530ee102e2..b653c4d3c9 100644 --- a/doc/ssl/ssl.pod +++ b/doc/ssl/ssl.pod @@ -687,6 +687,7 @@ L, L, L, L, L, L, +L, L, L, L, L, -- cgit v1.2.3