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.LengthInfo(length, offset)¶
Bases:
NamedTupleThe result of
decode_length().
- class x690.util.TypeClass(*values)¶
-
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:
objectDecoded 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_valueattribute.
- class x690.util.TypeNature(*values)¶
-
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:
NamedTupleThe result of
get_value_slice().
-
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:¶
- Return type:¶
- Returns:¶
The decoded length and the number of octets used to encode it. For the indefinite form the length is
-1and 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:
use the definite form (see 8.1.3.3) if the encoding is primitive;
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;
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'
-
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:¶
- Return type:¶
- 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:¶
- 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......