tls_extensions_psk.cpp

Go to the documentation of this file.

/*
* TLS Extension Pre Shared Key
* (C) 2022-2023 Jack Lloyd
*     2022 René Meusel - neXenio GmbH
*     2023 Fabian Albert, René Meusel - Rohde & Schwarz Cybersecurity
*
* Botan is released under the Simplified BSD License (see license.txt)
*/
 
#include <botan/tls_extensions.h>
 
#include <botan/credentials_manager.h>
#include <botan/tls_callbacks.h>
#include <botan/tls_exceptn.h>
#include <botan/tls_session.h>
#include <botan/tls_session_manager.h>
#include <botan/internal/stl_util.h>
#include <botan/internal/tls_cipher_state.h>
#include <botan/internal/tls_reader.h>
 
#include <algorithm>
#include <utility>
 
#if defined(BOTAN_HAS_TLS_13)
 
namespace Botan::TLS {
 
namespace {
 
decltype(auto) calculate_age(std::chrono::system_clock::time_point then, std::chrono::system_clock::time_point now) {
   // TODO: Currently this does not provide actual millisecond resolution.
   //       This might become a problem when "early data" is implemented and we
   //       deal with servers that employ a strict "freshness" criteria on the
   //       ticket's age.
   return std::chrono::duration_cast<std::chrono::milliseconds>(now - then);
}
 
class Client_PSK {
   public:
      Client_PSK(Session_with_Handle& session_to_resume, std::chrono::system_clock::time_point timestamp) :
            Client_PSK(PskIdentity(session_to_resume.handle.opaque_handle(),
                                   calculate_age(session_to_resume.session.start_time(), timestamp),
                                   session_to_resume.session.session_age_add()),
                       session_to_resume.session.ciphersuite().prf_algo(),
                       session_to_resume.session.extract_master_secret(),
                       Cipher_State::PSK_Type::Resumption) {}
 
      // NOLINTNEXTLINE(*-rvalue-reference-param-not-moved)
      Client_PSK(ExternalPSK&& psk) :
            Client_PSK(PskIdentity(PresharedKeyID(psk.identity())),
                       psk.prf_algo(),
                       psk.extract_master_secret(),
                       Cipher_State::PSK_Type::External) {}
 
      Client_PSK(PskIdentity id, std::vector<uint8_t> bndr) :
            m_identity(std::move(id)), m_binder(std::move(bndr)), m_is_resumption(false) {}
 
      Client_PSK(PskIdentity id,
                 std::string_view prf_algo,
                 secure_vector<uint8_t>&& master_secret,
                 Cipher_State::PSK_Type psk_type) :
            m_identity(std::move(id)),
 
            // RFC 8446 4.2.11.2
            //    Each entry in the binders list is computed as an HMAC over a transcript
            //    hash (see Section 4.4.1) containing a partial ClientHello up to and
            //    including the PreSharedKeyExtension.identities field.  That is, it
            //    includes all of the ClientHello but not the binders list itself.  The
            //    length fields for the message (including the overall length, the length
            //    of the extensions block, and the length of the "pre_shared_key"
            //    extension) are all set as if binders of the correct lengths were
            //    present.
            //
            // Hence, we fill the binders with dummy values of the correct length and use
            // `Client_Hello_13::truncate()` to split them off before calculating the
            // transcript hash that underpins the PSK binders. S.a. `calculate_binders()`
            m_binder(HashFunction::create_or_throw(prf_algo)->output_length()),
            m_is_resumption(psk_type == Cipher_State::PSK_Type::Resumption),
            m_cipher_state(
               Cipher_State::init_with_psk(Connection_Side::Client, psk_type, std::move(master_secret), prf_algo)) {}
 
      const PskIdentity& identity() const { return m_identity; }
 
      const std::vector<uint8_t>& binder() const { return m_binder; }
 
      bool is_resumption() const { return m_is_resumption; }
 
      void set_binder(std::vector<uint8_t> binder) { m_binder = std::move(binder); }
 
