Botan::TLS::Session_Manager_In_Memory Class Reference

#include <tls_session_manager_memory.h>

Inheritance diagram for Botan::TLS::Session_Manager_In_Memory:

Public Member Functions
size_t	capacity () const
virtual std::optional< std::pair< Session, uint16_t > >	choose_from_offered_tickets (const std::vector< PskIdentity > &tickets, std::string_view hash_function, Callbacks &callbacks, const Policy &policy)
bool	emits_session_tickets () override
virtual std::optional< Session_Handle >	establish (const Session &session, const std::optional< Session_ID > &id=std::nullopt, bool tls12_no_ticket=false)
	Save a new Session and assign a Session_Handle (TLS Server)
virtual std::vector< Session_with_Handle >	find (const Server_Information &info, Callbacks &callbacks, const Policy &policy)
	Find all sessions that match a given server info.
size_t	remove (const Session_Handle &handle) override
size_t	remove_all () override
virtual std::optional< Session >	retrieve (const Session_Handle &handle, Callbacks &callbacks, const Policy &policy)
	Retrieves a specific session given a handle.
	Session_Manager_In_Memory (const std::shared_ptr< RandomNumberGenerator > &rng, size_t max_sessions=1000)
void	store (const Session &session, const Session_Handle &handle) override
	Save a Session under a Session_Handle (TLS Client)

Protected Member Functions
std::vector< Session_with_Handle >	find_some (const Server_Information &info, size_t max_sessions_hint) override
	Internal retrieval function to find sessions to resume.
recursive_mutex_type &	mutex ()
std::optional< Session >	retrieve_one (const Session_Handle &handle) override
	Internal retrieval function for a single session.

Protected Attributes
std::shared_ptr< RandomNumberGenerator >	m_rng

Detailed Description

A thread-safe Session_Manager that stores TLS sessions in memory.

The Session_Handle objects emitted by this manager when establishing a new session (i.e in the TLS server) will never contain a Session_Ticket but only a Session_ID. Storing received sessions (i.e. in the TLS client) under either a Session_ID or a Session_Ticket will however echo them back.

In other words, this manager will support ticket-based resumption in a TLS client but it won't issue tickets on a TLS server.

For applications that implement a TLS client and that do not want to persist sessions to non-volatile memory, this is typically a good default option.

Definition at line 39 of file tls_session_manager_memory.h.

Constructor & Destructor Documentation

Session_Manager_In_Memory()

Botan::TLS::Session_Manager_In_Memory::Session_Manager_In_Memory	(	const std::shared_ptr< RandomNumberGenerator > &	rng,
		size_t	max_sessions = 1000 )

Parameters

