rasn1 0.16.1 → 0.16.3

data/lib/rasn1/tracer.rb

@@ -14,23 +14,25 @@ module RASN1
     # @return [Integer]
     attr_accessor :tracing_level
 
+    # @private
+    # Classes to trace
     TRACED_CLASSES = [Types::Any, Types::Choice, Types::Sequence, Types::SequenceOf, Types::Base].freeze
 
-    # @param [IO] io
+    # @param io [IO] io to use to put traces
     def initialize(io)
       @io = io
       @tracing_level = 0
     end
 
     # Puts +msg+ onto {#io}.
-    # @param [String] msg
+    # @param msg [String]
     # @return [void]
     def trace(msg)
       @io.puts(indent << msg)
     end
 
     # Return identation for given +level+. If +nil+, use {#tracing_level}.
-    # @param [Integer,nil] level
+    # @param level [Integer,nil]
     # @return [String]
     def indent(level=nil)
       level ||= @tracing_level
@@ -41,13 +43,13 @@ module RASN1
   # Trace RASN1 parsing to +io+.
   # All parsing methods called in block are traced to +io+. Each ASN.1 element is
   # traced in a line showing element's id, its length and its data.
-  # @param [IO] io
+  # @param io [IO]
+  # @return [void]
   # @example
   #   RASN1.trace do
   #     RASN1.parse("\x02\x01\x01")  # puts "INTEGER id: 2 (0x02), len: 1 (0x01), data: 0x01"
   #   end
   #   RASN1.parse("\x01\x01\xff")    # puts nothing onto STDOUT
-  # @return [void]
   def self.trace(io=$stdout)
     @tracer = Tracer.new(io)
     Tracer::TRACED_CLASSES.each(&:start_tracing)
@@ -62,6 +64,7 @@ module RASN1
   end
 
   # @private
+  # @return [Tracer]
   def self.tracer
     @tracer
   end
@@ -71,6 +74,7 @@ module RASN1
       class << self
         # @private
         # Patch {#do_parse} to add tracing ability
+        # @return [void]
         def start_tracing
           alias_method :do_parse_without_tracing, :do_parse
           alias_method :do_parse, :do_parse_with_tracing
@@ -80,6 +84,7 @@ module RASN1
 
         # @private
         # Unpatch {#do_parse} to remove tracing ability
+        # @return [void]
         def stop_tracing
           alias_method :do_parse, :do_parse_without_tracing
           alias_method :do_parse_explicit, :do_parse_explicit_without_tracing
@@ -88,6 +93,7 @@ module RASN1
 
       # @private
       # Parse +der+ with tracing abillity
+      # @!macro do_parse
       # @see #parse!
       def do_parse_with_tracing(der, ber:)
         ret = do_parse_without_tracing(der, ber: ber)
@@ -95,6 +101,11 @@ module RASN1
         ret
       end
 
+      # @private
+      # Delegate with tracing to explicit type to generate sub-value
+      # @param data [String]
+      # @return [void]
+      # @see #parse!
       def do_parse_explicit_with_tracing(data)
         RASN1.tracer.tracing_level += 1
         do_parse_explicit_without_tracing(data)
@@ -106,6 +117,7 @@ module RASN1
       class << self
         # @private
         # Patch {#parse!} to add tracing ability
+        # @return [void]
         def start_tracing
           alias_method :parse_without_tracing, :parse!
           alias_method :parse!, :parse_with_tracing
@@ -113,6 +125,7 @@ module RASN1
 
         # @private
         # Unpatch {#parse!} to remove tracing ability
+        # @return [void]
         def stop_tracing
           alias_method :parse!, :parse_without_tracing
         end
@@ -120,6 +133,7 @@ module RASN1
 
       # @private
       # Parse +der+ with tracing abillity
+      # @!macro do_parse
       # @see #parse!
       def parse_with_tracing(der, ber: false)
         RASN1.tracer.trace(self.trace)
@@ -131,6 +145,7 @@ module RASN1
       class << self
         # @private
         # Patch {#der_to_value} to add tracing ability
