Tls Client Module

class mtf.network_port.tls.tls_client.TLSClient

A class representing a TLS/DTLS client for secure communication.

This class provides methods to create, start, and manage a TLS/DTLS client connection using the specified configuration. It supports both DTLS (UDP) and TLS (TCP) protocols.

__init__(config: TLSConfigurator)

classmethod create(config: TLSConfigurator)

Creates a new instance of the TLSClient class with the provided configuration.

Args:

config (TLSConfigurator): The configuration for the client.

Returns:

TLSClient: A new instance of the TLSClient class.

psk_client_callback(ssl_conn, hint)

log_key_material_dict()

Log the contents of the key material dictionary.

This function prints each label and the associated key material stored in the key_material_dict. It helps in debugging and verifying the key material collected during the TLS sessions.

Returns:

None

start_client()

Starts the client and initiates the connection.

This method sets up the socket, initiates the SSL/TLS handshake, and sends a “Client Hello” message to the server. It handles both DTLS (UDP) and TLS (TCP) connections.

connect()

Establishes a connection to the specified server address using the provided configuration.

This method creates a root node that represents the connection to the server. The server’s address, port, and other connection parameters (such as the TLS record version and timeout) are derived from the object’s configuration. The root node is then assigned to the node attribute for further interactions.

Attributes:

node (ConnectCommand): The root node representing the established connection to the server.

generate_client_hello(ciphers: List[Any], version: ProtocolVersion | None = None, session_id: bytearray | None = None, random: bytearray | None = None, compression: List[str] | None = None, ssl2: bool = False, modifiers: List[str] | None = None)

Generates a TLS ClientHello message with the specified parameters and adds it as a child node to the current connection node.

This method allows you to configure and generate a ClientHello message, which is the first message sent by the client during the TLS handshake. The message can be customized with various parameters, including supported ciphers, TLS version, extensions, and more. The generated ClientHello message is then added as a child to the existing connection node.

Args:

ciphers (List[Any]): A list of supported cipher suites to include in the ClientHello message. version (Optional[ProtocolVersion], optional): The TLS version to use in the ClientHello message. Defaults to None. session_id (Optional[bytearray], optional): The session ID to include in the ClientHello message. Defaults to None. random (Optional[bytearray], optional): The random bytes used in the ClientHello message. Defaults to None. compression (Optional[List[str]], optional): A list of supported compression methods. Defaults to None. ssl2 (bool, optional): Whether to generate the ClientHello message in SSLv2 format. Defaults to False. modifiers (Optional[List[str]], optional): A list of modifiers to alter the ClientHello generation process. Defaults to None.

Attributes:

node (ClientHelloGenerator): The node representing the generated ClientHello message.

generate_client_key_exchange(cipher: Any | None = None, version: ProtocolVersion | None = None, client_version: ProtocolVersion | None = None, dh_yc: int | None = None, ecdh_yc: bytearray | None = None, premaster_secret: bytearray | None = None, padding_byte: int | None = None, reuse_encrypted_premaster: bool = False, encrypted_premaster_file: str | None = None, encrypted_premaster_length: int | None = None, random_premaster: bool = False)

Generates a Client Key Exchange message for the TLS handshake.

This method creates a key exchange message based on the specified parameters, which are used during the TLS handshake to establish shared secrets between the client and server.

Parameters:

cipher (Optional[Any]): The cipher suite to be used for the key exchange. If not specified, a default cipher will be used. version (Optional[ProtocolVersion]): The TLS version to be used. If not specified, a default version will be used. client_version (Optional[ProtocolVersion]): The client version for compatibility purposes. If not specified, defaults to the version parameter. dh_yc (Optional[int]): The public value for Diffie-Hellman key exchange. Required for DH key exchange. ecdh_yc (Optional[bytearray]): The public value for Elliptic Curve Diffie-Hellman key exchange. Required for ECDH key exchange. premaster_secret (Optional[bytearray]): The premaster secret to be used if provided. If not provided, will generate a new premaster secret. padding_byte (Optional[int]): Byte value for padding in the key exchange. If not specified, defaults to a standard padding byte. reuse_encrypted_premaster (bool): Flag indicating if the encrypted premaster secret should be reused. Defaults to False. encrypted_premaster_file (Optional[str]): Path to a file containing the encrypted premaster secret. If provided, this file will be used. encrypted_premaster_length (Optional[int]): Length of the encrypted premaster secret. Required if encrypted_premaster_file is provided. random_premaster (bool): Flag indicating if a random premaster secret should be generated. Defaults to False.

expect_server_key_exchange(version: ProtocolVersion | None = None, cipher_suite: Any | None = None, valid_sig_algs: List[int] | None = None, valid_groups: List[int] | None = None, valid_params: Set[tuple[int, int]] | None = None)

Configures the expectation for a Server Key Exchange message in the TLS handshake.

This method sets up the expected attributes of the Server Key Exchange message, including version, cipher suite, valid signature algorithms, valid groups, and parameters.

Parameters:

version (Optional[ProtocolVersion]): The TLS version expected in the Server Key Exchange message. If not specified, defaults to the version used in the handshake. cipher_suite (Optional[Any]): The expected cipher suite for the key exchange. If not specified, defaults to any valid cipher suite. valid_sig_algs (Optional[List[int]]): List of valid signature algorithms expected in the Server Key Exchange message. If not specified, defaults to all valid algorithms. valid_groups (Optional[List[int]]): List of valid groups (e.g., elliptic curves) for key exchange expected in the Server Key Exchange message. If not specified, defaults to all valid groups. valid_params (Optional[Set[tuple[int, int]]]): Set of explicit expected parameters used by the server, where the first element of the tuple is the expected generator and the second is the prime used for the DH calculation. Applicable only to ciphersuites that use FFDHE key exchange.

