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.

has_valid_psk()

Check if PSK identity or key is configured.

psk_client_callback(ssl_conn, hint)

Handles the PSK (Pre-Shared Key) callback when the server requests the PSK.

This method is invoked during the TLS handshake when the server requires a pre-shared key. It retrieves the PSK identity and key from the client’s configuration and optionally logs the server’s PSK hint if provided.

Args:

ssl_conn (SSL.Connection): The SSL/TLS connection object associated with the handshake.

hint (bytes): The PSK hint provided by the server, or an empty bytes

object if no hint is given.

Returns:

tuple: A tuple containing the PSK identity (str) and PSK key (bytes)

as configured in the client.

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(session: Session | None = None, session_list=None)

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.

Args:

session (Optional[Session]): A session defines certain connection parameters which may be re-used to speed up the setup of subsequent connections.

generate_client_hello(with_extensions=True, protocol_version: bytes | None = None, unix_time: bytes | None = None, random: bytes | None = None, session_id_length: int | None = None, session_id: bytes | None = None, compression_length: int | None = None, cipher_suite_length: int | None = None, cipher_suites: bytes | None = None, compressions: bytes | None = None, cookie: bytes | None = None, cookie_length: int | None = None) → None

Configures and generates a TLS/DTLS ClientHello message with customizable parameters.

This method constructs a ClientHello message, which is the initial message sent by the client during the TLS/DTLS handshake process. The ClientHello message contains information about the client’s capabilities and preferences, such as supported cipher suites, compression methods, and extensions.

Args:

with_extensions (bool): Indicates whether to include extensions in the ClientHello message. Defaults to True.

protocol_version (bytes, optional): Specifies the protocol version to use in the message. Defaults to None.

unix_time (bytes, optional): The Unix timestamp to include in the random field of the ClientHello. Defaults to None.

random (bytes, optional): A random value to use in the ClientHello’s

random field. Overrides unix_time if set. Defaults to None.

session_id_length (int, optional): The length of the session ID to include in the message. Defaults to None.

session_id (bytes, optional): The session ID to include in the ClientHello message. Defaults to None.

compression_length (int, optional): The number of compression methods listed in the message. Defaults to None.

cipher_suite_length (int, optional): The number of cipher suites supported by the client. Defaults to None.

cipher_suites (bytes, optional): Specifies the cipher suites supported by the client. Defaults to None.

compressions (bytes, optional): Specifies the compression methods supported by the client. Defaults to None.

cookie (bytes, optional): A cookie value for DTLS handshakes to prevent denial-of-service attacks. Defaults to None.

cookie_length (int, optional): The length of the cookie in the ClientHello message. Defaults to None.

generate_client_key_exchange(identity_length: int | None = None, identity: bytes | None = None) → None

Configures and generates a TLS/DTLS ClientKeyExchange message with customizable parameters.

This method creates a ClientKeyExchange message, which is sent by the client during the TLS/DTLS handshake to establish shared secrets with the server. The message includes keying material or an identifier used to derive the shared keys.

Args:

identity_length (int, optional): The length of the identity or keying material in bytes. If not specified, it will be calculated based on the provided identity. Defaults to None.

identity (bytes, optional): The identity or keying material used for key exchange. This is typically a public key or pre-shared key. Defaults to None.

expect_server_key_exchange()

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

expect_alert()

Configures the expectation for a specific TLS alert.

expect_server_hello()

Configures the expectation for a ServerHello message

expect_server_hello_done()

Configures the expectation for a ServerHelloDone message.

generate_alert(level: AlertLevel, description: AlertDescription) → None

Generates a TLS/DTLS 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()

Configures the expectation for 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.

generate_change_cipher_spec(ccs_protocol_type: bytes | None = None) → None

Configures and generates a TLS/DTLS ChangeCipherSpec message.

This method prepares the current node to generate a ChangeCipherSpec message during the TLS/DTLS handshake. The ChangeCipherSpec message is used to indicate that subsequent messages will be encrypted and integrity-protected using the newly negotiated cipher suite and keys.

Args:

ccs_protocol_type (bytes, optional): Specifies the protocol type for the ChangeCipherSpec message.

If not provided, a default protocol type will be used. Defaults to None.

generate_finished(verify_data: bytes | None = None) → None

Generates a TLS/DTLS 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.

Args:

verify_data (bytes, optional): Data to set in the Finished message’s verifyData field.

expect_finished()

Configures the expectation for a Finished message.

expect_hello_verify_request()

Configures the expectation for a HelloVerifyRequest message.

This method sets up the DTLS manager to expect a HelloVerifyRequest message during the DTLS handshake process. This method is only relevant for DTLS connections and does not modify the behavior for non-DTLS protocols.

Returns:

None: The DTLS manager is configured to expect the HelloVerifyRequest message.

expect_message_sequence(messages: List[TlsMessage]) → None

Receives a sequence of TLS messages specifically for TLS/DTLS.

This method is used in TLS/DTLS to expect a sequence of TlsMessage objects.

Args:

messages (List[TlsMessage]): A list of TlsMessage objects to be expected sequentially.

Returns:

None

generate_application_data() → None

Configures the expectation for an Application Data message.

This method generate an Application Data message during the TLS/DTLS connection.

expect_application_data()

Configures the expectation for an Application Data message.

This method expect an Application Data message during the TLS/DTLS connection.

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()

Cleans up resources and closes the TLS connection and socket.

This method ensures that the TLS connection and the client socket are properly shut down and released. It also handles any errors encountered during the cleanup process and logs them accordingly.

Args:

None

Returns:

None

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.

get_session()

Retrieves the current TLS session.

This method returns the current TLS session object, which can be used for session resumption or other purposes.

Returns:

SSL.Session: The current TLS session object.

get_message_class(msg_type) → Any

Retrieves the class corresponding to a specific message type.

Args:

msg_type: The type of the message to look up.

Returns:

The class associated with the given message type, as determined by the server TLS manager.

generate_reset_connection() → None

Generates a reset connection action for TLS/DTLS.

activate_encryption()

Activate TLS encryption for the client.

This method calls the client TLS manager to enable encryption for all subsequent communication.

deactivate_encryption()

Deactivate TLS encryption for the client.

This method calls the client TLS manager to disable encryption, reverting communication to an unencrypted state.

renegotiation()

Generates a renegotiation action for TLS/DTLS.

get_session_list() → Any

Retrieves the list of active TLS sessions from the client.

Returns:

Any: The list of active TLS sessions.

get_session_id() → Any

Retrieves the session ID setted by the server.

Returns:

Any: The current session ID