tlslite.utils.codec module

Classes for reading/writing binary data (such as TLS records).

exception tlslite.utils.codec.BadCertificateError

Bases: SyntaxError

Exception raised in case of bad certificate.

exception tlslite.utils.codec.DecodeError

Bases: SyntaxError

Exception raised in case of decoding errors.

class tlslite.utils.codec.Parser(bytes)

Bases: object

Parser for TLV and LV byte-based encodings.

Parser that can handle arbitrary byte-based encodings usually employed in Type-Length-Value or Length-Value binary encoding protocols like ASN.1 or TLS

Note: if the raw bytes don’t match expected values (like trying to read a 4-byte integer from a 2-byte buffer), most methods will raise a DecodeError exception.

TODO: don’t use an exception used by language parser to indicate errors in application code.

Variables:

• bytes (bytearray) – data to be interpreted (buffer)

• index (int) – current position in the buffer

• lengthCheck (int) – size of struct being parsed

• indexCheck (int) – position at which the structure begins in buffer

__init__(bytes)

Bind raw bytes with parser.

Parameters:

bytes (bytearray) – bytes to be parsed/interpreted

atLengthCheck()

Check if there is data in structure left for parsing.

Returns True if the whole structure was parsed, False if there is some data left.

Will raise an exception if overflow occured (amount of data read was greater than expected size)

get(length)

Read a single big-endian integer value encoded in ‘length’ bytes.

Parameters:

length (int) – number of bytes in which the value is encoded in

Return type:

int

getFixBytes(lengthBytes)

Read a string of bytes encoded in ‘lengthBytes’ bytes.

Parameters:

lengthBytes (int) – number of bytes to return

Return type:

bytearray

getFixList(length, lengthList)

Read a list of static length with same-sized ints.

Parameters:

• length (int) – size in bytes of a single element in list

• lengthList (int) – number of elements in list

Return type:

list of int

getRemainingLength()

Return amount of data remaining in struct being parsed.

getVarBytes(lengthLength)

Read a variable length string with a fixed length.

see Writer.add_var_bytes() for an inverse of this method

Parameters:

lengthLength (int) – number of bytes in which the length of the string is encoded in

Return type:

bytearray

getVarList(length, lengthLength)

Read a variable length list of same-sized integers.

Parameters:

• length (int) – size in bytes of a single element

• lengthLength (int) – size of the encoded length of the list

Return type:

list of int

getVarTupleList(elemLength, elemNum, lengthLength)

Read a variable length list of same sized tuples.

Parameters:

• elemLength (int) – length in bytes of single tuple element

• elemNum (int) – number of elements in tuple

• lengthLength (int) – length in bytes of the list length variable

Return type:

list of tuple of int

setLengthCheck(length)

Set length of struct and start a length check for parsing.

Parameters:

length (int) – expected size of parsed struct in bytes

skip_bytes(length)

Move the internal pointer ahead length bytes.

startLengthCheck(lengthLength)

Read length of struct and start a length check for parsing.

Parameters:

lengthLength (int) – number of bytes in which the length is encoded

stopLengthCheck()

Stop struct parsing, verify that no under- or overflow occurred.

In case the expected length was mismatched with actual length of processed data, raises an exception.

class tlslite.utils.codec.Writer

Bases: object

Serialisation helper for complex byte-based structures.

__init__()

Initialise the serializer with no data.

add(x, length)

Add a single positive integer value x, encode it in length bytes

Encode positive integer x in big-endian format using length bytes, add to the internal buffer.

Parameters:

• x (int) – value to encode

• length (int) – number of bytes to use for encoding the value

addFixSeq(seq, length)

Add a list of items, encode every item in length bytes

Uses the unbounded iterable seq to produce items, each of which is then encoded to length bytes

Parameters:

• seq (iterable of int) – list of positive integers to encode

• length (int) – number of bytes to which encode every element

addFour(val)

Add a four-byte wide element to buffer, see add().

addOne(val)

Add a single-byte wide element to buffer, see add().

addThree(val)

Add a three-byte wide element to buffer, see add().

addTwo(val)

Add a double-byte wide element to buffer, see add().

addVarSeq(seq, length, lengthLength)

Add a bounded list of same-sized values

Create a list of specific length with all items being of the same size

Parameters:

• seq (list of int) – list of positive integers to encode

• length (int) – amount of bytes in which to encode every item

• lengthLength (int) – amount of bytes in which to encode the overall length of the array

addVarTupleSeq(seq, length, lengthLength)

Add a variable length list of same-sized element tuples.

Note that all tuples must have the same size.

Inverse of Parser.getVarTupleList()

Parameters:

• seq (enumerable) – list of tuples

• length (int) – length of single element in tuple

• lengthLength (int) – length in bytes of overall length field

add_var_bytes(data, length_length)

Add a variable length array of bytes.

Inverse of Parser.getVarBytes()

Parameters:

• data (bytes) – bytes to add to the buffer

• length_length (int) – size of the field to represent the length of the data string

tlslite.utils.codec.bytes_to_int(bytes, byteorder='big', *, signed=False)

Return the integer represented by the given array of bytes.

bytes

Holds the array of bytes to convert. The argument must either support the buffer protocol or be an iterable object producing bytes. Bytes and bytearray are examples of built-in objects that support the buffer protocol.

byteorder

The byte order used to represent the integer. If byteorder is ‘big’, the most significant byte is at the beginning of the byte array. If byteorder is ‘little’, the most significant byte is at the end of the byte array. To request the native byte order of the host system, use `sys.byteorder’ as the byte order value. Default is to use ‘big’.

signed

Indicates whether two’s complement is used to represent the integer.