TLSExtensionManager

class mtf.network_port.tls.tls_helpers.TLSExtensionManager

A helper class for managing TLS extensions in the TLS context.

This class provides methods to add various TLS extensions to the context, including SNI, status request, and supported versions, among others.

__init__()

clear_extensions()

Clears all stored TLS extensions from the internal dictionary.

This method resets the extensions attribute to an empty dictionary, effectively removing all previously added extensions.

add_sni_ext(server_name: str)

Adds a Server Name Indication (SNI) extension to the TLS context.

The SNI extension is used to indicate the hostname of the server that the client is attempting to connect to, enabling virtual hosting.

RFC6066 - Extension value: 0

Args:: server_name (str): The server’s hostname.
Example:: self.add_sni_ext(‘example.com’)

add_status_request_ext(r_id_list: list[bytearray])

Adds a Status Request extension to the TLS context.

This extension is used to request the status of the certificate chain (e.g., OCSP stapling).

RFC6066 - Extension value: 5

Args:: r_id_list (List[bytearray]): List of responder IDs.
Example:: self.add_status_request_ext([bytearray(b’¢’) + bytearray([(i + 2) % 256] * 20) for i in range(625)])

add_supported_groups_ext(groups: list[int])

Adds a Supported Groups (formerly Elliptic Curves) extension to the TLS context.

This extension indicates the supported groups (curves) for key exchange.

RFC8422 - Extension value: 10

Args:: groups (List[int]): List of supported group identifiers.
Example:: self.add_supported_groups_ext([GroupName.secp256r1, GroupName.secp384r1])

add_point_formats_ext(point_formats: list[int])

Adds a Supported Point Formats extension to the TLS context.

This extension specifies the supported elliptic curve point formats.

RFC8442 - Extension value: 11

Args:

point_formats (List[int]): A list of elliptic curve point formats to add. Each format should: be an integer, such as ECPointFormat.uncompressed.

Example:

self.add_point_formats_ext([ECPointFormat.uncompressed])

add_srp_ext(name: str | bytearray)

Adds a Secure Remote Password (SRP) extension to the TLS context.

SRP is used for secure password-based authentication.

RFC5054 - Extension value: 12

Args:: name (Union[str, bytearray]): SRP username, either as a string or a bytearray.
Example:: self.add_srp_ext(‘user123’)

add_signature_algorithms_ext(sig_algs: list[tuple[int, int]])

Adds a Signature Algorithms extension to the TLS context.

This extension specifies the supported signature algorithms.

RFC8446 - Extension value: 13

Args:

sig_algs (List[Tuple[int, int]]): A list of supported signature algorithm identifiers,: where each tuple contains two integers representing the hash algorithm and the signature algorithm.

Example:

self.add_signature_algorithms_ext([(SignatureScheme.ecdsa_secp521r1_sha512, SignatureScheme.rsa_pss_rsae_sha256)])

add_heartbeat_ext(mode: int)

Adds a Heartbeat extension to the TLS context.

The Heartbeat extension provides a keep-alive mechanism to test and maintain the connection.

RFC6520 - Extension value: 15

Args:: mode (int): Heartbeat mode (1 for PeerAllowedToSend, 2 for PeerNotAllowedToSend).
Example:: self.add_heartbeat_ext(1)

add_alpn_ext(data: list[bytes])

Adds an Application-Layer Protocol Negotiation (ALPN) extension to the TLS context.

ALPN allows the application layer to negotiate which protocol to use over a TLS connection.

RFC7301 - Extension value: 16

Args:: data (list[bytes]): List of supported protocols.
Example:: self.add_alpn_ext([b’http/1.1’, b’h2’])

add_padding_ext(padding_len: int)

Adds a Padding extension to the TLS context.

Padding is used to adjust the size of the ClientHello message to mitigate certain attacks.

RFC7685 - Extension value: 21

Args:: padding_len (int): Length of the padding.
Example:: self.add_padding_ext(10)

add_record_size_limit_ext(size: int)

Adds a Record Size Limit extension to the TLS context.

This extension allows the client to specify the maximum record size it is willing to receive.

RFC8449 - Extension value: 28

Args:: size (int): Maximum record size.
Example:: self.add_record_size_limit_ext(65535)

add_supported_versions_ext(versions_list: list[ProtocolVersion])

Adds a Supported Versions extension to the TLS context.

This extension specifies the versions of TLS supported by the client.

RFC8446 - Extension value: 43

Args:: versions_list (list[ProtocolVersion]): List of supported TLS versions as ProtocolVersion enum members.
Example:: self.add_supported_versions_ext([ProtocolVersion.TLS13, ProtocolVersion.TLS12, ProtocolVersion.TLS11])

add_psk_identity_ext(psk_id: bytearray, psk_binder: int)

Adds a Pre-Shared Key (PSK) extension to the TLS context.

PSK is used for resuming sessions or fast-forwarding handshakes.

