maxmind-db 1.3.2 → 1.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9b642dbfca79a5abf8c5c5ab4a2ceb07051affb7148dd005514d0bc1a9950c3b
-  data.tar.gz: 6cb14299dec849aef6f054ca39cbf139d3e552ed593960ebfbd72a09a6ce5f27
+  metadata.gz: 19db0a99249703b86573eb824fe94f4eb4c807528699c7707b2b8ef7d22f89c9
+  data.tar.gz: efb878012b9565ffc0b7d9fde72b02685c85bbafe28819550ec184f88709640b
 SHA512:
-  metadata.gz: 232d60717fed7da9d7253edc041316eec8f71782b9fca2e72cdbd5ad5414e7253504d423b3bab105cd87c5fd1c62e6df2fe7b8a2d70ea19f97a5fc5fc493a572
-  data.tar.gz: c40ce6eec502c4f2f45d8b5036b179b9f498e680771571430228845f0a588a564e3a4adf66193f56440bb8c21940793cba5ee073f3eb444dbe9f303db9f6fe21
+  metadata.gz: b5b53cb8a651d3456fa8f0fa4f2ee40baf6a1cd4e80f732ae1476d7a28f7e17492a89073c75c081243b40f7760a4cfb1a362de7090a9ad5b03a0e3ccfdcec9a0
+  data.tar.gz: 897c4cb5a162a90b3481668ede6a366a4e598b7b392e536de5be57e73baa4a6f5515721806c3f6db402060a07e52207b166a8cfc459a4d84df12538e08c8f9ce

data/CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## 1.5.0 (2026-09-10)
+
+* Fixed two denial-of-service issues in the decoder. A crafted database could
+  nest data-section pointers to shared targets so that decoding one record
+  cost exponential time and memory from a small file, or point many times at
+  one large string or bytes value so that a record with few values
+  materialized gigabytes. The decoder now bounds each record it decodes and
+  the metadata decoded when a database is opened. A database that exceeds a
+  limit raises `InvalidDatabaseError`. The limits are:
+  * 65,536 decoded values, as the MaxMind DB specification recommends.
+  * 512 levels of nesting, as the specification recommends. This also stops
+    pointer cycles.
+  * 2 MiB of string, bytes, and integer payload. The specification leaves this
+    limit to the reader. 2 MiB matches libmaxminddb.
+* The decoder limits can be changed with the new `max_values`,
+  `max_payload_bytes`, and `max_depth` options to `MaxMind::DB.new`.
+* Pointers that target other pointers are now rejected as invalid, as required
+  by the MaxMind DB specification.
+* Lookups are faster. The decoder allocates fewer strings and dispatches on the
+  data type with a jump table. GeoLite City lookups in memory mode on CRuby
+  3.4 are about 18% faster than in 1.4.0.
+* Unnecessary files were removed from the published .gem.
+
+## 1.4.0 (2025-11-20)
+
+* Ruby 3.2+ is now required. If you're using Ruby 3.0 or 3.1, please use
+  version 1.3.2 of this gem.
+
 ## 1.3.2 (2025-04-03)
 
 * Re-release to fix a release script problem. There are no code changes.

data/README.md

@@ -35,7 +35,7 @@ For more information see the
 
 ## Requirements
 
-This code requires Ruby version 3.0 or higher.
+This code requires Ruby version 3.2 or higher.
 
 ## Contributing
 