      const Cipher_State& cipher_state() const {
         BOTAN_ASSERT_NONNULL(m_cipher_state);
         return *m_cipher_state;
      }
 
      std::unique_ptr<Cipher_State> take_cipher_state() { return std::exchange(m_cipher_state, nullptr); }
 
   private:
      PskIdentity m_identity;
      std::vector<uint8_t> m_binder;
      bool m_is_resumption;
 
      // Clients set up associated cipher states for PSKs
      // Servers leave this as nullptr
      std::unique_ptr<Cipher_State> m_cipher_state;
};
 
class Server_PSK {
   public:
      Server_PSK(uint16_t id) : m_selected_identity(id), m_session_to_resume_or_psk(std::monostate()) {}
 
      Server_PSK(uint16_t id, Session session) :
            m_selected_identity(id), m_session_to_resume_or_psk(std::move(session)) {}
 
      Server_PSK(uint16_t id, ExternalPSK psk) : m_selected_identity(id), m_session_to_resume_or_psk(std::move(psk)) {}
 
      uint16_t selected_identity() const { return m_selected_identity; }
 
      std::variant<std::monostate, Session, ExternalPSK> take_session_to_resume_or_psk() {
         BOTAN_STATE_CHECK(!std::holds_alternative<std::monostate>(m_session_to_resume_or_psk));
         return std::exchange(m_session_to_resume_or_psk, std::monostate());
      }
 
   private:
      uint16_t m_selected_identity;
 
      // Servers store the Session to resume or the PSK of their selection
      std::variant<std::monostate, Session, ExternalPSK> m_session_to_resume_or_psk;
};
 
}  // namespace
 
class PSK::PSK_Internal {
   public:
      PSK_Internal(Server_PSK srv_psk) : psk(std::move(srv_psk)) {}
 
      PSK_Internal(std::vector<Client_PSK> clt_psks) : psk(std::move(clt_psks)) {}
 
      // NOLINTNEXTLINE(*-non-private-member-variables-in-classes)
      std::variant<std::vector<Client_PSK>, Server_PSK> psk;
};
 
PSK::PSK(TLS_Data_Reader& reader, uint16_t extension_size, Handshake_Type message_type) {
   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");
   }
}
 
PSK::PSK(std::optional<Session_with_Handle>& session_to_resume, std::vector<ExternalPSK> psks, Callbacks& callbacks) {
   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));
}
 
PSK::PSK(Session session_to_resume, const uint16_t psk_index) :
      m_impl(std::make_unique<PSK_Internal>(Server_PSK(psk_index, std::move(session_to_resume)))) {}
 
PSK::PSK(ExternalPSK psk, const uint16_t psk_index) :
      m_impl(std::make_unique<PSK_Internal>(Server_PSK(psk_index, std::move(psk)))) {}
 
PSK::~PSK() = default;
 
bool PSK::empty() const {
   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();
}
 
std::pair<std::optional<std::string>, std::unique_ptr<Cipher_State>> PSK::take_selected_psk_info(
   const PSK& server_psk, const Ciphersuite& cipher) {
   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)};
}
 
std::unique_ptr<PSK> PSK::select_offered_psk(std::string_view host,
                                             const Ciphersuite& cipher,
                                             Session_Manager& session_mgr,
                                             Credentials_Manager& credentials_mgr,
                                             Callbacks& callbacks,
                                             const Policy& policy) {
   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;
}
 
void PSK::filter(const Ciphersuite& cipher) {
   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());
}
 
std::variant<Session, ExternalPSK> PSK::take_session_to_resume_or_psk() {
   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());
}
 
std::vector<uint8_t> PSK::serialize(Connection_Side side) const {
   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;
}
 
// See RFC 8446 4.2.11.2 for details on how these binders are calculated
void PSK::calculate_binders(const Transcript_Hash_State& truncated_transcript_hash) {
   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()));
   }
}
 
bool PSK::validate_binder(const PSK& server_psk, const std::vector<uint8_t>& binder) const {
   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;
}
 
}  // namespace Botan::TLS
 
#endif  // HAS_TLS_13