rasn1 0.16.2 → 0.17.0

data/lib/rasn1/types/choice.rb

@@ -10,32 +10,44 @@ module RASN1
   module Types
     # A ASN.1 CHOICE is a choice between different types.
     #
-    # == Create a CHOICE
-    # A CHOICE is defined this way:
+    # @example Create a CHOICE
     #   choice = Choice.new
     #   choice.value = [Integer.new(implicit: 0, class: :context),
     #                   Integer.new(implicit: 1, class: :context),
     #                   OctetString.new(implicit: 2, class: :context)]
-    # The chosen type may be set this way:
-    #   choice.chosen = 0   # choose :int1
-    # The chosen value may be set these ways:
+    #   # Choose an element
+    #   choice.chosen = 0   # choose int1
+    #   # Set chosen value
     #   choise.value[choice.chosen].value = 1
-    #   choise.set_chosen_value 1
-    # The chosen value may be got these ways:
+    #   # Also set chosen value
+    #   choise.set_chosen_value(1)
+    #   # Got chosen value
     #   choise.value[choice.chosen].value # => 1
     #   choice.chosen_value               # => 1
     #
-    # == Encode a CHOICE
-    # {#to_der} only encodes the chosen value:
-    #   choise.to_der   # => "\x80\x01\x01"
+    # @example Encode a CHOICE
+    #   choice = Choice.new
+    #   choice.value = [Integer.new(implicit: 0, class: :context, value: 1),
+    #                   Integer.new(implicit: 1, class: :context),
+    #                   OctetString.new(implicit: 2, class: :context, value: "a")]
+    #   # to_der only encodes the chosen value
+    #   choice.chosen = 0   # choose int1
+    #   choice.to_der   # => "\x80\x01\x01"
+    #   # another choice, another encoding string
+    #   choice.chosen_value = 2
+    #   choice.to_der   # => "\x82\x01a"
     #
-    # == Parse a CHOICE
-    # Parsing a CHOICE set {#chosen} and set value to chosen type. If parsed string does
-    # not contain a type from CHOICE, a {RASN1::ASN1Error} is raised.
-    #   str = "\x04\x03abc"
-    #   choice.parse! str
+    # @example Parse a CHOICE
+    #   choice = Choice.new
+    #   choice.value = [Integer.new(implicit: 0, class: :context, value: 1),
+    #                   Integer.new(implicit: 1, class: :context),
+    #                   OctetString.new(implicit: 2, class: :context, value: "a")]
+    #   # Parse an octet string
+    #   choice.parse!("\x82\x03abc")
     #   choice.chosen        # => 2
     #   choice.chosen_value  # => "abc"
+    #   # Parse an unexpected value
+    #   choice.parse!("\x04\x03abc") # => RASN1::ASN1Error
     # @author Sylvain Daubert
     class Choice < Base
       # Chosen type
@@ -44,7 +56,7 @@ module RASN1
 
       # Set chosen value.
       # @note {#chosen} MUST be set before calling this method
-      # @param [Object] value
+      # @param value [Object]
       # @return [Object] value
       # @raise [ChoiceError] {#chosen} not set
       def set_chosen_value(value) # rubocop:disable Naming/AccessorMethodName
@@ -68,9 +80,10 @@ module RASN1
         end
       end
 
-      # @note {#chosen} MUST be set before calling this method
+      # Encode Choice into DER encoding
       # @return [String] DER-formated string
       # @raise [ChoiceError] {#chosen} not set
+      # @note {#chosen} MUST be set before calling this method
       def to_der
         check_chosen
         @value[@chosen].to_der
@@ -78,8 +91,8 @@ module RASN1
 
       # Parse a DER string. This method updates object by setting {#chosen} and
       # chosen value.
-      # @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)
@@ -96,6 +109,7 @@ module RASN1
       end
 
       # @private
+      # @!macro do_parse
       # @see Types::Base#do_parse
       # @since 0.15.0 Specific +#do_parse+ to handle recursivity
       def do_parse(der, ber: false)
@@ -115,8 +129,8 @@ module RASN1
       end
 
       # Make choice value from DER/BER string.
