rasn1 0.16.2 → 0.16.3

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)

data/lib/rasn1/types/primitive.rb

@@ -10,6 +10,10 @@ module RASN1
   module Types
     # @abstract This class SHOULD be used as base class for all ASN.1 primitive
     #  types.
+    # This class is base class for all ASN.1 primitive types. A primitive type is not {Constructed}, or it cannot
+    # be broken down into more primitive types.
+    #
+    # Please note that a primitive type (b.e. {OctetString OCTET STRING}) may be set as constructed, to advertise it contains ASN.1 encoded data.
     # @author Sylvain Daubert
     class Primitive < Base
       # Primitive value

data/lib/rasn1/types/printable_string.rb

@@ -9,7 +9,10 @@
 module RASN1
   module Types
     # ASN.1 Printable String
+    #
+    # A PRINTABLE STRING is an {OctetString} limited to printable characters from ASCII table.
     # @author Sylvain Daubert
+    # @author LemonTree55
     class PrintableString < OctetString
       # PrintableString id value
       ID = 19
@@ -23,8 +26,8 @@ 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
       def der_to_value(der, ber: false)
@@ -34,11 +37,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
         m = @value.to_s.match(INVALID_CHARS)
         raise ASN1Error, "PRINTABLE STRING #{@name}: invalid character: '#{m[1]}'" if m

data/lib/rasn1/types/sequence.rb

@@ -35,6 +35,7 @@ module RASN1
       # Sequence id value
       ID = 0x10
 
+      # @!macro type_initialize
       # @see Base#initialize
       def initialize(options={})
         super
@@ -59,7 +60,7 @@ module RASN1
       end
 
       # Get element at index +idx+, or element of name +name+
-      # @param [Integer, String, Symbol] idx_or_name
+      # @param idx_or_name [Integer, String, Symbol]
       # @return [Object,nil]
       def [](idx_or_name)
         return unless @value.is_a?(Array)
@@ -73,8 +74,8 @@ module RASN1
       end
 
       # Make sequence 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
         if @value.is_a?(Array) && !@value.empty?
@@ -90,6 +91,7 @@ module RASN1
 
       private
 
+      # @return [String]
       def value_to_der
         case @value
         when Array
@@ -99,10 +101,12 @@ module RASN1
         end
       end
 
+      # @return [String]
       def trace_data
         ''
       end
 
+      # @return [Sequence]
       def explicit_type
         self.class.new(name: name, value: @value)
       end

data/lib/rasn1/types/sequence_of.rb

@@ -60,12 +60,13 @@ module RASN1
       attr_reader :of_type
 
       # A SEQUENCE OF is encoded as a SEQUENCE.
-      # @return ['SEQUENCE']
+      # @return [String]
       def self.encoded_type
         Sequence.encoded_type
       end
 
-      # @param [Class, Base] of_type base type for sequence of
+      # @param of_type [Class, Base] base type for sequence of
+      # @!macro type_initialize
       # @see Base#initialize
       def initialize(of_type, options={})
         super(options)
@@ -86,7 +87,9 @@ module RASN1
       end
 
       # Add an item to SEQUENCE OF
-      # @param [Object] obj
+      # @param obj [Object]
+      # @return [self]
+      # @version 0.16.2 return self
       # @note
       #   * if a SEQUENCE OF primitive type, +obj+ is an instance of primitive type or equivalent Ruby type
       #   * if a SEQUENCE OF composed type, +obj+ is an array of ruby type instances
@@ -96,11 +99,12 @@ module RASN1
         return push_composed_array(obj) if composed_of_type?
 
         push_model(obj)
+        self
       end
 
       # Get element of index +idx+
-      # @param [Integer] idx
-      # @return [Base]
+      # @param idx [Integer]
+      # @return [Base,Wrapper,Model]
       def [](idx)
         @value[idx]
       end
@@ -111,7 +115,7 @@ module RASN1
         @value.length
       end
 
-      # @param [::Integer] level
+      # @param level [::Integer]
       # @return [String]
       def inspect(level=0)
         str = common_inspect(level)
@@ -132,8 +136,8 @@ module RASN1
       end
 
       # Make sequence of 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
         @value = []
@@ -148,22 +152,31 @@ module RASN1
 
       private
 
+      # Get class of elements
+      # @return [Class]
       def of_type_class
         @of_type.is_a?(Class) ? @of_type : @of_type.class
       end
 
+      # Is this SEQUENCE OF a composed one (i.e. of_type is a SET or a SEQUENCE)?
+      # @return [Boolean]
       def composed_of_type?
         !@of_type.is_a?(Class) && [Sequence, Set].include?(of_type_class)
       end
 
