1SSL_SESSION_FREE(3)                 OpenSSL                SSL_SESSION_FREE(3)
2
3
4

NAME

6       SSL_SESSION_new, SSL_SESSION_dup, SSL_SESSION_up_ref, SSL_SESSION_free
7       - create, free and manage SSL_SESSION structures
8

SYNOPSIS

10        #include <openssl/ssl.h>
11
12        SSL_SESSION *SSL_SESSION_new(void);
13        SSL_SESSION *SSL_SESSION_dup(SSL_SESSION *src);
14        int SSL_SESSION_up_ref(SSL_SESSION *ses);
15        void SSL_SESSION_free(SSL_SESSION *session);
16

DESCRIPTION

18       SSL_SESSION_new() creates a new SSL_SESSION structure and returns a
19       pointer to it.
20
21       SSL_SESSION_dup() copies the contents of the SSL_SESSION structure in
22       src and returns a pointer to it.
23
24       SSL_SESSION_up_ref() increments the reference count on the given
25       SSL_SESSION structure.
26
27       SSL_SESSION_free() decrements the reference count of session and
28       removes the SSL_SESSION structure pointed to by session and frees up
29       the allocated memory, if the reference count has reached 0.  If session
30       is NULL nothing is done.
31

NOTES

33       SSL_SESSION objects are allocated, when a TLS/SSL handshake operation
34       is successfully completed. Depending on the settings, see
35       SSL_CTX_set_session_cache_mode(3), the SSL_SESSION objects are
36       internally referenced by the SSL_CTX and linked into its session cache.
37       SSL objects may be using the SSL_SESSION object; as a session may be
38       reused, several SSL objects may be using one SSL_SESSION object at the
39       same time. It is therefore crucial to keep the reference count (usage
40       information) correct and not delete a SSL_SESSION object that is still
41       used, as this may lead to program failures due to dangling pointers.
42       These failures may also appear delayed, e.g.  when an SSL_SESSION
43       object was completely freed as the reference count incorrectly became
44       0, but it is still referenced in the internal session cache and the
45       cache list is processed during a SSL_CTX_flush_sessions(3) operation.
46
47       SSL_SESSION_free() must only be called for SSL_SESSION objects, for
48       which the reference count was explicitly incremented (e.g.  by calling
49       SSL_get1_session(), see SSL_get_session(3)) or when the SSL_SESSION
50       object was generated outside a TLS handshake operation, e.g. by using
51       d2i_SSL_SESSION(3).  It must not be called on other SSL_SESSION
52       objects, as this would cause incorrect reference counts and therefore
53       program failures.
54

RETURN VALUES

56       SSL_SESSION_new returns a pointer to the newly allocated SSL_SESSION
57       structure or NULL on error.
58
59       SSL_SESSION_up_ref returns 1 on success or 0 on error.
60

SEE ALSO

62       ssl(7), SSL_get_session(3), SSL_CTX_set_session_cache_mode(3),
63       SSL_CTX_flush_sessions(3), d2i_SSL_SESSION(3)
64

HISTORY

66       The SSL_SESSION_dup() function was added in OpenSSL 1.1.1.
67

69       Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
70
71       Licensed under the OpenSSL license (the "License").  You may not use
72       this file except in compliance with the License.  You can obtain a copy
73       in the file LICENSE in the source distribution or at
74       <https://www.openssl.org/source/license.html>.
75
76
77
781.1.1q                            2023-07-20               SSL_SESSION_FREE(3)
Impressum