-      # @param [String] der
-      # @param [::Boolean] ber
+      # @param der [String]
+      # @param ber [::Boolean]
       # @return [void]
       # @since 0.15.0 Specific +#der_to_value+ to handle recursivity
       def der_to_value(der, ber: false)
@@ -130,7 +144,7 @@ module RASN1
         end
       end
 
-      # @param [::Integer] level
+      # @param level [::Integer]
       # @return [String]
       def inspect(level=0)
         str = common_inspect(level)
@@ -148,7 +162,7 @@ module RASN1
       end
 
       # Return empty array
-      # @return [Array()]
+      # @return [Array]
       # @since 0.15.0
       def void_value
         []
@@ -156,6 +170,8 @@ module RASN1
 
       private
 
+      # @return [void]
+      # @raise [ChoiceError] {#chosen} is not set
       def check_chosen
         raise ChoiceError.new(self) if !defined?(@chosen) || @chosen.nil?
       end

data/lib/rasn1/types/constrained.rb

@@ -25,7 +25,7 @@ module RASN1
         end
 
         # Check constraint, if defined
-        # @param [Object] value the value of the type to check
+        # @param value [Object] the value of the type to check
         # @raise [ConstraintError] constraint is not verified
         def check_constraint(value)
           return unless constrained?
@@ -36,6 +36,7 @@ module RASN1
       extend ClassMethods
 
       # Redefined +#value=+ to check constraint before assigning +val+
+      # @!macro value_setter
       # @see Types::Base#value=
       # @raise [ConstraintError] constraint is not verified
       def value=(val)
@@ -44,8 +45,8 @@ module RASN1
       end
 
       # Make value from +der+ string and check constraints
-      # @param [String] der
-      # @param [::Boolean] ber
+      # @param der [String]
+      # @param ber [::Boolean]
       # @return [void]
       # @raise [ConstraintError] constraint is not verified
       def der_to_value(der, ber: false)

data/lib/rasn1/types/constructed.rb

@@ -10,7 +10,9 @@ module RASN1
   module Types
     # @abstract This class SHOULD be used as base class for all ASN.1 primitive
     #  types.
-    # Base class for all ASN.1 constructed types
+    # This is the base class for all ASN.1 constructed types. A constructed type combines similar or different
+    # {Primitive primitive} types into ordered or unordered groups
+    #
     # @author Sylvain Daubert
     class Constructed < Base
       # Constructed value
@@ -30,7 +32,7 @@ module RASN1
         end
       end
 
-      # @param [::Integer] level (default: 0)
+      # @param level [::Integer] (default: 0)
       # @return [String]
       def inspect(level=0)
         case @value

data/lib/rasn1/types/enumerated.rb

@@ -10,18 +10,19 @@ module RASN1
   module Types
     # ASN.1 Enumerated
     #
-    # An enumerated type permits to assign names to integer values. It may be defined
-    # different ways:
+    # An ENUMERATED type permits to assign names to integer values. {Integer} may
+    # also be enumerated, but the tag {ID} is different.
+    #
+    # @example Example 1
     #  enum = RASN1::Types::Enumerated.new(enum: { 'a' => 0, 'b' => 1, 'c' => 2 })
+    #  enum.value = 'a'
+    #  enum.value       # => 'a'
+    # @example Example 2
     #  enum = RASN1::Types::Enumerated.new(enum: { a: 0, b: 1, c: 2 })
-    # Its value should be setting as an Integer or a String/symbol:
     #  enum.value = :b
     #  enum.value = 1   # equivalent to :b
-    # But its value is always stored as named integer:
-    #  enum.value = :b
-    #  enum.value      # => :b
-    #  enum.value = 0
-    #  enum.value      # => :a
+    #  # enum returned value is always symbolic (even if set with an integer)
+    #  enum.value       # => :b
     # A {EnumeratedError} is raised when set value is not in enumeration.
     # @author Sylvain Daubert
     class Enumerated < Integer

data/lib/rasn1/types/generalized_time.rb

@@ -15,26 +15,29 @@ module RASN1
     # +{#value} of a {GeneralizedTime} should be a ruby Time.
     #
     # ===Notes
