Module osyspyrt.asn1ber

Support ASN.1 BER.

Classes

class Asn1BerDecodeBuffer (istream)

Provides methods for decoding ASN.1 BER encoded data.

Parameters

istream : io.BufferedIOBase
Binary I/O providing the data to be read/decoded.

Class variables

var OIDMAXSUBIDS

Static methods

def from_bytes(byte_array)
def from_file(filename)

Methods

def bin_dump(self)

This method dumps the encoded message in a human-readable format showing a bit trace of all fields.

Returns

strbuf : str
String containing formatted data.
def decode_bcdstr(self, explicit=True, impllen=None)
def decode_bitstr(self, explicit=True, impllen=None, decode_cls=osyspyrt.asn1univtype.Asn1BitString)

This method decodes a BIT STRING value.

Parameters

explicit : bool
Flag indicating universal tag and length should be decoded.
impllen : Asn1BerLength
Implicit length. Length of content to be decoded if explicit is False.
decode_cls : Class
The class to instantiate. It must be a subclass of Asn1BitString, supporting the init signature of that class.

Returns

instance of decode_cls, by default an Asn1BitString. The decoded BIT STRING value.

def decode_bmpstr(self, explicit=True, impllen=None)

This method decodes a BMP character string value.

Parameters

explicit : bool
Flag indicating universal tag and length should be decoded.
impllen : Asn1BerLength
Implicit length. Length of content to be decoded if explicit is False.

Returns

result : str
Decoded BMP character string value.
def decode_boolean(self, explicit=True, impllen=None)

This method decodes a BOOLEAN value.

Parameters

explicit : bool
Flag indicating universal tag and length should be decoded.

Returns

result : bool
Decoded boolean value.
def decode_charstr(self, univtag, explicit=True, impllen=None)

This method decodes a character string value.

Parameters

univtag : int
Universal tag of the string being decoded.
explicit : bool
Flag indicating universal tag and length should be decoded.
impllen : Asn1BerLength
Implicit length. Length of content to be decoded if explicit is False.

Returns

result : str
Decoded character string value.
def decode_enum(self, explicit=True, impllen=None)

This method decodes an ENUMERATED value.

Parameters

explicit : bool
Flag indicating universal tag and length should be decoded.
impllen : Asn1BerLength
Implicit length. Length of content to be decoded if explicit is False.

Returns

result : int
Decoded integer enumerated value.
def decode_gentimestr(self, explicit=True, impllen=None)

This method decodes a GeneralizedTime character string value.

Parameters

explicit : bool
Flag indicating universal tag and length should be decoded.
impllen : Asn1BerLength
Implicit length. Length of content to be decoded if explicit is False.

Returns

result : str
Decoded GeneralizedTime character string value.
def decode_int_content(self, nbytes)

This method decodes the given number of bytes into an integer value. It may be used to decode ASN.1 INTEGER values as well as other fixed-sized integer values encoded in big-endian format.

Parameters

nbytes : int
Length of content in bytes to be decoded.

Returns

result : int
Decoded integer value.
def decode_integer(self, explicit=True, impllen=None)

This method decodes an INTEGER value.

Parameters

explicit : bool
Flag indicating universal tag and length should be decoded.
impllen : Asn1BerLength
Implicit length. Length of content to be decoded if explicit is False.

Returns

result : int
Decoded integer value.
def decode_length(self)

This method decodes a length value.

Returns

llen : Asn1BerLength
Decoded length value.
def decode_null(self, explicit=True, impllen=None)

This method decodes a null value.

Parameters

explicit : bool
Flag indicating universal tag and length should be decoded.
def decode_octetstr(self, explicit=True, impllen=None)

This method decodes an OCTET STRING value.

Parameters

explicit : bool
Flag indicating universal tag and length should be decoded.
impllen : Asn1BerLength
Implicit length. Length of content to be decoded if explicit is False.

Returns

result : bytearray
Decoded OCTET STRING value.
def decode_oid(self, explicit=True, impllen=None)

This method decodes an OBJECT IDENTIFIER value.

Parameters

explicit : bool
Flag indicating universal tag and length should be decoded.
impllen : Asn1BerLength
Implicit length. Length of content to be decoded if explicit is False.

Returns

result : Iterable collection of integers
Decoded OBJECT IDENTIFIER value.
def decode_oid_iri(self, explicit=True, impllen=None)

This method decodes an OID-IRI string value.

Parameters

explicit : bool
Flag indicating universal tag and length should be decoded.
impllen : Asn1BerLength
Implicit length. Length of content to be decoded if explicit is False.

