x690.util

Utility functions for working with the X.690 and related standards.

x690.util.INDENT_STRING = ' '

String to be used for indenting nested items during “pretty()” calls

class x690.util.Length(*values)

Bases: str, Enum

A simple “namespace” to avoid magic values for indefinite lengths.

class x690.util.LengthInfo(length, offset)

Bases: NamedTuple

The result of decode_length().

length : int

The length of the value in octets, or -1 if it is indefinite

offset : int

The number of octets used by the length information itself

class x690.util.TypeClass(*values)

Bases: str, Enum

The class of an X.690 type, taken from the two top bits of the identifier octet.

The members are strings, so they compare equal to their lower-case names. See TypeInfo.

class x690.util.TypeInfo(cls, nature, tag)

Bases: object

Decoded structure for an X.690 “type” octet. Example:

>>> TypeInfo.from_bytes(b'\x30')
TypeInfo(cls=<TypeClass.UNIVERSAL: 'universal'>, nature=<TypeNature.CONSTRUCTED: 'constructed'>, tag=16)

The structure contains 3 fields:

cls

The typeclass (a value taken from TypeClass)

nature

A value taken from TypeNature

tag

The actual type identifier.

The instance also keeps the raw value as it was seen in the _raw_value attribute.

static from_bytes(data)

Given one octet, extract the separate fields and return a TypeInfo instance:

>>> TypeInfo.from_bytes(b'\x30')
TypeInfo(cls=<TypeClass.UNIVERSAL: 'universal'>, nature=<TypeNature.CONSTRUCTED: 'constructed'>, tag=16)
Parameters:
data

The identifier octet, either as a single byte or as the equivalent integer.

Return type:

TypeInfo

Returns:

The decoded class, nature and tag.

Raises:

NotImplementedError – If the octet is 0xff (long identifier types are not supported).

class x690.util.TypeNature(*values)

Bases: str, Enum

Whether an X.690 value is primitive or constructed, taken from bit 6 of the identifier octet.

A constructed value contains further encoded values, a primitive value does not. See TypeInfo.

class x690.util.ValueMetaData(bounds, next_value_index)

Bases: NamedTuple

The result of get_value_slice().

bounds : slice

The location of the value’s content octets in the data stream

next_value_index : int

The index at which the next value in the data stream starts

x690.util.decode_length(data, index=0)

Given a bytes object, which starts with the length information of a TLV value, returns a namedtuple with the length and the number of bytes which contained the length information. So, given a TLV value, this function takes the “LV” part as input, parses the length information and returns the length plus the number of bytes which need to be skipped to arrive at the beginning of the value.

For values which are longer than 127 bytes, the length must be encoded into an unknown amount of “length” bytes. This function reads as many bytes as needed for the length. Consuming bytes for the value must therefore start after the bytes containing the length info. The second value returned from this function includes this information.

The second argument (index) tells the function at which position to look for the length information.

Parameters:
data

Data containing the length information.

index=0

Position of the first length octet.

Return type:

LengthInfo

Returns:

The decoded length and the number of octets used to encode it. For the indefinite form the length is -1 and the offset is -1.

Raises:

NotImplementedError – If the first length octet is 0xff, which X.690 reserves.

Examples:

>>> # length > 127, consume multiple length bytes
>>> decode_length(b'\x81\xc8...')
LengthInfo(length=200, offset=2)

>>> # length <= 127, consume one length byte
>>> decode_length(b'\x10...')
LengthInfo(length=16, offset=1)
TODO: Upon rereading this, I wonder if it would not make more sense to take

the complete TLV content as input.

x690.util.encode_length(value)

This function encodes the length of a variable into bytes conforming to the rules defined in X.690: The “length” field must be specially encoded for values above 127. Additionally, from X.690:

8.1.3.2 A sender shall:

  1. use the definite form (see 8.1.3.3) if the encoding is primitive;

  2. use either the definite form (see 8.1.3.3) or the indefinite form (see 8.1.3.6), a sender’s option, if the encoding is constructed and all immediately available;

  3. use the indefinite form (see 8.1.3.6) if the encoding is constructed and is not all immediately available.

See also: https://en.wikipedia.org/wiki/X.690#Length_octets

Example:

>>> encode_length(16)    # no need for special encoding.
b'\x10'
>>> encode_length(200)   # > 127, needs to be specially encoded.
b'\x81\xc8'
Parameters:
value

The length to encode, or Length.INDEFINITE to produce the indefinite form.

Return type:

bytes

Returns:

The encoded length octets.

x690.util.get_value_slice(data, index=0)

Helper method to extract lightweight information about value locations in a data-stream.

The function returns both a slice at which a value can be found, and the index at which the next value can be found.

Parameters:
data

The data stream containing one or more TLV values.

index=0

Position of the first octet (the type octet) of the value to locate.

Return type:

ValueMetaData

Returns:

The slice covering the value’s content octets and the index at which the next value starts. For indefinite lengths, the slice starts after the length octet and ends at the first end-of-contents marker (two zero octets).

Raises:

X690Error – If the announced length exceeds the available data.

x690.util.visible_octets(data)

Returns a geek-friendly (hexdump) output of a bytes object.

Parameters:
data

The octets to display.

Return type:

str

Returns:

A multi-line string with 16 octets per line, followed by their printable ASCII representation.

Developer note:

This is not super performant. But it’s not something that’s supposed to be run during normal operations (mostly for testing and debugging). So performance should not be an issue, and this is less obfuscated than existing solutions.

Example:

>>> from os import urandom
>>> print(visible_octets(urandom(40)))
99 1f 56 a9 25 50 f7 9b  95 7e ff 80 16 14 88 c5   ..V.%P...~......
f3 b4 83 d4 89 b2 34 b4  71 4e 5a 69 aa 9f 1d f8   ......4.qNZi....
1d 33 f9 8e f1 b9 12 e9                            .3......
x690.util.wrap(text, header, depth)

Wraps text in a border with a header, indented by depth levels.

Parameters:
text

The (possibly multi-line) text to put into the box.

header

Title shown in the first row of the box.

depth

Nesting level; each level indents by INDENT_STRING.

Return type:

str

Returns:

The boxed text.