OpenBSD manual page server

Manual Page Search Parameters

SSL_SESSION_FREE(3) Library Functions Manual SSL_SESSION_FREE(3)

SSL_SESSION_up_ref, SSL_SESSION_freeSSL_SESSION reference counting

#include <openssl/ssl.h>

int
SSL_SESSION_up_ref(SSL_SESSION *session);

void
SSL_SESSION_free(SSL_SESSION *session);

() increments the reference count of the given session by 1.

() decrements the reference count of the given session by 1. If the reference count reaches 0, it frees the memory used by the session. If session is a NULL pointer, no action occurs.

SSL_SESSION objects are allocated when a TLS/SSL handshake operation is successfully completed. Depending on the settings, see SSL_CTX_set_session_cache_mode(3), the SSL_SESSION objects are internally referenced by the SSL_CTX and linked into its session cache. SSL objects may be using the SSL_SESSION object; as a session may be reused, several SSL objects may be using one SSL_SESSION object at the same time. It is therefore crucial to keep the reference count (usage information) correct and not delete a SSL_SESSION object that is still used, as this may lead to program failures due to dangling pointers. These failures may also appear delayed, e.g., when an SSL_SESSION object is completely freed as the reference count incorrectly becomes 0, but it is still referenced in the internal session cache and the cache list is processed during a SSL_CTX_flush_sessions(3) operation.

() must only be called for SSL_SESSION objects, for which the reference count was explicitly incremented (e.g., by calling SSL_get1_session(3); see SSL_get_session(3)) or when the SSL_SESSION object was generated outside a TLS handshake operation, e.g., by using d2i_SSL_SESSION(3). It must not be called on other SSL_SESSION objects, as this would cause incorrect reference counts and therefore program failures.

SSL_SESSION_up_ref() returns 1 on success or 0 on error.

d2i_SSL_SESSION(3), ssl(3), SSL_CTX_flush_sessions(3), SSL_CTX_set_session_cache_mode(3), SSL_get_session(3), SSL_SESSION_new(3)

SSL_SESSION_free() first appeared in SSLeay 0.5.2 and has been available since OpenBSD 2.4.

SSL_SESSION_up_ref() first appeared in OpenSSL 1.1.0 and has been available since OpenBSD 6.3.

June 12, 2019 OpenBSD-6.9