Returns

result : str
Decoded character string value.
def decode_opentype(self)
def decode_real(self, explicit=True, impllen=None, specials=builtins.float)

This method decodes an ASN.1 REAL.

Parameters

explicit : bool
Flag indicating universal tag and length should be decoded.
impllen : Asn1BerLength
Implicit length. Length of content to be decoded if explicit is False.
specials : class
This controls whether 0, -0, +/-INF and NaN should be returned as a float or as decimal.Decimal.

Returns

float or decimal.Decimal
The decoded value. If the value was encoded using base 2, 8, or 16, a float will be returned. If the value was encoded using base 10, a decimal.Decimal will be returned. If the encoded value was 0, -0, +/-INF or NaN, an instance of specials will be returned.

Raises

Asn1LimitationError If the encoded value is too small or too large for the designated return type.

def decode_reloid_iri(self, explicit=True, impllen=None)

This method decodes an OID-IRI string value.

Parameters

explicit : bool
Flag indicating universal tag and length should be decoded.
impllen : Asn1BerLength
Implicit length. Length of content to be decoded if explicit is False.

Returns

result : str
Decoded character string value.
def decode_roid(self, explicit=True, impllen=None)

This method decodes a RELATIVE OID value.

Parameters

explicit : bool
Flag indicating universal tag and length should be decoded.
impllen : Asn1BerLength
Implicit length. Length of content to be decoded if explicit is False.

Returns

result : Iterable collection of integers
Decoded RELATIVE OID value.
def decode_tag(self)

This method decodes the tag value at the current decode buffer location.

Returns

tag : Asn1BerTag
Decoded tag value.
def decode_tag_and_length(self)

This method decodes a tag and length value.

Returns

tag : Asn1BerTag
Decoded tag value.
llen : Asn1BerLength
Decoded length value.
def decode_tag_bytes(self, tag_bytes)

This method decodes the tag value from the given byte array.

Parameters

tag_bytes : bytes
Byte array containing encoded tag to be decoded.

Returns

tag : Asn1BerTag
Decoded tag value.
def decode_tbcdstr(self, explicit=True, impllen=None)
def decode_universalstr(self, explicit=True, impllen=None)

This method decodes a Universal character string value.

Parameters

explicit : bool
Flag indicating universal tag and length should be decoded.
impllen : Asn1BerLength
Implicit length. Length of content to be decoded if explicit is False.

Returns

result : str
Decoded Universal character string value.
def decode_utctimestr(self, explicit=True, impllen=None)

This method decodes a UTCTime character string value.

Parameters

explicit : bool
Flag indicating universal tag and length should be decoded.
impllen : Asn1BerLength
Implicit length. Length of content to be decoded if explicit is False.

Returns

result : str
Decoded UTCTime character string value.
def mark(self)
def match_eoc(self)

This method attempts to matche an indefinite length end-of-contents marker at the current location in the decode buffer. If matched, the decode buffer cursor is advanced past to EOC tag and length.

Returns: result: bool True if EOC matched.

def match_tag_byte(self, tag, advance=True)

This method compares the given single-byte tag value with the next byte in the decode buffer. If matched, the decode buffer cursor is advanced past the matched tag byte, otherwise it is unchanged.

Parameters

tag : byte
Single byte tag value
advance : bool
True if decode buffer cursor is to be advanced on match.

Returns

result : boolean
Result of comparison operation.
def match_tag_bytes(self, tag, advance=True)

This method compares the given multi-byte tag value with the next len(tag) bytes in the decode buffer. If matched, the decode buffer cursor is advanced past the matched tag bytes, otherwise it is unchanged.

Parameters

tag : bytes
Multi-byte tag value. These are the bytes that would be encoded for the tag of interest.
advance : bool
True if decode buffer cursor is to be advanced on match.

Returns

result : boolean
Result of comparison operation.
def more_data(self)

This method will return true if more data is to be read in the buffer or stream or false otherwise.

def move_past_eoc(self)

This method moves the decode cursor past the next end-of-contents marker at this level. This method assumes an indefinite length marker has been parsed and the decode cursor advanced beyond this marker.

def parse(self, handler)

This method parses the complete message and invokes the event handler callback methods as various items are encountered.

Parameters

handler : Asn1TaggedEventHandler
Object implementing Asn1TaggedEventHandler class.
def parse_cons(self, handler, tag, length)
def parse_element(self, handler)

Parse an element TLV in a BER message.

Parameters

