Botan::TLS::PSK Class Reference

#include <tls_extensions.h>

Inheritance diagram for Botan::TLS::PSK:

Public Member Functions
void	calculate_binders (const Transcript_Hash_State &truncated_transcript_hash)
bool	empty () const override
void	filter (const Ciphersuite &cipher)
virtual bool	is_implemented () const
	PSK (std::optional< Session_with_Handle > &session_to_resume, std::vector< ExternalPSK > psks, Callbacks &callbacks)
	PSK (TLS_Data_Reader &reader, uint16_t extension_size, Handshake_Type message_type)
std::unique_ptr< PSK >	select_offered_psk (std::string_view host, const Ciphersuite &cipher, Session_Manager &session_mgr, Credentials_Manager &credentials_mgr, Callbacks &callbacks, const Policy &policy)
std::vector< uint8_t >	serialize (Connection_Side side) const override
std::pair< std::optional< std::string >, std::unique_ptr< Cipher_State > >	take_selected_psk_info (const PSK &server_psk, const Ciphersuite &cipher)
std::variant< Session, ExternalPSK >	take_session_to_resume_or_psk ()
Extension_Code	type () const override
bool	validate_binder (const PSK &server_psk, const std::vector< uint8_t > &binder) const
	~PSK () override

Static Public Member Functions
static Extension_Code	static_type ()

Detailed Description

Pre-Shared Key extension from RFC 8446 4.2.11

Definition at line 661 of file tls_extensions.h.

Constructor & Destructor Documentation

PSK() [1/2]

Botan::TLS::PSK::PSK	(	TLS_Data_Reader &	reader,
		uint16_t	extension_size,
		Handshake_Type	message_type )

Definition at line 142 of file tls_extensions_psk.cpp.

                                                                                      {
   if(message_type == Handshake_Type::ServerHello) {
      if(extension_size != 2) {
         throw TLS_Exception(Alert::DecodeError, "Server provided a malformed PSK extension");
      }
 
      const uint16_t selected_id = reader.get_uint16_t();
      m_impl = std::make_unique<PSK_Internal>(Server_PSK(selected_id));
   } else if(message_type == Handshake_Type::ClientHello) {
      const auto identities_length = reader.get_uint16_t();
      const auto identities_offset = reader.read_so_far();
 
      std::vector<PskIdentity> psk_identities;
      while(reader.has_remaining() && (reader.read_so_far() - identities_offset) < identities_length) {
         auto identity = reader.get_tls_length_value(2);
         const auto obfuscated_ticket_age = reader.get_uint32_t();
         psk_identities.emplace_back(std::move(identity), obfuscated_ticket_age);
      }
 
      if(psk_identities.empty()) {
         throw TLS_Exception(Alert::DecodeError, "Empty PSK list");
      }
 
      if(reader.read_so_far() - identities_offset != identities_length) {
         throw TLS_Exception(Alert::DecodeError, "Inconsistent PSK identity list");
      }
 
      const auto binders_length = reader.get_uint16_t();
      const auto binders_offset = reader.read_so_far();
 
      if(binders_length == 0) {
         throw TLS_Exception(Alert::DecodeError, "Empty PSK binders list");
      }
 
      std::vector<Client_PSK> psks;
      for(auto& psk_identity : psk_identities) {
         if(!reader.has_remaining() || reader.read_so_far() - binders_offset >= binders_length) {
            throw TLS_Exception(Alert::IllegalParameter, "Not enough PSK binders");
         }
 
         psks.emplace_back(std::move(psk_identity), reader.get_tls_length_value(1));
      }
 
      if(reader.read_so_far() - binders_offset != binders_length) {
         throw TLS_Exception(Alert::IllegalParameter, "Too many PSK binders");
      }
 
      m_impl = std::make_unique<PSK_Internal>(std::move(psks));
   } else {
      throw TLS_Exception(Alert::DecodeError, "Found a PSK extension in an unexpected handshake message");
   }
}

References Botan::TLS::ClientHello, Botan::TLS::TLS_Data_Reader::get_tls_length_value(), Botan::TLS::TLS_Data_Reader::get_uint16_t(), Botan::TLS::TLS_Data_Reader::get_uint32_t(), Botan::TLS::TLS_Data_Reader::has_remaining(), Botan::TLS::TLS_Data_Reader::read_so_far(), and Botan::TLS::ServerHello.

PSK() [2/2]

Botan::TLS::PSK::PSK	(	std::optional< Session_with_Handle > &	session_to_resume,
		std::vector< ExternalPSK >	psks,
		Callbacks &	callbacks )

Creates a PSK extension with a TLS 1.3 session object containing a master_secret. Note that it will extract that secret from the session, and won't create a copy of it.

Parameters

