1.\" $OpenBSD: SSL_SESSION_free.3,v 1.7 2019/06/12 09:36:30 schwarze Exp $ 2.\" full merge up to: OpenSSL b31db505 Mar 24 16:01:50 2017 +0000 3.\" 4.\" This file was written by Lutz Jaenicke <jaenicke@openssl.org> 5.\" and Matt Caswell <matt@openssl.org>. 6.\" Copyright (c) 2000, 2001, 2009, 2017 The OpenSSL Project. 7.\" All rights reserved. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 13.\" 1. Redistributions of source code must retain the above copyright 14.\" notice, this list of conditions and the following disclaimer. 15.\" 16.\" 2. Redistributions in binary form must reproduce the above copyright 17.\" notice, this list of conditions and the following disclaimer in 18.\" the documentation and/or other materials provided with the 19.\" distribution. 20.\" 21.\" 3. All advertising materials mentioning features or use of this 22.\" software must display the following acknowledgment: 23.\" "This product includes software developed by the OpenSSL Project 24.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" 25.\" 26.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to 27.\" endorse or promote products derived from this software without 28.\" prior written permission. For written permission, please contact 29.\" openssl-core@openssl.org. 30.\" 31.\" 5. Products derived from this software may not be called "OpenSSL" 32.\" nor may "OpenSSL" appear in their names without prior written 33.\" permission of the OpenSSL Project. 34.\" 35.\" 6. Redistributions of any form whatsoever must retain the following 36.\" acknowledgment: 37.\" "This product includes software developed by the OpenSSL Project 38.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" 39.\" 40.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY 41.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 42.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 43.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR 44.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 45.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 46.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 47.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 48.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 49.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 50.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED 51.\" OF THE POSSIBILITY OF SUCH DAMAGE. 52.\" 53.Dd $Mdocdate: June 12 2019 $ 54.Dt SSL_SESSION_FREE 3 55.Os 56.Sh NAME 57.Nm SSL_SESSION_up_ref , 58.Nm SSL_SESSION_free 59.Nd SSL_SESSION reference counting 60.Sh SYNOPSIS 61.In openssl/ssl.h 62.Ft int 63.Fn SSL_SESSION_up_ref "SSL_SESSION *session" 64.Ft void 65.Fn SSL_SESSION_free "SSL_SESSION *session" 66.Sh DESCRIPTION 67.Fn SSL_SESSION_up_ref 68increments the reference count of the given 69.Fa session 70by 1. 71.Pp 72.Fn SSL_SESSION_free 73decrements the reference count of the given 74.Fa session 75by 1. 76If the reference count reaches 0, it frees the memory used by the 77.Fa session . 78If 79.Fa session 80is a 81.Dv NULL 82pointer, no action occurs. 83.Pp 84.Vt SSL_SESSION 85objects are allocated when a TLS/SSL handshake operation is successfully 86completed. 87Depending on the settings, see 88.Xr SSL_CTX_set_session_cache_mode 3 , 89the 90.Vt SSL_SESSION 91objects are internally referenced by the 92.Vt SSL_CTX 93and linked into its session cache. 94.Vt SSL 95objects may be using the 96.Vt SSL_SESSION 97object; as a session may be reused, several 98.Vt SSL 99objects may be using one 100.Vt SSL_SESSION 101object at the same time. 102It is therefore crucial to keep the reference count (usage information) correct 103and not delete a 104.Vt SSL_SESSION 105object that is still used, as this may lead to program failures due to dangling 106pointers. 107These failures may also appear delayed, e.g., when an 108.Vt SSL_SESSION 109object is completely freed as the reference count incorrectly becomes 0, but it 110is still referenced in the internal session cache and the cache list is 111processed during a 112.Xr SSL_CTX_flush_sessions 3 113operation. 114.Pp 115.Fn SSL_SESSION_free 116must only be called for 117.Vt SSL_SESSION 118objects, for which the reference count was explicitly incremented (e.g., by 119calling 120.Xr SSL_get1_session 3 ; 121see 122.Xr SSL_get_session 3 ) 123or when the 124.Vt SSL_SESSION 125object was generated outside a TLS handshake operation, e.g., by using 126.Xr d2i_SSL_SESSION 3 . 127It must not be called on other 128.Vt SSL_SESSION 129objects, as this would cause incorrect reference counts and therefore program 130failures. 131.Sh RETURN VALUES 132.Fn SSL_SESSION_up_ref 133returns 1 on success or 0 on error. 134.Sh SEE ALSO 135.Xr d2i_SSL_SESSION 3 , 136.Xr ssl 3 , 137.Xr SSL_CTX_flush_sessions 3 , 138.Xr SSL_CTX_set_session_cache_mode 3 , 139.Xr SSL_get_session 3 , 140.Xr SSL_SESSION_new 3 141.Sh HISTORY 142.Fn SSL_SESSION_free 143first appeared in SSLeay 0.5.2 and has been available since 144.Ox 2.4 . 145.Pp 146.Fn SSL_SESSION_up_ref 147first appeared in OpenSSL 1.1.0 and has been available since 148.Ox 6.3 . 149