Botan 3.14.1
Crypto and TLS for C&
tls_extensions_psk.cpp
Go to the documentation of this file.
1/*
2* TLS Extension Pre Shared Key
3* (C) 2022-2023 Jack Lloyd
4* 2022 René Meusel - neXenio GmbH
5* 2023 Fabian Albert, René Meusel - Rohde & Schwarz Cybersecurity
6*
7* Botan is released under the Simplified BSD License (see license.txt)
8*/
9
10#include <botan/tls_extensions_13.h>
11
12#include <botan/credentials_manager.h>
13#include <botan/hash.h>
14#include <botan/tls_callbacks.h>
15#include <botan/tls_exceptn.h>
16#include <botan/tls_policy.h>
17#include <botan/tls_psk_identity_13.h>
18#include <botan/tls_session.h>
19#include <botan/tls_session_manager.h>
20#include <botan/internal/ct_utils.h>
21#include <botan/internal/stl_util.h>
22#include <botan/internal/tls_cipher_state.h>
23#include <botan/internal/tls_reader.h>
24#include <algorithm>
25#include <utility>
26
27namespace Botan::TLS {
28
29namespace {
30
31decltype(auto) calculate_age(std::chrono::system_clock::time_point then, std::chrono::system_clock::time_point now) {
32 // TODO: Currently this does not provide actual millisecond resolution.
33 // This might become a problem when "early data" is implemented and we
34 // deal with servers that employ a strict "freshness" criteria on the
35 // ticket's age.
36 return std::chrono::duration_cast<std::chrono::milliseconds>(now - then);
37}
38
39class Client_PSK {
40 public:
41 Client_PSK(Session_with_Handle& session_to_resume, std::chrono::system_clock::time_point timestamp) :
42 Client_PSK(PskIdentity(session_to_resume.handle.opaque_handle(),
43 calculate_age(session_to_resume.session.start_time(), timestamp),
44 session_to_resume.session.session_age_add()),
45 session_to_resume.session.ciphersuite().prf_algo(),
46 session_to_resume.session.extract_master_secret(),
47 Cipher_State::PSK_Type::Resumption) {}
48
49 // NOLINTNEXTLINE(*-rvalue-reference-param-not-moved)
50 explicit Client_PSK(ExternalPSK&& psk) :
51 Client_PSK(PskIdentity(PresharedKeyID(psk.identity())),
52 psk.prf_algo(),
53 psk.extract_master_secret(),
54 psk.is_imported() ? Cipher_State::PSK_Type::Imported : Cipher_State::PSK_Type::External) {}
55
56 Client_PSK(PskIdentity id, std::vector<uint8_t> bndr) :
57 m_identity(std::move(id)), m_binder(std::move(bndr)), m_is_resumption(false) {}
58
59 Client_PSK(PskIdentity id,
60 std::string_view prf_algo,
61 secure_vector<uint8_t>&& master_secret,
62 Cipher_State::PSK_Type psk_type) :
63 m_identity(std::move(id)),
64
65 // RFC 8446 4.2.11.2
66 // Each entry in the binders list is computed as an HMAC over a transcript
67 // hash (see Section 4.4.1) containing a partial ClientHello up to and
68 // including the PreSharedKeyExtension.identities field. That is, it
69 // includes all of the ClientHello but not the binders list itself. The
70 // length fields for the message (including the overall length, the length
71 // of the extensions block, and the length of the "pre_shared_key"
72 // extension) are all set as if binders of the correct lengths were
73 // present.
74 //
75 // Hence, we fill the binders with dummy values of the correct length and use
76 // `Client_Hello_13::truncate()` to split them off before calculating the
77 // transcript hash that underpins the PSK binders. S.a. `calculate_binders()`
78 m_binder(HashFunction::create_or_throw(prf_algo)->output_length()),
79 m_is_resumption(psk_type == Cipher_State::PSK_Type::Resumption),
80 m_cipher_state(Cipher_State::init_with_psk(
81 Connection_Side::Client, TLS_Flavor::TLS, psk_type, std::move(master_secret), prf_algo)) {}
82
83 const PskIdentity& identity() const { return m_identity; }
84
85 const std::vector<uint8_t>& binder() const { return m_binder; }
86
87 bool is_resumption() const { return m_is_resumption; }
88
89 void set_binder(std::vector<uint8_t> binder) { m_binder = std::move(binder); }
90
91 const Cipher_State& cipher_state() const {
92 BOTAN_ASSERT_NONNULL(m_cipher_state);
93 return *m_cipher_state;
94 }
95
96 std::unique_ptr<Cipher_State> take_cipher_state() { return std::exchange(m_cipher_state, nullptr); }
97
98 private:
99 PskIdentity m_identity;
100 std::vector<uint8_t> m_binder;
101 bool m_is_resumption;
102
103 // Clients set up associated cipher states for PSKs
104 // Servers leave this as nullptr
105 std::unique_ptr<Cipher_State> m_cipher_state;
106};
107
108class Server_PSK {
109 public:
110 explicit Server_PSK(uint16_t id) : m_selected_identity(id), m_session_to_resume_or_psk(std::monostate()) {}
111
112 Server_PSK(uint16_t id, Session session) :
113 m_selected_identity(id), m_session_to_resume_or_psk(std::move(session)) {}
114
115 Server_PSK(uint16_t id, ExternalPSK psk) : m_selected_identity(id), m_session_to_resume_or_psk(std::move(psk)) {}
116
117 uint16_t selected_identity() const { return m_selected_identity; }
118
119 std::variant<std::monostate, Session, ExternalPSK> take_session_to_resume_or_psk() {
120 BOTAN_STATE_CHECK(!std::holds_alternative<std::monostate>(m_session_to_resume_or_psk));
121 return std::exchange(m_session_to_resume_or_psk, std::monostate());
122 }
123
124 private:
125 uint16_t m_selected_identity;
126
127 // Servers store the Session to resume or the PSK of their selection
128 std::variant<std::monostate, Session, ExternalPSK> m_session_to_resume_or_psk;
129};
130
131} // namespace
132
133class PSK::PSK_Internal {
134 public:
135 explicit PSK_Internal(Server_PSK srv_psk) : psk(std::move(srv_psk)) {}
136
137 explicit PSK_Internal(std::vector<Client_PSK> clt_psks) : psk(std::move(clt_psks)) {}
138
139 // NOLINTNEXTLINE(*-non-private-member-variable*)
140 std::variant<std::vector<Client_PSK>, Server_PSK> psk;
141};
142
143PSK::PSK(TLS_Data_Reader& reader, uint16_t extension_size, Handshake_Type message_type) {
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}
208
209PSK::PSK(std::optional<Session_with_Handle>& session_to_resume, std::vector<ExternalPSK> psks, Callbacks& callbacks) {
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}
222
223PSK::PSK(Session session_to_resume, uint16_t psk_index) :
224 m_impl(std::make_unique<PSK_Internal>(Server_PSK(psk_index, std::move(session_to_resume)))) {}
225
226PSK::PSK(ExternalPSK psk, uint16_t psk_index) :
227 m_impl(std::make_unique<PSK_Internal>(Server_PSK(psk_index, std::move(psk)))) {}
228
229PSK::~PSK() = default;
230
231bool PSK::empty() const {
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}
239
240std::pair<std::optional<std::string>, std::unique_ptr<Cipher_State>> PSK::take_selected_psk_info(
241 const PSK& server_psk, const Ciphersuite& cipher) {
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}
283
284std::unique_ptr<PSK> PSK::select_offered_psk(std::string_view host,
285 const Ciphersuite& cipher,
286 Session_Manager& session_mgr,
287 Credentials_Manager& credentials_mgr,
288 Callbacks& callbacks,
289 const Policy& policy) {
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.
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}
388
389void PSK::filter(const Ciphersuite& cipher) {
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}
399
400void PSK::validate_updates(const PSK& new_psk) const {
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}
418
419std::variant<Session, ExternalPSK> PSK::take_session_to_resume_or_psk() {
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}
432
433std::vector<uint8_t> PSK::serialize(Connection_Side side) const {
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}
470
471// See RFC 8446 4.2.11.2 for details on how these binders are calculated
472void PSK::calculate_binders(const Transcript_Hash_State& truncated_transcript_hash) {
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}
481
482bool PSK::validate_binder(const PSK& server_psk, std::span<const uint8_t> binder) const {
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}
493
494} // namespace Botan::TLS
#define BOTAN_ASSERT_NOMSG(expr)
Definition assert.h:82
#define BOTAN_STATE_CHECK(expr)
Definition assert.h:49
#define BOTAN_ASSERT_NONNULL(ptr)
Definition assert.h:121
virtual std::optional< TLS::ExternalPSK > choose_preshared_key(std::string_view host, TLS::Connection_Side whoami, const std::vector< std::string > &identities, const std::optional< std::string > &prf=std::nullopt)
virtual std::chrono::system_clock::time_point tls_current_timestamp()
std::string prf_algo() const
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()
void filter(const Ciphersuite &cipher)
void validate_updates(const PSK &new_psk) const
std::vector< uint8_t > serialize(Connection_Side side) const override
void calculate_binders(const Transcript_Hash_State &truncated_transcript_hash)
bool validate_binder(const PSK &server_psk, std::span< const uint8_t > binder) const
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)
~PSK() override
bool empty() const override
PSK(TLS_Data_Reader &reader, uint16_t extension_size, Handshake_Type message_type)
virtual bool require_client_certificate_authentication() const
virtual std::optional< std::pair< Session, uint16_t > > choose_from_offered_tickets(const std::vector< PskIdentity > &tickets, std::string_view hash_function, Callbacks &callbacks, const Policy &policy)
size_t read_so_far() const
Definition tls_reader.h:35
std::vector< uint8_t > get_tls_length_value(size_t len_bytes)
Definition tls_reader.h:110
void set_algorithm(std::string_view algo_spec)
constexpr CT::Mask< T > is_equal(const T x[], const T y[], size_t len)
Definition ct_utils.h:803
Strong< std::string, struct PresharedKeyID_ > PresharedKeyID
holds a PSK identity as used in TLS 1.3
Definition tls_psk_13.h:28
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
std::vector< T, secure_allocator< T > > secure_vector
Definition secmem.h:128