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

#include <tls_extensions_13.h>

Inheritance diagram for Botan::TLS::Key_Share:
Botan::TLS::Extension

Public Member Functions

secure_vector< uint8_t > decapsulate (const Key_Share &server_keyshare, const Policy &policy, Callbacks &cb, RandomNumberGenerator &rng)
bool empty () const override
virtual bool is_implemented () const
 Key_Share (const Policy &policy, Callbacks &cb, RandomNumberGenerator &rng)
 Key_Share (Named_Group selected_group)
 Key_Share (TLS_Data_Reader &reader, uint16_t extension_size, Handshake_Type message_type)
std::vector< Named_Group > offered_groups () const
void retry_offer (const Key_Share &retry_request_keyshare, const std::vector< Named_Group > &supported_groups, Callbacks &cb, RandomNumberGenerator &rng)
Named_Group selected_group () const
std::vector< uint8_t > serialize (Connection_Side whoami) const override
secure_vector< uint8_t > take_shared_secret ()
Extension_Code type () const override
 ~Key_Share () override

Static Public Member Functions

static std::unique_ptr< Key_Share > create_as_encapsulation (Group_Params selected_group, const Key_Share &client_keyshare, const Policy &policy, Callbacks &cb, RandomNumberGenerator &rng)
static Extension_Code static_type ()

Detailed Description

Key_Share from RFC 8446 4.2.8

Definition at line 220 of file tls_extensions_13.h.

Constructor & Destructor Documentation

◆ Key_Share() [1/3]

Botan::TLS::Key_Share::Key_Share ( TLS_Data_Reader & reader,
uint16_t extension_size,
Handshake_Type message_type )

Definition at line 407 of file tls_extensions_key_share.cpp.

407 {
408 if(message_type == Handshake_Type::ClientHello) {
409 m_impl = std::make_unique<Key_Share_Impl>(Key_Share_ClientHello(reader, extension_size));
410 } else if(message_type == Handshake_Type::HelloRetryRequest) {
411 // Connection_Side::Server
412 m_impl = std::make_unique<Key_Share_Impl>(Key_Share_HelloRetryRequest(reader, extension_size));
413 } else if(message_type == Handshake_Type::ServerHello) {
414 // Connection_Side::Server
415 m_impl = std::make_unique<Key_Share_Impl>(Key_Share_ServerHello(reader, extension_size));
416 } else {
417 throw Invalid_Argument(std::string("cannot create a Key_Share extension for message of type: ") +
418 handshake_type_to_string(message_type));
419 }
420}
const char * handshake_type_to_string(Handshake_Type type)
Definition tls_magic.cpp:15

References Botan::TLS::ClientHello, Botan::TLS::handshake_type_to_string(), Botan::TLS::HelloRetryRequest, Key_Share(), and Botan::TLS::ServerHello.

Referenced by create_as_encapsulation(), decapsulate(), Key_Share(), Key_Share(), retry_offer(), and ~Key_Share().

◆ Key_Share() [2/3]

Botan::TLS::Key_Share::Key_Share ( const Policy & policy,
Callbacks & cb,
RandomNumberGenerator & rng )

Definition at line 423 of file tls_extensions_key_share.cpp.

423 :
424 m_impl(std::make_unique<Key_Share_Impl>(Key_Share_ClientHello(policy, cb, rng))) {}

References Key_Share().

◆ Key_Share() [3/3]

Botan::TLS::Key_Share::Key_Share ( Named_Group selected_group)
explicit

Definition at line 427 of file tls_extensions_key_share.cpp.

427 :
428 m_impl(std::make_unique<Key_Share_Impl>(Key_Share_HelloRetryRequest(selected_group))) {}

References selected_group().

◆ ~Key_Share()

Botan::TLS::Key_Share::~Key_Share ( )
overridedefault

References Key_Share(), and selected_group().

Member Function Documentation

◆ create_as_encapsulation()

std::unique_ptr< Key_Share > Botan::TLS::Key_Share::create_as_encapsulation ( Group_Params selected_group,
const Key_Share & client_keyshare,
const Policy & policy,
Callbacks & cb,
RandomNumberGenerator & rng )
static

Creates a Key_Share extension meant for the Server Hello that performs a key encapsulation with the selected public key from the client.

Note
This will retain the shared secret in the Key_Share extension until it is retrieved via take_shared_secret().

Definition at line 449 of file tls_extensions_key_share.cpp.

453 {
454 return std::unique_ptr<Key_Share>(new Key_Share(selected_group, client_keyshare, policy, cb, rng));
455}
Key_Share(TLS_Data_Reader &reader, uint16_t extension_size, Handshake_Type message_type)

References Key_Share(), and selected_group().

◆ decapsulate()

secure_vector< uint8_t > Botan::TLS::Key_Share::decapsulate ( const Key_Share & server_keyshare,
const Policy & policy,
Callbacks & cb,
RandomNumberGenerator & rng )

Decapsulate the shared secret with the peer's key share. This method can be called on a ClientHello's Key_Share with a ServerHello's Key_Share.