handler : Asn1TaggedEventHandler
Object implementing Asn1TaggedEventHandler class.

Returns

tag : Asn1BerTag
Parsed tag value.
length : Asn1BerLength
Parsed length value.
def parse_prim(self, handler, tag, length)
def peek(self, nbytes)

Peek at up to given number of bytes in decode input stream.

Parameters

nbytes : Number of bytes to peek at in stream.

Returns

ba : bytes
Byte array containing the bytes. If less than the requested number of bytes are available on the stream, this number of bytes will be returned.
def peek_byte(self)

Peek at the next available byte in decode input stream.

Returns

b : int
Next byte in decode stream
def read(self, nbytes)
def read_byte(self)
def read_chars(self, nbytes, encoding_)
def read_tag(self)
def reset(self)
def skip(self, nbytes)
def skip_element(self)

This method skips the element TLV at the current location.

def skip_tag(self)

This method skips the tag at the current location.

class Asn1BerDecodeContext (decbuf, conslen=None)

This class is mainly for internal use by the compiler to keep track of where nested constructed elements (SEQUENCE, SET, CHOICE, etc.) begin and end.

The constructor initializes all internal working variables.

Parameters

decbuf : Asn1BerDecodeBuffer
Reference to decode buffer object.
conslen : Asn1BerLength
Length of constructed type content. This may be indefinite.

Methods

def add_tag(self, tag)

This method adds a tag to the tag history list. This is used in the decoding of SET's to check for duplicate tags.

Parameters

tag : Asn1BerTag
Tag to be added to list

Returns

result : bool
True if tag added, false if it already exists on the list
def expired(self)

This method will determine if a decoding context is expired. A context is defined to be the wrapper in which a set of elements or a primitive data type resides..

Returns

result : bool
True if at the end of the context block
def match_elem_tag(self, enctag, advance=1)

This method will attempt to match the next element tag in a constructed type with the expected value. It will check to see if the context is expired and, if not, will match the given tag with the expected tag. The decode cursor is advanced if the boolean advance argument is true.

Parameters

enctag : bytes
Encoded tag bytes
advance : integer
0 = do not advance decode cursor 1 = advance past decode tag and length (default) 2 = advance past decoded content (i.e skip element)

Returns

parsed_len : Asn1BerLength
Parsed length value or None if tags do not match.
def match_set_elem_tag(self, enctag, advance=1)

This method will attempt to match the next element tag in a SET type with the expected value. It is the same as the match_elem_tag method except that it also does a duplicate tag check on successful match.

Parameters

enctag : bytes
Encoded tag bytes
advance : integer
0 = do not advance decode cursor 1 = advance past decode tag and length (default) 2 = advance past decoded content (i.e skip element)

Returns

parsed_len : Asn1BerLength
Parsed length value or None if tags do not match.
class Asn1BerEncodeBuffer (stream=None)

This class handles the encoding of ASN.1 messages as specified in the Basic Encoding Rules (BER) as specified in the ITU-T X.690 standard. A reference to an object of this type is passed to each of the ASN.1 type encode methods involved in encoding a particular message type.

Methods

def bin_dump(self)

This method dumps the encoded message in a human-readable format showing a bit trace of all fields.

Returns

strbuf : str
String containing formatted data.
def buffer(self)

Return the encoded data

Returns

bytearray
 
def encode_bcdstr(self, value, tagbytes=None)

Encode BCD STRING value.

Parameters

value : bytearray or string
If byte array value provided, encoded as a normal OCTET STRING. If string, digits are converted to binary and encoded.
tagbytes : bytearray
Encoded tag bytes used for implicit tagging to replace the universal tag that would be encoded by default.

Returns

length : int
Length in bytes of encoded item.
def encode_bitstr(self, value, tagbytes=None)

Encode the given BIT STRING value.

The value will be encoded in primitive form.

Parameters

value : Asn1BitString, bytes, or bytearray
 
tagbytes : bytearray
Encoded tag bytes used for implicit tagging to replace the universal tag that would be encoded by default.

Returns

int
The length of the encoded data.
def encode_bmpstr(self, value, tagbytes=None)

This method encodes a BMP character string value.

Parameters

value : str
Character string value to encode.
tagbytes : bytearray
Encoded tag bytes used for implicit tagging to replace the universal tag that would be encoded by default.

Returns

length : int
Length in bytes of encoded item.
def encode_boolean(self, value, tagbytes=None)

Encode boolean value.

Parameters

