MessageDHCP

Summary

Represents a DHCP Message object.

Methods: MessageDHCP.ack_ip()

MessageDHCP.add_lease_time()

MessageDHCP.add_option()

MessageDHCP.add_to_option()

MessageDHCP.capture()

MessageDHCP.capture_list()

MessageDHCP.clear_options()

MessageDHCP.close_writer()

MessageDHCP.delete_option()

MessageDHCP.discover()

MessageDHCP.get_all_bytes()

MessageDHCP.get_bytes()

MessageDHCP.get_hex_bytes()

MessageDHCP.get_option()

MessageDHCP.has_option()

MessageDHCP.hex_view()

MessageDHCP.is_segmented()

MessageDHCP.offer_ip()

MessageDHCP.open_writer()

MessageDHCP.receive()

MessageDHCP.receive_list()

MessageDHCP.request_ip()

MessageDHCP.send()

MessageDHCP.send_receive()

MessageDHCP.send_receive_list()

MessageDHCP.set_all_bytes()

MessageDHCP.set_bytes()

MessageDHCP.start_capture()

MessageDHCP.start_responding_machine()

MessageDHCP.stop_capture()

MessageDHCP.stop_responding_machine()

MessageDHCP.store()

MessageDHCP.tree_view()
Properties: MessageDHCP.allOptionTypes

MessageDHCP.assigned_ip_address

MessageDHCP.capture_info

MessageDHCP.ciaddr

MessageDHCP.client_mac_address

MessageDHCP.data_base

MessageDHCP.elapsed_time

MessageDHCP.ethernet_header

MessageDHCP.file

MessageDHCP.flags

MessageDHCP.frame_number

MessageDHCP.giaddr

MessageDHCP.hlen

MessageDHCP.hops

MessageDHCP.htype

MessageDHCP.ip_header

MessageDHCP.ipv4_header

MessageDHCP.ipv6_header

MessageDHCP.mode

MessageDHCP.network_protocol

MessageDHCP.op

MessageDHCP.option_bytes

MessageDHCP.payload

MessageDHCP.server_name

MessageDHCP.siaddr

MessageDHCP.timestamp

MessageDHCP.transport_header

MessageDHCP.transport_protocol

MessageDHCP.udp_header

MessageDHCP.vlan_tag

MessageDHCP.xid
Events: MessageDHCP.on_capture_start()

MessageDHCP.on_capture_stop()

MessageDHCP.on_message_received()

Structure

class MessageDHCP

ack_ip(ip: str, server_ip: str, subnet_mask: str, mac_client: str)

Creates a DHCPACK message.

Parameters

ip (str) – IP address assigned to the client.
server_ip (str) – Server IP address. It will be added to the options of the message.
subnet_mask (str) – Subnet mask. Like the server address, it will be added to the options of the message.
mac_client (str) – Hardware address of the client.

add_lease_time(seconds: int32)

Adds to the options array the lease time specified. Used by the server in DHCPOFFER and DHCPACK messages.

Parameters: seconds (int32) – Minimum amount of time an IP address will be allocated.

add_option(tag: uint8, data: IList[uint8])

Add a generic option to the message.

Parameters

tag (uint8) – The type of the option.
data (IList[uint8]) – The data of the option.

add_option(tag: uint8, value: int64, size: uint8)

Add a generic option to the message.

Parameters

tag (uint8) – The type of the option.
value (int64) – The value of the option.
size (uint8) – The size of the option.

add_to_option(byte_array: Array[uint8])

Adds the specified bytes to the options array, the bytes will be decoded as options.

Parameters: byte_array (Array[uint8]) – Bytes containing the information to add to the options array.

capture(filter: Filter = None) → MessageDHCP

Matches any message with the same protocol.

Parameters: filter (Filter) – Filter to use to narrow down packets to capture
Returns: Listens to the bus until a message is received and returns this first message
Return type: MessageDHCP

capture(timeout: int32, filter: Filter = None) → MessageDHCP

Waits for the first message having the same protocol that the sent message without verify the IP address and the port between send and respond message and return it. A timeout is specified to guarantee that the script can continue if no message is captured in a certain time interval.

Parameters

timeout (int32) – Max time in milliseconds to wait for the response.
filter (Filter) – Filter to use to narrow down packets to capture

Returns

First message captured from the bus or None in case no message is received.

Return type

MessageDHCP

capture_list(timeout: int32, filter: Filter = None) → IReadOnlyList[MessageDHCP]

Waits for any response having the same protocol that the sent message without verify the IP address and the port between send and respond message and return them all as a list. A timeout is specified to guarantee that the script can continue if no message is received in a certain time interval.

Parameters

timeout (int32) – Max time in milliseconds to wait for the response.
filter (Filter) – Filter to use to narrow down packets to capture

Returns