+      # @return [String]
       def value_to_der
         @value.map(&:to_der).join
       end
 
+      # @return [SequenceOf]
       def explicit_type
         self.class.new(self.of_type, name: name)
       end
 
+      # Push a primitice type into seld
+      # @param obj [Primitive]
+      # @return [void]
       def push_primitive(obj)
         @value <<
           case obj
@@ -174,6 +187,9 @@ module RASN1
           end
       end
 
+      # Push an array into a composed SEQUENCE OF
+      # @param obj [Array<Types::Base,Wrapper>]
+      # @return [void]
       def push_composed_array(obj)
         raise ASN1Error, 'object to add should be an Array' unless obj.is_a?(Array)
 
@@ -186,6 +202,9 @@ module RASN1
         @value << new_value
       end
 
+      # Push a model into self
+      # @param obj [Model]
+      # @return [void]
       def push_model(obj)
         case obj
         when Hash
@@ -197,6 +216,7 @@ module RASN1
         end
       end
 
+      # @return [String]
       def trace_data
         ''
       end

data/lib/rasn1/types/set_of.rb

@@ -15,7 +15,7 @@ module RASN1
       ID = Set::ID
 
       # A SET OF is encoded as a SET.
-      # @return ['SET']
+      # @return [String]
       def self.encoded_type
         Set.encoded_type
       end

data/lib/rasn1/types/utc_time.rb

@@ -14,6 +14,9 @@ module RASN1
     #
     # +{#value} of a +UtcTime+ should be a ruby Time.
     #
+    # Unlike {GeneralizedTime}, a UTCTime serializes only 2 digits for years.
+    # Unlike its name, a UTCTime may contain a local time.
+    #
     # ===Notes
     # When encoding, resulting string is always a UTC time, appended with +Z+.
     # Seconds are always generated.
@@ -34,8 +37,8 @@ module RASN1
       end
 
       # Make time value from +der+ string
-      # @param [String] der
-      # @param [::Boolean] ber
+      # @param der [String]
+      # @param ber [::Boolean]
       # @return [void]
       # @raise [ASN1Error] unrecognized  time format
       def der_to_value(der, ber: false) # rubocop:disable Lint/UnusedMethodArgument
@@ -59,10 +62,12 @@ module RASN1
 
       private
 
+      # @return [String]
       def value_to_der
         @value.getutc.strftime('%y%m%d%H%M%SZ')
       end
 
+      # @return [String]
       def trace_data
         return super if explicit?
 

data/lib/rasn1/types.rb

@@ -35,7 +35,7 @@ module RASN1
 
     # @private
     # Decode a DER string to extract identifier octets.
-    # @param [String] der
+    # @param der [String]
     # @return [Array] Return ASN.1 class as Symbol, contructed/primitive as Symbol,
     #                 ID and size of identifier octets
     def self.decode_identifier_octets(der)
@@ -63,7 +63,7 @@ module RASN1
 
     # Give ASN.1 type from a DER string. If ID is unknown, return a {Types::Base}
     # object.
-    # @param [String] der
+    # @param der [String]
     # @return [Types::Base]
     # @raise [ASN1Error] +tag+ is out of range
     def self.id2type(der)
@@ -93,9 +93,9 @@ module RASN1
 
     # Define a new ASN.1 type from a base one.
     # This new type may have a constraint defines on it.
-    # @param [Symbol,String] name new type name. Must start with a capital letter.
-    # @param [Types::Base] from class from which inherits
-    # @param [Module] in_module module in which creates new type (default to {RASN1::Types})
+    # @param name [Symbol,String] new type name. Must start with a capital letter.
+    # @param from [Types::Base] class from which inherits
+    # @param in_module [Module] module in which creates new type (default to {RASN1::Types})
     # @return [Class] newly created class
     # @yieldparam [Object] value value to set to type, or infered at parsing
     # @yieldreturn [Boolean]

data/lib/rasn1/version.rb

@@ -8,5 +8,5 @@
 
 module RASN1
   # RASN1 version number
-  VERSION = '0.16.2'
+  VERSION = '0.16.3'
 end

data/lib/rasn1/wrapper.rb

@@ -42,9 +42,13 @@ module RASN1
   class Wrapper < SimpleDelegator
     # @private Private class used to build/parse explicit wrappers
     class ExplicitWrapper < Types::Base
-      ID = 0 # not used
-      ASN1_PC = 0 # not constructed
+      # Explicit Wrapper ID (not used, but must be declared)
+      ID = 0
+      # PC bit: primitive
+      ASN1_PC = 0
 
+      # Blank type for explicit wrapper
+      # @return [String]
       def self.type
         ''
       end
@@ -60,17 +64,27 @@ module RASN1
 
       private
 