RFC8446 - Extension value: 41

Args:: psk_id (bytearray): PSK identifier. psk_binder (int): PSK binder (HMAC) value.
Example:: psk_id = bytearray([10]) psk_binder = 32 self.add_psk_identity_ext(psk_id, psk_binder)

add_cookie_ext(cookie_payload)

Adds a Cookie extension to the TLS context.

Cookies are used in DTLS to prevent denial-of-service attacks.

RFC8446 - Extension value: 44

Args:: cookie_payload (bytes): The cookie data.
Example:: cookie_payload = b’test_cookie’ self.add_cookie_ext(cookie_payload)

add_psk_exchange_ext(mode_list: list[int])

Adds a PSK Key Exchange Modes extension to the TLS context.

This extension specifies the key exchange modes allowed with PSK.

RFC8446 - Extension value: 45

Args:: mode_list (list[int]): List of supported key exchange modes.
Example:: mode_list = [PskKeyExchangeMode.psk_dhe_ke, PskKeyExchangeMode.psk_ke] self.add_psk_exchange_ext(mode_list)

add_signature_algorithms_cert_ext()

Adds a Signature Algorithms Certificate extension to the TLS context.

This extension specifies the signature algorithms that can be used in certificates.

RFC8446 - Extension value: 50

add_key_share_ext(group_id: int, key_share: bytearray)

Adds a Key Share extension to the TLS context.

This extension is used to facilitate key exchange in TLS 1.3.

RFC8446 - Extension value: 51

Args:: group_id (int): Identifier of the supported group. key_share (bytearray): Key share data.
Example:: group_id = 0x1300 key_share = bytearray(b’«’ * 32) self.add_key_share_ext(group_id, key_share)

add_npn_ext(data: list[bytes])

Adds an unofficial Next Protocol Negotiation (NPN) extension to the TLS context.

NPN is used to negotiate the application protocol during the TLS handshake.

Note: This is an unofficial extension.

RFC xxxx - Extension value: 13172

Args:: data (list[bytes]): List of supported protocols.
Example:: data = [b’http/1.1’] self.add_npn_ext(data)

add_renegotiation_indication_ext(data: bytes = b'')

Adds a Renegotiation Indication extension to the TLS context.

This extension is used to indicate whether renegotiation is supported.

RFC5746 - Extension value: 65281

Args:: data (bytes, optional): Optional renegotiation data. Defaults to an empty byte string.
Example:: self.add_renegotiation_indication_ext(b’some_data’)

add_max_fragment_length_ext(max_length: bytearray)

Adds a Max Fragment Length extension to the TLS context.

RFC6066 - Extension value: 1

Args:

max_length (bytearray): The maximum fragment length, represented as a power of 2.: For example, a value of 2 represents 2^10 bytes.

Example:

self.add_max_fragment_length_ext(2)

add_user_mapping_ext(mapping_type: bytearray)

Adds a User Mapping extension to the TLS context.

RFC4681 - Extension value: 6

Args:: mapping_type (bytearray): The user mapping type as a bytearray.
Example:: self.add_user_mapping_ext(bytearray(b’’))

add_client_authz_ext(authz_data: bytearray)

Adds a Client Authorization extension to the TLS context.

RFC5878 - Extension value: 7

Args:: authz_data (bytearray): The client authorization data.
Example:: self.add_client_authz_ext(bytearray(b’’))

add_cert_type_ext(cert_type: bytearray)

Adds a Certificate Type extension to the TLS context.

RFC6091 - Extension value: 9

