Botan 3.9.0
Crypto and TLS for C&
Botan::TLS::Client_Key_Exchange Class Referencefinal

#include <tls_messages.h>

Inheritance diagram for Botan::TLS::Client_Key_Exchange:
Botan::TLS::Handshake_Message

Public Member Functions

 Client_Key_Exchange (const std::vector< uint8_t > &buf, const Handshake_State &state, const Private_Key *server_rsa_kex_key, Credentials_Manager &creds, const Policy &policy, RandomNumberGenerator &rng)
 Client_Key_Exchange (Handshake_IO &io, Handshake_State &state, const Policy &policy, Credentials_Manager &creds, const Public_Key *server_public_key, std::string_view hostname, RandomNumberGenerator &rng)
const secure_vector< uint8_t > & pre_master_secret () const
const std::optional< std::string > & psk_identity () const
Handshake_Type type () const override
std::string type_string () const
virtual Handshake_Type wire_type () const

Detailed Description

Client Key Exchange Message

Definition at line 485 of file tls_messages.h.

Constructor & Destructor Documentation

◆ Client_Key_Exchange() [1/2]

Botan::TLS::Client_Key_Exchange::Client_Key_Exchange ( Handshake_IO & io,
Handshake_State & state,
const Policy & policy,
Credentials_Manager & creds,
const Public_Key * server_public_key,
std::string_view hostname,
RandomNumberGenerator & rng )

Definition at line 27 of file msg_client_kex.cpp.

