Language

Prensentation language as defined in RFC 8446 Section 3.

class siotls.language.TLSIO

Bases: BytesIO

BytesIO used to serialize and parse siotls.contents.

__init__(*args, **kwargs)
ensure_eof()

Ensure we are at the end of the stream.

This does NOT account for any limit() set.

Raises:

TooMuchDataError – when we are not at the end of the stream.

is_eof()

Return whether we are at the end of the stream or not.

This does NOT account for any limit() set.

Return type:

bool

limit(length)

Enters a context-manager that enforces reading the next length bytes, no more, no less.

This method can be used for parsing advanced data structures when the size of that structure is known but that the structure cannot be parsed by other (simpler) methods such as read_listint() and read_listvar().

It enforces a limit that is understood by all the read methods, they will all raise BufferOverflowError would reading more bytes be attempted.

Parameters:

length – the exact number of bytes to read before exiting the context manager.

Raises:

  • ValueError – upon entering the context manager, if another more restrictive limit is present already.

  • TooMuchDataError – upon exiting the context manager, if there are unread bytes remaining.

read(n=None)

Read at most n bytes, or all bytes until the limit/end-of-stream if n is negative.

Parameters:

n (int | None) – amount of bytes to read, or -1 to read all remaining bytes.

Raises:

BufferOverflowError – When trying to read more bytes than the current limit allows.

Return type:

bytes

read_exactly(n)

Read a fixed-length vector of n bytes.

Parameters:

n (int) – amount of bytes to read, no more, no less.

Raises:

  • ValueError – When n is negative.

  • MissingData – When trying to read more bytes than there are available on the buffer.

  • BufferOverflowError – When trying to read more bytes than the current limit allows.

Return type:

bytes

read_int(n)

Read a big-endian unsigned integer defined over n bytes.

Parameters:

n (int) – amount of bytes to read.

Raises:

  • ValueError – When n is not a strictly positive integer.

  • MissingData – When trying to read more bytes than there are available on the buffer.

  • BufferOverflowError – When trying to read more bytes than the current limit allows.

Return type:

int

read_listint(nlist, nitem)

Read a variable-length vector where each item is an integer. The vector is prefixed by its actual length as a big-endian unsigned integer over nlist bytes. All integers are big-endian unsigned integers of nitem bytes.

Parameters:

  • nlist (int) – amount of bytes reserved for the length of the vector, as the total number of bytes, not as the number of items.

  • nitem (int) – amount of bytes of every integer.

Raises:

  • TLSBufferError – when the actual length of the vector (read from the first nlist bytes) is not a multiple of nitem.

  • MissingData – When trying to read more bytes than there are available on the buffer.

  • BufferOverflowError – When trying to read more bytes than the current limit allows.

Return type:

MutableSequence[int]

read_listvar(nlist, nitem)

Read a variable-length vector where each item is itself a variable-length vector.

Parameters:

  • nlist – amount of bytes reserved for the length of the vector, as the total number of bytes, not as the number of items.

  • nitem – amount of bytes reserved for the length of every variable-length vector item.

Raises:

  • MissingData – When trying to read more bytes than there are available on the buffer.

  • BufferOverflowError – When trying to read more bytes than the current limit allows.

Return type:

MutableSequence[bytes]

read_var(n)

Read a variable-length vector. The vector is prefixed by its actual length as a big-endian unsigned integer over n bytes.

Parameters:

n (int) – amount of bytes reserved for the length of the vector.

Raises:

  • ValueError – When n is not a strictly positive integer.

  • MissingData – When trying to read more bytes than there are available on the buffer.

  • BufferOverflowError – When trying to read more bytes than the current limit allows.

Return type:

bytes

write_int(n, i)

Write a big-endian unsigned integer i over n bytes.

Parameters:

  • n (int)

  • i (int)

Return type:

None

write_listint(nlist, nitem, items)

Write items as a variable-length vector of integers.

Parameters:

  • nlist (int)

  • nitem (int)

  • items (Sequence[int])

Return type:

None

write_var(n, b)

Write a variable-length vector b. The actual length of the vector is written first as a big-endian unsigned integer over n bytes, the vector itself is only then written.

Parameters:

  • n (int)

  • b (bytes)

Return type:

None

class siotls.language.MissingData

Bases: TLSError

Occurs when reading more data than there are available in the buffer. The error is likely to go away once more data are fed into the buffer.

>>> stream = TLSIO(b"abc")
>>> stream.read_exactly(4)
Traceback (most recent call last):
...
MissingData: expected 4 bytes but can only read 3
class siotls.language.TLSBufferError

Bases: TLSError, BufferError

Top error class, occurs when an error occured while parsing or serializing data from/into the buffer.

Closely related to DecodeError.

class siotls.language.BufferOverflowError

Bases: TLSBufferError

Occurs when a TLSIO.limit() is active and that an operation that would had read/write over the limit was prevented.

class siotls.language.TooMuchDataError

Bases: TLSBufferError

Occurs when there are remaining unread data but that all the data should had been read.

>>> stream = TLSIO(b"abc")
>>> stream.ensure_eof()
Traceback (most recent call last):
...
TooMuchDataError: expected end of stream but 3 bytes remain