class ASN1::BER

• ASN1::BER
• BinData
• Reference
• Object

Overview

A single ASN.1 Basic Encoding Rules (BER) TLV element: an identifier (tag), a length and a payload. Used to build and parse SNMP, LDAP, X.509 and similar protocols.

require "bindata/asn1"

ber = ASN1::BER.new
ber.set_integer(42)
io.write_bytes(ber)

ber = io.read_bytes(ASN1::BER)
ber.get_integer # => 42

Typed payload accessors live in data_types.cr (#get_integer/#set_integer, #get_object_id/#set_object_id, #get_string, #get_boolean, ...). A constructed element can be split into / built from sub-elements with #children / #children=.

Defined in:

Constant Summary

AFTER_DESERIALIZE = [] of Nil

BEFORE_SERIALIZE = [] of Nil

DIRECT_STRING_TAGS = {UniversalTags::UTF8String, UniversalTags::CharacterString, UniversalTags::PrintableString, UniversalTags::IA5String, UniversalTags::OctetString, UniversalTags::NumericString, UniversalTags::VisibleString, UniversalTags::GeneralString, UniversalTags::GraphicString}

String types whose repertoire is ASCII-compatible, so the UTF-8 String.new decodes them directly. (T61String / VideotexString use the T.61 / videotex character sets, which are neither ASCII nor UTF-8, so they are not decoded here rather than mis-decoded.)

ENDIAN = ["big"]

GENERALIZEDTIME_FORMAT = /\A(\d{4})(\d{2})(\d{2})(\d{2})(\d{2})(\d{2})(\.\d+)?(Z|[+-]\d{4})\z/

YYYYMMDDHHMMSS(.fff)?(Z|±HHMM).

KLASS_NAME = [ASN1::BER]

MAX_OID_ARC_BYTES = 32

Largest sub-identifier we decode, in continuation octets. A base-128 arc of this many bytes holds ~224 bits — far beyond any real OID arc (a UUID-based 2.25 arc is 128-bit, ~19 bytes). Bounds the BigInt build against the super-linear CPU cost of a hostile continuation run.

PARTS = [{type: "basic", name: identifier, cls: ASN1::BER::Identifier, onlyif: nil, verify: nil, value: nil}, {type: "basic", name: length, cls: ASN1::BER::Length, onlyif: nil, verify: nil, value: nil}] of Nil

REMAINING = [] of Nil

UTCTIME_FORMAT = /\A(\d{2})(\d{2})(\d{2})(\d{2})(\d{2})(\d{2})?(Z|[+-]\d{4})\z/

YYMMDDHHMM[SS](Z|±HHMM) — the seconds are optional.

Class Method Summary

• .bit_fields

Instance Method Summary

• #__format__ : IO::ByteFormat

  A group or bit_field captures the endianness at its declaration point, so declaring endian after one would silently leave it system-endian.

• #bitstring_unused_bits : UInt8

  The number of unused (padding) bits in the final data byte (0..7).

• #children

  Parses the payload as a sequence of nested BER elements.

• #children=(parts)

  Encodes parts into the payload and marks this element constructed.

• #constructed
• #constructed=(custom : Bool)
• #eoc?

  Whether this is an end-of-contents marker (00 00) — a primitive universal EndOfContent element with an empty payload, used to terminate indefinite content.

• #extended
• #extended=(parts : Array(ExtendedIdentifier))
• #extended?
• #get_bit_array : BitArray

  The BIT STRING's significant bits as a BitArray, numbered MSB-first from the first data byte (ASN.1 bit 0 is the high bit of the first byte).

• #get_bitstring : Bytes

  Reads the BIT STRING data bytes (dropping the leading unused-bit count).

• #get_boolean

  Reads the payload as a BOOLEAN.

• #get_bytes : Slice(UInt8)

  Returns the raw bytes

• #get_hexstring(universal = true, tag = UniversalTags::OctetString)

  Gets a hex representation of the bytes

• #get_integer(check_tags = {UniversalTags::Integer, UniversalTags::Enumerated}, check_class = TagClass::Universal) : Int64

  Reads the payload as a two's-complement signed INTEGER (or ENUMERATED).

• #get_integer_bytes : Bytes
• #get_object_id

  Returns the object ID in string format.

• #get_string

  Decodes the payload to a String.

• #get_time : Time

  Reads the payload as a UTCTime or GeneralizedTime, normalised to UTC.

• #identifier : Identifier

  Components of a BER object

• #identifier=(identifier : Identifier)

  Components of a BER object

• #inspect(io : IO) : Nil

  Appends a String representation of this object which includes its class name, its object address and the values of all instance variables.

• #length : Length
• #length=(length : Length)
• #max_depth : Int32

  Maximum nesting depth that #children and the indefinite-length reader will descend before raising MaxDepthExceeded.

• #max_depth=(max_depth : Int32)

  Maximum nesting depth that #children and the indefinite-length reader will descend before raising MaxDepthExceeded.

• #null?

  Whether this is a well-formed universal NULL element: primitive, tag 05, empty payload (X.690 §8.8).

• #payload : Bytes
• #payload=(payload : Bytes)
• #read(io : IO) : IO

  Reads the fields of this instance from io, in declaration order, and returns io.

• #sequence?

  Whether this is a constructed universal Sequence or Set, i.e.

• #set_bit_array(bits : BitArray)

  Sets a BIT STRING from a BitArray (numbered MSB-first, as ASN.1 expects).

• #set_bitstring(bytes : Bytes, unused_bits : Int = 0)

  Sets a BIT STRING from bytes, with unused_bits (0..7) of padding in the final byte.

• #set_boolean(value)

  Sets a BOOLEAN payload.

• #set_bytes(data, tag = UniversalTags::OctetString, tag_class = TagClass::Universal)

  Sets the raw payload bytes and the given tag.

• #set_hexstring(string, tag = UniversalTags::OctetString, tag_class = TagClass::Universal)

  Sets bytes from a hexstring

• #set_integer(value, tag = UniversalTags::Integer, tag_class = TagClass::Universal)

  Encodes value as a minimal two's-complement INTEGER payload.

• #set_null

  Sets an empty, primitive NULL payload (encodes as 05 00).

• #set_object_id(oid)

  Sets a string representing an object ID.

• #set_string(string, tag = UniversalTags::UTF8String, tag_class = TagClass::Universal)

  Sets a string.

• #set_time(time : Time, tag = UniversalTags::GeneralizedTime)

  Encodes time (converted to UTC) as a GeneralizedTime (default) or UTCTime, in the canonical …Z form.

• #size

  The current payload length in bytes.

• #strict=(strict : Bool)

  When set, reject non-canonical (DER) encodings: non-minimal / indefinite length, non-{00,FF} / multi-byte BOOLEAN, empty / non-minimal INTEGER, non-minimal OID, embedded-NUL strings, and an out-of-order universal SET OF (tag 17).

• #strict? : Bool

  When set, reject non-canonical (DER) encodings: non-minimal / indefinite length, non-{00,FF} / multi-byte BOOLEAN, empty / non-minimal INTEGER, non-minimal OID, embedded-NUL strings, and an out-of-order universal SET OF (tag 17).

• #tag

  The universal tag as a UniversalTags enum.

• #tag_class
• #tag_class=(tag : TagClass)
• #tag_number
• #tag_number=(tag_type : Int | UniversalTags)
• #write(io : IO)

  Writes the fields of this instance to io in declaration order.

Class Method Detail

Instance Method Detail

class Person
  def initialize(@name : String, @age : Int32)
  end
end

Person.new("John", 32).inspect # => #<Person:0x10fd31f20 @name="John", @age=32>