33 {
34 const Kex_Algo kex_algo = state.ciphersuite().kex_method();
35
36 if(kex_algo == Kex_Algo::PSK) {
37 std::string identity_hint;
38
39 if(state.server_kex() != nullptr) {
40 TLS_Data_Reader reader("ClientKeyExchange", state.server_kex()->params());
41 identity_hint = reader.get_string(2, 0, 65535);
42 }
43
44 m_psk_identity = creds.psk_identity("tls-client", std::string(hostname), identity_hint);
45
46 append_tls_length_value(m_key_material, as_span_of_bytes(m_psk_identity.value()), 2);
47
48 SymmetricKey psk = creds.psk("tls-client", std::string(hostname), m_psk_identity.value());
49
50 std::vector<uint8_t> zeros(psk.length());
51
52 append_tls_length_value(m_pre_master, zeros, 2);
53 append_tls_length_value(m_pre_master, psk.bits_of(), 2);
54 } else if(state.server_kex() != nullptr) {
55 TLS_Data_Reader reader("ClientKeyExchange", state.server_kex()->params());
56
57 SymmetricKey psk;
58
59 if(kex_algo == Kex_Algo::ECDHE_PSK) {
60 std::string identity_hint = reader.get_string(2, 0, 65535);
61
62 m_psk_identity = creds.psk_identity("tls-client", std::string(hostname), identity_hint);
63
64 append_tls_length_value(m_key_material, as_span_of_bytes(m_psk_identity.value()), 2);
65
66 psk = creds.psk("tls-client", std::string(hostname), m_psk_identity.value());
67 }
68
69 if(kex_algo == Kex_Algo::DH) {
70 const auto modulus = BigInt::from_bytes(reader.get_range<uint8_t>(2, 1, 65535));
71 const auto generator = BigInt::from_bytes(reader.get_range<uint8_t>(2, 1, 65535));
72 const std::vector<uint8_t> peer_public_value = reader.get_range<uint8_t>(2, 1, 65535);
73
74 if(reader.remaining_bytes() > 0) {
75 throw Decoding_Error("Bad params size for DH key exchange");
76 }
77
78 DL_Group group(modulus, generator);
79
80 if(!group.verify_group(rng, false)) {
81 throw TLS_Exception(Alert::InsufficientSecurity, "DH group validation failed");
82 }
83
84 const auto private_key = state.callbacks().tls_generate_ephemeral_key(group, rng);
85 m_pre_master = CT::strip_leading_zeros(
86 state.callbacks().tls_ephemeral_key_agreement(group, *private_key, peer_public_value, rng, policy));
87 append_tls_length_value(m_key_material, private_key->public_value(), 2);
88 } else if(kex_algo == Kex_Algo::ECDH || kex_algo == Kex_Algo::ECDHE_PSK) {
89 const uint8_t curve_type = reader.get_byte();
90 if(curve_type != 3) {
91 throw Decoding_Error("Server sent non-named ECC curve");
92 }
93
94 const Group_Params curve_id = static_cast<Group_Params>(reader.get_uint16_t());
95 const std::vector<uint8_t> peer_public_value = reader.get_range<uint8_t>(1, 1, 255);
96
97 if(!curve_id.is_ecdh_named_curve() && !curve_id.is_x25519() && !curve_id.is_x448()) {
98 throw TLS_Exception(Alert::IllegalParameter,
99 "Server selected a group that is not compatible with the negotiated ciphersuite");
100 }
101
102 if(policy.choose_key_exchange_group({curve_id}, {}) != curve_id) {
103 throw TLS_Exception(Alert::HandshakeFailure, "Server sent ECC curve prohibited by policy");
104 }
105
106 const auto private_key = state.callbacks().tls_generate_ephemeral_key(curve_id, rng);
107 auto shared_secret =
108 state.callbacks().tls_ephemeral_key_agreement(curve_id, *private_key, peer_public_value, rng, policy);
109
110 if(kex_algo == Kex_Algo::ECDH) {
111 m_pre_master = std::move(shared_secret);
112 } else {
113 append_tls_length_value(m_pre_master, shared_secret, 2);
114 append_tls_length_value(m_pre_master, psk.bits_of(), 2);
115 }
116
117 if(curve_id.is_ecdh_named_curve()) {
118 auto* ecdh_key = dynamic_cast<ECDH_PublicKey*>(private_key.get());
119 if(ecdh_key == nullptr) {
120 throw TLS_Exception(Alert::InternalError, "Application did not provide a ECDH_PublicKey");
121 }
122 append_tls_length_value(m_key_material,
123 ecdh_key->public_value(state.server_hello()->prefers_compressed_ec_points()
126 1);
127 } else {
128 append_tls_length_value(m_key_material, private_key->public_value(), 1);
129 }
130 } else {
131 throw Internal_Error("Client_Key_Exchange: Unknown key exchange method was negotiated");
132 }
133
134 reader.assert_done();
135 } else {
136 // No server key exchange msg better mean RSA kex + RSA key in cert
137
138 if(kex_algo != Kex_Algo::STATIC_RSA) {
139 throw Unexpected_Message("No server kex message, but negotiated a key exchange that required it");
140 }
141
142 if(server_public_key == nullptr) {
143 throw Internal_Error("No server public key for RSA exchange");
144 }
145
146 if(const auto* rsa_pub = dynamic_cast<const RSA_PublicKey*>(server_public_key)) {
147 const Protocol_Version offered_version = state.client_hello()->legacy_version();
148
149 rng.random_vec(m_pre_master, 48);
150 m_pre_master[0] = offered_version.major_version();
151 m_pre_master[1] = offered_version.minor_version();
152
153 PK_Encryptor_EME encryptor(*rsa_pub, rng, "PKCS1v15");
154
155 const std::vector<uint8_t> encrypted_key = encryptor.encrypt(m_pre_master, rng);
156
157 append_tls_length_value(m_key_material, encrypted_key, 2);
158 } else {
159 throw TLS_Exception(Alert::HandshakeFailure,
160 "Expected a RSA key in server cert but got " + server_public_key->algo_name());
161 }
162 }
163
164 state.hash().update(io.send(*this));
165}
static BigInt from_bytes(std::span< const uint8_t > bytes)
Definition bigint.cpp:87
secure_vector< uint8_t > strip_leading_zeros(std::span< const uint8_t > input)
Definition ct_utils.cpp:94
void append_tls_length_value(std::vector< uint8_t, Alloc > &buf, const T *vals, size_t vals_size, size_t tag_size)
Definition tls_reader.h:184
OctetString SymmetricKey
Definition symkey.h:140
std::span< const uint8_t > as_span_of_bytes(const char *s, size_t len)
Definition mem_utils.h:28

References Botan::Asymmetric_Key::algo_name(), Botan::TLS::append_tls_length_value(), Botan::as_span_of_bytes(), Botan::TLS::TLS_Data_Reader::assert_done(), Botan::OctetString::bits_of(), Botan::TLS::Handshake_State::callbacks(), Botan::TLS::Policy::choose_key_exchange_group(), Botan::TLS::Handshake_State::ciphersuite(), Botan::TLS::Handshake_State::client_hello(), Botan::Compressed, Botan::TLS::DH, Botan::TLS::ECDH, Botan::TLS::ECDHE_PSK, Botan::PK_Encryptor::encrypt(), Botan::BigInt::from_bytes(), 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::Handshake_State::hash(), Botan::TLS::Group_Params::is_ecdh_named_curve(), Botan::TLS::Group_Params::is_x25519(), Botan::TLS::Group_Params::is_x448(), Botan::TLS::Ciphersuite::kex_method(), Botan::OctetString::length(), Botan::TLS::Protocol_Version::major_version(), Botan::TLS::Protocol_Version::minor_version(), Botan::TLS::PSK, Botan::Credentials_Manager::psk(), Botan::Credentials_Manager::psk_identity(), Botan::RandomNumberGenerator::random_vec(), Botan::TLS::TLS_Data_Reader::remaining_bytes(), Botan::TLS::Handshake_IO::send(), Botan::TLS::Handshake_State::server_hello(), Botan::TLS::Handshake_State::server_kex(), Botan::TLS::STATIC_RSA, Botan::CT::strip_leading_zeros(), Botan::TLS::Callbacks::tls_ephemeral_key_agreement(), Botan::TLS::Callbacks::tls_generate_ephemeral_key(), Botan::Uncompressed, Botan::TLS::Handshake_Hash::update(), and Botan::DL_Group::verify_group().

◆ Client_Key_Exchange() [2/2]

Botan::TLS::Client_Key_Exchange::Client_Key_Exchange ( const std::vector< uint8_t > & buf,
const Handshake_State & state,
const Private_Key * server_rsa_kex_key,
Credentials_Manager & creds,
const Policy & policy,
RandomNumberGenerator & rng )

Definition at line 170 of file msg_client_kex.cpp.

175 {
176 const Kex_Algo kex_algo = state.ciphersuite().kex_method();
177
178 if(kex_algo == Kex_Algo::STATIC_RSA) {
179 BOTAN_ASSERT(state.server_certs() && !state.server_certs()->cert_chain().empty(),
180 "RSA key exchange negotiated so server sent a certificate");
181
182 if(server_rsa_kex_key == nullptr) {
183 throw Internal_Error("Expected RSA kex but no server kex key set");
184 }
185
186 if(server_rsa_kex_key->algo_name() != "RSA") {
187 throw Internal_Error("Expected RSA key but got " + server_rsa_kex_key->algo_name());
188 }
189
190 TLS_Data_Reader reader("ClientKeyExchange", contents);
191 const std::vector<uint8_t> encrypted_pre_master = reader.get_range<uint8_t>(2, 0, 65535);
192 reader.assert_done();
193
194 PK_Decryptor_EME decryptor(*server_rsa_kex_key, rng, "PKCS1v15");
195
196 const uint8_t client_major = state.client_hello()->legacy_version().major_version();
197 const uint8_t client_minor = state.client_hello()->legacy_version().minor_version();
198
199 /*
200 * PK_Decryptor::decrypt_or_random will return a random value if
201 * either the length does not match the expected value or if the
202 * version number embedded in the PMS does not match the one sent
203 * in the client hello.
204 */
205 const size_t expected_plaintext_size = 48;
206 const size_t expected_content_size = 2;
207 const uint8_t expected_content_bytes[expected_content_size] = {client_major, client_minor};
208 const uint8_t expected_content_pos[expected_content_size] = {0, 1};
209
210 m_pre_master = decryptor.decrypt_or_random(encrypted_pre_master.data(),
211 encrypted_pre_master.size(),
212 expected_plaintext_size,
213 rng,
214 expected_content_bytes,
215 expected_content_pos,
216 expected_content_size);
217 } else {
218 TLS_Data_Reader reader("ClientKeyExchange", contents);
219
220 SymmetricKey psk;
221
222 if(key_exchange_is_psk(kex_algo)) {
223 m_psk_identity = reader.get_string(2, 0, 65535);
224
225 psk = creds.psk("tls-server", state.client_hello()->sni_hostname(), m_psk_identity.value());
226
227 if(psk.empty()) {
228 if(policy.hide_unknown_users()) {
229 psk = SymmetricKey(rng, 16);
230 } else {
231 throw TLS_Exception(Alert::UnknownPSKIdentity, "No PSK for identifier " + m_psk_identity.value());
232 }
233 }
234 }
235
236 if(kex_algo == Kex_Algo::PSK) {
237 std::vector<uint8_t> zeros(psk.length());
238 append_tls_length_value(m_pre_master, zeros, 2);
239 append_tls_length_value(m_pre_master, psk.bits_of(), 2);
240 } else if(kex_algo == Kex_Algo::DH || kex_algo == Kex_Algo::ECDH || kex_algo == Kex_Algo::ECDHE_PSK) {
241 const PK_Key_Agreement_Key& ka_key = state.server_kex()->server_kex_key();
242
243 const std::vector<uint8_t> client_pubkey = (ka_key.algo_name() == "DH")
244 ? reader.get_range<uint8_t>(2, 0, 65535)
245 : reader.get_range<uint8_t>(1, 1, 255);
246
247 const auto shared_group = state.server_kex()->shared_group();
248 BOTAN_STATE_CHECK(shared_group && shared_group.value() != Group_Params::NONE);
249
250 try {
251 auto shared_secret =
252 state.callbacks().tls_ephemeral_key_agreement(shared_group.value(), ka_key, client_pubkey, rng, policy);
253
254 if(ka_key.algo_name() == "DH") {
255 shared_secret = CT::strip_leading_zeros(shared_secret);
256 }
257
258 if(kex_algo == Kex_Algo::ECDHE_PSK) {
259 append_tls_length_value(m_pre_master, shared_secret, 2);
260 append_tls_length_value(m_pre_master, psk.bits_of(), 2);
261 } else {
262 m_pre_master = shared_secret;
263 }
264 } catch(Invalid_Argument& e) {
265 throw TLS_Exception(Alert::IllegalParameter, e.what());
266 } catch(TLS_Exception& e) {
267 // NOLINTNEXTLINE(cert-err60-cpp)
268 throw e;
269 } catch(std::exception&) {
270 /*
271 * Something failed in the DH/ECDH computation. To avoid possible
272 * attacks which are based on triggering and detecting some edge
273 * failure condition, randomize the pre-master output and carry on,
274 * allowing the protocol to fail later in the finished checks.
275 */
276 rng.random_vec(m_pre_master, ka_key.public_value().size());
277 }
278
279 reader.assert_done();
280 } else {
281 throw Internal_Error("Client_Key_Exchange: Unknown key exchange negotiated");
282 }
283 }
284}
#define BOTAN_STATE_CHECK(expr)
Definition assert.h:49
#define BOTAN_ASSERT(expr, assertion_made)
Definition assert.h:62
bool key_exchange_is_psk(Kex_Algo m)
Definition tls_algos.h:277

References Botan::Asymmetric_Key::algo_name(), Botan::TLS::append_tls_length_value(), Botan::TLS::TLS_Data_Reader::assert_done(), Botan::OctetString::bits_of(), BOTAN_ASSERT, BOTAN_STATE_CHECK, Botan::TLS::Handshake_State::callbacks(), Botan::TLS::Handshake_State::ciphersuite(), Botan::TLS::Handshake_State::client_hello(), Botan::PK_Decryptor::decrypt_or_random(), Botan::TLS::DH, Botan::TLS::ECDH, Botan::TLS::ECDHE_PSK, Botan::OctetString::empty(), Botan::TLS::TLS_Data_Reader::get_range(), Botan::TLS::TLS_Data_Reader::get_string(), Botan::TLS::Policy::hide_unknown_users(), Botan::TLS::Ciphersuite::kex_method(), Botan::TLS::key_exchange_is_psk(), Botan::OctetString::length(), Botan::TLS::PSK, Botan::Credentials_Manager::psk(), Botan::PK_Key_Agreement_Key::public_value(), Botan::RandomNumberGenerator::random_vec(), Botan::TLS::Handshake_State::server_certs(), Botan::TLS::Handshake_State::server_kex(), Botan::TLS::STATIC_RSA, Botan::CT::strip_leading_zeros(), Botan::TLS::Callbacks::tls_ephemeral_key_agreement(), and Botan::Exception::what().

Member Function Documentation

◆ pre_master_secret()

const secure_vector< uint8_t > & Botan::TLS::Client_Key_Exchange::pre_master_secret ( ) const
inline

Definition at line 489 of file tls_messages.h.

489{ return m_pre_master; }

◆ psk_identity()

const std::optional< std::string > & Botan::TLS::Client_Key_Exchange::psk_identity ( ) const
inline
Returns
the agreed upon PSK identity or std::nullopt if not applicable

Definition at line 494 of file tls_messages.h.

494{ return m_psk_identity; }

◆ type()

Handshake_Type Botan::TLS::Client_Key_Exchange::type ( ) const
inlineoverridevirtual
Returns
the message type

Implements Botan::TLS::Handshake_Message.

Definition at line 487 of file tls_messages.h.

References Botan::TLS::ClientKeyExchange.

◆ 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.

19 {
21}
virtual Handshake_Type type() const =0
const char * handshake_type_to_string(Handshake_Type type)

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

◆ 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.

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

References type().

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


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