# -*- ruby encoding: utf-8 -*- module Net # :nodoc: ## # == Basic Encoding Rules (BER) Support Module # # Much of the text below is cribbed from Wikipedia: # http://en.wikipedia.org/wiki/Basic_Encoding_Rules # # The ITU Specification is also worthwhile reading: # http://www.itu.int/ITU-T/studygroups/com17/languages/X.690-0207.pdf # # The Basic Encoding Rules were the original rules laid out by the ASN.1 # standard for encoding abstract information into a concrete data stream. # The rules, collectively referred to as a transfer syntax in ASN.1 # parlance, specify the exact octet sequences which are used to encode a # given data item. The syntax defines such elements as: the # representations for basic data types, the structure of length # information, and the means for defining complex or compound types based # on more primitive types. The BER syntax, along with two subsets of BER # (the Canonical Encoding Rules and the Distinguished Encoding Rules), are # defined by the ITU-T's X.690 standards document, which is part of the # ASN.1 document series. # # == Encoding # The BER format specifies a self-describing and self-delimiting format # for encoding ASN.1 data structures. Each data element is encoded as a # type identifier, a length description, the actual data elements, and # where necessary, an end-of-content marker. This format allows a receiver # to decode the ASN.1 information from an incomplete stream, without # requiring any pre-knowledge of the size, content, or semantic meaning of # the data. # # # # == Protocol Data Units (PDU) # Protocols are defined with schema represented in BER, such that a PDU # consists of cascaded type-length-value encodings. # # === Type Tags # BER type tags are represented as single octets (bytes). The lower five # bits of the octet are tag identifier numbers and the upper three bits of # the octet are used to distinguish the type as native to ASN.1, # application-specific, context-specific, or private. See # Net::BER::TAG_CLASS and Net::BER::ENCODING_TYPE for more information. # # If Class is set to Universal (0b00______), the value is of a type native # to ASN.1 (e.g. INTEGER). The Application class (0b01______) is only # valid for one specific application. Context_specific (0b10______) # depends on the context and private (0b11_______) can be defined in # private specifications # # If the primitive/constructed bit is zero (0b__0_____), it specifies that # the value is primitive like an INTEGER. If it is one (0b__1_____), the # value is a constructed value that contains type-length-value encoded # types like a SET or a SEQUENCE. # # === Defined Universal (ASN.1 Native) Types # There are a number of pre-defined universal (native) types. # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
NamePrimitive
Constructed
Number
EOC (End-of-Content)P0: 0 (0x0, 0b00000000)
BOOLEANP1: 1 (0x01, 0b00000001)
INTEGERP2: 2 (0x02, 0b00000010)
BIT STRINGP3: 3 (0x03, 0b00000011)
BIT STRINGC3: 35 (0x23, 0b00100011)
OCTET STRINGP4: 4 (0x04, 0b00000100)
OCTET STRINGC4: 36 (0x24, 0b00100100)
NULLP5: 5 (0x05, 0b00000101)
OBJECT IDENTIFIERP6: 6 (0x06, 0b00000110)
Object DescriptorP7: 7 (0x07, 0b00000111)
EXTERNALC8: 40 (0x28, 0b00101000)
REAL (float)P9: 9 (0x09, 0b00001001)
ENUMERATEDP10: 10 (0x0a, 0b00001010)
EMBEDDED PDVC11: 43 (0x2b, 0b00101011)
UTF8StringP12: 12 (0x0c, 0b00001100)
UTF8StringC12: 44 (0x2c, 0b00101100)
RELATIVE-OIDP13: 13 (0x0d, 0b00001101)
SEQUENCE and SEQUENCE OFC16: 48 (0x30, 0b00110000)
SET and SET OFC17: 49 (0x31, 0b00110001)
NumericStringP18: 18 (0x12, 0b00010010)
NumericStringC18: 50 (0x32, 0b00110010)
PrintableStringP19: 19 (0x13, 0b00010011)
PrintableStringC19: 51 (0x33, 0b00110011)
T61StringP20: 20 (0x14, 0b00010100)
T61StringC20: 52 (0x34, 0b00110100)
VideotexStringP21: 21 (0x15, 0b00010101)
VideotexStringC21: 53 (0x35, 0b00110101)
IA5StringP22: 22 (0x16, 0b00010110)
IA5StringC22: 54 (0x36, 0b00110110)
UTCTimeP23: 23 (0x17, 0b00010111)
UTCTimeC23: 55 (0x37, 0b00110111)
GeneralizedTimeP24: 24 (0x18, 0b00011000)
GeneralizedTimeC24: 56 (0x38, 0b00111000)
GraphicStringP25: 25 (0x19, 0b00011001)
GraphicStringC25: 57 (0x39, 0b00111001)
VisibleStringP26: 26 (0x1a, 0b00011010)
VisibleStringC26: 58 (0x3a, 0b00111010)
GeneralStringP27: 27 (0x1b, 0b00011011)
GeneralStringC27: 59 (0x3b, 0b00111011)
UniversalStringP28: 28 (0x1c, 0b00011100)
UniversalStringC28: 60 (0x3c, 0b00111100)
CHARACTER STRINGP29: 29 (0x1d, 0b00011101)
CHARACTER STRINGC29: 61 (0x3d, 0b00111101)
BMPStringP30: 30 (0x1e, 0b00011110)
BMPStringC30: 62 (0x3e, 0b00111110)
module BER VERSION = '0.2.2' ## # Used for BER-encoding the length and content bytes of a Fixnum integer # values. MAX_FIXNUM_SIZE = 0.size ## # BER tag classes are kept in bits seven and eight of the tag type # octet. # # # # # # # #
BitmaskDefinition
0b00______Universal (ASN.1 Native) Types
0b01______Application Types
0b10______Context-Specific Types
0b11______Private Types
TAG_CLASS = { :universal => 0b00000000, # 0 :application => 0b01000000, # 64 :context_specific => 0b10000000, # 128 :private => 0b11000000, # 192 } ## # BER encoding type is kept in bit 6 of the tag type octet. # # # # # #
BitmaskDefinition
0b__0_____Primitive
0b__1_____Constructed
ENCODING_TYPE = { :primitive => 0b00000000, # 0 :constructed => 0b00100000, # 32 } ## # Accepts a hash of hashes describing a BER syntax and converts it into # a byte-keyed object for fast BER conversion lookup. The resulting # "compiled" syntax is used by Net::BER::BERParser. # # This method should be called only by client classes of Net::BER (e.g., # Net::LDAP and Net::SNMP) and not by clients of those classes. # # The hash-based syntax uses TAG_CLASS keys that contain hashes of # ENCODING_TYPE keys that contain tag numbers with object type markers. # # : => { # : => { # => # }, # }, # # === Permitted Object Types # :string:: A string value, represented as BerIdentifiedString. # :integer:: An integer value, represented with Fixnum. # :oid:: An Object Identifier value; see X.690 section # 8.19. Currently represented with a standard array, # but may be better represented as a # BerIdentifiedOID object. # :array:: A sequence, represented as BerIdentifiedArray. # :boolean:: A boolean value, represented as +true+ or +false+. # :null:: A null value, represented as BerIdentifiedNull. # # === Example # Net::LDAP defines its ASN.1 BER syntax something like this: # # class Net::LDAP # AsnSyntax = Net::BER.compile_syntax({ # :application => { # :primitive => { # 2 => :null, # }, # :constructed => { # 0 => :array, # # ... # }, # }, # :context_specific => { # :primitive => { # 0 => :string, # # ... # }, # :constructed => { # 0 => :array, # # ... # }, # } # }) # end # # NOTE:: For readability and formatting purposes, Net::LDAP and its # siblings actually construct their syntaxes more deliberately, # as shown below. Since a hash is passed in the end in any case, # the format does not matter. # # primitive = { 2 => :null } # constructed = { # 0 => :array, # # ... # } # application = { # :primitive => primitive, # :constructed => constructed # } # # primitive = { # 0 => :string, # # ... # } # constructed = { # 0 => :array, # # ... # } # context_specific = { # :primitive => primitive, # :constructed => constructed # } # AsnSyntax = Net::BER.compile_syntax(:application => application, # :context_specific => context_specific) def self.compile_syntax(syntax) # TODO 20100327 AZ: Should we be allocating an array of 256 values # that will either be +nil+ or an object type symbol, or should we # allocate an empty Hash since unknown values return +nil+ anyway? out = [ nil ] * 256 syntax.each do |tag_class_id, encodings| tag_class = TAG_CLASS[tag_class_id] encodings.each do |encoding_id, classes| encoding = ENCODING_TYPE[encoding_id] object_class = tag_class + encoding classes.each do |number, object_type| out[object_class + number] = object_type end end end out end end end class Net::BER::BerError < RuntimeError; end ## # An Array object with a BER identifier attached. class Net::BER::BerIdentifiedArray < Array attr_accessor :ber_identifier def initialize(*args) super end end ## # A BER object identifier. class Net::BER::BerIdentifiedOid attr_accessor :ber_identifier def initialize(oid) if oid.is_a?(String) oid = oid.split(/\./).map {|s| s.to_i } end @value = oid end def to_ber to_ber_oid end def to_ber_oid @value.to_ber_oid end def to_s @value.join(".") end def to_arr @value.dup end end ## # A String object with a BER identifier attached. class Net::BER::BerIdentifiedString < String attr_accessor :ber_identifier def initialize args super args end end module Net::BER ## # A BER null object. class BerIdentifiedNull attr_accessor :ber_identifier def to_ber "\005\000" end end ## # The default BerIdentifiedNull object. Null = Net::BER::BerIdentifiedNull.new end require 'net/ber/core_ext'