Botan 3.14.1
Crypto and TLS for C&
Botan::TLS::PSK Class Referencefinal

#include <tls_extensions_13.h>

Inheritance diagram for Botan::TLS::PSK:
Botan::TLS::Extension

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, std::span< const uint8_t > binder) const
void validate_updates (const PSK &new_psk) 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 110 of file tls_extensions_13.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 143 of file tls_extensions_psk.cpp.

143 {
144 if(message_type == Handshake_Type::ServerHello) {
145 if(extension_size != 2) {
146 throw TLS_Exception(Alert::DecodeError, "Server provided a malformed PSK extension");
147 }
148
149 const uint16_t selected_id = reader.get_uint16_t();
150 m_impl = std::make_unique<PSK_Internal>(Server_PSK(selected_id));
151 } else if(message_type == Handshake_Type::ClientHello) {
152 const auto identities_length = reader.get_uint16_t();
153 const auto identities_offset = reader.read_so_far();
154
155 std::vector<PskIdentity> psk_identities;
156 while(reader.has_remaining() && (reader.read_so_far() - identities_offset) < identities_length) {
157 // RFC 9846 4.3.11
158 // struct {
159 // opaque identity<1..2^16-1>;
160 // uint32 obfuscated_ticket_age;
161 // } PskIdentity;
162 auto identity = reader.get_tls_length_value(2);
163 if(identity.empty()) {
164 throw TLS_Exception(Alert::DecodeError, "Empty PSK identity");
165 }
166 const auto obfuscated_ticket_age = reader.get_uint32_t();
167 psk_identities.emplace_back(std::move(identity), obfuscated_ticket_age);
168 }
169
170 if(psk_identities.empty()) {
171 throw TLS_Exception(Alert::DecodeError, "Empty PSK list");
172 }
173
174 if(reader.read_so_far() - identities_offset != identities_length) {
175 throw TLS_Exception(Alert::DecodeError, "Inconsistent PSK identity list");
176 }
177
178 const auto binders_length = reader.get_uint16_t();
179 const auto binders_offset = reader.read_so_far();
180
181 if(binders_length == 0) {
182 throw TLS_Exception(Alert::DecodeError, "Empty PSK binders list");
183 }
184
185 std::vector<Client_PSK> psks;
186 for(auto& psk_identity : psk_identities) {
187 if(!reader.has_remaining() || reader.read_so_far() - binders_offset >= binders_length) {
188 throw TLS_Exception(Alert::IllegalParameter, "Not enough PSK binders");
189 }
190
191 // RFC 8446 4.2.11 declares PskBinderEntry opaque<32..255>, but we accept any
192 // 0..255 length here and let validate_binder reject, which yields a bad_record_mac
193 // alert rather than decode_error. BoringSSL behaves the same way and BoGo has
194 // tests that specifically expect this.
195
196 psks.emplace_back(std::move(psk_identity), reader.get_tls_length_value(1));
197 }
198
199 if(reader.read_so_far() - binders_offset != binders_length) {
200 throw TLS_Exception(Alert::IllegalParameter, "Too many PSK binders");
201 }
202
203 m_impl = std::make_unique<PSK_Internal>(std::move(psks));
204 } else {
205 throw TLS_Exception(Alert::DecodeError, "Found a PSK extension in an unexpected handshake message");
206 }
207}

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.

Referenced by select_offered_psk(), take_selected_psk_info(), validate_binder(), validate_updates(), and ~PSK().

◆ 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_resumethe session to be resumed; note that the master secret will be taken away from the session object.
psksa list of non-resumption PSKs that should be offered to the server
callbacksthe application's callbacks

Definition at line 209 of file tls_extensions_psk.cpp.

209 {
210 std::vector<Client_PSK> cpsk;
211
212 if(session_to_resume.has_value()) {
213 cpsk.emplace_back(session_to_resume.value(), callbacks.tls_current_timestamp());
214 }
215
216 for(auto&& psk : psks) {
217 cpsk.emplace_back(std::move(psk));
218 }
219
220 m_impl = std::make_unique<PSK_Internal>(std::move(cpsk));
221}

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 472 of file tls_extensions_psk.cpp.

472 {
473 BOTAN_ASSERT_NOMSG(std::holds_alternative<std::vector<Client_PSK>>(m_impl->psk));
474 for(auto& psk : std::get<std::vector<Client_PSK>>(m_impl->psk)) {
475 auto tth = truncated_transcript_hash.clone();
476 const auto& cipher_state = psk.cipher_state();
477 tth.set_algorithm(cipher_state.hash_algorithm());
478 psk.set_binder(cipher_state.psk_binder_mac(tth.truncated()));
479 }
480}
#define BOTAN_ASSERT_NOMSG(expr)
Definition assert.h:82

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

