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_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_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.