@@ -48,7 +48,7 @@ Please report all issues with this code using the [GitHub issue
 tracker](https://github.com/maxmind/MaxMind-DB-Reader-ruby/issues).
 
 If you are having an issue with a MaxMind service that is not specific to the
-client API, please see [our support page](https://www.maxmind.com/en/support).
+client API, please see [our support page](https://support.maxmind.com/knowledge-base).
 
 ## Versioning
 
@@ -56,7 +56,7 @@ This library uses [Semantic Versioning](https://semver.org/).
 
 ## Copyright and License
 
-This software is Copyright (c) 2018 - 2024 by MaxMind, Inc.
+This software is Copyright (c) 2018 - 2026 by MaxMind, Inc.
 
 This is free software, licensed under the [Apache License, Version
 2.0](LICENSE-APACHE) or the [MIT License](LICENSE-MIT), at your option.

data/lib/maxmind/db/decoder.rb

@@ -12,12 +12,12 @@ module MaxMind
     #
     # @!visibility private
     class Decoder
-      # rubocop:disable Style/OptionalBooleanParameter
+      # rubocop:disable Style/OptionalBooleanParameter, Metrics/ParameterLists
 
       # Create a +Decoder+.
       #
-      # +io+ is the DB. It must provide a +read+ method. It must be opened in
-      # binary mode.
+      # +io+ is the DB. It must provide +read+ and +getbyte+ methods. It must be
+      # opened in binary mode.
       #
       # +pointer_base+ is the base number to use when decoding a pointer. It is
       # where the data section begins rather than the beginning of the file.
@@ -25,21 +25,102 @@ module MaxMind
       # section.
       #
       # +pointer_test+ is used for testing pointer code.
-      def initialize(io, pointer_base = 0, pointer_test = false)
+      #
+      # +max_values+, +max_payload_bytes+, and +max_depth+ set the per-decode
+      # limits described below and default to the constants there.
+      def initialize(io, pointer_base = 0, pointer_test = false,
+                     max_values: MAX_VALUES, max_payload_bytes: MAX_BYTES,
+                     max_depth: MAX_DEPTH)
         @io = io
         @pointer_base = pointer_base
         @pointer_test = pointer_test
+        @max_values = max_values
+        @max_payload_bytes = max_payload_bytes
+        @max_depth = max_depth
       end
-      # rubocop:enable Style/OptionalBooleanParameter
+      # rubocop:enable Style/OptionalBooleanParameter, Metrics/ParameterLists
+
+      # Per-decode limits. The value and depth limits are the ones the MaxMind DB
+      # specification recommends. The specification leaves the payload limit to
+      # the reader, and 2 MiB matches libmaxminddb. +budget+ is a three-element
+      # array, [values_remaining, depth, bytes_remaining], shared across the
+      # recursion so every count survives it. It is call-local, which keeps the
+      # decoder safe for concurrent reads.
+      #
+      # The value limit stops a pointer fan-out. It follows the specification's
+      # flat rule: the root is one value, each array reserves one value per
+      # element, and each map reserves two values per entry before iterating. A
+      # pointer is not charged separately from the logical value at the root or
+      # its position in a container. A re-decoded node drains the budget, and an
+      # oversized declared size is rejected before the loop reads anything. The
+      # largest real records decode a few hundred values.
+      #
+      # The byte limit stops payload amplification: a crafted database can point
+      # many times at one large string or bytes value, so a bounded value count
+      # still materializes gigabytes. Each string and bytes value, and each
+      # variable-length integer, subtracts its own length before it is read, so a
+      # re-decoded (fanned-out) target recharges its payload and an oversized
+      # declared length is rejected before any bytes are copied. Fixed-width
+      # scalars are not charged.
+      #
+      # The depth limit stops a pointer cycle or over-deep data before the stack
+      # overflows.
+      MAX_VALUES = 1 << 16
+      private_constant :MAX_VALUES
+
+      MAX_BYTES = 1 << 21
+      private_constant :MAX_BYTES
+
+      MAX_DEPTH = 512
+      private_constant :MAX_DEPTH
+
+      BUDGET_VALUES = 0
+      BUDGET_DEPTH = 1
+      BUDGET_BYTES = 2
+      private_constant :BUDGET_VALUES, :BUDGET_DEPTH, :BUDGET_BYTES
+
+      # JRuby can exhaust the stack before the depth limit is reached and raises
+      # a Java StackOverflowError, which is not a SystemStackError. Catch both so
+      # a pointer cycle always becomes an InvalidDatabaseError.
+      STACK_ERRORS = if defined?(JRUBY_VERSION)
+                       [SystemStackError, Java::JavaLang::StackOverflowError].freeze
+                     else
+                       [SystemStackError].freeze
+                     end
+      private_constant :STACK_ERRORS
 
       private
 
-      def decode_array(size, offset)
+      # The limit checks are inlined at each call site so containers and
+      # pointers do not add a helper call. Only the raise is factored out.
+      def raise_depth_exceeded
+        raise InvalidDatabaseError,
+              'The MaxMind DB file\'s data section exceeds the maximum depth'
+      end
+
+      def raise_values_exceeded
+        raise InvalidDatabaseError,
+              'The MaxMind DB file\'s data section exceeds the maximum number of values'
+      end
+
+      # Each string, bytes, and variable-length integer decoder charges its size
+      # against the payload budget inline, before the bytes are read, so an
+      # oversized declared length is rejected before it is copied. Ruby integers
+      # are arbitrary precision, so the subtraction cannot overflow.
+      def raise_bytes_exceeded
+        raise InvalidDatabaseError,
+              'The MaxMind DB file\'s data section exceeds the maximum number of bytes'
+      end
+
+      def decode_array(size, offset, budget)
+        raise_values_exceeded if (budget[BUDGET_VALUES] -= size) < 0
+        raise_depth_exceeded if (budget[BUDGET_DEPTH] += 1) > @max_depth
         array = []
         size.times do
-          value, offset = decode(offset)
+          value, offset = decode_with_budget(offset, budget)
           array << value
         end
+        budget[BUDGET_DEPTH] -= 1
         [array, offset]
       end
 
@@ -47,7 +128,8 @@ module MaxMind
         [size != 0, offset]
       end
 
-      def decode_bytes(size, offset)
+      def decode_bytes(size, offset, budget)
+        raise_bytes_exceeded if (budget[BUDGET_BYTES] -= size) < 0
         [@io.read(offset, size), offset + size]
       end
 
@@ -66,37 +148,45 @@ module MaxMind
       def verify_size(expected, actual)
         return if expected == actual
 
+        raise_invalid_size
+      end
+
+      def raise_invalid_size
         raise InvalidDatabaseError,
               'The MaxMind DB file\'s data section contains bad data (unknown data type or corrupt data)'
       end
 
-      def decode_int32(size, offset)
-        decode_int('l>', 4, size, offset)
+      def decode_int32(size, offset, budget)
+        decode_int('l>', 4, size, offset, budget)
       end
 
-      def decode_uint16(size, offset)
-        decode_int('n', 2, size, offset)
+      def decode_uint16(size, offset, budget)
+        decode_int('n', 2, size, offset, budget)
       end
 
-      def decode_uint32(size, offset)
-        decode_int('N', 4, size, offset)
+      def decode_uint32(size, offset, budget)
+        decode_int('N', 4, size, offset, budget)
       end
 
-      def decode_uint64(size, offset)
-        decode_int('Q>', 8, size, offset)
+      def decode_uint64(size, offset, budget)
+        decode_int('Q>', 8, size, offset, budget)
       end
 
-      def decode_int(type_code, type_size, size, offset)
+      def decode_int(type_code, type_size, size, offset, budget)
+        raise_invalid_size if size > type_size
         return 0, offset if size == 0
 
+        raise_bytes_exceeded if (budget[BUDGET_BYTES] -= size) < 0
         buf = @io.read(offset, size)
         buf = buf.rjust(type_size, "\x00") if size != type_size
         [buf.unpack1(type_code), offset + size]
       end
 
-      def decode_uint128(size, offset)
+      def decode_uint128(size, offset, budget)
+        raise_invalid_size if size > 16
         return 0, offset if size == 0
 
+        raise_bytes_exceeded if (budget[BUDGET_BYTES] -= size) < 0
         buf = @io.read(offset, size)
 
         if size <= 8
@@ -112,45 +202,49 @@ module MaxMind
         [a | b, offset + size]
       end
 
-      def decode_map(size, offset)
+      def decode_map(size, offset, budget)
+        # A map entry decodes a key and a value, so it costs two values.
+        raise_values_exceeded if (budget[BUDGET_VALUES] -= size * 2) < 0
+        raise_depth_exceeded if (budget[BUDGET_DEPTH] += 1) > @max_depth
         container = {}
         size.times do
-          key, offset = decode(offset)
-          value, offset = decode(offset)
+          key, offset = decode_with_budget(offset, budget)
+          value, offset = decode_with_budget(offset, budget)
           container[key] = value
         end
+        budget[BUDGET_DEPTH] -= 1
         [container, offset]
       end
 
       def decode_pointer(size, offset)
         pointer_size = size >> 3
 
+        # Build the pointer with integer arithmetic to avoid temporary strings
+        # when combining control bits with the payload bytes.
         case pointer_size
         when 0
           new_offset = offset + 1
-          buf = (size & 0x7).chr << @io.read(offset, 1)
-          pointer = buf.unpack1('n') + @pointer_base
+          pointer = ((size & 0x7) << 8) | @io.getbyte(offset)
         when 1
           new_offset = offset + 2
-          buf = "\x00".b << (size & 0x7).chr << @io.read(offset, 2)
-          pointer = buf.unpack1('N') + 2048 + @pointer_base
+          pointer = ((size & 0x7) << 16) | @io.read(offset, 2).unpack1('n')
+          pointer += 2048
         when 2
           new_offset = offset + 3
-          buf = (size & 0x7).chr << @io.read(offset, 3)
-          pointer = buf.unpack1('N') + 526_336 + @pointer_base
+          buf = @io.read(offset, 3)
+          pointer = ((size & 0x7) << 24) | (buf.getbyte(0) << 16) |
+                    (buf.getbyte(1) << 8) | buf.getbyte(2)
+          pointer += 526_336
         else
           new_offset = offset + 4
-          buf = @io.read(offset, 4)
-          pointer = buf.unpack1('N') + @pointer_base
+          pointer = @io.read(offset, 4).unpack1('N')
         end
-
-        return pointer, new_offset if @pointer_test
-
-        value, = decode(pointer)
-        [value, new_offset]
+        pointer += @pointer_base
+        [pointer, new_offset]
       end
 
-      def decode_utf8_string(size, offset)
+      def decode_utf8_string(size, offset, budget)
+        raise_bytes_exceeded if (budget[BUDGET_BYTES] -= size) < 0
         new_offset = offset + size
         buf = @io.read(offset, size)
         buf.force_encoding(Encoding::UTF_8)
@@ -159,23 +253,6 @@ module MaxMind
         [buf, new_offset]
       end
 
-      TYPE_DECODER = {
-        1 => :decode_pointer,
-        2 => :decode_utf8_string,
-        3 => :decode_double,
-        4 => :decode_bytes,
-        5 => :decode_uint16,
-        6 => :decode_uint32,
-        7 => :decode_map,
-        8 => :decode_int32,
-        9 => :decode_uint64,
-        10 => :decode_uint128,
-        11 => :decode_array,
-        14 => :decode_boolean,
-        15 => :decode_float,
-      }.freeze
-      private_constant :TYPE_DECODER
-
       public
 
       # Decode a section of the data section starting at +offset+.
@@ -187,23 +264,82 @@ module MaxMind
       #
       # Throws an exception if there is an error.
       def decode(offset)
+        # Bound the work per decode so a crafted database cannot exhaust CPU or
+        # memory. +budget+ carries the remaining value count, the current depth,
+        # and the remaining payload-byte allowance, and is call-local, which
+        # keeps the decoder safe for concurrent reads. The root value is charged
+        # here; containers charge their children. The depth limit catches a
+        # pointer cycle on MRI. JRuby can exhaust the stack before the limit is
+        # reached and raises a Java StackOverflowError, so catch that too and
+        # report the same error.
+        decode_with_budget(offset, [@max_values - 1, 0, @max_payload_bytes])
+      rescue *STACK_ERRORS
+        raise InvalidDatabaseError,
+              'The MaxMind DB file\'s data section exceeds the maximum depth'
+      end
+
+      private
+
+      # The dispatch below is one branch per data type, so the method's
+      # cyclomatic complexity is above the cop's default. It is inlined here
+      # for speed and the branches are uniform.
+      # rubocop:disable-next Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+      def decode_with_budget(offset, budget)
+        pointer_return_offset = nil
         new_offset = offset + 1
-        buf = @io.read(offset, 1)
-        ctrl_byte = buf.ord
+        ctrl_byte = @io.getbyte(offset)
         type_num = ctrl_byte >> 5
         type_num, new_offset = read_extended(new_offset) if type_num == 0
 
         size, new_offset = size_from_ctrl_byte(ctrl_byte, new_offset, type_num)
-        # We could check an element exists at `type_num', but for performance I
-        # don't.
-        send(TYPE_DECODER[type_num], size, new_offset)
-      end
+        if type_num == 1
+          pointer, pointer_return_offset = decode_pointer(size, new_offset)
+          return [pointer, pointer_return_offset] if @pointer_test
+
+          # The root or containing collection already charged the logical value
+          # at the pointer's position. Following it adds depth but no separate
+          # value. Its target cannot be another pointer, and decoding the target
+          # still reserves container children and charges payload bytes.
+          raise_depth_exceeded if (budget[BUDGET_DEPTH] += 1) > @max_depth
+          new_offset = pointer + 1
+          ctrl_byte = @io.getbyte(pointer)
+          type_num = ctrl_byte >> 5
+          if type_num == 1
+            raise InvalidDatabaseError,
+                  'The MaxMind DB file\'s data section contains bad data (pointer points to another pointer)'
+          end
+          type_num, new_offset = read_extended(new_offset) if type_num == 0
+          size, new_offset = size_from_ctrl_byte(ctrl_byte, new_offset, type_num)
+        end
 
-      private
+        # Direct case dispatch avoids looking the method up in a Hash and
+        # calling it with send.
+        result = case type_num
+                 when 2 then decode_utf8_string(size, new_offset, budget)
+                 when 3 then decode_double(size, new_offset)
+                 when 4 then decode_bytes(size, new_offset, budget)
+                 when 5 then decode_uint16(size, new_offset, budget)
+                 when 6 then decode_uint32(size, new_offset, budget)
+                 when 7 then decode_map(size, new_offset, budget)
+                 when 8 then decode_int32(size, new_offset, budget)
+                 when 9 then decode_uint64(size, new_offset, budget)
+                 when 10 then decode_uint128(size, new_offset, budget)
+                 when 11 then decode_array(size, new_offset, budget)
+                 when 14 then decode_boolean(size, new_offset)
+                 when 15 then decode_float(size, new_offset)
+                 else
+                   raise InvalidDatabaseError,
+                         "The MaxMind DB file's data section contains bad data (unknown data type #{type_num})"
+                 end
+        return result unless pointer_return_offset
+
+        budget[BUDGET_DEPTH] -= 1
+        result[1] = pointer_return_offset
+        result
+      end
 
       def read_extended(offset)
-        buf = @io.read(offset, 1)
-        next_byte = buf.ord
+        next_byte = @io.getbyte(offset)
         type_num = next_byte + 7
         if type_num < 7
           raise InvalidDatabaseError,
@@ -218,8 +354,7 @@ module MaxMind
         return size, offset if type_num == 1 || size < 29
 
         if size == 29
-          size_bytes = @io.read(offset, 1)
-          size = 29 + size_bytes.ord
+          size = 29 + @io.getbyte(offset)
           return size, offset + 1
         end
 

data/lib/maxmind/db/file_reader.rb

@@ -44,6 +44,11 @@ module MaxMind
         @fh.close
       end
 
+      # Return the byte at +offset+ as an Integer.
+      def getbyte(offset)
+        read(offset, 1).ord
+      end
+
       def read(offset, size)
         return ''.b if size == 0
 

data/lib/maxmind/db/memory_reader.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'maxmind/db/errors'
+
 module MaxMind
   class DB
     # @!visibility private
@@ -24,8 +26,23 @@ module MaxMind
 
       def close; end
 
+      # Return the byte at +offset+ as an Integer without allocating a String.
+      def getbyte(offset)
+        @buf.getbyte(offset) || raise_bad_data
+      end
+
       def read(offset, size)
-        @buf[offset, size]
+        return ''.b if size == 0
+
+        raise_bad_data if offset + size > @buf.length
+
+        @buf.byteslice(offset, size)
+      end
+
+      private
+
+      def raise_bad_data
+        raise InvalidDatabaseError, 'The MaxMind DB file contains bad data'
       end
     end
   end

data/lib/maxmind/db.rb

@@ -72,7 +72,7 @@ module MaxMind
     # @param database [String] a path to a {MaxMind
     #   DB}[https://maxmind.github.io/MaxMind-DB/].
     #
-    # @param options [Hash<Symbol, Symbol>] options controlling the behavior of
+    # @param options [Hash<Symbol, Object>] options controlling the behavior of
     #   the DB.
     #
     # @option options [Symbol] :mode Defines how to open the database. It may
@@ -80,11 +80,27 @@ module MaxMind
     #   one, DB uses MODE_AUTO. Refer to the definition of those constants for
     #   an explanation of their meaning.
     #
-    # @raise [InvalidDatabaseError] if the database is corrupt or invalid.
+    # @option options [Integer] :max_values The maximum number of values a
+    #   single record, or the metadata, may decode to. The default is 65,536.
+    #   The largest records MaxMind produces decode to a few hundred values.
+    #
+    # @option options [Integer] :max_payload_bytes The maximum total size in
+    #   bytes of the strings, bytes, and integers a single record, or the
+    #   metadata, may decode. The default is 2 MiB. The largest records MaxMind
+    #   produces hold about a kilobyte.
+    #
+    # @option options [Integer] :max_depth The maximum nesting depth of maps,
+    #   arrays, and pointers in a single record, or the metadata. The default
+    #   is 512.
     #
-    # @raise [ArgumentError] if the mode is invalid.
+    # @raise [InvalidDatabaseError] if the database is corrupt or invalid. A
+    #   database that exceeds any of the limits above raises this error from
+    #   the lookup, or from this constructor if the metadata exceeds them.
+    #
+    # @raise [ArgumentError] if the mode or a limit is invalid.
     def initialize(database, options = {})
       options[:mode] = MODE_AUTO unless options.key?(:mode)
+      limits = decoder_limits(options)
 
       case options[:mode]
       when MODE_AUTO, MODE_FILE
@@ -101,11 +117,11 @@ module MaxMind
         @size = @io.size
 
         metadata_start = find_metadata_start
-        metadata_decoder = Decoder.new(@io, metadata_start)
+        metadata_decoder = Decoder.new(@io, metadata_start, **limits)
         metadata_map, = metadata_decoder.decode(metadata_start)
         @metadata = Metadata.new(metadata_map)
         @decoder = Decoder.new(@io, @metadata.search_tree_size +
-                               DATA_SECTION_SEPARATOR_SIZE)
+                               DATA_SECTION_SEPARATOR_SIZE, **limits)
 
         # Store copies as instance variables to reduce method calls.
         @ip_version       = @metadata.ip_version
@@ -271,6 +287,24 @@ module MaxMind
       data
     end
 
+    LIMIT_OPTIONS = %i[max_values max_payload_bytes max_depth].freeze
+    private_constant :LIMIT_OPTIONS
+
+    # Return the decoder limits given in +options+ as keyword arguments for
+    # Decoder.new. An absent option keeps the decoder's default.
+    def decoder_limits(options)
+      limits = {}
+      LIMIT_OPTIONS.each do |name|
+        next unless options.key?(name)
+
+        value = options[name]
+        raise ArgumentError, "#{name} must be a positive integer" unless value.is_a?(Integer) && value.positive?
+
+        limits[name] = value
+      end
+      limits
+    end
+
     def find_metadata_start
       metadata_max_size = [@size, METADATA_MAX_SIZE].min