=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
-untouched for the underlying B<SSL_CTX>.
+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<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
=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
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
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
-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<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:
=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
--- /dev/null
+=pod
+
+=head1 NAME
+
+SSL_set_shutdown, SSL_get_shutdown - manipulate shutdown state of an SSL connection
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ 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<ssl> to B<mode>.
+
+SSL_get_shutdown() returns the shutdown mode of B<ssl>.
+
+=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<SSL_clear(3)|SSL_clear(3)> or L<SSL_free(3)|SSL_free(3)> 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<SSL_shutdown(3)|SSL_shutdown(3)>).
+
+If a "close notify" was received, SSL_RECEIVED_SHUTDOWN will be set,
+for setting SSL_SENT_SHUTDOWN the application must however still call
+L<SSL_shutdown(3)|SSL_shutdown(3)> 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<ssl(3)|ssl(3)>, L<SSL_shutdown(3)|SSL_shutdown(3)>,
+L<SSL_clear(3)|SSL_clear(3)>, L<SSL_free(3)|SSL_free(3)>
+
+=cut
=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<blocking>, SSL_shutdown() will only return once the
handshake has been finished or an error occurred.
=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
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)>,
projects / oweals / openssl.git / commitdiff