Botan::TLS::Session_Handle Class Reference

Helper class to embody a session handle in all protocol versions. More...

#include <tls_session.h>

Public Member Functions
decltype(auto)	get () const
std::optional< Session_ID >	id () const
bool	is_id () const
bool	is_opaque_handle () const
bool	is_ticket () const
Opaque_Session_Handle	opaque_handle () const
	Session_Handle (Opaque_Session_Handle ticket)
	Session_Handle (Session_ID id)
	Session_Handle (Session_Ticket ticket)
std::optional< Session_Ticket >	ticket () const

Detailed Description

Helper class to embody a session handle in all protocol versions.

Sessions in TLS 1.2 are identified by an arbitrary and unique ID of up to 32 bytes or by a self-contained arbitrary-length ticket (RFC 5077).

TLS 1.3 does not distinct between the two and handles both as tickets. Also a TLS 1.3 server can issue multiple tickets in one connection and the resumption mechanism is compatible with the PSK establishment.

Concrete implementations of Session_Manager use this helper to distinguish the different states and manage sessions for TLS 1.2 and 1.3 connections.

Note that all information stored in a Session_Handle might be transmitted in unprotected form. Hence, it should not contain any confidential information.

Definition at line 64 of file tls_session.h.

Constructor & Destructor Documentation

Session_Handle() [1/3]

Botan::TLS::Session_Handle::Session_Handle ( Session_ID id )

inline

Constructs a Session_Handle from a session ID which is an arbitrary byte vector that must be 32 bytes long at most.

Definition at line 70 of file tls_session.h.

: m_handle(std::move(id)) { validate_constraints(); }

Session_Handle() [2/3]

Botan::TLS::Session_Handle::Session_Handle ( Session_Ticket ticket )

inline

Constructs a Session_Handle from a session ticket which is a non-empty byte vector that must be 64kB long at most. Typically, tickets facilitate stateless server implementations and contain all relevant context in encrypted/authenticated form.

Note that (for technical reasons) we enforce that tickets are longer than 32 bytes.

Definition at line 81 of file tls_session.h.

: m_handle(std::move(ticket)) { validate_constraints(); }

Session_Handle() [3/3]

Botan::TLS::Session_Handle::Session_Handle ( Opaque_Session_Handle ticket )

inline

Constructs a Session_Handle from an Opaque_Handle such as TLS 1.3 uses them in its resumption mechanism. This could be either a Session_ID or a Session_Ticket and it is up to the Session_Manager to figure out what it actually is.

Definition at line 89 of file tls_session.h.

: m_handle(std::move(ticket)) { validate_constraints(); }

Member Function Documentation

get()

decltype(auto) Botan::TLS::Session_Handle::get ( ) const

inline

Definition at line 119 of file tls_session.h.

{ return m_handle; }

Referenced by ticket().

id()

std::optional< Session_ID > Botan::TLS::Session_Handle::id

(

)

const

If the Session_Handle was constructed with a Session_ID or an Opaque_Session_Handle that can be converted to a Session_ID (up to 32 bytes long), this returns the handle as a Session_ID. Otherwise, std::nullopt is returned.

Definition at line 57 of file tls_session.cpp.

                                                 {
   if(is_id()) {
      return std::get<Session_ID>(m_handle);
   }
 
   // Opaque handles can mimick as a Session_ID if they are short enough
   if(is_opaque_handle()) {
      const auto& handle = std::get<Opaque_Session_Handle>(m_handle);
      if(handle.size() <= 32) {
         return Session_ID(handle.get());
      }
   }
 
   return std::nullopt;
}

References is_id(), and is_opaque_handle().

Referenced by Botan::TLS::Client_Hello_12::Client_Hello_12(), Botan::TLS::Session_Manager_SQL::remove(), Botan::TLS::Session_Manager_SQL::retrieve_one(), Botan::TLS::Session_Manager_In_Memory::retrieve_one(), Botan::TLS::Session_Manager_SQL::store(), and Botan::TLS::Session_Manager_In_Memory::store().

is_id()

bool Botan::TLS::Session_Handle::is_id ( ) const

inline

Definition at line 91 of file tls_session.h.

{ return std::holds_alternative<Session_ID>(m_handle); }

Referenced by id().

is_opaque_handle()

bool Botan::TLS::Session_Handle::is_opaque_handle ( ) const

inline

Definition at line 95 of file tls_session.h.

{ return std::holds_alternative<Opaque_Session_Handle>(m_handle); }

Referenced by id(), and ticket().

is_ticket()

bool Botan::TLS::Session_Handle::is_ticket ( ) const

inline

Definition at line 93 of file tls_session.h.

{ return std::holds_alternative<Session_Ticket>(m_handle); }

Referenced by Botan::TLS::Client_Hello_12::Client_Hello_12(), and ticket().

opaque_handle()

Opaque_Session_Handle Botan::TLS::Session_Handle::opaque_handle

(

)

const

Returns the Session_Handle as an opaque handle. If the object was not constructed as an Opaque_Session_Handle, the contained value is converted.

Definition at line 52 of file tls_session.cpp.

                                                          {
   // both a Session_ID and a Session_Ticket could be an Opaque_Session_Handle
   return Opaque_Session_Handle(std::visit([](const auto& handle) { return handle.get(); }, m_handle));
}

ticket()

std::optional< Session_Ticket > Botan::TLS::Session_Handle::ticket

(

)

const

If the Session_Handle was constructed with a Session_Ticket or an Opaque_Session_Handle this returns the handle as a Session_ID. Otherwise, std::nullopt is returned.

Definition at line 73 of file tls_session.cpp.

                                                         {
   if(is_ticket()) {
      return std::get<Session_Ticket>(m_handle);
   }
 
   // Opaque handles can mimick 'normal' Session_Tickets at any time
   if(is_opaque_handle()) {
      return Session_Ticket(std::get<Opaque_Session_Handle>(m_handle).get());
   }
 
   return std::nullopt;
}

References get(), is_opaque_handle(), and is_ticket().

Referenced by Botan::TLS::Client_Hello_12::Client_Hello_12(), Botan::TLS::Session_Manager_SQL::remove(), Botan::TLS::Session_Manager_Stateless::retrieve_one(), and Botan::TLS::Session_Manager_SQL::store().

---

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

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