Referenced by ~PSK().

◆ empty()

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

Predicate if a TLS extension should be included or not

Returns
true if this extension should be encoded, otherwise false

Implements Botan::TLS::Extension.

Definition at line 231 of file tls_extensions_psk.cpp.

231 {
232 if(std::holds_alternative<Server_PSK>(m_impl->psk)) {
233 return false;
234 }
235
236 BOTAN_ASSERT_NOMSG(std::holds_alternative<std::vector<Client_PSK>>(m_impl->psk));
237 return std::get<std::vector<Client_PSK>>(m_impl->psk).empty();
238}
bool empty() const override

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 389 of file tls_extensions_psk.cpp.

389 {
390 BOTAN_STATE_CHECK(std::holds_alternative<std::vector<Client_PSK>>(m_impl->psk));
391 auto& psks = std::get<std::vector<Client_PSK>>(m_impl->psk);
392
393 const auto r = std::remove_if(psks.begin(), psks.end(), [&](const auto& psk) {
394 const auto& cipher_state = psk.cipher_state();
395 return !cipher_state.is_compatible_with(cipher);
396 });
397 psks.erase(r, psks.end());
398}
#define BOTAN_STATE_CHECK(expr)
Definition assert.h:49

References BOTAN_STATE_CHECK.

◆ is_implemented()

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

Predicate if the extension is known/implemented

Note
this exists primarily to support unknown extension handling and doesn't need to be overridden even in the custom extension case.
Returns
true if this extension is known

Reimplemented in Botan::TLS::Unknown_Extension.

Definition at line 113 of file tls_extensions.h.