+      # @return [String]
       def value_to_der
         @value.is_a?(String) ? @value : @value.to_der
       end
 
+      # @return [String]
       def inspect_value
         ''
       end
     end
 
-    # @param [Types::Base,Model] element element to wrap
-    # @param [Hash] options
+    # @param element [Types::Base,Model] element to wrap
+    # @param options [Hash]
+    # @option options [Integer] :explicit Create an explicit wrapper with given ID
+    # @option options [Integer] :implicit Crerate an implicit wrapper woth given ID
+    # @option options [Integer] :default Default value (explicit wrapper only)
+    # @option options [Boolean] :optional Define wrapper (explicit one only) as optional
+    # @option options [Symbol] :class Wrapper ASN.1 class. Default to +:context+
+    # @option options [::Boolean] :constructed if +true+, set wrapper as constructed.
+    # @option options [::String] :name name for this wrapper
+    # @raise [RASN1::Error] +:implicit+ and +:explicit+ options are both provided
     def initialize(element, options={})
       @lazy = true
       opts = explicit_implicit(options)
@@ -119,8 +133,8 @@ module RASN1
     end
 
     # 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
     # @since 0.12.0
@@ -142,6 +156,7 @@ module RASN1
     end
 
     # @private
+    # @!macro do_parse
     # @see Types::Base#do_parse
     def do_parse(der, ber: false)
       if implicit?
@@ -207,8 +222,9 @@ module RASN1
       !constructed?
     end
 
-    # @param [::Integer] level
+    # @param level [::Integer]
     # @return [String]
+    # @see Types::Base#inspect
     def inspect(level=0)
       return super() unless explicit?
 
@@ -217,6 +233,10 @@ module RASN1
 
     private
 
+    # @param options [Hash]
+    # @option options [Integer] :explicit
+    # @option options [Integer] :implicit
+    # @return [Hash] options with :explicit/:implicit keys deleted
     def explicit_implicit(options)
       opts = options.dup
       @explicit = opts.delete(:explicit)
@@ -224,12 +244,19 @@ module RASN1
       opts
     end
 
+    # @param options [Hash]
+    # @option options [Integer] :implicit
+    # @return [ExplicitWrapper]
     def generate_explicit_wrapper(options)
       # ExplicitWrapper is a hand-made explicit tag, but we have to use its implicit option
       # to force its tag value.
       @explicit_wrapper = ExplicitWrapper.new(options.merge(implicit: @explicit))
     end
 
+    # @param options [Hash]
+    # @option options [Integer] :default
+    # @option options [Boolean] :optional
+    # @return [Hash] hash with :default/:optional keys only
     def generate_explicit_wrapper_options(options)
       new_opts = {}
       new_opts[:default] = options[:default] if options.key?(:default)
@@ -237,6 +264,8 @@ module RASN1
       new_opts
     end
 
+    # @param from [Types::Base,nil]
+    # @return [Types::Base, Model]
     def generate_implicit_element(from=nil)
       el = (from || element).dup
       el.options = if element.explicit?
@@ -247,6 +276,8 @@ module RASN1
       el
     end
 
+    # @param register [Boolean]
+    # @return [Types::Base, Model]
     def lazy_generation(register: true)
       return __getobj__ unless @lazy
 

data/lib/rasn1.rb

@@ -21,6 +21,7 @@ require_relative 'rasn1/types/visible_string'
 # @author LemonTree
 module RASN1
   # @private
+  # Container types
   CONTAINER_CLASSES = [Types::Sequence, Types::Set].freeze
 
   # Parse a DER/BER string without checking a model
@@ -30,9 +31,9 @@ module RASN1
   #       ones use the same encoding as SEQUENCE and SET, respectively.
   # @note Real type of tagged value cannot be guessed. So, such tag will
   #       generate {Types::Base} objects.
-  # @param [String] der binary string to parse
-  # @param [Boolean] ber if +true+, decode a BER string, else a DER one
-  # @return [Types::Base, Array[Types::Base]]
+  # @param der [String] binary string to parse
+  # @param ber [Boolean] if +true+, decode a BER string, else a DER one
+  # @return [Types::Base, Array<Types::Base>]
   def self.parse(der, ber: false) # rubocop:disable Metrics/AbcSize
     result = []
     until der.nil? || der.empty?

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rasn1
 version: !ruby/object:Gem::Version
-  version: 0.16.2
+  version: 0.16.3
 platform: ruby
 authors:
 - LemonTree55
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-08-14 00:00:00.000000000 Z
+date: 2025-11-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: strptime
@@ -98,7 +98,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.15
+rubygems_version: 3.2.33
 signing_key:
 specification_version: 4
 summary: Ruby ASN.1 library