expect_alert(level: AlertLevel, description: AlertDescription)

Adds a node to expect a specific TLS alert.

Parameters:

level (AlertLevel): The level of the alert (e.g., warning or fatal) represented as an AlertLevel enum. description (AlertDescription): The description code for the alert represented as an AlertDescription enum.

Notes:

• Ensure that level and description correspond to valid TLS alert codes as defined in the AlertLevel and AlertDescription enums.

expect_server_hello(extensions: List[int | TlsExtensionType] | None = None, version: ProtocolVersion | None = None, resume: bool = False, cipher: Any | None = None, server_max_protocol: ProtocolVersion | None = None, force_resume: bool = False, description: Any | None = None)

Adds a node to expect a ServerHello message with the specified parameters.

Parameters:

extensions Optional[List[Union[int, TlsExtensionType]]]: List of expected extensions in the ServerHello message. Defaults to None. version (Optional[ProtocolVersion]): Expected TLS version. Defaults to None. resume (bool): Whether the server should resume the session. Defaults to False. cipher (Optional[Any]): Expected cipher suite. Defaults to None. server_max_protocol (Optional[ProtocolVersion]): Maximum protocol version supported by the server. Defaults to None. force_resume (bool): Whether to force session resumption. Defaults to False. description (Optional[Any]): Description or custom data for the ServerHello. Defaults to None.

expect_server_hello_done()

Adds a node to expect a ServerHelloDone message.

Notes:

• The ServerHelloDone message indicates that the server has finished sending its messages

for the first phase of the handshake.

generate_alert(level: AlertLevel, description: AlertDescription)

Adds a node to generate a TLS alert with the specified level and description.

Parameters:

level (AlertLevel): The severity level of the alert, such as ‘warning’ or ‘fatal’. description (AlertDescription): The specific description of the alert, such as ‘close_notify’ or ‘unexpected_message’.

expect_change_cipher_spec()

Adds a node to expect a ChangeCipherSpec message.

This method configures the current node to expect a ChangeCipherSpec message during the TLS handshake. It sets up the expectation for this specific message type.

Returns:

None: This method updates the internal state of the object by adding an ExpectChangeCipherSpec child to the current node.

generate_change_cipher_spec(extended_master_secret: Any | None = None, fake: bool = False)

Adds a node to generate a ChangeCipherSpec message with optional parameters.

This method configures the current node to generate a ChangeCipherSpec message during the TLS handshake. The message can be customized with an optional extended master secret and can be flagged as fake if needed.

Args:

extended_master_secret (Optional[Any], optional): An optional extended master secret for the ChangeCipherSpec message. Defaults to None. fake (bool, optional): Whether to generate a fake ChangeCipherSpec message. Defaults to False.

Returns:

None: This method updates the internal state of the object by adding a ChangeCipherSpecGenerator child to the current node.

generate_finished(trunc_start: int = 0, trunc_end: int | None = None, pad_byte: int = 0, pad_left: int = 0, pad_right: int = 0) → None

Adds a node to generate a Finished message with options to corrupt the verify_data.

This method configures the current node to generate a Finished message during the TLS handshake and allows optional corruption of the verify_data via truncation or padding.

Args:

trunc_start (int): The starting index for truncating the verify_data. Default is 0. trunc_end (Optional[int]): The ending index for truncating the verify_data. Default is None (no truncation). pad_byte (int): The byte value used for padding. Default is 0. pad_left (int): The number of padding bytes to add to the left of the verify_data. Default is 0. pad_right (int): The number of padding bytes to add to the right of the verify_data. Default is 0.

Returns:

None: This method updates the internal state of the object by adding a FinishedGenerator child to the current node.

expect_finished()

Adds a node to expect a Finished message.

This method configures the current node to expect a Finished message during the TLS handshake.

Returns:

None: This method updates the internal state of the object by adding an ExpectFinished child to the current node.

generate_application_data(data: bytearray | None = bytearray(b''))

Adds a node to generate an Application Data message.

This method configures the current node to generate an Application Data message during the TLS connection.

Args:

data (bytearray, optional): The application data to send. Default is an empty byte string.

Returns:

None: This method updates the internal state of the object by adding an ApplicationDataGenerator child to the current node.

expect_application_data()

Adds a node to expect an Application Data message.

This method configures the current node to expect an Application Data message during the TLS connection.

Returns:

None: This method updates the internal state of the object by adding an ExpectApplicationData child to the current node.

start_handshake()

Starts the TLS handshake process by running the handshake sequence with the current root node.

Raises:

Exception: If an error occurs during the handshake process.

log_handshake_progress(conn)

Log the current state of the SSL handshake.

Parameters:

conn – The SSL connection object.

is_running()

Checks if the client is currently running.

Returns:

bool: True if the client is running, False otherwise.

stop_client()

Stops the client and closes the connection.

This method shuts down the socket, if connected, and cleans up resources.

cleanup()

send_message(message)

Sends a message to the server.

Args:

message (bytes): The message to be sent.

send_hello_message()

Sends Hello from client! message to the server.

check_message(expected_message)

Checks if the received message matches the expected message.

Args:

expected_message (bytes): The expected message to be received.

set_expected_message(message)

Sets the expected message to be received.

Args:

message (bytes): The expected message.