+        # @return [void]
         def start_tracing
           alias_method :der_to_value_without_tracing, :der_to_value
           alias_method :der_to_value, :der_to_value_with_tracing
@@ -138,6 +153,7 @@ module RASN1
 
         # @private
         # Unpatch {#der_to_value} to remove tracing ability
+        # @return [void]
         def stop_tracing
           alias_method :der_to_value, :der_to_value_without_tracing
         end
@@ -145,6 +161,7 @@ module RASN1
 
       # @private
       # der_to_value +der+ with tracing abillity
+      # @!macro do_parse
       def der_to_value_with_tracing(der, ber: false)
         RASN1.tracer.tracing_level += 1
         der_to_value_without_tracing(der, ber: ber)
@@ -156,6 +173,7 @@ module RASN1
       class << self
         # @private
         # Patch {#der_to_value} to add tracing ability
+        # @return [void]
         def start_tracing
           alias_method :der_to_value_without_tracing, :der_to_value
           alias_method :der_to_value, :der_to_value_with_tracing
@@ -163,6 +181,7 @@ module RASN1
 
         # @private
         # Unpatch {#der_to_value} to remove tracing ability
+        # @return [void]
         def stop_tracing
           alias_method :der_to_value, :der_to_value_without_tracing
         end
@@ -170,6 +189,7 @@ module RASN1
 
       # @private
       # der_to_value +der+ with tracing abillity
+      # @!macro do_parse
       def der_to_value_with_tracing(der, ber: false)
         RASN1.tracer.tracing_level += 1
         der_to_value_without_tracing(der, ber: ber)

data/lib/rasn1/types/any.rb

@@ -10,7 +10,24 @@ module RASN1
   module Types
     # ASN.1 ANY: accepts any types
     #
+    # ANY is often used with an {ObjectId} to detect real type.
+    #
+    # On encoding, ANY is replaced by its values (which must be an RASN1 type).
     # If `any#value` is `nil` and Any object is not {#optional?}, `any` will be encoded as a {Null} object.
+    #
+    # @example Parsing with any model
+    #   class AnyModel < RASN1::Model
+    #     sequence :seq,
+    #              content: [objectid(:id), any(:data)]
+    #   end
+    #   model = AnyModel.new
+    #   model.parse!("\x30\x09\x06\x03\x2a\x03\x04\x02\x02\x01\xff")
+    #   model[:id].value    #=> "1.2.3.4"
+    #   model[:data].value  #=> "\x02\x02\x01\xff"
+    #   # As we knwon object with id 1.2.3.4 is an integer, with then parse data as such
+    #   data = RASN1::Types::Integer.new
+    #   data.parse!(model[:data].value)
+    #   data.value          #=> 511
     # @author Sylvain Daubert
     class Any < Base
       # @return [String] DER-formated string
@@ -27,21 +44,22 @@ module RASN1
         end
       end
 
+      # @return [Boolean]
       def can_build?
         value? || !optional?
       end
 
       # Parse a DER string. This method updates object: {#value} will be a DER
       # string.
-      # @param [String] der DER string
-      # @param [Boolean] ber if +true+, accept BER encoding
+      # @param der [String] DER string
+      # @param ber [Boolean] if +true+, accept BER encoding
       # @return [Integer] total number of parsed bytes
       def parse!(der, ber: false)
         total_length, _data = do_parse(der, ber: ber)
         total_length
       end
 
-      # @param [::Integer] level
+      # @param level [::Integer]
       # @return [String]
       def inspect(level=0)
         str = common_inspect(level)
@@ -66,6 +84,7 @@ module RASN1
 
       private
 
+      # @param level [Integer]
       def common_inspect(level)
         lvl = [0, level].max
         str = '  ' * lvl
@@ -77,6 +96,7 @@ module RASN1
       end
 
       # @private
+      # @!macro do_parse
       # @see Types::Base#do_parse
       def do_parse(der, ber: false)
         if der.empty?
@@ -96,6 +116,7 @@ module RASN1
         [total_length, real_value]
       end
 
