#include <tls_extensions_13.h>

Inheritance diagram for Botan::TLS::Key_Share:

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 210 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 377 of file tls_extensions_key_share.cpp.

                                                                                                  {
   if(message_type == Handshake_Type::ClientHello) {
      m_impl = std::make_unique<Key_Share_Impl>(Key_Share_ClientHello(reader, extension_size));
   } else if(message_type == Handshake_Type::HelloRetryRequest) {
      // Connection_Side::Server
      m_impl = std::make_unique<Key_Share_Impl>(Key_Share_HelloRetryRequest(reader, extension_size));
   } else if(message_type == Handshake_Type::ServerHello) {
      // Connection_Side::Server
      m_impl = std::make_unique<Key_Share_Impl>(Key_Share_ServerHello(reader, extension_size));
   } else {
      throw Invalid_Argument(std::string("cannot create a Key_Share extension for message of type: ") +
                             handshake_type_to_string(message_type));
   }
}

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 393 of file tls_extensions_key_share.cpp.

393 :

394 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 397 of file tls_extensions_key_share.cpp.

397 :

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

Botan::TLS::Key_Share::selected_group

Named_Group selected_group() const

Definition tls_extensions_key_share.cpp:446

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

                                                                                          {
   return std::unique_ptr<Key_Share>(new Key_Share(selected_group, client_keyshare, policy, cb, rng));
}

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 427 of file tls_extensions_key_share.cpp.

                                                                          {
   return std::visit(overloaded{[&](Key_Share_ClientHello& ch, const Key_Share_ServerHello& sh) {
                                   return ch.decapsulate(sh, policy, cb, rng);
                                },
                                [](const auto&, const auto&) -> secure_vector<uint8_t> {
                                   throw Invalid_Argument(
                                      "can only decapsulate in ClientHello Key_Share with a ServerHello Key_Share");
                                }},
                     m_impl->key_share,
                     server_keyshare.m_impl->key_share);
}

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 415 of file tls_extensions_key_share.cpp.

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

◆ 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 442 of file tls_extensions_key_share.cpp.

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

Referenced by 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 459 of file tls_extensions_key_share.cpp.

                                                        {
   std::visit(overloaded{[&](Key_Share_ClientHello& ch, const Key_Share_HelloRetryRequest& hrr) {
                            auto selected = hrr.selected_group();
                            // RFC 8446 4.2.8
                            //    [T]he selected_group field [MUST correspond] to a group which was provided in
                            //    the "supported_groups" extension in the original ClientHello
                            if(!value_exists(supported_groups, selected)) {
                               throw TLS_Exception(Alert::IllegalParameter, "group was not advertised as supported");
                            }
 
                            return ch.retry_offer(selected, cb, rng);
                         },
                         [](const auto&, const auto&) {
                            throw Invalid_Argument("can only retry with HelloRetryRequest on a ClientHello Key_Share");
                         }},
              m_impl->key_share,
              retry_request_keyshare.m_impl->key_share);
}

References 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 446 of file tls_extensions_key_share.cpp.

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

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

whoami which peer we are acting as in the protocol

Returns: serialized binary for the extension

Implements Botan::TLS::Extension.

Definition at line 411 of file tls_extensions_key_share.cpp.

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

◆ static_type()

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

inlinestatic

Definition at line 212 of file tls_extensions_13.h.

212{ return Extension_Code::KeyShare; }

Botan::TLS::Extension_Code::KeyShare

@ KeyShare

Definition tls_extensions.h:73

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 450 of file tls_extensions_key_share.cpp.

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

◆ 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 214 of file tls_extensions_13.h.

214{ return static_type(); }

Botan::TLS::Key_Share::static_type

static Extension_Code static_type()

Definition tls_extensions_13.h:212

References static_type().

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

src/lib/tls/tls13/tls_extensions_13.h
src/lib/tls/tls13/tls_extensions_key_share.cpp

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ Key_Share() [1/3]

◆ Key_Share() [2/3]

◆ Key_Share() [3/3]

◆ ~Key_Share()

Member Function Documentation

◆ create_as_encapsulation()

◆ decapsulate()

◆ empty()

◆ is_implemented()

◆ offered_groups()

◆ retry_offer()

◆ selected_group()

◆ serialize()

◆ static_type()

◆ take_shared_secret()

◆ type()