Botan::TLS::Key_Share Class Reference

#include <tls_extensions.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 761 of file tls_extensions.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 404 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::handshake_type_to_string().

Referenced by create_as_encapsulation().

Key_Share() [2/3]

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

Definition at line 420 of file tls_extensions_key_share.cpp.

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

Key_Share() [3/3]

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

explicit

Definition at line 424 of file tls_extensions_key_share.cpp.

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

~Key_Share()

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

overridedefault

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 446 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 454 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);
}

empty()

bool Botan::TLS::Key_Share::empty ( ) const

overridevirtual

Returns

if we should encode this extension or not

Implements Botan::TLS::Extension.

Definition at line 442 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

Returns

true if this extension is known and implemented by Botan

Reimplemented in Botan::TLS::Unknown_Extension.

Definition at line 116 of file tls_extensions.h.

{ 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 469 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 486 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 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 473 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().

serialize()

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

overridevirtual

Returns

serialized binary for the extension

Implements Botan::TLS::Extension.

Definition at line 438 of file tls_extensions_key_share.cpp.

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

static_type()

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

inlinestatic

Definition at line 763 of file tls_extensions.h.

{ return Extension_Code::KeyShare; }

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 477 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

Returns

code number of the extension

Implements Botan::TLS::Extension.

Definition at line 765 of file tls_extensions.h.

{ return static_type(); }

---

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

• src/lib/tls/tls_extensions.h
• src/lib/tls/tls13/tls_extensions_key_share.cpp