rng	a RNG used for generating session key and for session encryption
max_sessions	a hint on the maximum number of sessions to keep in memory at any one time. (If zero, don't cap)

Definition at line 18 of file tls_session_manager_memory.cpp.

                                                                          :
      Session_Manager(rng), m_max_sessions(max_sessions) {
   if(max_sessions > 0) {
      m_fifo.emplace();
   }
}

Member Function Documentation

capacity()

size_t Botan::TLS::Session_Manager_In_Memory::capacity ( ) const

inline

Definition at line 53 of file tls_session_manager_memory.h.

{ return m_max_sessions; }

Referenced by store().

choose_from_offered_tickets()

std::optional< std::pair< Session, uint16_t > > Botan::TLS::Session_Manager::choose_from_offered_tickets ( const std::vector< PskIdentity > & tickets, std::string_view hash_function, Callbacks & callbacks, const Policy & policy )

virtualinherited

Lets the server application choose a PSK to use for a new TLS connection. Implementers must make sure that the PSK's associated hash function is equal to the passed hash_function.

RFC 8446 4.2.11 The server MUST ensure that it selects a compatible PSK (if any) and cipher suite.

The default implementation simply tries to retrieve all tickets in the order offered by the peer and picks the first that is found and features a matching hash algorithm.

This method is called only by TLS 1.3 servers.

Parameters

tickets	a list of tickets that were offered by the client
hash_function	the hash algorithm name we are going to use for the to-be-negotiated connection
callbacks	callbacks to be used for session policy decisions
policy	policy to be used for session policy decisions

Returns

a std::pair of the Session associated to the choosen PSK and the index of the selected ticket; std::nullopt if no PSK was chosen for usage (will result in a full handshake)

Note

if no PSK is chosen, the server will attempt a regular handshake.

Definition at line 206 of file tls_session_manager.cpp.

                         {
   // Note that the TLS server currently does not ensure that tickets aren't
   // reused. As a result, no locking is required on this level.
 
   for(uint16_t i = 0; const auto& ticket : tickets) {
      auto session = retrieve(Opaque_Session_Handle(ticket.identity()), callbacks, policy);
      if(session.has_value() && session->ciphersuite().prf_algo() == hash_function &&
         session->version().is_tls_13_or_later()) {
         return std::pair{std::move(session.value()), i};
      }
 
      // RFC 8446 4.2.10
      //    For PSKs provisioned via NewSessionTicket, a server MUST validate
      //    that the ticket age for the selected PSK identity [...] is within a
      //    small tolerance of the time since the ticket was issued.  If it is
      //    not, the server SHOULD proceed with the handshake but reject 0-RTT,
      //    and SHOULD NOT take any other action that assumes that this
      //    ClientHello is fresh.
      //
      // TODO: The ticket-age is currently not checked (as 0-RTT is not
      //       implemented) and we simply take the SHOULD at face value.
      //       Instead we could add a policy check letting the user decide.
 
      ++i;
   }
 
   return std::nullopt;
}

Referenced by Botan::TLS::PSK::select_offered_psk().

emits_session_tickets()

bool Botan::TLS::Session_Manager_In_Memory::emits_session_tickets ( )

inlineoverridevirtual

Declares whether the given Session_Manager implementation may emit session tickets. Note that this does not mean that the implementation must always emit tickets.

Concrete implementations should declare this, to allow the TLS implementations to act accordingly. E.g. to advertise support for session tickets in their Server Hello.

Returns

true if the Session_Manager produces session tickets

Reimplemented from Botan::TLS::Session_Manager.

Definition at line 55 of file tls_session_manager_memory.h.

{ return false; }

establish()

std::optional< Session_Handle > Botan::TLS::Session_Manager::establish ( const Session & session, const std::optional< Session_ID > & id = std::nullopt, bool tls12_no_ticket = false )

virtualinherited

Save a new Session and assign a Session_Handle (TLS Server)

Save a new session on a best effort basis; the manager may not in fact be able to save the session for whatever reason; this is not an error. Callers cannot assume that calling establish() followed immediately by retrieve() or choose_from_offered_tickets() will result in a successful lookup. In case no session was stored, std::nullopt is returned.

This method is only called on TLS servers.

Note that implementations will silently refrain from sending session tickets to the client when this method returns std::nullopt.

Parameters

session	to save
id	to use (instead of an ID chosen by the manager)
tls12_no_ticket	disable tickets for this establishment (set when TLS 1.2 client does not support them)

Returns

a Session_Handle containing either an ID or a ticket if the session was saved, otherwise std::nullopt

Reimplemented in Botan::TLS::Session_Manager_Hybrid, Botan::TLS::Session_Manager_Noop, and Botan::TLS::Session_Manager_Stateless.

Definition at line 21 of file tls_session_manager.cpp.

                                                                               {
   // Establishing a session does not require locking at this level as
   // concurrent TLS instances on a server will create unique sessions.
 
   // By default, the session manager does not emit session tickets anyway
   BOTAN_UNUSED(tls12_no_ticket);
   BOTAN_ASSERT(session.side() == Connection_Side::Server, "Client tried to establish a session");
 
   Session_Handle handle(id.value_or(m_rng->random_vec<Session_ID>(32)));
   store(session, handle);
   return handle;
}

References BOTAN_ASSERT, BOTAN_UNUSED, Botan::TLS::Session_Manager::m_rng, Botan::TLS::Server, Botan::TLS::Session_Base::side(), and Botan::TLS::Session_Manager::store().

find()

std::vector< Session_with_Handle > Botan::TLS::Session_Manager::find ( const Server_Information & info, Callbacks & callbacks, const Policy & policy )

virtualinherited

Find all sessions that match a given server info.

TLS clients use this to obtain session resumption information for a server they are wishing to handshake with. Typically, session info will have been received in prior connections to that same server and stored using Session_Manager::store().

The default implementation will invoke Session_Manager::find_some() and filter the result against a policy. Most notably an expiry check. Expired sessions will be removed via Session_Manager::remove().

The TLS client implementations will query the session manager exactly once per handshake attempt. If no reuse is desired, the session manager may remove the sessions internally when handing them out to the client. The default implementation adheres to Policy::reuse_session_tickets().

For TLS 1.2 the client implementation will attempt a resumption with the first session in the returned list. For TLS 1.3, it will offer all found sessions to the server.

Applications that wish to implement their own Session_Manager may override the default implementation to add further policy checks. Though, typically implementing Session_Manager::find_some() and relying on the default implementation is enough.

Parameters

info	the info about the server we want to handshake with
callbacks	callbacks to be used for session policy decisions
policy	policy to be used for session policy decisions

Returns

a list of usable sessions that might be empty if no such session exists or passed the policy validation

Reimplemented in Botan::TLS::Session_Manager_Hybrid.

Definition at line 161 of file tls_session_manager.cpp.

                                                                             {
   auto allow_reusing_tickets = policy.reuse_session_tickets();
 
   // Session_Manager::find() must be an atomic getter if ticket reuse is not
   // allowed. I.e. each ticket handed to concurrently requesting threads must
   // be unique. In that case we must hold a lock while retrieving a ticket.
   // Otherwise, no locking is required on this level.
   std::optional<lock_guard_type<recursive_mutex_type>> lk;
   if(!allow_reusing_tickets) {
      lk.emplace(mutex());
   }
 
   auto sessions_and_handles = find_and_filter(info, callbacks, policy);
 
   // std::vector::resize() cannot be used as the vector's members aren't
   // default constructible.
   const auto session_limit = policy.maximum_session_tickets_per_client_hello();
   while(session_limit > 0 && sessions_and_handles.size() > session_limit) {
      sessions_and_handles.pop_back();
   }
 
   // RFC 8446 Appendix C.4
   //    Clients SHOULD NOT reuse a ticket for multiple connections. Reuse of
   //    a ticket allows passive observers to correlate different connections.
   //
   // When reuse of session tickets is not allowed, remove all tickets to be
   // returned from the implementation's internal storage.
   if(!allow_reusing_tickets) {
      // The lock must be held here, otherwise we cannot guarantee the
      // transactional retrieval of tickets to concurrently requesting clients.
      BOTAN_ASSERT_NOMSG(lk.has_value());
      for(const auto& [session, handle] : sessions_and_handles) {
         if(!session.version().is_pre_tls_13() || !handle.is_id()) {
            remove(handle);
         }
      }
   }
 
   return sessions_and_handles;
}

References BOTAN_ASSERT_NOMSG, Botan::TLS::Policy::maximum_session_tickets_per_client_hello(), and Botan::TLS::Policy::reuse_session_tickets().

find_some()

std::vector< Session_with_Handle > Botan::TLS::Session_Manager_In_Memory::find_some ( const Server_Information & info, size_t max_sessions_hint )

overrideprotectedvirtual

Internal retrieval function to find sessions to resume.

Try to find saved sessions using info about the server we're planning to connect to. It should return a list of sessions in preference order of the session manager.

Applications that wish to implement their own Session_Manager will have to provide an implementation for it.

Note that the TLS client implementations do not perform any checks on the validity of the session for a given info. Particularly, it is the Session_Manager's responsibility to ensure the restrictions posed in RFC 8446 4.6.1 regarding server certificate validity for the given info.

This is called for TLS clients only.

Parameters

info	the information about the server
max_sessions_hint	a non-binding guideline for an upper bound of sessions to return from this method (will be at least 1 but potentially more)

Returns

the found sessions along with their handles (containing either a session ID or a ticket)

Implements Botan::TLS::Session_Manager.

Definition at line 63 of file tls_session_manager_memory.cpp.

                                                                                                      {
   BOTAN_UNUSED(max_sessions_hint);
 
   lock_guard_type<recursive_mutex_type> lk(mutex());
 
   std::vector<Session_with_Handle> found_sessions;
   // TODO: std::copy_if?
   for(const auto& [_, session_and_handle] : m_sessions) {
      if(session_and_handle.session.server_info() == info) {
         found_sessions.emplace_back(session_and_handle);
      }
   }
 
   return found_sessions;
}

References BOTAN_UNUSED, and Botan::TLS::Session_Manager::mutex().

mutex()

recursive_mutex_type & Botan::TLS::Session_Manager::mutex ( )

inlineprotectedinherited

Returns the base class' recursive mutex for reuse in derived classes

Definition at line 267 of file tls_session_manager.h.

{ return m_mutex; }

Referenced by find_some(), Botan::TLS::Session_Manager_SQL::find_some(), remove(), Botan::TLS::Session_Manager_SQL::remove(), remove_all(), Botan::TLS::Session_Manager_SQL::remove_all(), retrieve_one(), Botan::TLS::Session_Manager_SQL::retrieve_one(), store(), and Botan::TLS::Session_Manager_SQL::store().

remove()

size_t Botan::TLS::Session_Manager_In_Memory::remove ( const Session_Handle & handle )

overridevirtual

Remove a specific session from the cache, if it exists. The handle might contain either a session ID or a ticket.

Parameters

handle

a Session_Handle of the session to be removed

Returns

the number of sessions that were removed

Implements Botan::TLS::Session_Manager.

Definition at line 80 of file tls_session_manager_memory.cpp.

                                                                     {
   lock_guard_type<recursive_mutex_type> lk(mutex());
   return remove_internal(handle);
}

References Botan::TLS::Session_Manager::mutex().

remove_all()

size_t Botan::TLS::Session_Manager_In_Memory::remove_all ( )

overridevirtual

Remove all sessions from the cache

Returns

the number of sessions that were removed

Implements Botan::TLS::Session_Manager.

Definition at line 126 of file tls_session_manager_memory.cpp.

                                             {
   lock_guard_type<recursive_mutex_type> lk(mutex());
 
   const auto sessions = m_sessions.size();
   m_sessions.clear();
   if(m_fifo.has_value()) {
      m_fifo->clear();
   }
 
   return sessions;
}

References Botan::TLS::Session_Manager::mutex().

retrieve()

std::optional< Session > Botan::TLS::Session_Manager::retrieve ( const Session_Handle & handle, Callbacks & callbacks, const Policy & policy )

virtualinherited

Retrieves a specific session given a handle.

This is typically used by TLS servers to obtain resumption information for a previous call to Session_Manager::establish() when a client requested resumption using the handle.

Even if the session is found successfully, it is returned only if it passes policy validations. Most notably an expiry check. If the expiry check fails, the default implementation calls Session_Manager::remove() for the provided handle.

Applications that wish to implement their own Session_Manager may override the default implementation to add further policy checks. Though, typically implementing Session_Manager::retrieve_one() and relying on the default implementation is enough.

Parameters

handle	the Session_Handle to be retrieved
callbacks	callbacks to be used for session policy decisions
policy	policy to be used for session policy decisions

Returns

the obtained session or std::nullopt if no session was found or the policy checks failed

Reimplemented in Botan::TLS::Session_Manager_Hybrid.

Definition at line 36 of file tls_session_manager.cpp.

                                                                       {
   // Retrieving a session for a given handle does not require locking on this
   // level. Concurrent threads might handle the removal of an expired ticket
   // more than once, but removing an already removed ticket is a harmless NOOP.
 
   auto session = retrieve_one(handle);
   if(!session.has_value()) {
      return std::nullopt;
   }
 
   // A value of '0' means: No policy restrictions.
   const std::chrono::seconds policy_lifetime =
      (policy.session_ticket_lifetime().count() > 0) ? policy.session_ticket_lifetime() : std::chrono::seconds::max();
 
   // RFC 5077 3.3 -- "Old Session Tickets"
   //    A server MAY treat a ticket as valid for a shorter or longer period of
   //    time than what is stated in the ticket_lifetime_hint.
   //
   // RFC 5246 F.1.4 -- TLS 1.2
   //    If either party suspects that the session may have been compromised, or
   //    that certificates may have expired or been revoked, it should force a
   //    full handshake.  An upper limit of 24 hours is suggested for session ID
   //    lifetimes.
   //
   // RFC 8446 4.6.1 -- TLS 1.3
   //    A server MAY treat a ticket as valid for a shorter period of time than
   //    what is stated in the ticket_lifetime.
   //
   // Note: This disregards what is stored in the session (e.g. "lifetime_hint")
   //       and only takes the local policy into account. The lifetime stored in
   //       the sessions was taken from the same policy anyways and changes by
   //       the application should have an immediate effect.
   const auto ticket_age =
      std::chrono::duration_cast<std::chrono::seconds>(callbacks.tls_current_timestamp() - session->start_time());
   const bool expired = ticket_age > policy_lifetime;
 
   if(expired) {
      remove(handle);
      return std::nullopt;
   } else {
      return session;
   }
}

References Botan::TLS::Session_Manager::remove(), Botan::TLS::Session_Manager::retrieve_one(), Botan::TLS::Policy::session_ticket_lifetime(), and Botan::TLS::Callbacks::tls_current_timestamp().

retrieve_one()

std::optional< Session > Botan::TLS::Session_Manager_In_Memory::retrieve_one ( const Session_Handle & handle )

overrideprotectedvirtual

Internal retrieval function for a single session.

Try to obtain a Session from a Session_Handle that contains either a session ID or a session ticket. This method should not apply any policy decision (such as ticket expiry) but simply be a storage interface.

Applications that wish to implement their own Session_Manager will have to provide an implementation for it.

This method is called only by servers.

Parameters

handle

a Session_Handle containing either an ID or a ticket

Returns

the obtained session or std::nullopt if none can be obtained

Implements Botan::TLS::Session_Manager.

Definition at line 50 of file tls_session_manager_memory.cpp.

                                                                                         {
   lock_guard_type<recursive_mutex_type> lk(mutex());
 
   if(auto id = handle.id()) {
      const auto session = m_sessions.find(id.value());
      if(session != m_sessions.end()) {
         return session->second.session;
      }
   }
 
   return std::nullopt;
}

References Botan::TLS::Session_Handle::id(), and Botan::TLS::Session_Manager::mutex().

store()

void Botan::TLS::Session_Manager_In_Memory::store ( const Session & session, const Session_Handle & handle )

overridevirtual

Save a Session under a Session_Handle (TLS Client)

Save a session on a best effort basis; the manager may not in fact be able to save the session for whatever reason; this is not an error. Callers cannot assume that calling store() followed immediately by find() will result in a successful lookup.

In contrast to establish(), this stores sessions that were created by the server along with a Session_Handle also coined by the server.

This method is only called on TLS clients.

Parameters

session	to save
handle	a Session_Handle on which this session shoud by stored

Implements Botan::TLS::Session_Manager.

Definition at line 26 of file tls_session_manager_memory.cpp.

                                                                                          {
   // TODO: C++20 allows CTAD for template aliases (read: lock_guard_type), so
   //       technically we should be able to omit the explicit mutex type.
   //       Unfortuately clang does not agree, yet.
   lock_guard_type<recursive_mutex_type> lk(mutex());
 
   if(m_fifo.has_value()) {
      while(m_sessions.size() >= capacity()) {
         BOTAN_ASSERT_NOMSG(m_sessions.size() <= m_fifo->size());
         m_sessions.erase(m_fifo->front());
         m_fifo->pop_front();
      }
   }
 
   // Generate a random session ID if the peer did not provide one. Note that
   // this ID is just for internal use and won't be returned on ::find().
   auto id = handle.id().value_or(m_rng->random_vec<Session_ID>(32));
   m_sessions.emplace(id, Session_with_Handle{session, handle});
 
   if(m_fifo.has_value()) {
      m_fifo->emplace_back(std::move(id));
   }
}

References BOTAN_ASSERT_NOMSG, capacity(), Botan::TLS::Session_Handle::id(), Botan::TLS::Session_Manager::m_rng, and Botan::TLS::Session_Manager::mutex().

Member Data Documentation

m_rng

std::shared_ptr<RandomNumberGenerator> Botan::TLS::Session_Manager::m_rng

protectedinherited

Definition at line 275 of file tls_session_manager.h.

Referenced by Botan::TLS::Session_Manager::establish(), Botan::TLS::Session_Manager_Stateless::establish(), Botan::TLS::Session_Manager::Session_Manager(), store(), and Botan::TLS::Session_Manager_SQL::store().

---

The documentation for this class was generated from the following files:

• src/lib/tls/tls_session_manager_memory.h
• src/lib/tls/tls_session_manager_memory.cpp