113{ 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
PSKextension object that can be added to the Server Hello response
std::nullptrif no PSK offered by the client is convenient

Definition at line 284 of file tls_extensions_psk.cpp.

289 {
290 BOTAN_STATE_CHECK(std::holds_alternative<std::vector<Client_PSK>>(m_impl->psk));
291
292 auto& psks = std::get<std::vector<Client_PSK>>(m_impl->psk);
293
294 //
295 // PSK for Session Resumption
296 //
297 std::vector<PskIdentity> psk_identities;
298 std::transform(
299 psks.begin(), psks.end(), std::back_inserter(psk_identities), [&](const auto& psk) { return psk.identity(); });
300 if(auto selected_session =
301 session_mgr.choose_from_offered_tickets(psk_identities, cipher.prf_algo(), callbacks, policy)) {
302 auto& [session, psk_index] = selected_session.value();
303
304 // A session manager shared with our client role must not resume a session
305 // here that we stored as a client: its peer certificates are a remote
306 // server's, and this connection would adopt them as the client's. The
307 // session manager must never hand out such a session to a server.
308 if(session.side() != Connection_Side::Server) {
309 throw TLS_Exception(Alert::InternalError,
310 "Session manager chose a session stored by a TLS client for server-side resumption");
311 }
312
313 // Refuse to resume a ticket across SNI: a session minted for one
314 // virtual host must not be presentable against another. Treat as a
315 // cache miss and fall through to the external PSK path rather than
316 // failing the connection.
317 if(session.server_info().hostname() == host) {
318 // RFC 8446 4.6.1
319 // Any ticket MUST only be resumed with a cipher suite that has the
320 // same KDF hash algorithm as that used to establish the original
321 // connection.
322 if(session.ciphersuite().prf_algo() != cipher.prf_algo()) {
323 throw TLS_Exception(Alert::InternalError,
324 "Application chose a ticket that is not compatible with the negotiated ciphersuite");
325 }
326
327 return std::unique_ptr<PSK>(new PSK(std::move(session), psk_index));
328 }
329 }
330
331 //
332 // Externally provided PSKs
333 //
334
335 // RFC 8446 4.3.2
336 // Servers which are authenticating with a PSK MUST NOT send the
337 // CertificateRequest message in the main handshake
338 //
339 // Selecting an external PSK would silently drop a mandatory client
340 // certificate, so ignore them and perform a full handshake instead.
341 if(policy.require_client_certificate_authentication()) {
342 return nullptr;
343 }
344
345 std::vector<std::string> psk_ids;
346 std::transform(psks.begin(), psks.end(), std::back_inserter(psk_ids), [&](const auto& psk) {
347 return psk.identity().identity_as_string();
348 });
349 if(auto selected_psk =
350 credentials_mgr.choose_preshared_key(host, Connection_Side::Server, psk_ids, cipher.prf_algo())) {
351 auto& psk = selected_psk.value();
352
353 // RFC 8446 4.2.11
354 // Each PSK is associated with a single Hash algorithm. [...]
355 // The server MUST ensure that it selects a compatible PSK (if any)
356 // and cipher suite.
357 if(psk.prf_algo() != cipher.prf_algo()) {
358 throw TLS_Exception(Alert::InternalError,
359 "Application chose a PSK that is not compatible with the negotiated ciphersuite");
360 }
361
362 const auto selected_itr =
363 std::find_if(psk_identities.begin(), psk_identities.end(), [&](const auto& offered_psk) {
364 return offered_psk.identity_as_string() == psk.identity();
365 });
366 if(selected_itr == psk_identities.end()) {
367 throw TLS_Exception(Alert::InternalError,
368 "Application provided a PSK with an identity that was not offered by the client");
369 }
370
371 // When implementing a server that works with PSKs exclusively, we might
372 // want to take TLS::Policy::hide_unknown_users() into account and
373 // obfuscate malicious "identity guesses" by generating a random PSK and
374 // letting the handshake continue.
375 //
376 // Currently, we do not have a notion of "a server that solely supports
377 // PSK handshakes". However, such applications are free to implement such
378 // a mitigation in their override of Credentials_Manager::choose_preshared_key().
379 //
380 // TODO: Take RFC 8446 Appendix E.6 into account, especially when
381 // implementing PSK_KE (aka. PSK-only mode).
382 return std::unique_ptr<PSK>(
383 new PSK(std::move(psk), static_cast<uint16_t>(std::distance(psk_identities.begin(), selected_itr))));
384 }
385
386 return nullptr;
387}
PSK(TLS_Data_Reader &reader, uint16_t extension_size, Handshake_Type message_type)

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

◆ serialize()

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

Serialize a TLS extension

Parameters
whoamiwhich peer we are acting as in the protocol
Returns
serialized binary for the extension

Implements Botan::TLS::Extension.

Definition at line 433 of file tls_extensions_psk.cpp.

433 {
434 std::vector<uint8_t> result;
435
436 std::visit(overloaded{
437 [&](const Server_PSK& psk) {
439 result.reserve(2);
440 const uint16_t id = psk.selected_identity();
441 result.push_back(get_byte<0>(id));
442 result.push_back(get_byte<1>(id));
443 },
444 [&](const std::vector<Client_PSK>& psks) {
446
447 std::vector<uint8_t> identities;
448 std::vector<uint8_t> binders;
449 for(const auto& psk : psks) {
450 const auto& psk_identity = psk.identity();
451 append_tls_length_value(identities, psk_identity.identity(), 2);
452
453 const uint32_t obfuscated_ticket_age = psk_identity.obfuscated_age();
454 identities.push_back(get_byte<0>(obfuscated_ticket_age));
455 identities.push_back(get_byte<1>(obfuscated_ticket_age));
456 identities.push_back(get_byte<2>(obfuscated_ticket_age));
457 identities.push_back(get_byte<3>(obfuscated_ticket_age));
458
459 append_tls_length_value(binders, psk.binder(), 1);
460 }
461
462 append_tls_length_value(result, identities, 2);
463 append_tls_length_value(result, binders, 2);
464 },
465 },
466 m_impl->psk);
467
468 return result;
469}
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:182
constexpr uint8_t get_byte(T input)
Definition loadstor.h:79
overloaded(Ts...) -> overloaded< Ts... >

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

◆ static_type()

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

Definition at line 112 of file tls_extensions_13.h.

References Botan::TLS::PresharedKey.

Referenced by type().

◆ 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 authoritative value for the user. We therefore report the identity of externally provided PSKs only.

Definition at line 240 of file tls_extensions_psk.cpp.

241 {
242 BOTAN_STATE_CHECK(std::holds_alternative<std::vector<Client_PSK>>(m_impl->psk));
243 BOTAN_STATE_CHECK(std::holds_alternative<Server_PSK>(server_psk.m_impl->psk));
244
245 const auto id = std::get<Server_PSK>(server_psk.m_impl->psk).selected_identity();
246 auto& ids = std::get<std::vector<Client_PSK>>(m_impl->psk);
247
248 // RFC 8446 4.2.11
249 // Clients MUST verify that the server's selected_identity is within the
250 // range supplied by the client, [...]. If these values are not
251 // consistent, the client MUST abort the handshake with an
252 // "illegal_parameter" alert.
253 if(id >= ids.size()) {
254 throw TLS_Exception(Alert::IllegalParameter, "PSK identity selected by server is out of bounds");
255 }
256
257 auto& selected_psk = ids.at(id);
258 auto cipher_state = selected_psk.take_cipher_state();
259
260 BOTAN_ASSERT_NONNULL(cipher_state);
261
262 auto psk_id = [&]() -> std::optional<std::string> {
263 if(selected_psk.is_resumption()) {
264 return std::nullopt;
265 }
266 return selected_psk.identity().identity_as_string();
267 }();
268
269 // destroy cipher states and PSKs that were not selected by the server
270 ids.clear();
271
272 // RFC 8446 4.2.11
273 // Clients MUST verify that [...] the server selected a cipher suite
274 // indicating a Hash associated with the PSK [...]. If these values
275 // are not consistent, the client MUST abort the handshake with an
276 // "illegal_parameter" alert.
277 if(!cipher_state->is_compatible_with(cipher)) {
278 throw TLS_Exception(Alert::IllegalParameter, "PSK and ciphersuite selected by server are not compatible");
279 }
280
281 return {std::move(psk_id), std::move(cipher_state)};
282}
#define BOTAN_ASSERT_NONNULL(ptr)
Definition assert.h:121

References BOTAN_ASSERT_NONNULL, BOTAN_STATE_CHECK, and PSK().

◆ 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 419 of file tls_extensions_psk.cpp.

419 {
420 BOTAN_STATE_CHECK(std::holds_alternative<Server_PSK>(m_impl->psk));
421
422 return std::visit(
423 [](auto out) -> std::variant<Session, ExternalPSK> {
424 if constexpr(std::is_same_v<decltype(out), std::monostate>) {
425 throw TLS_Exception(AlertType::InternalError, "cannot extract an empty PSK");
426 } else {
427 return out;
428 }
429 },
430 std::get<Server_PSK>(m_impl->psk).take_session_to_resume_or_psk());
431}

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

◆ type()

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

Return TLS extension code

Returns
code number of the extension

Implements Botan::TLS::Extension.

Definition at line 114 of file tls_extensions_13.h.

114{ return static_type(); }
static Extension_Code static_type()

References static_type().

◆ validate_binder()

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

Definition at line 482 of file tls_extensions_psk.cpp.

482 {
483 BOTAN_STATE_CHECK(std::holds_alternative<std::vector<Client_PSK>>(m_impl->psk));
484 BOTAN_STATE_CHECK(std::holds_alternative<Server_PSK>(server_psk.m_impl->psk));
485
486 const uint16_t index = std::get<Server_PSK>(server_psk.m_impl->psk).selected_identity();
487 const auto& psks = std::get<std::vector<Client_PSK>>(m_impl->psk);
488
489 BOTAN_STATE_CHECK(index < psks.size());
490 const auto& expected_binder = psks[index].binder();
491 return CT::is_equal<uint8_t>(binder, expected_binder).as_bool();
492}
constexpr CT::Mask< T > is_equal(const T x[], const T y[], size_t len)
Definition ct_utils.h:803

References BOTAN_STATE_CHECK, Botan::CT::is_equal(), and PSK().

Referenced by ~PSK().

◆ validate_updates()

void Botan::TLS::PSK::validate_updates ( const PSK & new_psk) const

Validates that the PSK extension of a ClientHello sent in response to a Hello Retry Request (new_psk) only removed PSK identities offered in this extension, but did not add or reorder any. Otherwise an Alert::IllegalParameter TLS exception is thrown.

Both extensions must be from a ClientHello.

Definition at line 400 of file tls_extensions_psk.cpp.

400 {
401 BOTAN_STATE_CHECK(std::holds_alternative<std::vector<Client_PSK>>(m_impl->psk));
402 BOTAN_STATE_CHECK(std::holds_alternative<std::vector<Client_PSK>>(new_psk.m_impl->psk));
403
404 const auto& old_psks = std::get<std::vector<Client_PSK>>(m_impl->psk);
405 const auto& new_psks = std::get<std::vector<Client_PSK>>(new_psk.m_impl->psk);
406
407 auto old_itr = old_psks.begin();
408 for(const auto& psk : new_psks) {
409 old_itr = std::find_if(old_itr, old_psks.end(), [&](const Client_PSK& old_psk) {
410 return old_psk.identity().identity() == psk.identity().identity();
411 });
412 if(old_itr == old_psks.end()) {
413 throw TLS_Exception(Alert::IllegalParameter, "PSK identities changed in updated Client Hello");
414 }
415 ++old_itr;
416 }
417}

References BOTAN_STATE_CHECK, and PSK().


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