lib/libssl/man/SSL_SESSION_free.3

   1 .\" $OpenBSD: SSL_SESSION_free.3,v 1.6 2018/03/27 17:35:50 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: March 27 2018 $
  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
  68 increments the reference count of the given
  69 .Fa session
  70 by 1.
  71 .Pp
  72 .Fn SSL_SESSION_free
  73 decrements the reference count of the given
  74 .Fa session
  75 by 1.
  76 If the reference count reaches 0, it frees the memory used by the
  77 .Fa session .
  78 If
  79 .Fa session
  80 is a
  81 .Dv NULL
  82 pointer, no action occurs.
  83 .Pp
  84 .Vt SSL_SESSION
  85 objects are allocated when a TLS/SSL handshake operation is successfully
  86 completed.
  87 Depending on the settings, see
  88 .Xr SSL_CTX_set_session_cache_mode 3 ,
  89 the
  90 .Vt SSL_SESSION
  91 objects are internally referenced by the
  92 .Vt SSL_CTX
  93 and linked into its session cache.
  94 .Vt SSL
  95 objects may be using the
  96 .Vt SSL_SESSION
  97 object; as a session may be reused, several
  98 .Vt SSL
  99 objects may be using one
 100 .Vt SSL_SESSION
 101 object at the same time.
 102 It is therefore crucial to keep the reference count (usage information) correct
 103 and not delete a
 104 .Vt SSL_SESSION
 105 object that is still used, as this may lead to program failures due to dangling
 106 pointers.
 107 These failures may also appear delayed, e.g., when an
 108 .Vt SSL_SESSION
 109 object is completely freed as the reference count incorrectly becomes 0, but it
 110 is still referenced in the internal session cache and the cache list is
 111 processed during a
 112 .Xr SSL_CTX_flush_sessions 3
 113 operation.
 114 .Pp
 115 .Fn SSL_SESSION_free
 116 must only be called for
 117 .Vt SSL_SESSION
 118 objects, for which the reference count was explicitly incremented (e.g., by
 119 calling
 120 .Xr SSL_get1_session 3 ;
 121 see
 122 .Xr SSL_get_session 3 )
 123 or when the
 124 .Vt SSL_SESSION
 125 object was generated outside a TLS handshake operation, e.g., by using
 126 .Xr d2i_SSL_SESSION 3 .
 127 It must not be called on other
 128 .Vt SSL_SESSION
 129 objects, as this would cause incorrect reference counts and therefore program
 130 failures.
 131 .Sh RETURN VALUES
 132 .Fn SSL_SESSION_up_ref
 133 returns 1 on success or 0 on error.
 134 .Sh SEE ALSO
 135 .Xr d2i_SSL_SESSION 3 ,
 136 .Xr SSL_CTX_flush_sessions 3 ,
 137 .Xr SSL_CTX_set_session_cache_mode 3 ,
 138 .Xr SSL_get_session 3 ,
 139 .Xr SSL_SESSION_new 3
 140 .Sh HISTORY
 141 .Fn SSL_SESSION_free
 142 first appeared in SSLeay 0.5.2 and has been available since
 143 .Ox 2.4 .
 144 .Pp
 145 .Fn SSL_SESSION_up_ref
 146 first appeared in OpenSSL 1.1.0 and has been available since
 147 .Ox 6.3 .