NAME

       ssl_session_cache_api - TLS session cache API

DESCRIPTION

       Defines  the  API  for the TLS session cache (pre TLS-1.3) so that the data storage scheme
       can be replaced by defining a new callback module implementing this API.

DATA TYPES

       session_cache_ref() = any()

       session_cache_key() = {partial_key(), ssl:session_id()}

              A key to an entry in the session cache.

       partial_key()

              The opaque part of the key. Does not need to be handled by the callback.

       session()

              The session data that is stored for each session.

EXPORTS

       Module:delete(Cache, Key) -> _

              Types:

                 Cache =  session_cache_ref()
                 Key = session_cache_key()

              Deletes a cache entry. Is only called from the cache handling process.

       Module:foldl(Fun, Acc0, Cache) -> Acc

              Types:

                 Fun = fun()
                 Acc0 = Acc = term()
                 Cache =  session_cache_ref()

              Calls Fun(Elem, AccIn) on successive elements of the cache, starting with AccIn  ==
              Acc0.  Fun/2  must  return a new accumulator, which is passed to the next call. The
              function returns the final value of the accumulator. Acc0 is returned if the  cache
              is empty.

          Note:
              Since  OTP-23.3 this functions is only used on the client side and does not need to
              implemented for a server cache.

       Module:init(Args) -> Cache

              Types:

                 Cache =  session_cache_ref()
                 Args = proplists:proplist()

              Includes property {role, client | server}. Currently this is  the  only  predefined
              property,   there  can  also  be  user-defined  properties.  See  also  application
              environment variable session_cb_init_args.

              Performs possible initializations of the cache and returns a reference to  it  that
              is  used  as  parameter to the other API functions. Is called by the cache handling
              processes init function, hence putting the same requirements  on  it  as  a  normal
              process  init  function.  This  function  is  called  twice  when  starting the SSL
              application, once with the role client and once with the role server,  as  the  SSL
              application must be prepared to take on both roles.

       Module:lookup(Cache, Key) -> Entry

              Types:

                 Cache =  session_cache_ref()
                 Key = session_cache_key()
                 Session = session() | undefined

              Looks up a cache entry. Is to be callable from any process.

       Module:select_session(Cache, PartialKey) -> [Session]

              Types:

                 Cache =  session_cache_ref()
                 PartialKey =  partial_key()
                 Session = session()

              Selects  sessions  that  can be reused, that is sessions that include PartialKey in
              its key. Is to be callable from any process.

          Note:
              Since OTP-23.3 This functions is only used on the client side and does not need  to
              implemented for a server cache.

       Module:size(Cache) -> integer()

              Types:

                 Cache =  session_cache_ref()

              Returns  the number of sessions in the cache. If size exceeds the maximum number of
              sessions, the current  cache  entries  will  be  invalidated  regardless  of  their
              remaining lifetime. Is to be callable from any process.

       Module:terminate(Cache) -> _

              Types:

                 Cache =  session_cache_ref()
                   As returned by init/0

              Takes  care  of  possible  cleanup  that  is needed when the cache handling process
              terminates.

       Module:update(Cache, Key, Session) -> _

              Types:

                 Cache =  session_cache_ref()
                 Key = session_cache_key()
                 Session = session()

              Caches a new session or updates an already cached one.  Is  only  called  from  the
              cache handling process.