Botan::TLS::Server_Key_Exchange Class Reference

#include <tls_messages.h>

Inheritance diagram for Botan::TLS::Server_Key_Exchange:

Public Member Functions
const std::vector< uint8_t > &	params () const
const PK_Key_Agreement_Key &	server_kex_key () const
	Server_Key_Exchange (const std::vector< uint8_t > &buf, Kex_Algo kex_alg, Auth_Method sig_alg, Protocol_Version version)
	Server_Key_Exchange (Handshake_IO &io, Handshake_State &state, const Policy &policy, Credentials_Manager &creds, RandomNumberGenerator &rng, const Private_Key *signing_key=nullptr)
const std::optional< Group_Params > &	shared_group () const
Handshake_Type	type () const override
std::string	type_string () const
bool	verify (const Public_Key &server_key, const Handshake_State &state, const Policy &policy) const
virtual Handshake_Type	wire_type () const

Detailed Description

Server Key Exchange Message

Definition at line 881 of file tls_messages.h.

Constructor & Destructor Documentation

Server_Key_Exchange() [1/2]

Botan::TLS::Server_Key_Exchange::Server_Key_Exchange	(	Handshake_IO &	io,
		Handshake_State &	state,
		const Policy &	policy,
		Credentials_Manager &	creds,
		RandomNumberGenerator &	rng,
		const Private_Key *	signing_key = nullptr )

Create a new Server Key Exchange message

Definition at line 28 of file msg_server_kex.cpp.

                                                                         {
   const std::string hostname = state.client_hello()->sni_hostname();
   const Kex_Algo kex_algo = state.ciphersuite().kex_method();
 
   if(kex_algo == Kex_Algo::PSK || kex_algo == Kex_Algo::ECDHE_PSK) {
      std::string identity_hint = creds.psk_identity_hint("tls-server", hostname);
 
      append_tls_length_value(m_params, identity_hint, 2);
   }
 
   if(kex_algo == Kex_Algo::DH) {
      const std::vector<Group_Params> dh_groups = state.client_hello()->supported_dh_groups();
 
      m_shared_group = Group_Params::NONE;
 
      /*
      RFC 7919 requires that if the client sends any groups in the FFDHE
      range, that we must select one of these. If this is not possible,
      then we are required to reject the connection.
 
      If the client did not send any DH groups, but did offer DH ciphersuites
      and we selected one, then consult the policy for which DH group to pick.
      */
 
      if(dh_groups.empty()) {
         m_shared_group = policy.default_dh_group();
      } else {
         m_shared_group = policy.choose_key_exchange_group(dh_groups, {});
      }
 
      if(m_shared_group.value() == Group_Params::NONE) {
         throw TLS_Exception(Alert::HandshakeFailure, "Could not agree on a DH group with the client");
      }
 
      // The policy had better return a group we know about:
      BOTAN_ASSERT(m_shared_group.value().is_dh_named_group(), "DH ciphersuite is using a known finite field group");
 
      // Note: TLS 1.2 allows defining and using arbitrary DH groups (additional
      //       to the named and standardized ones). This API doesn't allow the
      //       server to make use of that at the moment. TLS 1.3 does not
      //       provide this flexibility!
      //
      // A possible implementation strategy in case one would ever need that:
      // `Policy::default_dh_group()` could return a `std::variant<Group_Params,
      // DL_Group>`, allowing it to define arbitrary groups.
      m_kex_key = state.callbacks().tls_generate_ephemeral_key(m_shared_group.value(), rng);
      auto* dh = dynamic_cast<DH_PrivateKey*>(m_kex_key.get());
      if(dh == nullptr) {
         throw TLS_Exception(Alert::InternalError, "Application did not provide a Diffie-Hellman key");
      }
 
      append_tls_length_value(m_params, dh->get_int_field("p").serialize(), 2);
      append_tls_length_value(m_params, dh->get_int_field("g").serialize(), 2);
      append_tls_length_value(m_params, dh->public_value(), 2);
   } else if(kex_algo == Kex_Algo::ECDH || kex_algo == Kex_Algo::ECDHE_PSK) {
      const std::vector<Group_Params> ec_groups = state.client_hello()->supported_ecc_curves();
 
      if(ec_groups.empty()) {
         throw Internal_Error("Client sent no ECC extension but we negotiated ECDH");
      }
 
      m_shared_group = policy.choose_key_exchange_group(ec_groups, {});
 
      if(m_shared_group.value() == Group_Params::NONE) {
         throw TLS_Exception(Alert::HandshakeFailure, "No shared ECC group with client");
      }
 
      std::vector<uint8_t> ecdh_public_val;
 
      if(m_shared_group.value() == Group_Params::X25519 || m_shared_group.value() == Group_Params::X448) {
         m_kex_key = state.callbacks().tls_generate_ephemeral_key(m_shared_group.value(), rng);
         if(!m_kex_key) {
            throw TLS_Exception(Alert::InternalError, "Application did not provide an EC key");
         }
         ecdh_public_val = m_kex_key->public_value();
      } else {
         m_kex_key = state.callbacks().tls_generate_ephemeral_key(m_shared_group.value(), rng);
         auto* ecdh = dynamic_cast<ECDH_PrivateKey*>(m_kex_key.get());
         if(ecdh == nullptr) {
            throw TLS_Exception(Alert::InternalError, "Application did not provide a EC-Diffie-Hellman key");
         }
 
         // follow client's preference for point compression
         ecdh_public_val =
            ecdh->public_value(state.client_hello()->prefers_compressed_ec_points() ? EC_Point_Format::Compressed
                                                                                    : EC_Point_Format::Uncompressed);
      }
 
      const uint16_t named_curve_id = m_shared_group.value().wire_code();
      m_params.push_back(3);  // named curve
      m_params.push_back(get_byte<0>(named_curve_id));
      m_params.push_back(get_byte<1>(named_curve_id));
 
      append_tls_length_value(m_params, ecdh_public_val, 1);
   } else if(kex_algo != Kex_Algo::PSK) {
      throw Internal_Error("Server_Key_Exchange: Unknown kex type " + kex_method_to_string(kex_algo));
   }
 
   if(state.ciphersuite().signature_used()) {
      BOTAN_ASSERT(signing_key, "Signing key was set");
 
      std::pair<std::string, Signature_Format> format = state.choose_sig_format(*signing_key, m_scheme, false, policy);
 
      std::vector<uint8_t> buf = state.client_hello()->random();
 
      buf += state.server_hello()->random();
      buf += params();
 
      m_signature = state.callbacks().tls_sign_message(*signing_key, rng, format.first, format.second, buf);
   }
 
   state.hash().update(io.send(*this));
}