value : boolean
Boolean value to encode.
tagbytes : bytearray
Encoded tag bytes used for implicit tagging to replace the universal tag that would be encoded by default.

Returns

length : int
Length in bytes of encoded item.
def encode_bytes(self, value)

Encode the given bytes value.

Parameters

value : bytes or bytearray
 

Returns

int
The number of bytes encoded, which will be len(value).
def encode_charstr(self, value, univtag, tagbytes=None)

Encode character string value.

Parameters

value : str
Character string value to encode.
univtag : int
Universal tag value
tagbytes : bytearray
Encoded tag bytes used for implicit tagging to replace the universal tag that would be encoded by default.

Returns

length : int
Length in bytes of encoded item.
def encode_def_len(self, length)

Encode definite length value.

Parameters

length : int
Length value to encode.

Returns

enclen : int
Length in bytes of encoded length.
def encode_enum(self, value, tagbytes=None)

This method encodes an enumerated value.

Parameters

value : int
Integer enumerated value to be encoded. It is assumed this value has been validated to belong to the enumeration.
tagbytes : bytearray
Encoded tag bytes used for implicit tagging to replace the universal tag that would be encoded by default.

Returns

length : int
Length in bytes of encoded item.
def encode_gentimestr(self, value, tagbytes=None)

This method encodes a GeneralizedTime character string value.

Parameters

value : str
Character string value to encode.
tagbytes : bytearray
Encoded tag bytes used for implicit tagging to replace the universal tag that would be encoded by default.

Returns

length : int
Length in bytes of encoded item.
def encode_identifier(self, ident)

Encode an identifier such as the ones used in tags or object identifiers.

Parameters

ident : int
Identifier to be encoded.

Returns

enclen : int
Length of the encoded component in octets
encident : bytearray
The encoded identifier in a bytearray
def encode_integer(self, value, tagbytes=None)

This method encodes an integer value.

Parameters

value : int or NamedInt
Integer value to be encoded
tagbytes : bytearray
Encoded tag bytes used for implicit tagging to replace the universal tag that would be encoded by default.

Returns

length : int
Length in bytes of encoded item.
def encode_null(self, tagbytes=None)

Encode null value.

Parameters

tagbytes : bytearray
Encoded tag bytes used for implicit tagging to replace the universal tag that would be encoded by default.

Returns

length : int
Length in bytes of encoded item.
def encode_octetstr(self, value, tagbytes=None)

Encode OCTET STRING value.

Parameters

value : bytearray
Byte array value to encode.
tagbytes : bytearray
Encoded tag bytes used for implicit tagging to replace the universal tag that would be encoded by default.

Returns

length : int
Length in bytes of encoded item.
def encode_oid(self, oid, tagbytes=None)

Encode OBJECT IDENTIFIER value.

Parameters

oid : Iterable of integers
OBJECT IDENTIFIER to encode.
tagbytes : bytearray
Encoded tag bytes used for implicit tagging to replace the universal tag that would be encoded by default.

Returns

length : int
Length in bytes of encoded item.
def encode_oid_iri(self, value, tagbytes=None)

Encode character string value.

Parameters

value : str
Character string value to encode.
tagbytes : bytearray
Encoded tag bytes used for implicit tagging to replace the universal tag that would be encoded by default.

Returns

length : int
Length in bytes of encoded item.
def encode_opentype(self, value)

Encode the given open type value. The value is assumed to be a complete encoded TLV.

Parameters

value : bytes or bytearray
 

Returns

int
The number of bytes encoded, which will be len(value).
def encode_real(self, value, tagbytes=None)

Encode given value as an ASN.1 REAL value.

A float or int value is encoded in base 2 and a decimal.Decimal is encoded in base 10 using NR3 form.

Parameters

value : int, float or decimal.Decimal
 
tagbytes : bytearray
Encoded tag bytes used for implicit tagging to replace the universal tag that would be encoded by default.

Returns

length : int
Length in bytes of encoded item.
def encode_reloid_iri(self, value, tagbytes=None)

Encode character string value.

Parameters

value : str
Character string value to encode.
tagbytes : bytearray
Encoded tag bytes used for implicit tagging to replace the universal tag that would be encoded by default.

Returns

length : int
Length in bytes of encoded item.
def encode_roid(self, roid, tagbytes=None)

Encode RELATIVE OID value.

Parameters

roid : Iterable of integers
RELATIVE OID to encode.
tagbytes : bytearray
Encoded tag bytes used for implicit tagging to replace the universal tag that would be encoded by default.

Returns