+      # @return [String]
       def trace_any
         msg_type(no_id: true) << trace_data(value)
       end

data/lib/rasn1/types/base.rb

@@ -75,7 +75,7 @@ module RASN1
       attr_reader :asn1_class
       # @return [Object,nil] default value, if defined
       attr_reader :default
-      # @return [Hash[Symbol, Object]]
+      # @return [Hash{Symbol => Object}]
       attr_reader :options
       # @return [String] raw parsed data
       attr_reader :raw_data
@@ -99,10 +99,10 @@ module RASN1
       end
 
       # Parse a DER or BER string
-      # @param [String] der_or_ber string to parse
-      # @param [Hash] options
-      # @return [Base]
+      # @param der_or_ber [String] string to parse
+      # @param options [Hash]
       # @option options [Boolean] :ber if +true+, parse a BER string, else a DER one
+      # @return [Base]
       # @note More options are supported. See {Base#initialize}.
       def self.parse(der_or_ber, options={})
         obj = self.new(options)
@@ -117,18 +117,19 @@ module RASN1
         false
       end
 
-      # @param [Hash] options
-      # @option options [Symbol] :class ASN.1 class. Default value is +:universal+.
-      #  If +:explicit+ or +:implicit:+ is defined, default value is +:context+.
-      # @option options [::Boolean] :optional define this tag as optional. Default
-      #   is +false+
-      # @option options [Object] :default default value (ASN.1 DEFAULT)
-      # @option options [Object] :value value to set
-      # @option options [::Integer] :implicit define an IMPLICIT tagged type
-      # @option options [::Integer] :explicit define an EXPLICIT tagged type
-      # @option options [::Boolean] :constructed if +true+, set type as constructed.
-      #  May only be used when +:explicit+ is defined, else it is discarded.
-      # @option options [::String] :name name for this node
+      # @!macro [new] type_initialize
+      #   @param options [Hash]
+      #   @option options [Symbol] :class ASN.1 class. Default value is +:universal+.
+      #    If +:explicit+ or +:implicit:+ is defined, default value is +:context+.
+      #   @option options [::Boolean] :optional define this tag as optional. Default
+      #     is +false+
+      #   @option options [Object] :default default value (ASN.1 DEFAULT)
+      #   @option options [Object] :value value to set
+      #   @option options [::Integer] :implicit define an IMPLICIT tagged type
+      #   @option options [::Integer] :explicit define an EXPLICIT tagged type
+      #   @option options [::Boolean] :constructed if +true+, set type as constructed.
+      #    May only be used when +:explicit+ is defined, else it is discarded.
+      #   @option options [::String] :name name for this node
       def initialize(options={})
         @constructed = nil
         set_value(options.delete(:value))
@@ -142,6 +143,7 @@ module RASN1
       def specific_initializer; end
 
       # Deep copy @value and @default.
+      # @return [void]
       def initialize_copy(*)
         super
         @value = @value.dup
@@ -150,6 +152,7 @@ module RASN1
       end
 
       # Get value or default value
+      # @return [Object]
       def value
         if value?
           @value
@@ -159,12 +162,16 @@ module RASN1
       end
 
       # Set value. If +val+ is +nil+, unset value
-      # @param [Object,nil] val
+      # @!macro [new] value_setter
+      #   @param val [Object,nil]
+      #   @return [Object] return +val+
       def value=(val)
         set_value(val)
       end
 
       # @abstract Define 'void' value (i.e. 'value' when no value was set)
+      # For base type, this is an empty string
+      # @return [Object]
       def void_value
         ''
       end
@@ -202,11 +209,13 @@ module RASN1
         build
       end
 
+      # Say if self is defined as primitive (subclass of {Primitive} and constructed not defined in tag)
       # @return [::Boolean] +true+ if this is a primitive type
       def primitive?
         (self.class < Primitive) && !@constructed
       end
 
+      # Say if self is defined as constructed (subclass of {Constructed} or constructed defined in tag)
       # @return [::Boolean] +true+ if this is a constructed type
       def constructed?
         (self.class < Constructed) || !!@constructed