References Botan::TLS::append_tls_length_value(), BOTAN_ASSERT, Botan::TLS::Handshake_State::callbacks(), Botan::TLS::Policy::choose_key_exchange_group(), Botan::TLS::Handshake_State::choose_sig_format(), Botan::TLS::Handshake_State::ciphersuite(), Botan::TLS::Handshake_State::client_hello(), Botan::Compressed, Botan::TLS::Policy::default_dh_group(), Botan::TLS::DH, Botan::TLS::ECDH, Botan::TLS::ECDHE_PSK, Botan::get_byte(), Botan::TLS::Handshake_State::hash(), Botan::TLS::Ciphersuite::kex_method(), Botan::TLS::kex_method_to_string(), params(), Botan::TLS::PSK, Botan::Credentials_Manager::psk_identity_hint(), Botan::ECDH_PrivateKey::public_value(), Botan::TLS::Handshake_IO::send(), Botan::TLS::Handshake_State::server_hello(), Botan::TLS::Ciphersuite::signature_used(), Botan::TLS::Callbacks::tls_generate_ephemeral_key(), Botan::TLS::Callbacks::tls_sign_message(), Botan::Uncompressed, Botan::TLS::Handshake_Hash::update(), and Botan::TLS::Group_Params::wire_code().

Server_Key_Exchange() [2/2]

Botan::TLS::Server_Key_Exchange::Server_Key_Exchange	(	const std::vector< uint8_t > &	buf,
		Kex_Algo	kex_alg,
		Auth_Method	sig_alg,
		Protocol_Version	version )

Deserialize a Server Key Exchange message

Definition at line 150 of file msg_server_kex.cpp.

                                                                   {
   BOTAN_UNUSED(version);  // remove this
   TLS_Data_Reader reader("ServerKeyExchange", buf);
 
   /*
   * Here we are deserializing enough to find out what offset the
   * signature is at. All processing is done when the Client Key Exchange
   * is prepared.
   */
 
   if(kex_algo == Kex_Algo::PSK || kex_algo == Kex_Algo::ECDHE_PSK) {
      reader.get_string(2, 0, 65535);  // identity hint
   }
 
   if(kex_algo == Kex_Algo::DH) {
      // 3 bigints, DH p, g, Y
 
      for(size_t i = 0; i != 3; ++i) {
         reader.get_range<uint8_t>(2, 1, 65535);
      }
   } else if(kex_algo == Kex_Algo::ECDH || kex_algo == Kex_Algo::ECDHE_PSK) {
      reader.get_byte();                     // curve type
      reader.get_uint16_t();                 // curve id
      reader.get_range<uint8_t>(1, 1, 255);  // public key
   } else if(kex_algo != Kex_Algo::PSK) {
      throw Decoding_Error("Server_Key_Exchange: Unsupported kex type " + kex_method_to_string(kex_algo));
   }
 
   m_params.assign(buf.data(), buf.data() + reader.read_so_far());
 
   if(auth_method != Auth_Method::IMPLICIT) {
      m_scheme = Signature_Scheme(reader.get_uint16_t());
      m_signature = reader.get_range<uint8_t>(2, 0, 65535);
   }
 
   reader.assert_done();
}

