Conversion functions

For efficiency purposes, packet-data is conceptualised as sequences of bytes, since it has very limited interaction with human operators. This is great for performance, but not so great when writing code.

To maintain efficiency and avoid errors, a number of optimised convenience routines are provided and described below. However, they are all encapsulated within the getOption and setOption methods of DHCPPacket, so it is rare that you will need to invoke them directly.

Type-conversion

DHCP needs to encode a wide variety of data and it can be easy to confuse byte-ordering. That’s where the conversion-functions come into play.

Decoders

The following functions convert from byte-sequences into more familiar data-types. They are additionally bound via autoconversion.

dhcp_types.conversion.listToNumber(l)

Sums a sequence of bytes in big-endian order, producing an integer.

Parameters:l (sequence) – A sequence of ints, between 0 and 255. Return int:The corresponding value.

dhcp_types.conversion.listToInt(l)

Converts a pair of bytes, in big-endian order, into an integer.

Parameters:l (sequence) – A sequence of ints, between 0 and 255. If longer than two, only the head is used; if less than two, zero-padded to LSD. Return int:The corresponding value.

dhcp_types.conversion.listToInts(l)

Converts pairs of bytes, in big-endian order, into integers.

Parameters:l (sequence) – A sequence of ints, between 0 and 255. If not a multiple of two, zero-padded to LSD. Return list:A list of ints corresponding to the byte-pairs.

dhcp_types.conversion.listToLong(l)

Converts a quartet of bytes, in big-endian order, into an integer.

Parameters:l (sequence) – A sequence of ints, between 0 and 255. If longer than four, only the head is used; if less than four, zero-padded to LSD. Return int:The corresponding value.

dhcp_types.conversion.listToLongs(l)

Converts quartets of bytes, in big-endian order, into integers.

Parameters:l (sequence) – A sequence of ints, between 0 and 255. If not a multiple of four, zero-padded to LSD. Return list:A list of ints corresponding to the byte-quartets.

dhcp_types.conversion.listToStr(l)

Converts a sequence of bytes into a byte-string.

Parameters:l (sequence) – The bytes to be converted. Return str:The converted byte-string.

dhcp_types.conversion.listToIP(l)

Converts almost anything into an IPv4 address.

Parameters:l (sequence(4)) – The bytes to be converted. Returns:The equivalent IPv4 address. Raises ValueError:  The list could not be processed.

dhcp_types.conversion.listToIPs(l)

Converts almost anything into IPv4 addresses.

Parameters:l (sequence) – The bytes to be converted, as a flat sequence with length a multiple of four. Return list:The equivalent IPv4 addresses. Raises ValueError:  The list could not be processed.

Encoders

When writing values to a packet, the following methods, additionally bound via autoconversion, will handle the hard part.

dhcp_types.conversion.intToList(i)

Converts an integer into a pair of bytes in big-endian order.

Parameters:i (int) – The integer to be converted. If outside the range of 0 to 65535, only the low-order sixteen bits are considered. Return list(2):The converted value.

dhcp_types.conversion.intsToList(l)

Converts a sequence of integers into pairs of bytes in big-endian order.

Parameters:l (sequence) – The sequence to be converted. If any values are outside the range of 0 to 65535, only the low-order sixteen bits are considered. Return list:The converted values.

dhcp_types.conversion.longToList(l)

Converts an integer into a quartet of bytes in big-endian order.

Parameters:l (int) – The integer to be converted. If outside the range of 0 to 4294967296, only the low-order thirty-two bits are considered. Return list(4):The converted value.

dhcp_types.conversion.longsToList(l)

Converts a sequence of integers into quartets of bytes in big-endian order.

Parameters:l (sequence) – The sequence to be converted. If any values are outside the range of 0 to 4294967296, only the low-order thirty-two bits are considered. Return list:The converted values.

dhcp_types.conversion.strToList(s)

Converts a string into a sequence of bytes.

This will also handle unicode strings, so sanitise all input.

Parameters:s (str) – The string to be converted. Return list:A sequence of bytes.

dhcp_types.conversion.strToPaddedList(s, l)

Converts a string into a sequence of bytes, with a fixed length.

This will also handle unicode strings, so sanitise all input.

Parameters:

• s (str) – The string to be converted.
• l (int) – The length of the resulting list.

Return list:

A sequence of bytes of length l, truncated or null-padded as appropriate.

dhcp_types.conversion.ipToList(ip)

Converts an IPv4 address into a list of four bytes in big-endian order.

Parameters:ip (object) – Any valid IPv4 format (string, 32-bit integer, list of bytes, IPv4). Return list(4):The converted address. Raises ValueError:  The IP could not be processed.

dhcp_types.conversion.ipsToList(ips)

Converts a IPv4 addresses into a flat list of multiples of four bytes in big-endian order.

Parameters:ips (list) – A list of any valid IPv4 formats (string, 32-bit integer, list of bytes, IPv4). Return list:The converted addresses. Raises ValueError:  The IPs could not be processed.

RFC conversions

DHCP has many extending RFCs, and many of those have their own data-formats.

Where possible, libpydhcpserver provides routines for processing their content, letting you focus on logic, not bitwise shifts.

Decoders