length : int
Length in bytes of encoded item.
def encode_tbcdstr(self, value, tagbytes=None)

Encode TBCD STRING value.

Parameters

value : bytearray or string
If byte array value provided, encoded as a normal OCTET STRING. If string, digits are converted to binary and encoded.
tagbytes : bytearray
Encoded tag bytes used for implicit tagging to replace the universal tag that would be encoded by default.

Returns

length : int
Length in bytes of encoded item.
def encode_tlv(self, tagbytes, content)

Encode tag-length-value. Length is encoded in definite length form.

Parameters

tagbytes : bytearray
BER-encoded tag bytes to be written to output stream
content : bytearray
BER-encoded content bytes to be written to output stream

Returns

total_len : integer
Length in bytes of encoded TLV
def encode_universalstr(self, value, tagbytes=None)

This method encodes a Universal character string value.

Parameters

value : str
Character string value to encode.
tagbytes : bytearray
Encoded tag bytes used for implicit tagging to replace the universal tag that would be encoded by default.

Returns

length : int
Length in bytes of encoded item.
def encode_utctimestr(self, value, tagbytes=None)

This method encodes a UTCTime character string value.

Parameters

value : str
Character string value to encode.
tagbytes : bytearray
Encoded tag bytes used for implicit tagging to replace the universal tag that would be encoded by default.

Returns

length : int
Length in bytes of encoded item.
class Asn1BerLength (length=None, indef=False)

Represents a BER length, which may be either an int value for a known length, or an indefinite length.

Attributes

value : int or None
If not indef, this is the length, otherwise it is None. Setting this to an int sets indef to False; setting it to None sets indef to True.
indef : bool
If true, this is an indefinite length. If false, value is the length. Setting this to True sets value to None. Setting this to False sets value to zero.

Methods

guard(buffer) Create a guard to protect against violating a definite length boundary. It can also be used as an iterator to iterate over (Asn1BerTag, Asn1BerLength) tuples for constructed content. For example: len = buffer.decode_length() with len.guard(buffer) as guard: # protected code cannot go past def len boundary

        for tag,len in guard:
            # loop over each tag and length

Instance variables

var indef
var value

Methods

def guard(self, decoder)

Return a guard that can be used with the with statement, such as: length = buffer.decode_length() with length.guard(buffer): do stuff that must not go past length

Parameters

decoder : Asn1BerDecodeBuffer
 
def set_def_len(self, length)
def set_indef_len(self)
class Asn1BerTag (cls=0, form=0, id_code=0)
  • This specifies that explicit tagging should be used.

Class variables

var APPL
  • Mask value for a context-specific tag
var BIT_STRING
var BMPSTRING
var BOOLEAN
var CLASSMASK
  • Mask value for PRIMITIVE form
var CONS
  • Mask value to mask the form bit from a tag
var CTXT
  • Mask value for a PRIVATE tag
var DATE
var DATE_TIME
var DURATION
var EMBEDDED_PDV
var ENUMERATED
var EXPL
  • This specifies that implicit tagging should be used.
var EXTERNAL
var EXTIDCODE
  • Mask value to mask the tag ID bits from a tag
var FORMMASK
  • Mask value for extended tag identifier indicator
var GENERALIZED_TIME
var GENERALSTRING
var GRAPHICSTRING
var IA5STRING
var IDMASK

Universal tag values

var IMPL
  • Mask value for a UNIVERSAL tag
var INTEGER
var NULL
var NUMERICSTRING
var OBJECT_DESCRIPTOR
var OBJECT_ID
var OCTET_STRING
var OID_IRI
var PRIM
  • Mask value for CONSTRUCTED form
var PRINTABLESTRING
var PRIV
  • Mask value to mask the class bits from a tag
var REAL
var RELATIVE_OID
var RELATIVE_OID_IRI
  • The constructor initializes all fields to the given values *
  • @param cls Tag class value (UNIV, APPL, CTXT, or PRIV)
  • @param form Tag form value (PRIM or CONS)
  • @param id_code Tag identifier code
var T61STRING
var TELETEXSTRING
var TIME
var TIME_OF_DAY
var UNIV
  • Mask value for an APPLICATION tag
var UNIVERSALSTRING
var UTC_TIME
var UTF8STRING
var VIDEOTEXSTRING
var VISIBLESTRING

Methods

def is_constructed(self)

This method tests if the tag is constructed.

def is_eoc(self)

Test if tag is an EOC tag.

def is_universal(self, tagid)

Test if tag is a UNIVERSAL tag with given tagid.