References Botan::TLS::TLS_Data_Reader::assert_done(), BOTAN_UNUSED, Botan::TLS::DH, Botan::TLS::ECDH, Botan::TLS::ECDHE_PSK, Botan::TLS::TLS_Data_Reader::get_byte(), Botan::TLS::TLS_Data_Reader::get_range(), Botan::TLS::TLS_Data_Reader::get_string(), Botan::TLS::TLS_Data_Reader::get_uint16_t(), Botan::TLS::IMPLICIT, Botan::TLS::kex_method_to_string(), Botan::TLS::PSK, and Botan::TLS::TLS_Data_Reader::read_so_far().

Member Function Documentation

params()

const std::vector< uint8_t > & Botan::TLS::Server_Key_Exchange::params ( ) const

inline

Definition at line 885 of file tls_messages.h.

{ return m_params; }

Referenced by Server_Key_Exchange(), and verify().

server_kex_key()

const PK_Key_Agreement_Key & Botan::TLS::Server_Key_Exchange::server_kex_key

(

)

const

Definition at line 236 of file msg_server_kex.cpp.

                                                                      {
   BOTAN_ASSERT_NONNULL(m_kex_key);
   return *m_kex_key;
}

References BOTAN_ASSERT_NONNULL.

shared_group()

const std::optional< Group_Params > & Botan::TLS::Server_Key_Exchange::shared_group ( ) const

inline

Returns

the agreed upon KEX group or std::nullopt if the KEX type does not depend on a group

Definition at line 896 of file tls_messages.h.

{ return m_shared_group; }

type()

Handshake_Type Botan::TLS::Server_Key_Exchange::type ( ) const

inlineoverridevirtual

Returns

the message type

Implements Botan::TLS::Handshake_Message.

Definition at line 883 of file tls_messages.h.

{ return Handshake_Type::ServerKeyExchange; }

References Botan::TLS::ServerKeyExchange.

type_string()

std::string Botan::TLS::Handshake_Message::type_string ( ) const

inherited

Returns

string representation of this message type

Definition at line 19 of file tls_handshake_state.cpp.

                                               {
   return handshake_type_to_string(type());
}

References Botan::TLS::handshake_type_to_string(), and type().

verify()

bool Botan::TLS::Server_Key_Exchange::verify	(	const Public_Key &	server_key,
		const Handshake_State &	state,
		const Policy &	policy ) const

Verify a Server Key Exchange message

Definition at line 212 of file msg_server_kex.cpp.

                                                             {
   policy.check_peer_key_acceptable(server_key);
 
   std::pair<std::string, Signature_Format> format =
      state.parse_sig_format(server_key, m_scheme, state.client_hello()->signature_schemes(), false, policy);
 
   std::vector<uint8_t> buf = state.client_hello()->random();
 
   buf += state.server_hello()->random();
   buf += params();
 
   const bool signature_valid =
      state.callbacks().tls_verify_message(server_key, format.first, format.second, buf, m_signature);
 
#if defined(BOTAN_UNSAFE_FUZZER_MODE)
   BOTAN_UNUSED(signature_valid);
   return true;
#else
   return signature_valid;
#endif
}

References BOTAN_UNUSED, Botan::TLS::Handshake_State::callbacks(), Botan::TLS::Policy::check_peer_key_acceptable(), Botan::TLS::Handshake_State::client_hello(), params(), Botan::TLS::Handshake_State::parse_sig_format(), Botan::TLS::Handshake_State::server_hello(), and Botan::TLS::Callbacks::tls_verify_message().

wire_type()

virtual Handshake_Type Botan::TLS::Handshake_Message::wire_type ( ) const

inlinevirtualinherited

Returns

the wire representation of the message's type

Reimplemented in Botan::TLS::Hello_Retry_Request.

Definition at line 39 of file tls_handshake_msg.h.

                                               {
         // Usually equal to the Handshake_Type enum value,
         // with the exception of TLS 1.3 Hello Retry Request.
         return type();
      }

References type().

Referenced by Botan::TLS::Stream_Handshake_IO::send().

---

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

• src/lib/tls/tls_messages.h
• src/lib/tls/tls12/msg_server_kex.cpp