Args:: cert_type (bytearray): The type of certificate.
Example:: self.add_cert_type_ext(bytearray(b’'))

add_use_srtp_ext(srtp_profiles: bytearray)

Adds a Use SRTP extension to the TLS context.

RFC5764 - Extension value: 14

Args:: srtp_profiles (bytearray): The SRTP profiles to be used.
Example:: self.add_use_srtp_ext(bytearray(b’’))

add_status_request_v2_ext(status_data: bytearray)

Adds a Status Request V2 extension to the TLS context. This extension is used to request the status of the certificate chain, specifically

RFC6961 - Extension value: 17

Args:: status_data (bytearray): Status request data.
Example:: self.add_status_request_v2_ext(bytearray(b’'))

add_client_cert_type_ext(cert_type: bytearray)

Adds a Client Certificate Type extension to the TLS context.

RFC7250 - Extension value: 19

Args:: cert_type (bytearray): The client certificate type to be used.
Example:: self.add_client_cert_type_ext(bytearray(b’'))

add_server_cert_type_ext(cert_type: bytearray)

Adds a Server Certificate Type extension to the TLS context.

RFC7250 - Extension value: 20

Args:: cert_type (bytearray): The server certificate type to be used.
Example:: self.add_server_cert_type_ext(bytearray(b’'))

add_compress_certificate_ext(compress_algorithms: bytearray)

Adds a Compress Certificate extension to the TLS context.

RFC8879 - Extension value: 27

Args:: compress_algorithms (bytearray): The compression algorithms to be used.
Example:: self.add_compress_certificate_ext(bytearray(b’’))

add_connection_id_ext(conn_id: bytearray)

Adds a Connection ID extension to the TLS context.

RFC9146 - Extension value: 54

Args:: conn_id (bytearray): The connection ID data.
Example:: self.add_connection_id_ext(bytearray(b’'))

add_external_id_hash_ext(external_id: bytearray)

Adds an External ID Hash extension to the TLS context.

Draft RFC - Extension value: 55

Args:: external_id (bytearray): The external ID hash data.
Example:: self.add_external_id_hash_ext(bytearray(b’'))

add_external_session_id_ext(session_id: bytearray)

Adds an External Session ID extension to the TLS context.

Draft RFC - Extension value: 56

Args:: session_id (bytearray): The external session ID data.
Example:: self.add_external_session_id_ext(bytearray(b’'))

add_quic_transport_parameters_ext(quic_params: bytearray)

Adds a QUIC Transport Parameters extension to the TLS context.

RFC9001 - Extension value: 57

Args:: quic_params (bytearray): The QUIC transport parameters data.
Example:: self.add_quic_transport_parameters_ext(bytearray(b’'))

add_ticket_request_ext(request_param: bytearray)

Adds a Ticket Request extension to the TLS context.

This extension is used to request a ticket for session resumption or similar purposes.

Draft RFC - Extension value: 58

Args:: request_param (bytearray): The ticket request parameters data.
Example:: self.add_ticket_request_ext(bytearray(b’'))

add_dnssec_chain_ext(chain_data: bytearray)

Adds a DNSSEC Chain extension to the TLS context.

Draft RFC - Extension value: 59

Args:: chain_data (bytearray): The DNSSEC chain data.
Example:: self.add_dnssec_chain_ext(bytearray(b’'))

add_connection_id_deprecated_ext(conn_id: bytearray)

Adds a deprecated Connection ID extension to the TLS context.

RFC xxxx - Extension value: 53

Args:: conn_id (bytearray): Deprecated Connection ID data.
Example:: self.add_connection_id_deprecated_ext(bytearray(b’'))

add_transparency_info_ext(transparency_data: bytearray)

Adds a Transparency Info extension to the TLS context.

This extension is used for Certificate Transparency, which helps in detecting fraudulent certificates.

RFC xxxx - Extension value: 52

Args:: transparency_data (bytearray): Transparency information data.
Example:: self.add_transparency_info_ext(bytearray(b’’))

add_encrypt_then_mac_ext(data: bytearray)

Adds an Encrypt-Then-MAC extension to the TLS context.

This extension specifies the use of Encrypt-Then-MAC as a security mechanism.

RFC xxxx - Extension value: 22

Args:: data (bytearray): Encrypt-Then-MAC data.
Example:: self.add_encrypt_then_mac_ext(bytearray(b’'))

add_extended_master_secret_ext(master_secret: bytearray)

Adds an Extended Master Secret extension to the TLS context.

This extension allows the use of an extended master secret to enhance security against certain attacks.

RFC5077 - Extension value: 23

Args:: master_secret (bytearray): extended master secret.
Example:: self.add_extended_master_secret_ext(bytearray(b’'))

add_session_ticket_ext(ticket_data: bytearray)

Adds a Session Ticket extension to the TLS context.

This extension allows for session resumption by using a session ticket.

RFC xxxx - Extension value: 35

Args:: ticket_data (bytearray): Session ticket data.
Example:: self.add_session_ticket_ext(bytearray(b’'))

add_extended_random_ext(random_data: bytearray)

Adds an Extended Random extension to the TLS context.

This extension extends the random data used in the handshake to improve security.

Draft RFC - Extension value: 40

Args:: random_data (bytearray): Extended random data.
Example:: self.add_extended_random_ext(bytearray(b’'))

add_early_data_ext(early_data: bytearray)

Adds an Early Data extension to the TLS context.

This extension is used to negotiate and send early data before the handshake completes.

RFC8446 - Extension value: 42

Args:: early_data (bytearray): Early data to be sent.
Example:: self.add_early_data_ext(bytearray(b’'))

add_post_handshake_auth_ext(authentication: bytearray)

Adds a Post-Handshake Authentication extension to the TLS context.

This extension allows for authentication after the initial handshake has been completed.

RFC8446 - Extension value: 49

Args:: authentication (bytearray): authentication
Example:: self.add_post_handshake_auth_ext()

add_extension(ext_value: int | TlsExtensionType)

Adds the specified extension with dummy data to the TLS context.

This method automatically selects and adds an extension based on the provided extension value, using predefined dummy data where applicable.

Args:: ext_value (Union[int, TlsExtensionType]): The extension number or type to be added.