@@ -227,8 +236,8 @@ module RASN1
       # @abstract This method SHOULD be partly implemented by subclasses to parse
       #  data. Subclasses SHOULD respond to +#der_to_value+.
       # Parse a DER string. This method updates object.
-      # @param [String] der DER string
-      # @param [Boolean] ber if +true+, accept BER encoding
+      # @param der [String] DER string
+      # @param ber [Boolean] if +true+, accept BER encoding
       # @return [Integer] total number of parsed bytes
       # @raise [ASN1Error] error on parsing
       def parse!(der, ber: false)
@@ -250,7 +259,7 @@ module RASN1
         value_to_der.size
       end
 
-      # @param [Integer] level
+      # @param level [Integer]
       # @return [String]
       def inspect(level=0)
         str = common_inspect(level)
@@ -261,14 +270,14 @@ module RASN1
       end
 
       # Objects are equal if they have same class AND same DER
-      # @param [Base] other
+      # @param other [Base]
       # @return [Boolean]
       def ==(other)
         (other.class == self.class) && (other.to_der == self.to_der)
       end
 
       # Set options to this object
-      # @param [Hash] options
+      # @param options [Hash]
       # @return [void]
       # @since 0.12
       def options=(options)
@@ -307,10 +316,12 @@ module RASN1
         end
       end
 
-      # @private Parse tage and length from binary string. Return data length and binary data.
-      # @param [String] der
-      # @param [Boolean] ber
-      # @return [Array(::Integer, String)]
+      # @private
+      # Parse tage and length from binary string. Return data length and binary data.
+      # @!macro [new] do_parse
+      #   @param der [String]
+      #   @param ber [Boolean]
+      #   @return [Array(::Integer, String)]
       # @since 0.15.0 was private before
       def do_parse(der, ber: false)
         return [0, ''] unless check_id(der)
@@ -323,8 +334,9 @@ module RASN1
         [total_length, data]
       end
 
-      # @private Delegate to #explicit type to generate sub-value
-      # @param [String] data
+      # @private
+      # Delegate to explicit type to generate sub-value
+      # @param data [String]
       # @return [void]
       # @since 0.15.0 was private before
       def do_parse_explicit(data)
@@ -334,8 +346,8 @@ module RASN1
       end
 
       # Make value from DER/BER string
-      # @param [String] der
-      # @param [::Boolean] ber
+      # @param der [String]
+      # @param ber [::Boolean]
       # @return [void]
       # @since 0.15.0 was private before
       def der_to_value(der, ber: false) # rubocop:disable Lint/UnusedMethodArgument
@@ -344,16 +356,21 @@ module RASN1
 
       private
 
+      # @private Tracer private API
+      # @return [String]
       def trace_real
-        encoded_id = unpack(encode_identifier_octets)
+        encoded_id = bin2hex(encode_identifier_octets)
         data_length = raw_data.length
-        encoded_length = unpack(raw_length)
+        encoded_length = bin2hex(raw_length)
         msg = msg_type
         msg << " (0x#{encoded_id}),"
         msg << " len: #{data_length} (0x#{encoded_length})"
         msg << trace_data
       end
 
+      # @private Tracer private API
+      # @param data [String,nil]
+      # @return [String]
       def trace_data(data=nil)
         byte_count = 0
         data ||= raw_data
@@ -372,24 +389,33 @@ module RASN1
         lines.map(&:rstrip).join << "\n"
       end
 
+      # @private Tracer private API
+      # @param count [Integer]
+      # @return [String]
       def trace_format_new_data_line(count)
         head_line = RASN1.tracer.indent(RASN1.tracer.tracing_level + 1)
         ("\n#{head_line}%04x " % count) << ' ' * 68
       end
 
+      # @private Tracer private API
+      # @param byte_count [Integer]
+      # @param byte_count_mul [Integer]
+      # @param offset [Integer]
+      # @return [Integer]
       def compute_trace_index(byte_count, byte_count_mul=1, offset=0)
         base_idx = 7 + RASN1.tracer.indent(RASN1.tracer.tracing_level + 1).length
         base_idx + offset + (byte_count % 16) * byte_count_mul
       end
 