The following functions decode RFC options, providing easy-to-process data. They are bound and invoked, where appriopriate, via autoconversion.

dhcp_types.rfc.rfc3046_decode(s)

Extracts sub-options from an RFC3046 option (82).

Parameters:s (sequence) – The option’s raw data. Return dict:The sub-options, as byte-lists, keyed by ID.

dhcp_types.rfc.rfc3925_decode(s, identifier_size=4)

Extracts sub-options from an RFC3925 option (124, 125 (with identifier_size=1)).

You probably want to use rfc3925_125_decode() when dealing with option 125 specifically.

Parameters:

• s (sequence) – The option’s raw data.
• identifier_size (int) – The width of the identifier in bytes.

Return dict:

A dictionary of data as strings keyed by ID numbers.

dhcp_types.rfc.rfc3925_125_decode(l)

Extracts sub-options from an RFC3925 option (125).

Parameters:s (sequence) – The option’s raw data. Return dict:A dictionary of data as dictionaries mapping data as strings keyed by ID numbers.

Encoders

For setting RFC options, the following classes can be passed in place of byte-sequences, handling all logic internally.

class dhcp_types.rfc.RFC

A generic special RFC object, used to simplify the process of setting complex options.

getValue()

Provides the type’s data as a list of bytes.

Note that this is the actual internal list; modifications to the list will be persistent.

Return list:A list of bytes.

class dhcp_types.rfc.rfc1035_plus(data)

Bases: dhcp_types.rfc.RFC

Formats FQDNs as an RFC1035-formatted sequence.

Parameters:data (str) – The comma-delimited FQDNs to process.

class dhcp_types.rfc.rfc2610_78(mandatory, data)

Bases: dhcp_types.rfc.RFC

Formats native IPv4s as encoded IPv4 addresses.

Parameters:

• mandatory (bool) – True if the IPv4 addresses have to be respected.
• data (str) – The comma-delimited IPv4s to process.

class dhcp_types.rfc.rfc2610_79(mandatory, data)

Bases: dhcp_types.rfc.RFC

Formats scope-list data.

Parameters:

• mandatory (bool) – True if the scope-list has to be respected.
• data (str) – The scope-list to process.

class dhcp_types.rfc.rfc3361_120(data)

Bases: dhcp_types.rfc.RFC

Formats the given data into multiple IPv4 addresses or RFC1035-formatted strings.

Parameters:data (str) – The comma-delimited IPv4s or FQDNs to process. Raises ValueError:  Both IPv4s and FQDNs were provided.

class dhcp_types.rfc.rfc3397_119(data)

Bases: dhcp_types.rfc.rfc1035_plus

Formats FQDNs as an RFC1035-formatted sequence.

Parameters:data (str) – The comma-delimited FQDNs to process.

class dhcp_types.rfc.rfc3442_121(classless_addresses)

Bases: dhcp_types.rfc.RFC

Accepts a sequence of CIDR entries and routers to produce classless static route byte-blocks.

You’ll probably want to put ((“0.0.0.0”, 0), packet.getOption(“router”)) at the start to ensure the default gateway is set as expected.

Parameters:classless_addresses – ((network IPv4, CIDR-mask), router IPv4) elements, like ((“169.254.0.0”, 16), “0.0.0.0”). Raises ValueError:  An illegal address or mask was encountered.

class dhcp_types.rfc.rfc3925_124(data)

Bases: dhcp_types.rfc.RFC

Sets vendor_class data.

Parameters:data (dict) – A dictionary of data-strings keyed by ID-ints.

class dhcp_types.rfc.rfc3925_125(data)

Bases: dhcp_types.rfc.RFC

Sets vendor_specific data.

Parameters:data (dict) – A dictionary of dictionaries of data-strings, keyed by ID-ints at both levels.

class dhcp_types.rfc.rfc4174_83(isns_functions, dd_access, admin_flags, isns_security, ips)

Bases: dhcp_types.rfc.RFC

Sets iSNS configuration parameters.

Parameters:

• isns_functions (int) – A sixteen-bit value.
• dd_access (int) – A sixteen-bit value.
• admin_flags (int) – A sixteen-bit value.
• isns_security (int) – A thirty-two-bit value.
• ips (str) – Comma-delimited IPv4s to be processed.

class dhcp_types.rfc.rfc4280_88(data)

Bases: dhcp_types.rfc.rfc1035_plus

Formats FQDNs as an RFC1035-formatted sequence.

Parameters:data (str) – The comma-delimited FQDNs to process.

class dhcp_types.rfc.rfc5223_137(data)

Bases: dhcp_types.rfc.rfc1035_plus

Formats FQDNs as an RFC1035-formatted sequence.

Parameters:data (str) – The comma-delimited FQDNs to process.

class dhcp_types.rfc.rfc5678_139(values)

Bases: dhcp_types.rfc.RFC

Formats the given data into multiple IPv4 addresses associated with sub-option codes.

Parameters:values (sequence) – A sequence of (code:int, IPv4s:string) elements.

class dhcp_types.rfc.rfc5678_140(values)

Bases: dhcp_types.rfc.RFC

Formats the given data into multiple RFC1035-formatted strings associated with sub-option codes.

Parameters:values (sequence) – A sequence of (code:int, FQDNs:string) elements.