TLSServer

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.

has_valid_psk()

Check if PSK identity or key is configured.

psk_server_callback(ssl_conn, identity)

Handles the PSK (Pre-Shared Key) callback when a client attempts to connect using PSK.

This method is invoked during the TLS handshake to authenticate a client based on its provided identity. If the client’s identity matches the configured PSK identity, the corresponding PSK key is returned. Otherwise, the connection is rejected.

Args:

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

identity (str): The PSK identity provided by the client.

Returns:

bytes: The PSK key if the client’s identity matches the configured PSK identity. None: If the client’s identity does not match the configured PSK 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.

generate_server_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, selected_cipher_suites: bytes | None = None, selected_compression_method: bytes | None = None, auto_set_hello_retry_mode_in_key_share: bool | None = None) → None

Configures and generates a TLS/DTLS ServerHello message with options to customize its content.

This method sets up a ServerHello message that the server sends in response to a ClientHello message during the TLS handshake. It provides flexibility to configure various parameters of the ServerHello message.

Args:

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

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

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

random (bytes, optional): A random value to use in the ServerHello’s random field. Overrides unix_time if set.

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

session_id (bytes, optional): The session ID to use in the ServerHello message.

selected_cipher_suites (bytes, optional): Specifies the cipher suite chosen by the server.

selected_compression_method (bytes, optional): Specifies the compression method selected by the server.

auto_set_hello_retry_mode_in_key_share (bool, optional): Enables or disables automatic handling of HelloRetryRequest mode for key share extensions. Defaults to None.

expect_client_hello()

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

This method configures the expectation of receiving a ClientHello message.

generate_server_hello_done() → None

Generates a TLS ServerHelloDone message.

This method generates a ServerHelloDone message, which is sent by the server to indicate the end of the server’s hello message.

generate_server_key_exchange(identity_hint: bytes | None = None, identity_hint_length: int | None = None) → None

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

This method sets up a ServerKeyExchange message, which is sent by the server during the TLS handshake to exchange keying material or parameters with the client. It provides flexibility to include an optional identity hint and its length.

Args:

identity_hint (bytes, optional): A hint or identifier provided by the server to assist in selecting a shared secret or keying material. Defaults to None.

identity_hint_length (int, optional): The length of the identity hint in bytes. If not specified, it will be calculated based on the provided identity_hint. Defaults to None.

expect_client_key_exchange()

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

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

Set up the expectation for a specific TLS/DTLS alert.

expect_change_cipher_spec()

Set up the expectation for a ChangeCipherSpec message.

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 value will be used. Defaults to None.

expect_finished()

Set up the expectation for a Finished message.

generate_encrypted_extensions() → None

Generates and sends the TLS 1.3 EncryptedExtensions message to the client.

In TLS 1.3, the EncryptedExtensions message is used by the server to provide additional information to the client after the ServerHello has been sent, such as ALPN protocols, server certificate extensions, or other server-specific parameters. This method delegates to the server’s TLS manager to handle the actual sending of the message.

Returns:

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.

generate_hello_verify_request(protocol_version: bytes | None = None, cookie_length: bytes | None = None, cookie: bytes | None = None) → None

Configures and generates a DTLS HelloVerifyRequest message with customizable parameters.

This method sets up the DTLS manager to generate a HelloVerifyRequest message during the DTLS handshake process. The HelloVerifyRequest message is used in DTLS to prevent denial-of-service attacks by ensuring the client can respond to the server with a valid cookie. This method is only applicable to DTLS connections and does not affect non-DTLS protocols.

Args:

protocol_version (bytes, optional): Specifies the protocol version to use in the HelloVerifyRequest message. If not provided, a default version will be used. Defaults to None.

cookie_length (bytes, optional): Specifies the length of the cookie in the HelloVerifyRequest message. If not provided, it will be calculated based on the cookie parameter. Defaults to None.

cookie (bytes, optional): The cookie value to include in the HelloVerifyRequest message. Defaults to None.

expect_message_sequence(messages: List[TlsMessage]) → None

Receives a sequence of TLS/DTLS messages specifically for 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

Generates a TLS/DTLS an Application Data message.

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

expect_application_data()

Set up the expectation for an Application Data message.

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.

get_session_list() → Any

Retrieves the list of active TLS sessions from the server.

Returns:

Any: The list of active TLS sessions.

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.

activate_encryption()

Activate TLS encryption for the server.

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

deactivate_encryption()

Deactivate TLS encryption for the server.

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