-      def unpack(binstr)
-        binstr.unpack1('H*')
-      end
-
+      # Give ASN.1 tag class as a string. Universal class is returned as an empty string.
+      # @return [String]
       def asn1_class_to_s
         asn1_class == :universal ? '' : asn1_class.to_s.upcase << ' '
       end
 
+      # @private Tracer private API
+      # @param no_id [Boolean] if +true+, do not show id
+      # @return [String]
       def msg_type(no_id: false)
         msg = name.nil? ? +'' : "#{name} "
         msg << "[ #{asn1_class_to_s}#{id} ] " unless no_id
@@ -405,6 +431,8 @@ module RASN1
         msg
       end
 
+      # Return a byte with P/C bit set accordingly to self
+      # @return [Integer]
       def pc_bit
         if @constructed.nil?
           self.class.const_get(:ASN1_PC)
@@ -415,6 +443,9 @@ module RASN1
         end
       end
 
+      # Common part for {#inspect}
+      # @param level [Integer]
+      # @return [String]
       def common_inspect(level)
         lvl = [level, 0].max
         str = '  ' * lvl
@@ -425,6 +456,8 @@ module RASN1
         str << "#{type}:"
       end
 
+      # Value part for {#inspect}
+      # @return [String]
       def inspect_value
         if value?
           value.inspect
@@ -433,6 +466,8 @@ module RASN1
         end
       end
 
+      # Serialize value to DER encoding
+      # @return [String]
       def value_to_der
         case @value
         when Base
@@ -442,6 +477,10 @@ module RASN1
         end
       end
 
+      # Set class
+      # @param asn1_class [Symbol, nil]
+      # @return [Symbol] ASN.1 symbol class from {CLASSES}
+      # @raise [ClassError]
       def set_class(asn1_class) # rubocop:disable Naming/AccessorMethodName
         case asn1_class
         when nil
@@ -455,16 +494,28 @@ module RASN1
         end
       end
 
+      # Set @optional
+      # @param optional [Object]
+      # @return [Boolean]
       def set_optional(optional) # rubocop:disable Naming/AccessorMethodName
         @optional = !!optional
       end
 
+      # Set @default
+      # @param default [Object] default value to set
+      # @return [Object] +default+
       def set_default(default) # rubocop:disable Naming/AccessorMethodName
         @default = default
       end
 
       # handle undocumented option +:tag_value+, used internally by
       # {RASN1.parse} to parse non-universal class tags.
+      # @param options [Hash]
+      # @option options [Boolean] :constructed
+      # @option options [Integer] :explicit
+      # @option options [Integer] :implicit
+      # @option options [Integer] :tag_value
+      # @return [void]
       def set_tag(options) # rubocop:disable Naming/AccessorMethodName
         @constructed = options[:constructed]
         if options[:explicit]
@@ -480,6 +531,9 @@ module RASN1
         @asn1_class = :context if defined?(@tag) && (@asn1_class == :universal)
       end
 
+      # Set value
+      # @param value [Object]
+      # @return [Object] +value+ or {#void_value} if +value+ is +nil
       def set_value(value) # rubocop:disable Naming/AccessorMethodName
         if value.nil?
           @no_value = true
@@ -491,6 +545,8 @@ module RASN1
         value
       end
 
+      # Encode +self+ to BER encoding
+      # @return [String]
       def build
         if can_build?
           if explicit?
@@ -506,16 +562,22 @@ module RASN1
         end
       end
 
+      # Return ID part of tag
+      # @return [Integer]
       def id_value
         return @id_value if defined?(@id_value) && !@id_value.nil?
 
         self.class.const_get(:ID)
       end
 
+      # Encode ID
+      # @return [String]
       def encode_identifier_octets
         id2octets.pack('C*')
       end
 
+      # Generate an aray of bytes from ID
+      # @return [Array<Integer>]
       def id2octets
         first_octet = CLASSES[asn1_class] | pc_bit
         if id < MULTI_OCTETS_ID
