Loading doc/ssl/SSL_clear.pod +12 −2 Original line number Diff line number Diff line Loading @@ -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 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 Loading @@ -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 +12 −1 Original line number Diff line number Diff line Loading @@ -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 +19 −2 Original line number Diff line number Diff line Loading @@ -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 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: Loading @@ -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 +14 −4 Original line number Diff line number Diff line Loading @@ -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<blocking>, SSL_shutdown() will only return once the handshake has been finished or an error occurred. Loading Loading @@ -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 +1 −0 Original line number Diff line number Diff line Loading @@ -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)>, Loading Loading
doc/ssl/SSL_clear.pod +12 −2 Original line number Diff line number Diff line Loading @@ -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 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 Loading @@ -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 +12 −1 Original line number Diff line number Diff line Loading @@ -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 +19 −2 Original line number Diff line number Diff line Loading @@ -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 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: Loading @@ -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 +14 −4 Original line number Diff line number Diff line Loading @@ -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<blocking>, SSL_shutdown() will only return once the handshake has been finished or an error occurred. Loading Loading @@ -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 +1 −0 Original line number Diff line number Diff line Loading @@ -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)>, Loading