-    # When encoding, resulting string is always a UTC time, appended with +Z+.
+    # On encoding, resulting string is always a UTC time, appended with +Z+.
     # Minutes and seconds are always generated. Fractions of second are generated
     # if value Time object have them.
     #
-    # On parsing, are supported:
+    # On parsing, this class supports:
     # * UTC times (ending with +Z+),
     # * local times (no suffix),
     # * local times with difference between UTC and this local time (ending with
     #   +sHHMM+, where +s+ is +++ or +-+, and +HHMM+ is the time differential
     #   betwen UTC and local time).
     # These times may include minutes and seconds. Fractions of hour, minute and
-    # second are supported.
+    # second are also supported.
     # @author Sylvain Daubert
+    # @author LemonTree55
     class GeneralizedTime < Primitive
       # GeneralizedTime id value
       ID = 24
 
       # @private
+      # Second count in one hour
       HOUR_TO_SEC = 3600
       # @private
+      # Second count in one minute
       MINUTE_TO_SEC = 60
       # @private
       SECOND_TO_SEC = 1
@@ -51,8 +54,8 @@ module RASN1
       end
 
       # Make time value from +der+ string
-      # @param [String] der
-      # @param [::Boolean] ber
+      # @param der [String]
+      # @param ber [::Boolean]
       # @return [void]
       def der_to_value(der, ber: false) # rubocop:disable Lint/UnusedMethodArgument
         date_hour, fraction = der.split('.')
@@ -70,6 +73,7 @@ module RASN1
 
       private
 
+      # @return [String]
       def value_to_der
         utc_value = @value.getutc
         if utc_value.nsec.positive?
@@ -80,6 +84,9 @@ module RASN1
         end
       end
 
+      # Set internal value to a Time defined from date and hour from +date_hour+, without fraction.
+      # @param date_hour [String]
+      # @return [void]
       def value_when_fraction_empty(date_hour)
         tz = compute_tz(date_hour)
         year = date_hour.slice!(0, 4).to_i
@@ -91,21 +98,21 @@ module RASN1
         @value = Time.new(year, month, day, hour, minute, second, tz)
       end
 
-      # Ruby 3.0: special handle for timezone
-      #   From 3.1: "Z" and "-0100" are supported
-      #   Below 3.1: should be "-01:00" or "+00:00"
+      # Compute TZ from +date_hour+ string
+      # @param date_hour [String]
+      # @return [String]
       def compute_tz(date_hour)
         if date_hour.end_with?('Z')
           date_hour.slice!(-1, 1)
-          '+00:00' # Ruby 3.0: to remove after end-of support of ruby 3.0
         elsif date_hour.match?(/[+-]\d+$/)
-          # Ruby 3.0
-          # date_hour.slice!(-5, 5)
-          zone = date_hour.slice!(-5, 5).to_s
-          "#{zone[0, 3]}:#{zone[3, 2]}"
+          date_hour.slice!(-5, 5)
         end
       end
 
+      # Set value in special case where fraction ends with 'Z'
+      # @param date_hour [String]
+      # @param fraction [String]
+      # @return [void]
       def value_when_fraction_ends_with_z(date_hour, fraction)
         fraction = fraction[0...-1]
         date_hour << 'Z'
@@ -114,6 +121,10 @@ module RASN1
         fix_value(fraction, frac_base)
       end
 
+      # Set value in general case
+      # @param date_hour [String]
+      # @param fraction [String]
+      # @return [void]
       def value_on_others_cases(date_hour, fraction)
         match = fraction.match(/(\d+)([+-]\d+)/)
         if match
@@ -127,11 +138,18 @@ module RASN1
         fix_value(fraction, frac_base)
       end
 
+      # Fix internal value with +fraction+, based on +frac_base+
+      # @param fraction [String]
+      # @param frac_base [::Integer]
+      # @return [void]
       def fix_value(fraction, frac_base)
         frac = ".#{fraction}".to_r * frac_base
         @value = (@value + frac) unless fraction.nil?
       end
 
