Tls Helpers Module

mtf.network_port.tls.tls_helpers.render_template(template_name: str, output_name: str, context: dict) → str

Renders a Jinja2 template and writes it to a file.

Args:

template_name (str): Name of the template file.

output_name (str): Name of the output XML file.

context (dict): Context dictionary for rendering the template.

Returns:

str: The file path to the generated XML configuration.

mtf.network_port.tls.tls_helpers.prepare_server_config(**kwargs) → str

Generates a server XML configuration using Jinja2 templates.

mtf.network_port.tls.tls_helpers.prepare_client_config(**kwargs) → str

Generates a client XML configuration using Jinja2 templates.

class mtf.network_port.tls.tls_helpers.BaseTlsManager

The BaseTlsManager class provides fundamental methods and attributes common to all concrete TLS manager implementations. Its primary purpose is to serve as an interface and utility provider, rather than implementing any actual TLS handshake logic directly.

Subclasses should extend this class to handle specific roles (client or server) and responsibilities (e.g., managing TLS handshakes, processing messages, maintaining session state).

__init__(target_ip: str | None, target_port: int | None, psk_key: str, psk_identity: str, session_id: str | None, cipher: str | List[str] | None, dtls_version: ProtocolVersion, timeout: float, send_handshake_messages_within_single_record: bool = False, tls_attacker_apps_path: str | None = None, psk_hint: str | None = None, source_ip: str | None = None, source_port: int | None = None)

set_default_psk_sets_in_java(psk_sets_data: list) → JClass

Creates a Java ArrayList containing multiple PskSet objects configured with the given PSK data. If ticket_age is not provided, it defaults to 1.

Args:

psk_sets_data (list): A list of tuples, where each tuple contains (pre_shared_key_identity,

pre_shared_key, ticket_age). Each value should be a string. If ticket_age is not provided, it will default to 1.

Returns:

jpype.JClass: A Java ArrayList containing the configured PskSet objects.

Raises:

ValueError: If the psk_sets_data list is empty or any of the required PSK set data elements are missing or invalid.

set_server_name_in_java(server_name_str: str, server_name_type: int = 0)

Creates a Java ArrayList containing a ServerNamePair object configured with the given server name and server name type.

Args:

server_name_str (str): The server name to set in the ServerNamePair. server_name_type (int): The server name type, provided as a byte value (default is 0).

Returns:

jpype.JClass: A Java ArrayList containing the configured ServerNamePair.

Raises:

ValueError: If the server name string is empty or the server name type is not within byte range.

prepare_ciphers_for_argument(ciphers: str | List[str]) → str

Prepares a string representation of the cipher(s) to be passed as an argument to the TLS-Attacker client.

Args:

ciphers (Union[str, List[str]]): A single cipher (as a string) or a list of ciphers.

Returns:

str: A comma-separated string of cipher names in IANA format.

add_extension(extension_type: TlsExtensionType, value: Any | None = None, status: bool | None = True) → None

Adds or configures a TLS extension for the client or server.

This method enables a specified TLS extension and optionally assigns a value to its associated property. If the extension is not supported or an error occurs, it logs an appropriate error message.

Args:

extension_type (TlsExtensionType): The type of the TLS extension to be added.

value (Optional[Any]): The value to set for the extension, if applicable. Defaults to None.

status (Optional[bool]): The status indicating whether the extension should be enabled or disabled. Defaults to True.

Returns:

None

set_extension_property(property_name: str, value: Any) → None

Abstract method to set extension properties.

send_action(message_types: list[TlsMessage], message_properties: dict | None = None, with_extensions=True) → None

Dynamically sends a series of TLS messages from/to the server/client during a handshake, with optional properties for each message type.

Args:

message_types (list[TlsMessage]): A list of TlsMessage enum members representing the

message types to send.

message_properties (dict, optional): A dictionary where keys are TlsMessage types and values are

dictionaries of properties to set (e.g., {‘verify_data’: b’…’}).

with_extensions (bool, optional): A flag indicating whether to include extensions

in the TLS messages. Defaults to True.

get_config(message_type: TlsMessage)

Should be implemented by subclasses to provide the appropriate configuration.

receive_action(message_types: list[TlsMessage]) → None

Dynamically receives a series of TLS/DTLS messages from/to the server/client during a handshake.

Args:

message_types (list[TlsMessage]): A list of TlsMessage enum members

representing the message types to receive.

activate_encryption() → None

Should be implemented by subclasses to handle client/server-specific receive actions.

deactivate_encryption()

Should be implemented by subclasses to handle client/server-specific receive actions.

add_wait_action(delay_ms: int) → None

Adds a wait action to pause for the specified duration.

Args:

delay_ms (int): The delay in milliseconds to wait.

shutdown() → None

Shuts down the JVM if it is currently running.

get_message_class(msg_type) → Any

Identifies and retrieves the class of a specific message type from the list of exchanged messages.

Args:

msg_type: The type of the message to be matched.

Returns:

The message class that matches the specified message type.

get_messages()

Should be implemented by subclasses to handle client/server-specific received/sent messages.

check_message_class(message) → Any

Maps a specific TLS message type to its corresponding class and initializes it with the provided message data.

Args:

message: The raw message object containing the data to be mapped and processed.

Returns:

An instance of the corresponding message class initialized with the relevant attributes.

class mtf.network_port.tls.tls_helpers.TlsClientManager

The TlsClientManager class extends BaseTlsManager, providing the client-side logic necessary for initiating and handling a TLS handshake. It manages the sending and receiving of TLS messages, coordinates state transitions, and maintains client-specific session information.

__init__(**kwargs)

set_extension_property(property_name: str, value: Any) → None

Sets a property for the TLS client.

get_config(message_type: TlsMessage)

Provides the client-specific configuration.

start_client()

Starts the TLS-Attacker client.

get_messages() → Any

Retrieves all messages exchanged with the TLS server, including both received and sent messages.

Returns:

A combined list of messages, where the first part contains the received messages and the second part contains the sent messages.

reset_connection()

Resets the connection of the TLS-Attacker client.

activate_encryption() → None

Activates the encryption in the handshake

deactivate_encryption() → None

Deactivates the encryption in the handshake

add_extension(extension_type: TlsExtensionType, value: Any | None = None, status: bool | None = True) → None

Adds or configures a TLS extension for the client or server.

This method enables a specified TLS extension and optionally assigns a value to its associated property. If the extension is not supported or an error occurs, it logs an appropriate error message.

Args:

extension_type (TlsExtensionType): The type of the TLS extension to be added.

value (Optional[Any]): The value to set for the extension, if applicable. Defaults to None.

status (Optional[bool]): The status indicating whether the extension should be enabled or disabled. Defaults to True.

Returns:

None

add_wait_action(delay_ms: int) → None

Adds a wait action to pause for the specified duration.

Args:

delay_ms (int): The delay in milliseconds to wait.

check_message_class(message) → Any

Maps a specific TLS message type to its corresponding class and initializes it with the provided message data.

Args:

message: The raw message object containing the data to be mapped and processed.

Returns:

An instance of the corresponding message class initialized with the relevant attributes.

get_message_class(msg_type) → Any

Identifies and retrieves the class of a specific message type from the list of exchanged messages.

Args:

msg_type: The type of the message to be matched.

Returns:

The message class that matches the specified message type.

prepare_ciphers_for_argument(ciphers: str | List[str]) → str

Prepares a string representation of the cipher(s) to be passed as an argument to the TLS-Attacker client.

Args:

ciphers (Union[str, List[str]]): A single cipher (as a string) or a list of ciphers.

Returns:

str: A comma-separated string of cipher names in IANA format.

receive_action(message_types: list[TlsMessage]) → None

Dynamically receives a series of TLS/DTLS messages from/to the server/client during a handshake.

Args:

message_types (list[TlsMessage]): A list of TlsMessage enum members

representing the message types to receive.

send_action(message_types: list[TlsMessage], message_properties: dict | None = None, with_extensions=True) → None

Dynamically sends a series of TLS messages from/to the server/client during a handshake, with optional properties for each message type.

Args:

message_types (list[TlsMessage]): A list of TlsMessage enum members representing the

message types to send.

message_properties (dict, optional): A dictionary where keys are TlsMessage types and values are

dictionaries of properties to set (e.g., {‘verify_data’: b’…’}).

with_extensions (bool, optional): A flag indicating whether to include extensions

in the TLS messages. Defaults to True.

set_default_psk_sets_in_java(psk_sets_data: list) → JClass

Creates a Java ArrayList containing multiple PskSet objects configured with the given PSK data. If ticket_age is not provided, it defaults to 1.

Args:

psk_sets_data (list): A list of tuples, where each tuple contains (pre_shared_key_identity,

pre_shared_key, ticket_age). Each value should be a string. If ticket_age is not provided, it will default to 1.

Returns:

jpype.JClass: A Java ArrayList containing the configured PskSet objects.

Raises:

ValueError: If the psk_sets_data list is empty or any of the required PSK set data elements are missing or invalid.

set_server_name_in_java(server_name_str: str, server_name_type: int = 0)

Creates a Java ArrayList containing a ServerNamePair object configured with the given server name and server name type.

Args:

server_name_str (str): The server name to set in the ServerNamePair. server_name_type (int): The server name type, provided as a byte value (default is 0).