session_to_resume	the session to be resumed; note that the master secret will be taken away from the session object.
psks	a list of non-resumption PSKs that should be offered to the server
callbacks	the application's callbacks

Definition at line 195 of file tls_extensions_psk.cpp.

                                                                                                               {
   std::vector<Client_PSK> cpsk;
 
   if(session_to_resume.has_value()) {
      cpsk.emplace_back(session_to_resume.value(), callbacks.tls_current_timestamp());
   }
 
   for(auto&& psk : psks) {
      cpsk.emplace_back(std::move(psk));
   }
 
   m_impl = std::make_unique<PSK_Internal>(std::move(cpsk));
}

References Botan::TLS::Callbacks::tls_current_timestamp().

~PSK()

Botan::TLS::PSK::~PSK ( )

overridedefault

Member Function Documentation

calculate_binders()

void Botan::TLS::PSK::calculate_binders

(

const Transcript_Hash_State &

truncated_transcript_hash

)

Definition at line 413 of file tls_extensions_psk.cpp.

                                                                                  {
   BOTAN_ASSERT_NOMSG(std::holds_alternative<std::vector<Client_PSK>>(m_impl->psk));
   for(auto& psk : std::get<std::vector<Client_PSK>>(m_impl->psk)) {
      auto tth = truncated_transcript_hash.clone();
      const auto& cipher_state = psk.cipher_state();
      tth.set_algorithm(cipher_state.hash_algorithm());
      psk.set_binder(cipher_state.psk_binder_mac(tth.truncated()));
   }
}

References BOTAN_ASSERT_NOMSG, Botan::TLS::Transcript_Hash_State::clone(), and Botan::TLS::Transcript_Hash_State::set_algorithm().

empty()

bool Botan::TLS::PSK::empty ( ) const

overridevirtual

Returns

if we should encode this extension or not

Implements Botan::TLS::Extension.

Definition at line 217 of file tls_extensions_psk.cpp.

                      {
   if(std::holds_alternative<Server_PSK>(m_impl->psk)) {
      return false;
   }
 
   BOTAN_ASSERT_NOMSG(std::holds_alternative<std::vector<Client_PSK>>(m_impl->psk));
   return std::get<std::vector<Client_PSK>>(m_impl->psk).empty();
}

References BOTAN_ASSERT_NOMSG, and empty().

Referenced by empty().

filter()

void Botan::TLS::PSK::filter

(

const Ciphersuite &

cipher

)

Remove PSK identities from the list in m_psk that are not compatible with the passed in cipher suite. This is useful to react to Hello Retry Requests. See RFC 8446 4.1.4.

Definition at line 349 of file tls_extensions_psk.cpp.

                                          {
   BOTAN_STATE_CHECK(std::holds_alternative<std::vector<Client_PSK>>(m_impl->psk));
   auto& psks = std::get<std::vector<Client_PSK>>(m_impl->psk);
 
   const auto r = std::remove_if(psks.begin(), psks.end(), [&](const auto& psk) {
      const auto& cipher_state = psk.cipher_state();
      return !cipher_state.is_compatible_with(cipher);
   });
   psks.erase(r, psks.end());
}

References BOTAN_STATE_CHECK.

is_implemented()

virtual bool Botan::TLS::Extension::is_implemented ( ) const

inlinevirtualinherited

Returns

true if this extension is known and implemented by Botan

Reimplemented in Botan::TLS::Unknown_Extension.

Definition at line 116 of file tls_extensions.h.

{ return true; }

select_offered_psk()

std::unique_ptr< PSK > Botan::TLS::PSK::select_offered_psk	(	std::string_view	host,
		const Ciphersuite &	cipher,
		Session_Manager &	session_mgr,
		Credentials_Manager &	credentials_mgr,
		Callbacks &	callbacks,
		const Policy &	policy )

Selects one of the offered PSKs that is compatible with cipher.

Return values

PSK	extension object that can be added to the Server Hello response
std::nullptr	if no PSK offered by the client is convenient