List of messages captured from the bus during a given period of time.

Return type

IReadOnlyList[MessageDHCP]

clear_options(): Clear the options of the message.

close_writer(): Closes the file previously created with open_writer(file).

delete_option(tag: uint8)

Delete an option from the message if it's found.

Parameters: tag (uint8) – The type of the option to delete.

discover(time_out: int32) → IMessageBase

Creates a DHCPDISCOVER message and waits for a response from the DHCP server. It is possible to specify the desired IP address in order to check if it is still available.

Parameters: time_out (int32) – Max time to wait for a response to discover the message.
Returns: DHCP message sent by the server as a response to the request made.
Return type: IMessageBase

discover(ip: str, time_out: int32) → IMessageBase

Creates a DHCPDISCOVER message and waits for a response from the DHCP server. It is possible to specify the desired IP address in order to check if it is still available.

Parameters

ip (str) – (optional) IP address of the client that would like to get.
time_out (int32) – Max time to wait for a response to discover the message.

Returns

DHCP message sent by the server as a response to the request made.

Return type

IMessageBase

get_all_bytes() → Array[uint8]

Gets the content of the whole message from Ethernet layer.

Returns: Array of bytes representing the message from Ethernet layer.
Return type: Array[uint8]

get_bytes() → Array[uint8]

Gets the content of the payload.

Returns: Array of bytes representing the payload of the message.
Return type: Array[uint8]

get_hex_bytes() → str

Converts the payload of the message from decimal to hex and outputs it to a string of bytes.

Returns: Payload of message in hex bytes.
Return type: str

get_option(tag: uint8) → Array[uint8]

Gets the option data specified by the tag.

Parameters: tag (uint8) – Option type.
Returns: The data of the option None if the message doesn't have the option type.
Return type: Array[uint8]

has_option(tag: uint8) → bool

Checks if the message has the option specified by the tag.

Parameters: tag (uint8) – Option type.
Returns: True if the message has the option, False otherwise.
Return type: bool

hex_view() → str

Allows to visualize messages in hexadecimal format.

Returns: Hexadecimal representation of the whole message.
Return type: str

hex_view(nb_bytes_per_line: int32) → str

Allows to visualize messages in hexadecimal format.

Parameters: nb_bytes_per_line (int32) – (optional) number of bytes per line.
Returns: Hexadecimal representation of the whole message.
Return type: str

is_segmented() → bool

Checks if the message is segmented.

Returns: True if the message is segmented. False if not
Return type: bool

offer_ip(ip: str, server_ip: str, subnet_mask: str, mac_client: str, timeout: int32) → IMessageBase

Creates a DHCPOFFER message and waits for a response. A timeout is specified to guarantee that the script can continue if no message is captured in a certain time interval.

Parameters

ip (str) – IP address assigned to the client.
server_ip (str) – Server IP address. It will be added to the options of the message.
subnet_mask (str) – Subnet mask. Like the server address, it will be added to the options of the message.
mac_client (str) – Hardware address of the client.
timeout (int32) – Max time to wait for a response from the DHCP client

Returns

DHCP message sent by the client as a response to the offer made.

Return type

IMessageBase

open_writer(file: str, fileFormat: FILEFORMAT or None = None)

Creates a PCAP or PCAPNG file for writing the received messages. If the file already exists, it will be overwritten (old file data will be lost). Use the store() method to record received messages into the file.

Parameters

file (str) – Absolute path of the file where the messages will be stored
fileFormat (FILEFORMAT or None) – Obsolete, you don't need to specify this argument anymore

receive() → MessageDHCP

Matches a response for the used message.

Returns: Listens to the bus until a message is received and returns this first message
Return type: MessageDHCP

receive(timeout: int32) → MessageDHCP

Waits for the first response having the IP address destination equals to the IP address source of the sent message and return it. A timeout is specified to guarantee that the script can continue if no message is received in a certain time interval.

Parameters: timeout (int32) – Max time in milliseconds to wait for the response.
Returns: First message received from the bus or None in case no message is received.
Return type: MessageDHCP

receive_list(timeout: int32) → IReadOnlyList[MessageDHCP]

Waits for any response having the IP address destination equals to the IP address source of sent message and return them all as a list. A timeout is specified to guarantee that the script can continue if no message is received in a certain time interval.

Parameters: timeout (int32) – Max time in milliseconds to wait for the response.
Returns: List of messages received from the bus during a given period of time.
Return type: IReadOnlyList[MessageDHCP]

request_ip(ip: str, timeout: int32) → IMessageBase

Creates a DHCPREQUEST message and waits for a response from the DHCP server. A timeout is specified to guarantee that the script can continue if no message is captured in a certain time interval.

Parameters

ip (str) – IP address assigned to the client.
timeout (int32) – Max time to wait for a response from the DHCP client

