Tls Server Module

class mtf.network_port.tls.tls_server.TLSServer

TLSServer is responsible for setting up and managing a TLS/DTLS server instance.

This class allows for the creation, configuration, and management of secure server connections using either TLS (TCP) or DTLS (UDP) protocols. It also supports handling client connections and processing received messages with optional callback functions.

__init__(config: TLSConfigurator, callback=None)

classmethod create(config: TLSConfigurator, callback=None)

Creates a TLSServer instance with the provided configuration and optional callback.

Args:

config (TLSConfigurator): Configuration for the server. callback (function, optional): Callback function for handling received messages.

Returns:

TLSServer: Instance of the created TLSServer.

psk_server_callback(ssl_conn, identity)

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

Starts the server and listens for client connections.

is_running()

Checks if the server is currently running.

Returns:

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

accept()

Accept a connection to the specified client address using the provided configuration.

This method creates a root node that represents the connection to the client. The client’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 (AcceptConnection): The root node representing the established connection to the client.

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

Generates a TLS ServerHello 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 ServerHello message, which is sent by the server in response to the ClientHello message. The message can be customized with various parameters, including supported ciphers, TLS version, session ID, and extensions. The generated ServerHello message is then added as a child to the existing connection node.

Args:

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

Attributes:

node (ServerHelloGenerator): The node representing the generated ServerHello message.

expect_client_hello(ciphers: List[Any] | None = None)

Set up the expectation for a ClientHello message from the server.

This method configures the expectation of receiving a ClientHello message with specified parameters, such as TLS version, supported ciphers, and session ID. The expected ClientHello message will be processed according to the provided parameters.

Args:

ciphers (Optional[List[Any]], optional): List of supported cipher suites expected in the ClientHello message. Defaults to None.

generate_server_hello_done(version: ProtocolVersion | None = None)

Generates a TLS ServerHelloDone message and adds it as a child node to the current connection node.

This method generates a ServerHelloDone message, which is sent by the server to indicate the end of the server’s hello message. The generated ServerHelloDone message is then added as a child to the existing connection node.

Attributes:

node (ServerHelloDoneGenerator): The node representing the generated ServerHelloDone message.

generate_server_key_exchange(version: ProtocolVersion | None = None, identity: bytes | None = None)

Generates a TLS ServerKeyExchange 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 ServerKeyExchange message, which is sent by the server to exchange keying material or parameters with the client. The generated ServerKeyExchange message is then added as a child to the existing connection node.

Args:

version (Optional[ProtocolVersion], optional): The TLS version to use in the ServerKeyExchange message. Defaults to None. identity (Optional[bytes], optional): The identity or keying material for the ServerKeyExchange message. Defaults to None.

Attributes:

node (ServerKeyExchangeGenerator): The node representing the generated ServerKeyExchange message.

expect_client_key_exchange(version: ProtocolVersion | None = None, identity: bytes | None = None)

Set up the expectation for a ClientKeyExchange message from the server.

This method configures the expectation of receiving a ClientKeyExchange message with specified parameters, such as TLS version and identity. The expected ClientKeyExchange message will be processed according to the provided parameters.

Args:

version (Optional[ProtocolVersion], optional): The expected TLS version of the ClientKeyExchange message. Defaults to None. identity (Optional[bytes], optional): The expected identity or keying material in the ClientKeyExchange message. Defaults to None.

expect_finished_no_verify(version: ProtocolVersion | None = None)

Set up the expectation for a Finished message from the server.

This method configures the expectation of receiving a Finished message from the server, indicating the end of the handshake. It will process the Finished message according to the provided TLS version.

Args:

version (Optional[ProtocolVersion], optional): The expected TLS version of the Finished message. Defaults to None.

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_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_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.

Note:

• In TLS, this method adds a child node to the workflow to expect the ChangeCipherSpec message.

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 = True)

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.

Note:

• In TLS, this method adds a child node to the workflow to expect the ChangeCipherSpec message.

Returns:

None: This method updates the internal state of the object by adding an ExpectChangeCipherSpec 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_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.

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.

handle_message(data)

Handles received messages.

Args:

data (bytes): The received message data.

handle_client_hello(data)

Processes a “Client Hello” message.

Args:

data (bytes): The “Client Hello” message data.

check_message(data)

Validates if the received message matches the expected message.

Args:

data (bytes): The received message data.

set_expected_message(message)

Sets the expected message for validation.

Args:

message (bytes): The expected message data.

send_message(message)

Send a hello message to the client.

Parameters:

message – The message to send.

stop_server()

Stops the server and closes the socket.