Definition at line 270 of file tls_extensions_psk.cpp.

                                                                   {
   BOTAN_STATE_CHECK(std::holds_alternative<std::vector<Client_PSK>>(m_impl->psk));
 
   auto& psks = std::get<std::vector<Client_PSK>>(m_impl->psk);
 
   //
   // PSK for Session Resumption
   //
   std::vector<PskIdentity> psk_identities;
   std::transform(
      psks.begin(), psks.end(), std::back_inserter(psk_identities), [&](const auto& psk) { return psk.identity(); });
   if(auto selected_session =
         session_mgr.choose_from_offered_tickets(psk_identities, cipher.prf_algo(), callbacks, policy)) {
      auto& [session, psk_index] = selected_session.value();
 
      // RFC 8446 4.6.1
      //    Any ticket MUST only be resumed with a cipher suite that has the
      //    same KDF hash algorithm as that used to establish the original
      //    connection.
      if(session.ciphersuite().prf_algo() != cipher.prf_algo()) {
         throw TLS_Exception(Alert::InternalError,
                             "Application chose a ticket that is not compatible with the negotiated ciphersuite");
      }
 
      return std::unique_ptr<PSK>(new PSK(std::move(session), psk_index));
   }
 
   //
   // Externally provided PSKs
   //
   std::vector<std::string> psk_ids;
   std::transform(psks.begin(), psks.end(), std::back_inserter(psk_ids), [&](const auto& psk) {
      return psk.identity().identity_as_string();
   });
   if(auto selected_psk =
         credentials_mgr.choose_preshared_key(host, Connection_Side::Server, psk_ids, cipher.prf_algo())) {
      auto& psk = selected_psk.value();
 
      // RFC 8446 4.2.11
      //    Each PSK is associated with a single Hash algorithm. [...]
      //    The server MUST ensure that it selects a compatible PSK (if any)
      //    and cipher suite.
      if(psk.prf_algo() != cipher.prf_algo()) {
         throw TLS_Exception(Alert::InternalError,
                             "Application chose a PSK that is not compatible with the negotiated ciphersuite");
      }
 
      const auto selected_itr =
         std::find_if(psk_identities.begin(), psk_identities.end(), [&](const auto& offered_psk) {
            return offered_psk.identity_as_string() == psk.identity();
         });
      if(selected_itr == psk_identities.end()) {
         throw TLS_Exception(Alert::InternalError,
                             "Application provided a PSK with an identity that was not offered by the client");
      }
 
      // When implementing a server that works with PSKs exclusively, we might
      // want to take TLS::Policy::hide_unknown_users() into account and
      // obfuscate malicious "identity guesses" by generating a random PSK and
      // letting the handshake continue.
      //
      // Currently, we do not have a notion of "a server that solely supports
      // PSK handshakes". However, such applications are free to implement such
      // a mitigation in their override of Credentials_Manager::choose_preshared_key().
      //
      // TODO: Take RFC 8446 Appendix E.6 into account, especially when
      //       implementing PSK_KE (aka. PSK-only mode).
      return std::unique_ptr<PSK>(
         new PSK(std::move(psk), static_cast<uint16_t>(std::distance(psk_identities.begin(), selected_itr))));
   }
 
   return nullptr;
}

References BOTAN_STATE_CHECK, Botan::TLS::Session_Manager::choose_from_offered_tickets(), Botan::Credentials_Manager::choose_preshared_key(), Botan::TLS::Ciphersuite::prf_algo(), Botan::TLS::PSK, and Botan::TLS::Server.

Referenced by Botan::TLS::Server_Hello_13::Server_Hello_13().

serialize()

std::vector< uint8_t > Botan::TLS::PSK::serialize ( Connection_Side whoami ) const

overridevirtual

Returns

serialized binary for the extension

Implements Botan::TLS::Extension.

Definition at line 374 of file tls_extensions_psk.cpp.

                                                            {
   std::vector<uint8_t> result;
 
   std::visit(overloaded{
                 [&](const Server_PSK& psk) {
                    BOTAN_STATE_CHECK(side == Connection_Side::Server);
                    result.reserve(2);
                    const uint16_t id = psk.selected_identity();
                    result.push_back(get_byte<0>(id));
                    result.push_back(get_byte<1>(id));
                 },
                 [&](const std::vector<Client_PSK>& psks) {
                    BOTAN_STATE_CHECK(side == Connection_Side::Client);
 
                    std::vector<uint8_t> identities;
                    std::vector<uint8_t> binders;
                    for(const auto& psk : psks) {
                       const auto& psk_identity = psk.identity();
                       append_tls_length_value(identities, psk_identity.identity(), 2);
 
                       const uint32_t obfuscated_ticket_age = psk_identity.obfuscated_age();
                       identities.push_back(get_byte<0>(obfuscated_ticket_age));
                       identities.push_back(get_byte<1>(obfuscated_ticket_age));
                       identities.push_back(get_byte<2>(obfuscated_ticket_age));
                       identities.push_back(get_byte<3>(obfuscated_ticket_age));
 
                       append_tls_length_value(binders, psk.binder(), 1);
                    }
 
                    append_tls_length_value(result, identities, 2);
                    append_tls_length_value(result, binders, 2);
                 },
              },
              m_impl->psk);
 
   return result;
}

References Botan::TLS::append_tls_length_value(), BOTAN_STATE_CHECK, Botan::TLS::Client, Botan::get_byte(), and Botan::TLS::Server.

static_type()

static Extension_Code Botan::TLS::PSK::static_type ( )

inlinestatic