+      # Compute fraction base from +date_hour+ string
+      # @param date_hour [String]
+      # @return [::Integer]
       def compute_frac_base(date_hour)
         case date_hour.size
         when 10, 11
@@ -152,6 +170,7 @@ module RASN1
         end
       end
 
+      # @return [String]
       def trace_data
         return super if explicit?
 

data/lib/rasn1/types/integer.rb

@@ -9,25 +9,50 @@
 module RASN1
   module Types
     # ASN.1 Integer
+    #
+    # An INTEGER is a primitive type to represent integers.
+    # There is no limit on integer size.
+    #
+    # @example Simple Integers
+    #   # Simple integer with a value associated
+    #   int1 = RASN1::Types::Integer.new(value: 42)
+    #   # Integer without value, but a default one
+    #   int2 = RASN1::Types::Integer.new(default: -42)
+    #
+    # @example Enumerated Integer
+    #   enum = RASN1::Types::Integer.new(enum: {one: 1, two: 2})
+    #   enum.value = :two
+    #   enum.value #=> :two
+    #   enum.to_i  #=> 2
     # @author Sylvain Daubert
+    # @author LemonTree55
     class Integer < Primitive
-      # @return [Hash,nil]
+      # Associated enumeration
+      # @return [Hash{String=>::Integer},nil]
       attr_reader :enum
 
       # Integer id value
       ID = 2
 
-      # @option options [Hash] :enum enumeration hash. Keys are names, and values
+      # @!macro type_initialize
+      # @option options [Hash{String=>::Integer}] :enum enumeration hash. Keys are names, and values
       #   are integers.
       # @raise [EnumeratedError] +:default+ value is unknown when +:enum+ key is present
-      # @see Base#initialize common options to all ASN.1 types
       def initialize(options={})
         super
         initialize_enum(@options[:enum])
       end
 
-      # @param [Integer,String,Symbol,nil] val
+      # Set integer value from a Ruby integer, or a String or a Symbol (only when {#enum} is defined).
+      # @param val [::Integer,String,Symbol,nil]
       # @return [void]
+      # @note
+      #   An enumerated INTEGER may be set with an integer value out of enumeration,
+      #   only when no value is set.
+      # @raise [EnumeratedError] string/symbol value: no enum defined or +val+ not in enum
+      # @raise [EnumeratedError] integer value: value already set and new value not in enum
+      # @raise [TypeError] unsupported +val+ type
+      # @since 0.16.2 raise TypeError (was EnumeratedError)
       def value=(val)
         @no_value = false
         case val
@@ -39,17 +64,17 @@ module RASN1
           @no_value = true
           @value = void_value
         else
-          raise EnumeratedError, "#{@name}: not in enumeration"
+          raise TypeError, "#{val.class} not supported"
         end
       end
 
-      # @return [Integer]
+      # @return [::Integer]
       def void_value
         0
       end
 
       # Integer value
-      # @return [Integer]
+      # @return [::Integer]
       def to_i
         val = value? ? @value : @default
         case val
@@ -61,8 +86,8 @@ module RASN1
       end
 
       # Make integer value from +der+ string.
-      # @param [String] der
-      # @param [::Boolean] ber
+      # @param der [String]
+      # @param ber [::Boolean]
       # @return [void]
       def der_to_value(der, ber: false)
         int_value = der_to_int_value(der, ber: ber)
@@ -75,6 +100,9 @@ module RASN1
 
       private
 
+      # Initialize integer with given enum hash.
+      # @param enum [Hash{String=>::Integer}]
+      # @return [void]
       def initialize_enum(enum)
         @enum = enum || {}
         return if @enum.empty?
@@ -85,6 +113,10 @@ module RASN1
         check_enum_default
       end
 
+      # Check defined default is coherent with enum
+      # @return [void]
+      # @raise [EnumeratedError] default value not defined in {#enum}
+      # @raise [TypeError] unsupported type for default value
       def check_enum_default
         case @default
         when String, Symbol
@@ -99,6 +131,10 @@ module RASN1
         end
       end
 
