Finish first round of session cache documentation.

doc/ssl/SSL_clear.pod

@@ -13,8 +13,17 @@ SSL_clear - reset SSL object to allow another connection
 =head1 DESCRIPTION
 
 Reset B<ssl> to allow another connection. All settings (method, ciphers,
-BIOs) are kept. A completely negotiated B<SSL_SESSION> is not freed but left
+BIOs) are kept.
-untouched for the underlying B<SSL_CTX>.
+
+=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<open>, it is considered bad and will be removed
+from the session cache, as required by RFC2246. A session is considered open,
+if L<SSL_shutdown(3)|SSL_shutdown(3)> was not called for the connection
+or at least L<SSL_set_shutdown(3)|SSL_set_shutdown(3)> was used to
+set the SSL_SENT_SHUTDOWN state.
 
 =head1 RETURN VALUES
 
@@ -34,6 +43,7 @@ The SSL_clear() operation was successful.
 =back
 
 L<SSL_new(3)|SSL_new(3)>, L<SSL_free(3)|SSL_free(3)>,
+L<SSL_shutdown(3)|SSL_shutdown(3)>, L<SSL_set_shutdown(3)|SSL_set_shutdown(3)>,
 L<SSL_CTX_set_options(3)|SSL_CTX_set_options(3)>, L<ssl(3)|ssl(3)>
 
 =cut

doc/ssl/SSL_free.pod

@@ -16,18 +16,29 @@ SSL_free() decrements the reference count of B<ssl>, and removes the SSL
 structure pointed to by B<ssl> 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<ssl>, the B<SSL_SESSION>.
 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<SSL_shutdown(3)|SSL_shutdown(3)> was not called for the connection
+and L<SSL_set_shutdown(3)|SSL_set_shutdown(3)> 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<SSL_new(3)|SSL_new(3)>, L<SSL_clear(3)|SSL_clear(3)>,
+L<SSL_shutdown(3)|SSL_shutdown(3)>, L<SSL_set_shutdown(3)|SSL_set_shutdown(3)>,
 L<ssl(3)|ssl(3)>
 
 =cut

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<SSL_SESSION> actually used in
 B<ssl>. The reference count of the B<SSL_SESSION> is not incremented, so
-that the pointer can become invalid when the B<ssl> is freed and
+that the pointer can become invalid by other operations.
-SSL_SESSION_free() is implicitly called.
 
 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<SSL_SESSION> 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<SSL_clear(3)|SSL_clear(3)> or
+L<SSL_free(3)|SSL_free(3)> 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<SSL_CTX_flush_sessions(3)|SSL_CTX_flush_sessions(3)>.
+
+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<SSL_SESSION_free(3)|SSL_SESSION_free(3)>, 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<ssl(3)|ssl(3)>, L<SSL_free(3)|SSL_free(3)>,
+L<SSL_clear(3)|SSL_clear(3)>,
 L<SSL_SESSION_free(3)|SSL_SESSION_free(3)>
 
 =cut

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
+SSL_shutdown() shuts down an active TLS/SSL connection. It sends the 
-alert to the peer. The behaviour of SSL_shutdown() depends on the underlying
+"close notify" shutdown alert to the peer.
-BIO. 
+
+=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<blocking>, 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<ret> to find out the reason.
 =head1 SEE ALSO
 
 L<SSL_get_error(3)|SSL_get_error(3)>, L<SSL_connect(3)|SSL_connect(3)>,
-L<SSL_accept(3)|SSL_accept(3)>, L<ssl(3)|ssl(3)>, L<bio(3)|bio(3)>
+L<SSL_accept(3)|SSL_accept(3)>, L<SSL_set_shutdown(3)|SSL_set_shutdown(3)>,
+L<SSL_clear(3)|SSL_clear(3), L<SSL_free(3)|SSL_free(3)>,
+L<ssl(3)|ssl(3)>, L<bio(3)|bio(3)>
 
 =cut

doc/ssl/ssl.pod

@@ -687,6 +687,7 @@ L<SSL_new(3)|SSL_new(3)>,
 L<SSL_read(3)|SSL_read(3)>, L<SSL_set_bio(3)|SSL_set_bio(3)>,
 L<SSL_set_fd(3)|SSL_set_fd(3)>, L<SSL_pending(3)|SSL_pending(3)>,
 L<SSL_set_session(3)|SSL_set_session(3)>,
+L<SSL_set_shutdown(3)|SSL_set_shutdown(3)>,
 L<SSL_shutdown(3)|SSL_shutdown(3)>, L<SSL_write(3)|SSL_write(3)>,
 L<SSL_SESSION_free(3)|SSL_SESSION_free(3)>,
 L<SSL_SESSION_get_ex_new_index(3)|SSL_SESSION_get_ex_new_index(3)>,