DHCP data-types

Networking is a complex subject, with lots of different ways to communicate the same information. To make this easier, abstract encapsulations are provided that behave like all of the most common expressions simultaneously.

If you ever find yourself needing to pass or work with an IPv4 or MAC address, wrap it with one of these. If it’s coming out of the library, chances are it’s one already.

IPv4 addresses

A fairly straightforward representation of a conventional IP address. It can be coerced into a familiar dotted-quad string, an efficient sequence of bytes, or a somewhat intimidating unsigned, 32-bit integer. It can also be assembled from any of these things, as well as other instances of this class.

class dhcp_types.ipv4.IPv4(address)

Constructs an IPv4 abstraction from a concrete representation.

Parameters:address – An IPv4, which may be a dotted quad, a quadruple of bytes, or a 32-bit, unsigned integer. Raises ValueError:  The address could not be processed.

isSubnetMember(address, prefix)

Evaluates whether this IPv4 address is a member of the specifed subnet.

Parameters:

• address – An IPv4, which may be a dotted quad, a quadruple of bytes, or a 32-bit, unsigned integer.
• prefix – A subnet mask or CIDR prefix, like ‘255.255.255.0’ or 24.

Return bool:

True if this IPv4 is a member of the subnet.

Raises ValueError:  

The address or prefix could not be processed.

classmethod parseSubnet(subnet)

Splits a subnet-specifier written in common “ip/mask” notation into its constituent parts, allowing patterns like (address, prefix) = IPv4.parseSubnet(“10.50.0.0/255.255.0.0”) and <IPv4>.isSubnetMember(*<IPv4>.parseSubnet(“192.168.0.0/24”)).

Parameters:subnet – A string, using dotted-quad-slash-notation, with either an IPv4 mask or a CIDR integer as its complement. Return tuple(2):  The address and prefix components of the subnet. Raises ValueError:  The subnet could not be interpreted.

MAC addresses

A simple, friendly representation of a standard six-octet MAC address. It can be coerced into a string of colon-delimited hex-values, an efficient sequence of bytes, or a scary unsigned integer. It can be built from any of these things, too, other instances of the class, or hex-strings that may or may not contain any delimiters you like.

class dhcp_types.mac.MAC(address)

Constructs a MAC abstraction from a concrete representation.

Parameters:address – A MAC, which may be a string of twelve hex digits, optionally separated by non-hex characters, like ‘:’, ‘.’, or ‘-‘, a sequence of six bytes, or an unsigned integer. Raises ValueError:  The address could not be processed.

DHCP packets

The heart of the library, data-structure-wise, a DHCP packet to be examined, modified, and serialised for transmission.

Constants

dhcp_types.packet.FLAGBIT_BROADCAST

The “broadcast bit”, described in RFC 2131.

Classes

class dhcp_types.packet.DHCPPacket(data=None, _copy_data=None)

Initialises a DHCP packet.

Parameters:

• data – An optional byte-encoded DHCP packet, used to set initial values.
• _copy_data – Pre-formatted data from a Packet, used to quickly initialise a duplicate.

Raises ValueError:  

Invalid packet-data was provided.

word_align = False

If set, every option with an odd length in bytes will be padded, to ensure 16-bit word-alignment.

word_size = 4

The number of bytes in a word; 32-bit by network convention by default.

terminal_pad = False

If set, pad the packet to a multiple of word_size.

response_mac = None

If set to something coerceable into a MAC, the packet will be sent to this MAC, rather than its default.

response_ip = None

If set to something coerceable into an IPv4, the packet will be sent to this IP, rather than its default.

response_port = None

If set to an integer, the packet will be sent to this port, rather than its default.

response_source_port = None

If set to an integer, the packet will be reported as being sent from this port, rather than its default.

meta

A dictionary that can be freely manipulated to store data for the lifetime of the packet.

This data is not used by the packet in any way.

copy()

Provides a mutable copy of a packet.

Returns:A copy of the packet.

encodePacket()

Assembles all data into a single, byte-encoded string.

All options are arranged in order, per RFC2131 (details under ‘router’).

Return str:The encoded packet.

getHardwareAddress()

Provides the client’s MAC address.

Returns:The client’s MAC address.

setHardwareAddress(mac)

Sets the client’s MAC address.

Parameters:mac – The MAC to be assigned. Raises Exception:  Proivded MAC could not be processed.

getFlag(bitflag)

Retrieves a flag-bit from the header.

Parameters:bitflag (int) – One of the flag-constants defined in this module, like FLAGBIT_BROADCAST. Return bool:The state of the bit.

setFlag(bitflag, state)

Modifies the header to set a flag-bit.

Parameters:

• bitflag (int) – One of the flag-constants defined in this module, like FLAGBIT_BROADCAST.
• state (bool) – Whether the bit should be set or not.

Return tuple(2):  

Whether the bit was changed and its initial value, expressed in boolean.

isOption(option)

Indicates whether an option is currently set within the packet.

Parameters:option – The numeric ID or name of the option to check. Return bool:True if the option has been set.

deleteOption(option)

Drops a value from the packet.

If the value is part of the DHCP core, it is set to zero. Otherwise, it is removed from the option-pool.

Parameters:option – The numeric ID or name of the option to remove. Return bool:True if something was removed.

getOption(option, convert=False)

Retrieves the value of a field or option from the packet.

Parameters:

• option – The numeric ID or name of the option to retrieve.
• convert (bool) – Whether the option’s value should be deserialised.

Returns:

The option’s value or None, if it has not been set.

setOption(option, value, validate=True, force_selection=False)

Validates and sets a field or option on the packet.

Parameters:

• option – The numeric ID or name of the option to set.
• value – The value to be assigned.
• validate (bool) – Whether validation tests should be performed.
• force_selection (bool) – Whether the option should be included in the serialised packet, even if option 55 was provided and it was not explicitly requested.

Raises:

• ValueError – Validation failed.
• LookupError – Option not recognised.
• TypeError – Value could not be serialised.

getSelectedOptions(translate=False)

Returns all options marked for serialisation.

Parameters:translate (bool) – If True, the returned items will be names, not integers. Return tuple:All options slated to be included when serialised.

setSelectedOptions(added=None, removed=None)

Changes the set of selected options.

This does not affect option-data currently defined, just what will be serialised.

If both added and removed are None, all options will be selected.

If the all-selected state is active, setting either parameter will begin with an empty set.

added is applied before removed.

Parameters:

• added (collection) – The numeric IDs or names of options to add.
• removed (collection) – The numeric IDs or names of options to remove.

isSelectedOption(option)

Indicates whether the specified option is slated for serialisation.

Parameters:option – The numeric ID or name of the option to check. Return bool:True if the option is slated for serialisation.

extractIPOrNone(option)

Provides the IP associated with a DHCP field or option.

Parameters:option – The numeric ID or name of the option to check. Returns:The associated address or None, if undefined.

getDHCPMessageTypeName()

Provides the DHCP message-type of this packet.

Return str:The DHCP message-type of this packet.

isDHCPAckPacket()

Indicates whether this is an ACK packet.

Return bool:True if this is an ACK packet.

isDHCPDeclinePacket()

Indicates whether this is a DECLINE packet.

Return bool:True if this is a DECLINE packet.

isDHCPDiscoverPacket()

Indicates whether this is a DISCOVER packet.

Return bool:True if this is a DISCOVER packet.

isDHCPInformPacket()

Indicates whether this is an INFORM packet.

Return bool:True if this is an INFORM packet.

isDHCPLeaseActivePacket()

Indicates whether this is a LEASEACTIVE packet.

Return bool:True if this is a LEASEACTIVE packet.

isDHCPLeaseQueryPacket()

Indicates whether this is a LEASEQUERY packet.

Return bool:True if this is a LEASEQUERY packet.

isDHCPLeaseUnassignedPacket()

Indicates whether this is a LEASEUNASSIGNED packet.

Return bool:True if this is a LEASEUNASSIGNED packet.

isDHCPLeaseUnknownPacket()

Indicates whether this is a LEASEUNKNOWN packet.

Return bool:True if this is a LEASEUNKNOWN packet.

isDHCPOfferPacket()

Indicates whether this is an OFFER packet.

Return bool:True if this is an OFFER packet.

isDHCPNakPacket()

Indicates whether this is a NAK packet.

Return bool:True if this is a NAK packet.

isDHCPReleasePacket()

Indicates whether this is a RELEASE packet.

Return bool:True if this is a RELEASE packet.

isDHCPRequestPacket()

Indicates whether this is a REQUEST packet.

Return bool:True if this is a REQUEST packet.

transformToDHCPAckPacket()

Transforms a packet received from a client into an ACK packet to be returned to the client.

transformToDHCPLeaseActivePacket()

Transforms a packet received from a client into a LEASEACTIVE packet to be returned to the client.

transformToDHCPLeaseUnassignedPacket()

Transforms a packet received from a client into a LEASEUNASSIGNED packet to be returned to the client.

transformToDHCPLeaseUnknownPacket()

Transforms a packet received from a client into a LEASEUNKNOWN packet to be returned to the client.

transformToDHCPOfferPacket()

Transforms a packet received from a client into an OFFER packet to be returned to the client.

transformToDHCPNakPacket()

Transforms a packet received from a client into a NAK packet to be returned to the client.