Definition at line 663 of file tls_extensions.h.

{ return Extension_Code::PresharedKey; }

take_selected_psk_info()

std::pair< std::optional< std::string >, std::unique_ptr< Cipher_State > > Botan::TLS::PSK::take_selected_psk_info	(	const PSK &	server_psk,
		const Ciphersuite &	cipher )

Returns the PSK identity (in case of an externally provided PSK) and the cipher state representing the PSK selected by the server. Note that this destructs the list of offered PSKs and its cipher states and must therefore not be called more than once.

Note

Technically, PSKs used for resumption also carry an identity. Though, typically, this is an opaque value meaningful only to the peer and of no authorative value for the user. We therefore report the identity of externally provided PSKs only.

Definition at line 226 of file tls_extensions_psk.cpp.

                                                     {
   BOTAN_STATE_CHECK(std::holds_alternative<std::vector<Client_PSK>>(m_impl->psk));
   BOTAN_STATE_CHECK(std::holds_alternative<Server_PSK>(server_psk.m_impl->psk));
 
   const auto id = std::get<Server_PSK>(server_psk.m_impl->psk).selected_identity();
   auto& ids = std::get<std::vector<Client_PSK>>(m_impl->psk);
 
   // RFC 8446 4.2.11
   //    Clients MUST verify that the server's selected_identity is within the
   //    range supplied by the client, [...].  If these values are not
   //    consistent, the client MUST abort the handshake with an
   //    "illegal_parameter" alert.
   if(id >= ids.size()) {
      throw TLS_Exception(Alert::IllegalParameter, "PSK identity selected by server is out of bounds");
   }
 
   auto& selected_psk = ids.at(id);
   auto cipher_state = selected_psk.take_cipher_state();
 
   BOTAN_ASSERT_NONNULL(cipher_state);
 
   auto psk_id = [&]() -> std::optional<std::string> {
      if(selected_psk.is_resumption()) {
         return std::nullopt;
      }
      return selected_psk.identity().identity_as_string();
   }();
 
   // destroy cipher states and PSKs that were not selected by the server
   ids.clear();
 
   // RFC 8446 4.2.11
   //    Clients MUST verify that [...] the server selected a cipher suite
   //    indicating a Hash associated with the PSK [...].  If these values
   //    are not consistent, the client MUST abort the handshake with an
   //   "illegal_parameter" alert.
   if(!cipher_state->is_compatible_with(cipher)) {
      throw TLS_Exception(Alert::IllegalParameter, "PSK and ciphersuite selected by server are not compatible");
   }
 
   return {std::move(psk_id), std::move(cipher_state)};
}

References BOTAN_ASSERT_NONNULL, and BOTAN_STATE_CHECK.

take_session_to_resume_or_psk()

std::variant< Session, ExternalPSK > Botan::TLS::PSK::take_session_to_resume_or_psk

(

)

Pulls the preshared key or the Session to resume from a PSK extension in Server Hello.

Definition at line 360 of file tls_extensions_psk.cpp.

                                                                    {
   BOTAN_STATE_CHECK(std::holds_alternative<Server_PSK>(m_impl->psk));
 
   return std::visit(
      [](auto out) -> std::variant<Session, ExternalPSK> {
         if constexpr(std::is_same_v<decltype(out), std::monostate>) {
            throw TLS_Exception(AlertType::InternalError, "cannot extract an empty PSK");
         } else {
            return out;
         }
      },
      std::get<Server_PSK>(m_impl->psk).take_session_to_resume_or_psk());
}

References BOTAN_STATE_CHECK, and Botan::TLS::InternalError.

type()

Extension_Code Botan::TLS::PSK::type ( ) const

inlineoverridevirtual

Returns

code number of the extension

Implements Botan::TLS::Extension.

Definition at line 665 of file tls_extensions.h.

{ return static_type(); }

validate_binder()

bool Botan::TLS::PSK::validate_binder	(	const PSK &	server_psk,
		const std::vector< uint8_t > &	binder ) const

Definition at line 423 of file tls_extensions_psk.cpp.

                                                                                       {
   BOTAN_STATE_CHECK(std::holds_alternative<std::vector<Client_PSK>>(m_impl->psk));
   BOTAN_STATE_CHECK(std::holds_alternative<Server_PSK>(server_psk.m_impl->psk));
 
   const uint16_t index = std::get<Server_PSK>(server_psk.m_impl->psk).selected_identity();
   const auto& psks = std::get<std::vector<Client_PSK>>(m_impl->psk);
 
   BOTAN_STATE_CHECK(index < psks.size());
   return psks[index].binder() == binder;
}

References BOTAN_STATE_CHECK.

---

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

• src/lib/tls/tls_extensions.h
• src/lib/tls/tls13/tls_extensions_psk.cpp