Returns:

jpype.JClass: A Java ArrayList containing the configured ServerNamePair.

Raises:

ValueError: If the server name string is empty or the server name type is not within byte range.

shutdown() → None

Shuts down the JVM if it is currently running.

class mtf.network_port.tls.tls_helpers.TlsServerManager

The TlsServerManager class extends BaseTlsManager, providing the server-side logic necessary for responding to client-initiated TLS handshakes. It manages the reception and processing of TLS messages, coordinates server-side state transitions, and maintains server-specific session information.

__init__(**kwargs)

set_extension_property(property_name: str, value: Any) → None

Sets a property for the TLS server.

get_config(message_type: TlsMessage)

Provides the server-specific configuration.

start_server()

Starts the TLS-Attacker server.

get_session_list() → Any

Retrieves the list of active TLS sessions from the server.

Returns:

Any: The list of active TLS sessions.

get_messages() → Any

Retrieves all messages exchanged with the TLS client, including both received and sent messages.

Returns:

A combined list of messages, where the first part contains the received messages and the second part contains the sent messages.

activate_encryption() → None

Activates the encryption in the handshake

deactivate_encryption() → None

Deactivates the encryption in the handshake

add_extension(extension_type: TlsExtensionType, value: Any | None = None, status: bool | None = True) → None

Adds or configures a TLS extension for the client or server.

This method enables a specified TLS extension and optionally assigns a value to its associated property. If the extension is not supported or an error occurs, it logs an appropriate error message.

Args:

extension_type (TlsExtensionType): The type of the TLS extension to be added.

value (Optional[Any]): The value to set for the extension, if applicable. Defaults to None.

status (Optional[bool]): The status indicating whether the extension should be enabled or disabled. Defaults to True.

Returns:

None

add_wait_action(delay_ms: int) → None

Adds a wait action to pause for the specified duration.

Args:

delay_ms (int): The delay in milliseconds to wait.

check_message_class(message) → Any

Maps a specific TLS message type to its corresponding class and initializes it with the provided message data.

Args:

message: The raw message object containing the data to be mapped and processed.

Returns:

An instance of the corresponding message class initialized with the relevant attributes.

get_message_class(msg_type) → Any

Identifies and retrieves the class of a specific message type from the list of exchanged messages.

Args:

msg_type: The type of the message to be matched.

Returns:

The message class that matches the specified message type.

prepare_ciphers_for_argument(ciphers: str | List[str]) → str

Prepares a string representation of the cipher(s) to be passed as an argument to the TLS-Attacker client.

Args:

ciphers (Union[str, List[str]]): A single cipher (as a string) or a list of ciphers.

Returns:

str: A comma-separated string of cipher names in IANA format.

receive_action(message_types: list[TlsMessage]) → None

Dynamically receives a series of TLS/DTLS messages from/to the server/client during a handshake.

Args:

message_types (list[TlsMessage]): A list of TlsMessage enum members

representing the message types to receive.

send_action(message_types: list[TlsMessage], message_properties: dict | None = None, with_extensions=True) → None

Dynamically sends a series of TLS messages from/to the server/client during a handshake, with optional properties for each message type.

Args:

message_types (list[TlsMessage]): A list of TlsMessage enum members representing the

message types to send.

message_properties (dict, optional): A dictionary where keys are TlsMessage types and values are

dictionaries of properties to set (e.g., {‘verify_data’: b’…’}).

with_extensions (bool, optional): A flag indicating whether to include extensions

in the TLS messages. Defaults to True.

set_default_psk_sets_in_java(psk_sets_data: list) → JClass

Creates a Java ArrayList containing multiple PskSet objects configured with the given PSK data. If ticket_age is not provided, it defaults to 1.

Args:

psk_sets_data (list): A list of tuples, where each tuple contains (pre_shared_key_identity,

pre_shared_key, ticket_age). Each value should be a string. If ticket_age is not provided, it will default to 1.

Returns:

jpype.JClass: A Java ArrayList containing the configured PskSet objects.

Raises:

ValueError: If the psk_sets_data list is empty or any of the required PSK set data elements are missing or invalid.

set_server_name_in_java(server_name_str: str, server_name_type: int = 0)

Creates a Java ArrayList containing a ServerNamePair object configured with the given server name and server name type.

Args:

server_name_str (str): The server name to set in the ServerNamePair. server_name_type (int): The server name type, provided as a byte value (default is 0).

Returns:

jpype.JClass: A Java ArrayList containing the configured ServerNamePair.

Raises:

ValueError: If the server name string is empty or the server name type is not within byte range.

shutdown() → None

Shuts down the JVM if it is currently running.