Note
After the decapsulation the client's private key is destroyed. Multiple calls will result in an exception.

Definition at line 457 of file tls_extensions_key_share.cpp.

460 {
461 return std::visit(overloaded{[&](Key_Share_ClientHello& ch, const Key_Share_ServerHello& sh) {
462 return ch.decapsulate(sh, policy, cb, rng);
463 },
464 [](const auto&, const auto&) -> secure_vector<uint8_t> {
465 throw Invalid_Argument(
466 "can only decapsulate in ClientHello Key_Share with a ServerHello Key_Share");
467 }},
468 m_impl->key_share,
469 server_keyshare.m_impl->key_share);
470}
std::vector< T, secure_allocator< T > > secure_vector
Definition secmem.h:128
overloaded(Ts...) -> overloaded< Ts... >

References Key_Share().

◆ empty()

bool Botan::TLS::Key_Share::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 445 of file tls_extensions_key_share.cpp.

445 {
446 return std::visit([](const auto& key_share) { return key_share.empty(); }, m_impl->key_share);
447}

◆ 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; }

◆ offered_groups()

std::vector< Named_Group > Botan::TLS::Key_Share::offered_groups ( ) const
Returns
key exchange groups the peer offered key share entries for

Definition at line 472 of file tls_extensions_key_share.cpp.

472 {
473 return std::visit([](const auto& keyshare) { return keyshare.offered_groups(); }, m_impl->key_share);
474}

Referenced by Botan::TLS::Server_Hello_13::create(), and Botan::TLS::Hello_Retry_Request::Hello_Retry_Request().

◆ retry_offer()

void Botan::TLS::Key_Share::retry_offer ( const Key_Share & retry_request_keyshare,
const std::vector< Named_Group > & supported_groups,
Callbacks & cb,
RandomNumberGenerator & rng )

Update a ClientHello's Key_Share to comply with a HelloRetryRequest.

This will create new Key_Share_Entries and should only be called on a ClientHello Key_Share with a HelloRetryRequest Key_Share.

Definition at line 489 of file tls_extensions_key_share.cpp.

492 {
493 std::visit(overloaded{[&](Key_Share_ClientHello& ch, const Key_Share_HelloRetryRequest& hrr) {
494 const auto selected = hrr.selected_group();
495 // RFC 8446 4.2.8
496 // [T]he selected_group field [MUST correspond] to a group which was provided in
497 // the "supported_groups" extension in the original ClientHello
498 if(!value_exists(supported_groups, selected) ||
499 !group_usable_in_version(selected, Protocol_Version::TLS_V13)) {
500 throw TLS_Exception(Alert::IllegalParameter, "group was not advertised as supported");
501 }
502
503 return ch.retry_offer(selected, cb, rng);
504 },
505 [](const auto&, const auto&) {
506 throw Invalid_Argument("can only retry with HelloRetryRequest on a ClientHello Key_Share");
507 }},
508 m_impl->key_share,
509 retry_request_keyshare.m_impl->key_share);
510}
bool group_usable_in_version(Group_Params group, Protocol_Version version)
bool value_exists(const std::vector< T > &vec, const V &val)
Definition stl_util.h:44

References Botan::TLS::group_usable_in_version(), Key_Share(), and Botan::value_exists().

◆ selected_group()

Named_Group Botan::TLS::Key_Share::selected_group ( ) const
Returns
key exchange group that was selected by a Hello Retry Request

Definition at line 476 of file tls_extensions_key_share.cpp.

476 {
477 return std::visit([](const auto& keyshare) { return keyshare.selected_group(); }, m_impl->key_share);
478}

Referenced by create_as_encapsulation(), Key_Share(), and ~Key_Share().

◆ serialize()

std::vector< uint8_t > Botan::TLS::Key_Share::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 441 of file tls_extensions_key_share.cpp.

441 {
442 return std::visit([](const auto& key_share) { return key_share.serialize(); }, m_impl->key_share);
443}

◆ static_type()

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

Definition at line 222 of file tls_extensions_13.h.

References Botan::TLS::KeyShare.

Referenced by type().

◆ take_shared_secret()

secure_vector< uint8_t > Botan::TLS::Key_Share::take_shared_secret ( )
Returns
the shared secret that was obtained by constructing this Key_Share object with the peer's.
Note
the shared secret value is std:move'd out. Multiple calls will result in an exception.

Definition at line 480 of file tls_extensions_key_share.cpp.

480 {
481 return std::visit(
482 overloaded{[](Key_Share_ServerHello& server_keyshare) { return server_keyshare.take_shared_secret(); },
483 [](auto&) -> secure_vector<uint8_t> {
484 throw Invalid_Argument("Only the key share in Server Hello contains a shared secret");
485 }},
486 m_impl->key_share);
487}

◆ type()

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

Return TLS extension code

Returns
code number of the extension

Implements Botan::TLS::Extension.

Definition at line 224 of file tls_extensions_13.h.

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

References static_type().


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