rasn1 0.16.2 → 0.17.0

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

data/lib/rasn1/types/bit_string.rb

@@ -9,7 +9,18 @@
 module RASN1
   module Types
     # ASN.1 Bit String
+    #
+    # A BIT STRING is a primitive ASN.1 type, able to embbed data whose length is not multiple of a byte.
+    #
+    # To specify a non byte multiple length, +:bit_length+ option must be used.
+    #
+    # @example Simple bit string
+    #   # A 4-bit length bit string, with value 1000b
+    #   bs = RASN1::Types::BitString.new(value: "\x80", bit_length: 4)
+    #   # As DER/BER encode data on bytes, such encodings specify unused part in binary string
+    #   bs.to_der   #=> "\x03\x02\x04\x80"
     # @author Sylvain Daubert
+    # @author LemonTree55
     class BitString < Primitive
       # BitString id value
       ID = 3
@@ -17,10 +28,9 @@ module RASN1
       # @return [Integer]
       attr_writer :bit_length
 
-      # @param [Hash] options
+      # @!macro type_initialize
       # @option options [Object] :bit_length default bit_length value. Should be
       #   present if +:default+ is set
-      # @see Base#initialize common options to all ASN.1 types
       def initialize(options={})
         super
         if @default
@@ -40,7 +50,7 @@ module RASN1
         end
       end
 
-      # @param [Integer] level
+      # @param level [Integer]
       # @return [String]
       def inspect(level=0)
         str = common_inspect(level)
@@ -55,8 +65,8 @@ module RASN1
       end
 
       # Make value from DER/BER string. Also set {#bit_length}.
-      # @param [String] der
-      # @param [::Boolean] ber
+      # @param der [String]
+      # @param ber [::Boolean]
       # @return [void]
       # @see Types::Base#der_to_value
       def der_to_value(der, ber: false) # rubocop:disable Lint/UnusedMethodArgument
@@ -70,6 +80,7 @@ module RASN1
 
       # @author Sylvain Daubert
       # @author adfoster-r7
+      # @return [String]
       def value_to_der
         raise ASN1Error, "#{@name}: bit length is not set" if bit_length.nil?
 
@@ -89,6 +100,7 @@ module RASN1
         der
       end
 
+      # @return [String]
       def generate_value_with_correct_length
         value = (@value || '').dup.force_encoding('BINARY')
         value << "\x00".b while value.length * 8 < @bit_length.to_i
@@ -98,6 +110,7 @@ module RASN1
         value[0, max_len].to_s
       end
 
+      # @return [BitString]
       def explicit_type
         self.class.new(name: name, value: @value, bit_length: @bit_length)
       end

data/lib/rasn1/types/boolean.rb

@@ -9,7 +9,16 @@
 module RASN1
   module Types
     # ASN.1 Boolean
+    #
+    # BOOLEAN is a primitive type to handle true or false values.
+    # @example Booelan
+    #   bool = RASN1::Types::Boolean.new(value: true)
+    #   bool2 = RASN1.parse(bool.to_der)
+    #   bool2.class       #=> RASN1::Types::Boolean
+    #   bool3.value       #=> true
+    #
     # @author Sylvain Daubert
+    # @author LemonTree55
     class Boolean < Primitive
       # Boolean id value
       ID = 0x01
@@ -25,8 +34,8 @@ module RASN1
       end
 
       # Make boolean value from DER/BER string.
-      # @param [String] der
-      # @param [::Boolean] ber
+      # @param der [String]
+      # @param ber [::Boolean]
       # @return [void]
       # @see Types::Base#der_to_value
       # @raise [ASN1Error] +der+ is not 1-byte long
@@ -49,14 +58,16 @@ module RASN1
 
       private
 
+      # @return [String]
       def value_to_der
         [@value ? DER_TRUE : DER_FALSE].pack('C')
       end
 
+      # @return [String]
       def trace_data
         return super if explicit?
 
-        "    #{raw_data == "\x00".b ? 'FALSE' : 'TRUE'} (0x#{raw_data.unpack1('H*')})"
+        "    #{raw_data == "\x00".b ? 'FALSE' : 'TRUE'} (0x#{bin2hex(raw_data)})"
       end
     end
   end