@@ -528,6 +590,8 @@ module RASN1
       # Encode an unsigned integer on multiple octets.
       # Value is encoded on bit 6-0 of each octet, bit 7(MSB) indicates wether
       # further octets follow.
+      # @param value [Integer]
+      # @return [Array<Integer>]
       def unsigned_to_chained_octets(value)
         ary = []
         while value.positive?
@@ -538,6 +602,9 @@ module RASN1
         ary
       end
 
+      # Encode size to bytes
+      # @param size [integer]
+      # @return [String]
       def encode_size(size)
         if size >= INDEFINITE_LENGTH
           bytes = []
@@ -554,6 +621,7 @@ module RASN1
       end
 
       # Check ID from +der+ is the one expected
+      # @param der [String] DER binary data
       # @return [Boolean] +true+ is ID is expected, +false+ if it is not but +self+ is {#optional?}
       #   or has a {#default} value.
       # @raise [ASN1Error] ID was not expected, is not optional and has no default value
@@ -573,6 +641,10 @@ module RASN1
         false
       end
 
+      # Extract data from DER/BER binary string
+      # @param der [String]
+      # @param ber [Boolean] +false+ => DER encoding, +true+ => BER encoding
+      # @return [Array(Integer, String)] Tuple of total element length in bytes and its data
       def get_data(der, ber)
         return [0, ''] if der.nil? || der.empty?
 
@@ -588,6 +660,10 @@ module RASN1
         [total_length, data]
       end
 
+      # Extract length of element from DER/BER binary string
+      # @param der [String]
+      # @param ber [Boolean] +false+ => DER encoding, +true+ => BER encoding
+      # @return [Array(Integer, Integer)] Tuple of length of data and length of length field, in bytes
       def get_length(der, ber)
         length = der.unpack1('C').to_i
         length_length = 0
@@ -603,6 +679,9 @@ module RASN1
         [length, length_length]
       end
 
+      # @param ber [Boolean] +false+ => DER encoding, +true+ => BER encoding
+      # @raise [ASN1Error] indefinite length and primitive type or DER encoding
+      # @raise [NotImplementedError] indefinite length and BER encoding
       def raise_on_indefinite_length(ber)
         if primitive?
           raise ASN1Error, "malformed #{type}: indefinite length " \
@@ -614,16 +693,24 @@ module RASN1
         end
       end
 
+      # Return a new object of explicit type class
+      # @return [Types::Base]
       def explicit_type
         self.class.new(name: name)
       end
 
+      # Raise bad id error
+      # @param der [String] DER/BER data
+      # @return [void]
+      # @raise [ASN1Error]
       def raise_id_error(der)
         msg = name.nil? ? +'' : "#{name}: "
         msg << "Expected #{self2name} but get #{der2name(der)}"
         raise ASN1Error, msg
       end
 
+      # Return human-readable tag name for self
+      # @return [String]
       def self2name
         name = "#{asn1_class.to_s.upcase} #{constructed? ? 'CONSTRUCTED' : 'PRIMITIVE'}"
         if implicit? || explicit?
@@ -633,6 +720,9 @@ module RASN1
         end
       end
 
+      # Return human-readable tag name for given +der+
+      # @param der [String] DER/BER data
+      # @return [String]
       def der2name(der)
         return 'no ID' if der.nil? || der.empty?
 
@@ -642,12 +732,18 @@ module RASN1
         name << " #{type.nil? ? '0x%X (0x%s)' % [id, bin2hex(der[0...id_size])] : type.encoded_type}"
       end
 
+      # Return RASN1 class associated with +id+
+      # @param id [Integer]
+      # @return [Class,nil]
       def find_type(id)
         Types.constants.map { |c| Types.const_get(c) }
              .select { |klass| klass < Primitive || klass < Constructed }
              .find { |klass| id == klass::ID }
       end
 
+      # Unpack given binary string to hex string
+      # @param str [String] binary string
+      # @return [String] hex string
       def bin2hex(str)
         str.unpack1('H*')
       end