+      # Set value from given string or symbol value
+      # @param val [String,Symbol]
+      # @return [void]
+      # @raise [EnumeratedError] no enum defined or +val+ not in enum
       def value_from_string_or_symbol(val)
         raise EnumeratedError, "#{@name} has no :enum" if @enum.empty?
         raise EnumeratedError, "#{@name}: unknwon enumerated value #{val}" unless @enum.key? val
@@ -106,6 +142,10 @@ module RASN1
         @value = val
       end
 
+      # Set value from given integer value.
+      # @param val [::Integer]
+      # @return [void]
+      # @raise [EnumeratedError] +val+ not in enum
       def value_from_integer(val)
         if @enum.empty?
           @value = val
@@ -116,6 +156,8 @@ module RASN1
         end
       end
 
+      # @param value [::Integer]
+      # @return [String]
       def int_value_to_der(value)
         size = compute_size(value)
         comp_value = value >= 0 ? value : (~(-value) + 1) & ((1 << (size * 8)) - 1)
@@ -125,12 +167,16 @@ module RASN1
         ary.reverse.pack('C*')
       end
 
+      # Get size in bytes of +value+ integer
+      # @param value [::Integer]
+      # @return [::Integer]
       def compute_size(value)
         size = value.bit_length / 8 + ((value.bit_length % 8).positive? ? 1 : 0)
         size = 1 if size.zero?
         size
       end
 
+      # @return [String]
       def value_to_der
         case @value
         when String, Symbol
@@ -142,6 +188,9 @@ module RASN1
         end
       end
 
+      # @param der [String]
+      # @param ber [::Boolean]
+      # @return [::Integer]
       def der_to_int_value(der, ber: false) # rubocop:disable Lint/UnusedMethodArgument
         ary = der.unpack('C*')
         v = ary.reduce(0) { |len, b| (len << 8) | b }
@@ -149,22 +198,29 @@ module RASN1
         v
       end
 
+      # Return value to show  (enumerated if enum is defined, else integer)
+      # @param int [::Integer]
+      # @param check_enum [::Boolean]
+      # @return [String,::Integer]
+      # @raise [EnumeratedError] +check_enum+ is +true+, enum is defined, and +int+ is not in enum
       def int_to_enum(int, check_enum: true)
         raise EnumeratedError, "#{@name}: value #{int} not in enumeration" if check_enum && !@enum.value?(int)
 
         @enum.key(int) || int
       end
 
+      # @return [::Integer]
       def explicit_type
         self.class.new(name: name, enum: enum)
       end
 
+      # @return [String]
       def trace_data
         return super if explicit?
-        return "    #{der_to_int_value(raw_data)} (0x#{raw_data.unpack1('H*')})" if @enum.empty?
+        return "    #{der_to_int_value(raw_data)} (0x#{bin2hex(raw_data)})" if @enum.empty?
 
         v = int_to_enum(der_to_int_value(raw_data), check_enum: false)
-        "    #{v} (0x#{raw_data.unpack1('H*')})"
+        "    #{v} (0x#{bin2hex(raw_data)})"
       end
     end
   end

data/lib/rasn1/types/null.rb

@@ -9,11 +9,14 @@
 module RASN1
   module Types
     # ASN.1 Null
+    #
+    # This type is a placeholder when a value is not mandatory (in a {Choice}, by example).
     # @author Sylvain Daubert
     class Null < Primitive
       # Null id value
       ID = 0x05
 
+      # @param level [Integer]
       # @return [String]
       def inspect(level=0)
         str = common_inspect(level)[0..-2] # remove terminal ':'
@@ -21,15 +24,15 @@ module RASN1
         str
       end
 
-      # @return [Boolean]
       # Build only if not optional
+      # @return [Boolean]
       def can_build?
         !optional?
       end
 
       # Check +der+ string
-      # @param [String] der
-      # @param [::Boolean] ber
+      # @param der [String]
+      # @param ber [::Boolean]
       # @return [void]
       # @raise [ASN1Error] +der+ is not empty
       def der_to_value(der, ber: false) # rubocop:disable Lint/UnusedMethodArgument
@@ -41,6 +44,7 @@ module RASN1
 
       private
 
+      # @return [String]
       def value_to_der
         ''
       end