Returns

DHCP message sent by the server as a response to the request made

Return type

IMessageBase

request_ip(ip: str, server_ip: str, mac_client: str, time_out: int32) → IMessageBase

Creates a DHCPREQUEST message and waits for a response from the DHCP client.

Parameters

ip (str) – IP address assigned to the client.
server_ip (str) – Server IP address. It will be added to the options of the message.
mac_client (str) – Hardware address of the client.
time_out (int32) – Max time to wait for a response to discover the message.

Returns

DHCP message sent by the server as a response to the request made

Return type

IMessageBase

send() → bool

Sends the message (the one used to call the method) through the Ethernet bus.

Returns: Returns True if the message is sent successfully. Otherwise, an exception will be thrown.
Return type: bool

send_receive(timeout: int32 = 1000) → MessageDHCP

Sends the message (the one used to call the method) through the Ethernet bus and waits for a possible response, i.e. a message from the target address to our own address. It is possible to specify a timeout to guarantee that the script can continue if no response is detected in a certain time interval.

Parameters: timeout (int32) – (optional) Max time in milliseconds to wait for the response. Default 1 second
Returns: First message detected from the destination address to our address. This can be the response to the message sent but it is not 100% guaranteed; additional traffic can be captured before this expected response and thus returned.
Return type: MessageDHCP

send_receive_list(timeout: int32) → IReadOnlyList[MessageDHCP]

Sends the message through the Ethernet bus, listens for a while and returns a list with all the messages captured in that period. It is possible to specify a timeout to guarantee that the script can continue if no response is detected in a certain time interval.

Parameters: timeout (int32) – Max time in milliseconds to wait for the response.
Returns: List of messages detected from the destination address to our address. This can be the response to the message sent but it is not 100% guaranteed; additional traffic can be captured before this expected response and thus returned.
Return type: IReadOnlyList[MessageDHCP]

set_all_bytes(all_packet: Array[uint8]) → bool

Sets the content of the whole message from Ethernet layer, byte per byte.

Parameters: all_packet (Array[uint8]) – All packet to set.
Returns: True if the operation was successful, False otherwise.
Return type: bool

set_bytes(payload: Array[uint8])

Sets the content of the payload, byte per byte.

Parameters: payload (Array[uint8]) – Array of bytes to set.

start_capture(filter: Filter = None)

Used for online capture(capturing network traffic from an adapter). Used with callback function(on_message_received()) and stop_capture() method.

Parameters: filter (Filter) – Filter to use to narrow down packets to capture

start_capture(file: str, wait_eof: bool, filter: Filter = None)

Used for offline capture(reading packets from pcap or asc file). Used with callback function(on_message_received()) and stop_capture() method.

Parameters

file (str) – The trace file from where the messages will be read.
wait_eof (bool) – If True the function would block until all frames in the file are read. If False the function would read the frames in the background.
filter (Filter) – Filter to use to narrow down packets to capture

start_responding_machine(): With this function, it is possible to simulate an ECU. It captures packets and, for every received message, it calls is_request callback. If it returns True, then it calls the make_reply callback

stop_capture(): Stops capturing Ethernet messages, either directly from the bus or from a trace file (depending on the version used to start the capture).

stop_responding_machine(): Stops the responding machine activated with start_responding_machine.

store(file: str)

Writes the message into the trace file.

Parameters: file (str) – Path of the file where the messages will be stored.

store(): Writes the message into the trace file opened with open_writer(file).

tree_view() → str

Gives the tree view of the message.

Returns: Tree view representation of the message.
Return type: str

@on_capture_start: The event is triggered when the capture of Ethernet messages is started. See start_capture .

@on_capture_stop: The event is triggered when the capture of Ethernet messages is stopped. See stop_capture .

@on_message_received(message: MessageDHCP)

Event is triggered every time a message is read from the Ethernet bus or a trace file. See start_capture.

Parameters: message (MessageDHCP) – The message object being handled.

allOptionTypes

List of all the option types of the message.

Type: List[uint8]

assigned_ip_address

IP address that the server is assigning to the client. Also, known as YIADDR

Type: str

capture_info

General information about the context in which the message was captured from. None if the message was not captured

Type: CaptureInfo

ciaddr

Client's IP Address.

Type: str

client_mac_address

Client hardware's address. Also, known as CHADDR.

Type: str

data_base

Takes the database object.

Type: Database

elapsed_time

Elapsed time in seconds since the beginning of the DHCP from the client side.

Type: int16

ethernet_header

Object containing all the information from the Ethernet header like the source and destination MAC addresses of the message.

Type: HeaderEthernet

file

Generic name (optional) used by a client in a DHCPDISCOVER message to request a particular type of boot file. In DHCPOFFER messages sent by a server, fully qualified directory path and file name.