data/lib/rasn1/types/numeric_string.rb

@@ -9,7 +9,14 @@
 module RASN1
   module Types
     # ASN.1 Numeric String
+    #
+    # A NUMERIC STRING is an {OctetString} limited to numeric digit.
+    # @example Numeric string
+    #   ns = RASN1::Types::NumrericString.new(value: "123")
+    #   ns.to_der                     #=> "\x12\x03123"
+    #   RASN1.parse(ns.to_der).value  #=> "123"
     # @author Sylvain Daubert
+    # @author LemonTree55
     class NumericString < OctetString
       # NumericString id value
       ID = 18
@@ -23,10 +30,11 @@ module RASN1
       end
 
       # Make string value from +der+ string
-      # @param [String] der
-      # @param [::Boolean] ber
+      # @param der [String]
+      # @param ber [::Boolean]
       # @return [void]
       # @raise [ASN1Error] invalid characters detected
+      # @raise [ASN1Error] invalid character in string
       def der_to_value(der, ber: false)
         super
         check_characters
@@ -34,11 +42,15 @@ module RASN1
 
       private
 
+      # @return [String]
+      # @raise [ASN1Error] invalid character in string
       def value_to_der
         check_characters
         @value.to_s.b
       end
 
+      # @return [void]
+      # @raise [ASN1Error] invalid character in string
       def check_characters
         raise ASN1Error, "NUMERIC STRING #{@name}: invalid character: '#{$1}'" if @value.to_s =~ INVALID_CHARS
       end

data/lib/rasn1/types/object_id.rb

@@ -9,6 +9,15 @@
 module RASN1
   module Types
     # ASN.1 Object ID
+    #
+    # An OBJECT ID provides unique identifiers.
+    #
+    # Object Id are shown as numbered dotted strings, like +0.1.2.1256.1+. First number is in range [0-2], the second
+    # in range [0-39]. Others are not limited.
+    #
+    # @example Object id
+    #    oid = RASN1::Types::ObjectId.new(value: "0.2.145.65589.1")
+    #    oid.to_der   #=> "\x06\a\x02\x81\x11\x84\x805\x01"
     # @author Sylvain Daubert
     # @author LemonTree55
     class ObjectId < Primitive
@@ -16,8 +25,8 @@ module RASN1
       ID = 6
 
       # Make object id value from +der+ string
-      # @param [String] der
-      # @param [::Boolean] ber
+      # @param der [String]
+      # @param ber [::Boolean]
       # @return [void]
       def der_to_value(der, ber: false) # rubocop:disable Lint/UnusedMethodArgument
         bytes = der.unpack('C*')
@@ -41,6 +50,7 @@ module RASN1
 
       private
 
+      # @return [String]
       # @raise [ASN1Error]
       def value_to_der
         ids = @value.to_s.split('.').map(&:to_i)
@@ -59,8 +69,9 @@ module RASN1
         octets.pack('C*')
       end
 
-      # @param [Array[::Integer]] ids
-      # @raise [ASN1Error]
+      # @param ids [Array<::Integer>]
+      # @return [void]
+      # @raise [ASN1Error] one in two first ids are out of range
       def check_first_ids(ids)
         raise ASN1Error, "OBJECT ID #{@name}: first subidentifier should be less than 3" if ids[0] > 2
         raise ASN1Error, "OBJECT ID #{@name}: second subidentifier should be less than 40" if (ids[0] < 2) && (ids[1] > 39)

data/lib/rasn1/types/octet_string.rb

@@ -21,7 +21,7 @@ module RASN1
       # OctetString id value
       ID = 4
 
-      # @param [::Integer] level
+      # @param level [::Integer]
       # @return [String]
       def inspect(level=0)
         str = common_inspect(level)
@@ -29,8 +29,8 @@ module RASN1
       end
 
       # Make string value from +der+ string. Force encoding to UTF-8
-      # @param [String] der
-      # @param [::Boolean] ber
+      # @param der [String]
+      # @param ber [::Boolean]
       # @return [void]
       # @since 0.15.0 Handle ENCODING constant, if defined by subclass
       def der_to_value(der, ber: false)