netsnmp 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b080e928ed8014ae935e3bafd2356c21304b60f1c29c2c5327f7694e2825567a
-  data.tar.gz: de052efcd0958285cf8ae5609fadca6519d94e48af2076f74d1a76886e6f5309
+  metadata.gz: 60a9c68e56e5ad0600d056eedd315d8639cfd3965aa5e1eb62f5f3f935b4ad6a
+  data.tar.gz: ea560ac1131bff9ca6af0fec5e426bd37edbfbc7520ceb629f1de279a905ced0
 SHA512:
-  metadata.gz: 9ead6354c915b389219ef88a0227fe509347897b4980278cd4daf08d410014effeb1863c2d4aa36ddcc019c9dd018f9ec383771812e50de75ed3f6d29d35fd38
-  data.tar.gz: 323eb76b9ed6538704897d000b03d100c04b3443dd2b7c6b2313da67db065a0adca5f31431eef0b571eb9a29a4d9762fd6151fc90840c149cdf023634ab802d3
+  metadata.gz: 8410a3a38d7d7eab07692009ae4d870dbae8e7abc50dbc724d9ad3f8a4e029b441ffba62e9477ae587f8845a561cb0ba2e2c5613540d615bdce0cf62cb448098
+  data.tar.gz: 85d0d898983f99dedb4a71cf6bd33f665cfda496bb8a60eb76be36a96de6f28a9984505c564701bfab6bf74e8367544ec2f5adbcf8faf152d9a71679b73b5df1

data/README.md

@@ -32,7 +32,7 @@ This gem provides:
 
 * Implementation in ruby of the SNMP Protocol for v3, v2c and v1 (most notable the rfc3414 and 3826).
 * Client/Manager API with simple interface for get, genext, set and walk.
-* No dependencies.
+* Pure Ruby.
 * Support for concurrency and evented I/O.
 
 ## Why?
@@ -54,11 +54,12 @@ All of these issues are resolved here.
 ## Features
 
 * Client Interface, which supports SNMP v3, v2c, and v1
-* Supports get, getnext, set and walk calls.
-* MIB support.
+* Supports get, getnext, set and walk calls
+* MIB support
 * Proxy IO object support (for eventmachine/celluloid-io)
 * Ruby >= 2.1 support (modern)
 * Pure Ruby (no FFI)
+* Easy PDU debugging
 
 ## Examples
 
@@ -236,10 +237,24 @@ NETSNMP::Client.new(share_options.merge(proxy: router_proxy, security_parameters
 end
 ```
 
+## Compatibility
+
+This library supports and is tested against ruby versions 2.1 or more recent, including ruby 3. It also supports and tests against Truffleruby.
+
 ## OpenSSL
 
 All encoding/decoding/encryption/decryption/digests are done using `openssl`, which is (still) a part of the standard library. If at some point `openssl` is removed and not specifically distributed, you'll have to install it yourself. Hopefully this will never happen.
 
+## Debugging
+
+You can either set the `NETSNMP_DEBUG` to the desided debug level (currently, 1 and 2). The logs will be written to stderr.
+
+You can also set it for a specific client:
+
+```ruby
+manager2 = NETSNMP::Client.new(debug: $stderr, debug_level: 2, ....)
+```
+
 
 ## Tests
 

data/lib/netsnmp.rb

@@ -33,51 +33,9 @@ rescue LoadError
   end
 end
 
-module NETSNMP
-  module IsNumericExtensions
-    refine String do
-      def integer?
-        each_byte do |byte|
-          return false unless byte >= 48 && byte <= 57
-        end
-        true
-      end
-    end
-  end
-
-  module StringExtensions
-    # If you wonder why this is there: the oauth feature uses a refinement to enhance the
-    # Regexp class locally with #match? , but this is never tested, because ActiveSupport
-    # monkey-patches the same method... Please ActiveSupport, stop being so intrusive!
-    # :nocov:
-    refine(String) do
-      def match?(*args)
-        !match(*args).nil?
-      end
-    end
-  end
-
-  def self.debug=(io)
-    @debug_output = io
-  end
-
-  def self.debug(&blk)
-    @debug_output << blk.call + "\n" if @debug_output
-  end
-
-  unless defined?(Hexdump) # support the hexdump gem
-    module Hexdump
-      def self.dump(data, width: 8)
-        pairs = data.unpack("H*").first.scan(/.{4}/)
-        pairs.each_slice(width).map do |row|
-          row.join(" ")
-        end.join("\n")
-      end
-    end
-  end
-end
-
 require "netsnmp/errors"
+require "netsnmp/extensions"
+require "netsnmp/loggable"
 
 require "netsnmp/timeticks"
 

data/lib/netsnmp/client.rb

@@ -153,7 +153,7 @@ module NETSNMP
       retries = @retries
       begin
         yield
-      rescue Timeout::Error => e
+      rescue Timeout::Error, IdNotInTimeWindowError => e
         raise e if retries.zero?
         retries -= 1
         retry

data/lib/netsnmp/encryption/aes.rb

@@ -22,13 +22,12 @@ module NETSNMP
         end
 
         encrypted_data = cipher.update(decrypted_data) + cipher.final
-        NETSNMP.debug { "encrypted:\n#{Hexdump.dump(encrypted_data)}" }
 
         [encrypted_data, salt]
       end
 
       def decrypt(encrypted_data, salt:, engine_boots:, engine_time:)
-        raise Error, "invalid priv salt received" unless (salt.length % 8).zero?
+        raise Error, "invalid priv salt received" unless !salt.empty? && (salt.length % 8).zero?
 
         cipher = OpenSSL::Cipher::AES128.new(:CFB)
         cipher.padding = 0
@@ -39,7 +38,6 @@ module NETSNMP
         cipher.key = aes_key
         cipher.iv = iv
         decrypted_data = cipher.update(encrypted_data) + cipher.final
-        NETSNMP.debug { "decrypted:\n#{Hexdump.dump(decrypted_data)}" }
 
         hlen, bodylen = OpenSSL::ASN1.traverse(decrypted_data) { |_, _, x, y, *| break x, y }
         decrypted_data.byteslice(0, hlen + bodylen)

data/lib/netsnmp/encryption/des.rb

@@ -24,7 +24,6 @@ module NETSNMP
         end
 
         encrypted_data = cipher.update(decrypted_data) + cipher.final
-        NETSNMP.debug { "encrypted:\n#{Hexdump.dump(encrypted_data)}" }
         [encrypted_data, salt]
       end
 
@@ -41,7 +40,6 @@ module NETSNMP
         cipher.key = des_key
         cipher.iv = iv
         decrypted_data = cipher.update(encrypted_data) + cipher.final
-        NETSNMP.debug { "decrypted:\n#{Hexdump.dump(decrypted_data)}" }
 
         hlen, bodylen = OpenSSL::ASN1.traverse(decrypted_data) { |_, _, x, y, *| break x, y }
         decrypted_data.byteslice(0, hlen + bodylen)

data/lib/netsnmp/errors.rb

@@ -4,4 +4,5 @@ module NETSNMP
   Error = Class.new(StandardError)
   ConnectionFailed = Class.new(Error)
   AuthenticationFailed = Class.new(Error)
+  IdNotInTimeWindowError = Class.new(Error)
 end

data/lib/netsnmp/extensions.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module NETSNMP
+  module IsNumericExtensions
+    refine String do
+      def integer?
+        each_byte do |byte|
+          return false unless byte >= 48 && byte <= 57
+        end
+        true
+      end
+    end
+  end
+
+  module StringExtensions
+    refine(String) do
+      unless String.method_defined?(:match?)
+        def match?(*args)
+          !match(*args).nil?
+        end
+      end
+
+      unless String.method_defined?(:unpack1)
+        def unpack1(format)
+          unpack(format).first
+        end
+      end
+    end
+  end
+
+  module ASNExtensions
+    ASN_COLORS = {
+      OpenSSL::ASN1::Sequence => 34, # blue
+      OpenSSL::ASN1::OctetString => 32, # green
+      OpenSSL::ASN1::Integer => 33, # yellow
+      OpenSSL::ASN1::ObjectId => 35, # magenta
+      OpenSSL::ASN1::ASN1Data => 36 # cyan
+    }.freeze
+
+    # basic types
+    ASN_COLORS.each_key do |klass|
+      refine(klass) do
+        def to_hex
+          "#{colorize_hex} (#{value.to_s.inspect})"
+        end
+      end
+    end
+
+    # composite types
+    refine(OpenSSL::ASN1::Sequence) do
+      def to_hex
+        values = value.map(&:to_der).join
+        hex_values = value.map(&:to_hex).map { |s| s.gsub(/(\t+)/) { "\t#{Regexp.last_match(1)}" } }.map { |s| "\n\t#{s}" }.join
+        der = to_der
+        der = der.sub(values, "")
+
+        "#{colorize_hex(der)}#{hex_values}"
+      end
+    end
+
+    refine(OpenSSL::ASN1::ASN1Data) do
+      attr_reader :label
+
+      def with_label(label)
+        @label = label
+        self
+      end
+
+      def to_hex
+        case value
+        when Array
+          values = value.map(&:to_der).join
+          hex_values = value.map(&:to_hex)
+                            .map { |s| s.gsub(/(\t+)/) { "\t#{Regexp.last_match(1)}" } }
+                            .map { |s| "\n\t#{s}" }.join
+          der = to_der
+          der = der.sub(values, "")
+        else
+          der = to_der
+          hex_values = nil
+        end
+
+        "#{colorize_hex(der)}#{hex_values}"
+      end
+
+      private
+
+      def colorize_hex(der = to_der)
+        hex = Hexdump.dump(der, separator: " ")
+        lbl = @label || self.class.name.split("::").last
+        "#{lbl}: \e[#{ASN_COLORS[self.class]}m#{hex}\e[0m"
+      end
+    end
+  end
+
+  module Hexdump
+    using StringExtensions
+
+    def self.dump(data, width: 8, in_groups_of: 4, separator: "\n")
+      pairs = data.unpack1("H*").scan(/.{#{in_groups_of}}/)
+      pairs.each_slice(width).map do |row|
+        row.join(" ")
+      end.join(separator)
+    end
+  end
+
+  # Like a string, but it prints an hex-string version of itself
+  class HexString < String
+    def inspect
+      Hexdump.dump(self, in_groups_of: 2, separator: " ")
+    end
+  end
+end

data/lib/netsnmp/loggable.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module NETSNMP
+  module Loggable
+    DEBUG = ENV.key?("NETSNMP_DEBUG") ? $stderr : nil
+    DEBUG_LEVEL = (ENV["NETSNMP_DEBUG"] || 1).to_i
+
+    def initialize(debug: DEBUG, debug_level: DEBUG_LEVEL, **opts)
+      super(**opts)
+      @debug = debug
+      @debug_level = debug_level
+    end
+
+    private
+
+    COLORS = {
+      black: 30,
+      red: 31,
+      green: 32,
+      yellow: 33,
+      blue: 34,
+      magenta: 35,
+      cyan: 36,
+      white: 37
+    }.freeze
+
+    def log(level: @debug_level)
+      return unless @debug
+      return unless @debug_level >= level
+
+      debug_stream = @debug
+
+      debug_stream << (+"\n" << yield << "\n")
+    end
+  end
+end

data/lib/netsnmp/message.rb

@@ -2,41 +2,71 @@
 
 module NETSNMP
   # Factory for the SNMP v3 Message format
-  module Message
-    module_function
+  class Message
+    using ASNExtensions
 
-    AUTHNONE               = OpenSSL::ASN1::OctetString.new("\x00" * 12)
+    prepend Loggable
+
+    AUTHNONE               = OpenSSL::ASN1::OctetString.new("\x00" * 12).with_label(:auth_mask)
     PRIVNONE               = OpenSSL::ASN1::OctetString.new("")
-    MSG_MAX_SIZE       = OpenSSL::ASN1::Integer.new(65507)
-    MSG_SECURITY_MODEL = OpenSSL::ASN1::Integer.new(3) # usmSecurityModel
-    MSG_VERSION        = OpenSSL::ASN1::Integer.new(3)
+    MSG_MAX_SIZE       = OpenSSL::ASN1::Integer.new(65507).with_label(:max_message_size)
+    MSG_SECURITY_MODEL = OpenSSL::ASN1::Integer.new(3).with_label(:security_model) # usmSecurityModel
+    MSG_VERSION        = OpenSSL::ASN1::Integer.new(3).with_label(:message_version)
     MSG_REPORTABLE     = 4
 
+    def initialize(**); end
+
     # @param [String] payload of an snmp v3 message which can be decoded
     # @param [NETSMP::SecurityParameters, #decode] security_parameters knowns how to decode the stream
     #
     # @return [NETSNMP::ScopedPDU] the decoded PDU
     #
     def decode(stream, security_parameters:)
-      asn_tree = OpenSSL::ASN1.decode(stream)
-      _version, _headers, sec_params, pdu_payload = asn_tree.value
+      log { "received encoded V3 message" }
+      log { Hexdump.dump(stream) }
+      asn_tree = OpenSSL::ASN1.decode(stream).with_label(:v3_message)
+
+      version, headers, sec_params, pdu_payload = asn_tree.value
+      version.with_label(:message_version)
+      headers.with_label(:headers)
+      sec_params.with_label(:security_params)
+      pdu_payload.with_label(:pdu)
+
+      _, _, message_flags, = headers.value
 
-      sec_params_asn = OpenSSL::ASN1.decode(sec_params.value).value
+      # get last byte
+      # discard the left-outermost bits and keep the remaining two
+      security_level = message_flags.with_label(:message_flags).value.unpack("C*").last & 3
 
-      engine_id, engine_boots, engine_time, _username, auth_param, priv_param = sec_params_asn.map(&:value)
+      sec_params_asn = OpenSSL::ASN1.decode(sec_params.value).with_label(:security_params)
+
+      engine_id, engine_boots, engine_time, username, auth_param, priv_param = sec_params_asn.value
+      engine_id.with_label(:engine_id)
+      engine_boots.with_label(:engine_boots)
+      engine_time.with_label(:engine_time)
+      username.with_label(:username)
+      auth_param.with_label(:auth_param)
+      priv_param.with_label(:priv_param)
+
+      log(level: 2) { asn_tree.to_hex }
+      log(level: 2) { sec_params_asn.to_hex }
 
       # validate_authentication
-      security_parameters.verify(stream.sub(auth_param, AUTHNONE.value), auth_param)
+      auth_param = auth_param.value
+      security_parameters.verify(stream.sub(auth_param, AUTHNONE.value), auth_param, security_level: security_level)
 
-      engine_boots = engine_boots.to_i
-      engine_time = engine_time.to_i
+      engine_boots = engine_boots.value.to_i
+      engine_time = engine_time.value.to_i
 
-      encoded_pdu = security_parameters.decode(pdu_payload, salt: priv_param,
+      encoded_pdu = security_parameters.decode(pdu_payload, salt: priv_param.value,
                                                             engine_boots: engine_boots,
-                                                            engine_time: engine_time)
+                                                            engine_time: engine_time,
+                                                            security_level: security_level)
 
+      log { "received response PDU" }
       pdu = ScopedPDU.decode(encoded_pdu)
-      [pdu, engine_id, engine_boots, engine_time]
+      log(level: 2) { pdu.to_hex }
+      [pdu, engine_id.value, engine_boots, engine_time]
     end
 
     # @param [NETSNMP::ScopedPDU] the PDU to encode in the message
@@ -45,36 +75,48 @@ module NETSNMP
     # @return [String] the byte representation of an SNMP v3 Message
     #
     def encode(pdu, security_parameters:, engine_boots: 0, engine_time: 0)
+      log(level: 2) { pdu.to_hex }
+      log { "encoding PDU in V3 message..." }
       scoped_pdu, salt_param = security_parameters.encode(pdu, salt: PRIVNONE,
                                                                engine_boots: engine_boots,
                                                                engine_time: engine_time)
 
       sec_params = OpenSSL::ASN1::Sequence.new([
-                                                 OpenSSL::ASN1::OctetString.new(security_parameters.engine_id),
-                                                 OpenSSL::ASN1::Integer.new(engine_boots),
-                                                 OpenSSL::ASN1::Integer.new(engine_time),
-                                                 OpenSSL::ASN1::OctetString.new(security_parameters.username),
+                                                 OpenSSL::ASN1::OctetString.new(security_parameters.engine_id).with_label(:engine_id),
+                                                 OpenSSL::ASN1::Integer.new(engine_boots).with_label(:engine_boots),
+                                                 OpenSSL::ASN1::Integer.new(engine_time).with_label(:engine_time),
+                                                 OpenSSL::ASN1::OctetString.new(security_parameters.username).with_label(:username),
                                                  AUTHNONE,
                                                  salt_param
-                                               ])
+                                               ]).with_label(:security_params)
+      log(level: 2) { sec_params.to_hex }
+
       message_flags = MSG_REPORTABLE | security_parameters.security_level
-      message_id    = OpenSSL::ASN1::Integer.new(SecureRandom.random_number(2147483647))
+      message_id    = OpenSSL::ASN1::Integer.new(SecureRandom.random_number(2147483647)).with_label(:message_id)
       headers = OpenSSL::ASN1::Sequence.new([
-                                              message_id, MSG_MAX_SIZE,
-                                              OpenSSL::ASN1::OctetString.new([String(message_flags)].pack("h*")),
+                                              message_id,
+                                              MSG_MAX_SIZE,
+                                              OpenSSL::ASN1::OctetString.new([String(message_flags)].pack("h*")).with_label(:message_flags),
                                               MSG_SECURITY_MODEL
-                                            ])
+                                            ]).with_label(:headers)
 
       encoded = OpenSSL::ASN1::Sequence([
                                           MSG_VERSION,
                                           headers,
-                                          OpenSSL::ASN1::OctetString.new(sec_params.to_der),
+                                          OpenSSL::ASN1::OctetString.new(sec_params.to_der).with_label(:security_params),
                                           scoped_pdu
-                                        ]).to_der
+                                        ]).with_label(:v3_message)
+      log(level: 2) { encoded.to_hex }
+
+      encoded = encoded.to_der
+      log { Hexdump.dump(encoded) }
       signature = security_parameters.sign(encoded)
       if signature
-        auth_salt = OpenSSL::ASN1::OctetString.new(signature)
+        log { "signing V3 message..." }
+        auth_salt = OpenSSL::ASN1::OctetString.new(signature).with_label(:auth)
+        log(level: 2) { auth_salt.to_hex }
         encoded.sub!(AUTHNONE.to_der, auth_salt.to_der)
+        log { Hexdump.dump(encoded) }
       end
       encoded
     end

data/lib/netsnmp/mib.rb

@@ -48,12 +48,10 @@ module NETSNMP
       [prefix, *suffix].join(".")
     end
 
-    # This is a helper function, do not rely on this functionality in future
-    # versions
     def identifier(oid)
-      @object_identifiers.select do |_, full_oid|
-        full_oid.start_with?(oid)
-      end
+      @object_identifiers.select do |_, ids_oid|
+        oid.start_with?(ids_oid)
+      end.sort_by(&:size).first
     end
 
     #
@@ -86,7 +84,7 @@ module NETSNMP
       true
     end
 
-    TYPES = ["OBJECT-TYPE", "OBJECT IDENTIFIER", "MODULE-IDENTITY"].freeze
+    TYPES = ["OBJECT IDENTIFIER", "OBJECT-TYPE", "MODULE-IDENTITY"].freeze
 
     STATIC_MIB_TO_OID = {
       "iso" => "1"
@@ -98,41 +96,54 @@ module NETSNMP
     def do_load(mod)
       data = @parser_mutex.synchronize { PARSER.parse(File.read(mod)) }
 
-      imports = load_imports(data)
+      imports = load_imports(data[:imports])
 
-      data[:declarations].each_with_object(@object_identifiers) do |dec, types|
-        next unless TYPES.include?(dec[:type])
+      declarations = Hash[
+        data[:declarations].reject { |dec| !dec.key?(:name) || !TYPES.include?(dec[:type]) }
+                           .map { |dec| [String(dec[:name]), String(dec[:value]).split(/ +/)] }
+      ]
 
-        oid = String(dec[:value]).split(/ +/).flat_map do |cp|
-          if cp.integer?
-            cp
-          else
-            STATIC_MIB_TO_OID[cp] || @object_identifiers[cp] || begin
-              imported_mod, = imports.find do |_, identifiers|
-                identifiers.include?(cp)
-              end
+      declarations.each do |nme, value|
+        store_oid_in_identifiers(nme, value, imports: imports, declarations: declarations)
+      end
+    end
 
-              raise Error, "didn't find a module to import \"#{cp}\" from" unless imported_mod
+    def store_oid_in_identifiers(nme, value, imports:, declarations:)
+      oid = value.flat_map do |cp|
+        if cp.integer?
+          cp
+        elsif @object_identifiers.key?(cp)
+          @object_identifiers[cp]
+        elsif declarations.key?(cp)
+          store_oid_in_identifiers(cp, declarations[cp], imports: imports, declarations: declarations)
+          @object_identifiers[cp]
+        else
+          STATIC_MIB_TO_OID[cp] || begin
+            imported_mod, = imports.find do |_, identifiers|
+              identifiers.include?(cp)
+            end
 
-              load(imported_mod)
+            raise Error, "didn't find a module to import \"#{cp}\" from" unless imported_mod
 
-              @object_identifiers[cp]
-            end
+            load(imported_mod)
+
+            @object_identifiers[cp]
           end
-        end.join(".")
+        end
+      end.join(".")
 
-        types[String(dec[:name])] = oid
-      end
+      @object_identifiers[nme] = oid
     end
 
     #
     # Reformats the import lists into an hash indexed by module name, to a list of
     # imported names
     #
-    def load_imports(data)
-      return unless data[:imports]
+    def load_imports(imports)
+      return unless imports
 
-      data[:imports].each_with_object({}) do |import, imp|
+      imports = [imports] unless imports.respond_to?(:to_ary)
+      imports.each_with_object({}) do |import, imp|
         imp[String(import[:name])] = case import[:ids]
                                      when Hash
                                        [String(import[:ids][:name])]

data/lib/netsnmp/pdu.rb

@@ -5,7 +5,11 @@ module NETSNMP
   # Abstracts the PDU base structure into a ruby object. It gives access to its varbinds.
   #
   class PDU
+    using ASNExtensions
+
     MAXREQUESTID = 2147483647
+
+    using ASNExtensions
     class << self
       def decode(der)
         asn_tree = case der
@@ -53,6 +57,7 @@ module NETSNMP
               when :inform    then 6
               when :trap      then 7
               when :response  then 2
+              when :report    then 8
               else raise Error, "#{type} is not supported as type"
               end
         new(type: typ, **args)
@@ -85,6 +90,10 @@ module NETSNMP
       to_asn.to_der
     end
 
+    def to_hex
+      to_asn.to_hex
+    end
+
     # Adds a request varbind to the pdu
     #
     # @param [OID] oid a valid oid
@@ -96,25 +105,27 @@ module NETSNMP
     alias << add_varbind
 
     def to_asn
-      request_id_asn = OpenSSL::ASN1::Integer.new(@request_id)
-      error_asn = OpenSSL::ASN1::Integer.new(@error_status)
-      error_index_asn = OpenSSL::ASN1::Integer.new(@error_index)
+      request_id_asn = OpenSSL::ASN1::Integer.new(@request_id).with_label(:request_id)
+      error_asn = OpenSSL::ASN1::Integer.new(@error_status).with_label(:error)
+      error_index_asn = OpenSSL::ASN1::Integer.new(@error_index).with_label(:error_index)
 
-      varbind_asns = OpenSSL::ASN1::Sequence.new(@varbinds.map(&:to_asn))
+      varbind_asns = OpenSSL::ASN1::Sequence.new(@varbinds.map(&:to_asn)).with_label(:varbinds)
 
       request_asn = OpenSSL::ASN1::ASN1Data.new([request_id_asn,
                                                  error_asn, error_index_asn,
                                                  varbind_asns], @type,
-                                                :CONTEXT_SPECIFIC)
+                                                :CONTEXT_SPECIFIC).with_label(:request)
 
-      OpenSSL::ASN1::Sequence.new([*encode_headers_asn, request_asn])
+      OpenSSL::ASN1::Sequence.new([*encode_headers_asn, request_asn]).with_label(:pdu)
     end
 
     private
 
     def encode_headers_asn
-      [OpenSSL::ASN1::Integer.new(@version),
-       OpenSSL::ASN1::OctetString.new(@community)]
+      [
+        OpenSSL::ASN1::Integer.new(@version).with_label(:snmp_version),
+        OpenSSL::ASN1::OctetString.new(@community).with_label(:community)
+      ]
     end
 
     # http://www.tcpipguide.com/free/t_SNMPVersion2SNMPv2MessageFormats-5.htm#Table_219

data/lib/netsnmp/scoped_pdu.rb

@@ -2,6 +2,8 @@
 
 module NETSNMP
   class ScopedPDU < PDU
+    using ASNExtensions
+
     attr_reader :engine_id
 
     def initialize(type:, headers:, **options)
@@ -12,8 +14,10 @@ module NETSNMP
     private
 
     def encode_headers_asn
-      [OpenSSL::ASN1::OctetString.new(@engine_id || ""),
-       OpenSSL::ASN1::OctetString.new(@context || "")]
+      [
+        OpenSSL::ASN1::OctetString.new(@engine_id || "").with_label(:engine_id),
+        OpenSSL::ASN1::OctetString.new(@context || "").with_label(:context)
+      ]
     end
   end
 end

data/lib/netsnmp/security_parameters.rb

@@ -8,6 +8,9 @@ module NETSNMP
   # It also provides validation of the security options passed with a client is initialized in v3 mode.
   class SecurityParameters
     using StringExtensions
+    using ASNExtensions
+
+    prepend Loggable
 
     IPAD = "\x36" * 64
     OPAD = "\x5c" * 64
@@ -72,7 +75,10 @@ module NETSNMP
       if encryption
         encrypted_pdu, salt = encryption.encrypt(pdu.to_der, engine_boots: engine_boots,
                                                              engine_time: engine_time)
-        [OpenSSL::ASN1::OctetString.new(encrypted_pdu), OpenSSL::ASN1::OctetString.new(salt)]
+        [
+          OpenSSL::ASN1::OctetString.new(encrypted_pdu).with_label(:encrypted_pdu),
+          OpenSSL::ASN1::OctetString.new(salt).with_label(:salt)
+        ]
       else
         [pdu.to_asn, salt]
       end
@@ -82,15 +88,16 @@ module NETSNMP
     # @param [String] salt the salt from the incoming der
     # @param [Integer] engine_time the reported engine time
     # @param [Integer] engine_boots the reported engine boots
-    def decode(der, salt:, engine_time:, engine_boots:)
+    def decode(der, salt:, engine_time:, engine_boots:, security_level: @security_level)
       asn = OpenSSL::ASN1.decode(der)
-      if encryption
-        encrypted_pdu = asn.value
-        pdu_der = encryption.decrypt(encrypted_pdu, salt: salt, engine_time: engine_time, engine_boots: engine_boots)
-        OpenSSL::ASN1.decode(pdu_der)
-      else
-        asn
-      end
+      return asn if security_level < 3
+
+      return asn unless encryption
+
+      encrypted_pdu = asn.value
+      pdu_der = encryption.decrypt(encrypted_pdu, salt: salt, engine_time: engine_time, engine_boots: engine_boots)
+      log(level: 2) { "message has been decrypted" }
+      OpenSSL::ASN1.decode(pdu_der)
     end
 
     # @param [String] message the already encoded snmp v3 message
@@ -120,10 +127,11 @@ module NETSNMP
     # @param [String] salt the incoming payload''s salt
     #
     # @raise [NETSNMP::Error] if the message's integration has been violated
-    def verify(stream, salt)
-      return if @security_level < 1
+    def verify(stream, salt, security_level: @security_level)
+      return if security_level < 1
       verisalt = sign(stream)
       raise Error, "invalid message authentication salt" unless verisalt == salt
+      log(level: 2) { "message has been verified" }
     end
 
     def must_revalidate?

data/lib/netsnmp/session.rb

@@ -4,6 +4,8 @@ module NETSNMP
   # Let's just remind that there is no session in snmp, this is just an abstraction.
   #
   class Session
+    prepend Loggable
+
     TIMEOUT = 2
 
     # @param [Hash] opts the options set
@@ -36,9 +38,16 @@ module NETSNMP
     # @return [NETSNMP::PDU] the response pdu
     #
     def send(pdu)
+      log { "sending request..." }
+      log(level: 2) { pdu.to_hex }
       encoded_request = pdu.to_der
+      log { Hexdump.dump(encoded_request) }
       encoded_response = @transport.send(encoded_request)
-      PDU.decode(encoded_response)
+      log { "received response" }
+      log { Hexdump.dump(encoded_response) }
+      response_pdu = PDU.decode(encoded_response)
+      log(level: 2) { response_pdu.to_hex }
+      response_pdu
     end
 
     private

data/lib/netsnmp/v3_session.rb

@@ -8,6 +8,7 @@ module NETSNMP
       @context = context
       @security_parameters = opts.delete(:security_parameters)
       super
+      @message_serializer = Message.new(**opts)
     end
 
     # @see {NETSNMP::Session#build_pdu}
@@ -20,10 +21,18 @@ module NETSNMP
 
     # @see {NETSNMP::Session#send}
     def send(pdu)
+      log { "sending request..." }
       encoded_request = encode(pdu)
       encoded_response = @transport.send(encoded_request)
-      pdu, = decode(encoded_response)
-      pdu
+      response_pdu, *args = decode(encoded_response)
+      if response_pdu.type == 8
+        varbind = response_pdu.varbinds.first
+        if varbind.oid == "1.3.6.1.6.3.15.1.1.2.0" # IdNotInTimeWindow
+          _, @engine_boots, @engine_time = args
+          raise IdNotInTimeWindowError, "request timestamp is already out of time window"
+        end
+      end
+      response_pdu
     end
 
     private
@@ -60,7 +69,8 @@ module NETSNMP
       report_sec_params = SecurityParameters.new(security_level: 0,
                                                  username: @security_parameters.username)
       pdu = ScopedPDU.build(:get, headers: [])
-      encoded_report_pdu = Message.encode(pdu, security_parameters: report_sec_params)
+      log { "sending probe..." }
+      encoded_report_pdu = @message_serializer.encode(pdu, security_parameters: report_sec_params)
 
       encoded_response_pdu = @transport.send(encoded_report_pdu)
 
@@ -69,13 +79,13 @@ module NETSNMP
     end
 
     def encode(pdu)
-      Message.encode(pdu, security_parameters: @security_parameters,
-                          engine_boots: @engine_boots,
-                          engine_time: @engine_time)
+      @message_serializer.encode(pdu, security_parameters: @security_parameters,
+                                      engine_boots: @engine_boots,
+                                      engine_time: @engine_time)
     end
 
     def decode(stream, security_parameters: @security_parameters)
-      Message.decode(stream, security_parameters: security_parameters)
+      @message_serializer.decode(stream, security_parameters: security_parameters)
     end
   end
 end

data/lib/netsnmp/varbind.rb

@@ -4,6 +4,8 @@ module NETSNMP
   # Abstracts the PDU variable structure into a ruby object
   #
   class Varbind
+    using StringExtensions
+
     attr_reader :oid, :value
 
     def initialize(oid, value: nil, type: nil)
@@ -48,18 +50,15 @@ module NETSNMP
     def convert_val(asn_value)
       case asn_value
       when OpenSSL::ASN1::OctetString
-        # yes, we are forcing all output to UTF-8
+        val = asn_value.value
+
         # it's kind of common in snmp, some stuff can't be converted,
         # like Hexa Strings. Parse them into a readable format a la netsnmp
-        val = asn_value.value
-        begin
-          val.encode("UTF-8")
-        rescue Encoding::UndefinedConversionError,
-               Encoding::ConverterNotFoundError,
-               Encoding::InvalidByteSequenceError
-          # hexdump me!
-          val.unpack("H*")[0].upcase.scan(/../).join(" ")
-        end
+        # https://github.com/net-snmp/net-snmp/blob/ed90aaaaea0d9cc6c5c5533f1863bae598d3b820/snmplib/mib.c#L650
+        is_hex_string = val.each_char.any? { |c| !c.match?(/[[:print:]]/) && !c.match?(/[[:space:]]/) }
+
+        val = HexString.new(val) if is_hex_string
+        val
       when OpenSSL::ASN1::Primitive
         val = asn_value.value
         val = val.to_i if val.is_a?(OpenSSL::BN)
@@ -81,11 +80,11 @@ module NETSNMP
                    when :ipaddress then 0
                    when :counter32
                      asn_val = [value].pack("N*")
-                     asn_val = asn_val[1..-1] while asn_val[0] == "\x00".b && asn_val[1].unpack("B").first != "1"
+                     asn_val = asn_val[1..-1] while asn_val[0] == "\x00".b && asn_val[1].unpack1("B") != "1"
                      1
                    when :gauge
                      asn_val = [value].pack("N*")
-                     asn_val = asn_val[1..-1] while asn_val[0] == "\x00".b && asn_val[1].unpack("B").first != "1"
+                     asn_val = asn_val[1..-1] while asn_val[0] == "\x00".b && asn_val[1].unpack1("B") != "1"
                      2
                    when :timetick
                      return Timetick.new(value).to_asn

data/lib/netsnmp/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module NETSNMP
-  VERSION = "0.3.0"
+  VERSION = "0.4.0"
 end

data/sig/loggable.rbs

@@ -0,0 +1,16 @@
+module NETSNMP
+  module Loggable
+    interface _Debugger
+      def <<: (string) -> void
+    end
+
+    DEBUG_LEVEL: Integer
+    DEBUG: _Debugger
+
+    private
+
+    def initialize: (?debug: _DEBUGGER, ?debug_level: Integer, **untyped) -> void
+
+    def log: (?level: Integer) { () -> String } -> void
+  end
+end

data/sig/message.rbs

@@ -1,7 +1,9 @@
 module NETSNMP
-  module Message
-    def self?.decode: (String stream, security_parameters: SecurityParameters) -> [ScopedPDU, String, Integer, Integer]
+  class Message
+    prepend Loggable
 
-    def self?.encode: (ScopedPDU pdu, security_parameters: SecurityParameters, ?engine_boots: Integer, ?engine_time: Integer) -> String
+    def decode: (String stream, security_parameters: SecurityParameters) -> [ScopedPDU, String, Integer, Integer]
+
+    def encode: (ScopedPDU pdu, security_parameters: SecurityParameters, ?engine_boots: Integer, ?engine_time: Integer) -> String
   end
 end

data/sig/mib.rbs

@@ -1,5 +1,8 @@
 module NETSNMP
   module MIB
+    type import = {ids: Array[{name: string}], name: string} | {ids: {name: string}, name: string}
+
+
     MIBDIRS: Array[String]
     PARSER: Parser
 
@@ -12,7 +15,7 @@ module NETSNMP
 
     def self?.load: (String mod) -> void
 
-    def self?.load_imports: (?Hash[Symbol, untyped] data) -> Hash[String, Array[String]]?
+    def self?.load_imports: ((Array[import] | import)? data) -> Hash[String, Array[String]]?
     def self?.load_defaults: () -> void
   end
 end

data/sig/netsnmp.rbs

@@ -16,8 +16,4 @@ module NETSNMP
   end
 
   type snmp_version = 0 | 1 | 3 | :v1 | :v2c | :v3 | nil
-
-  def self.debug=: (_Logger) -> void
-
-  def self.debug: { () -> string } -> void
 end

data/sig/pdu.rbs

@@ -12,7 +12,7 @@ module NETSNMP
     # }
 
     attr_reader varbinds: Array[Varbind]
-    attr_reader type: pdu_type
+    attr_reader type: Integer
     attr_reader version: snmp_version
     attr_reader community: String
     attr_reader request_id: Integer

data/sig/security_parameters.rbs

@@ -1,5 +1,7 @@
 module NETSNMP
   class SecurityParameters
+    prepend Loggable
+
     type security_level = :noauth | :auth_no_priv | :auth_priv | 0 | 1 | 3 | nil
 
     type auth_protocol = :md5 | :sha
@@ -21,11 +23,11 @@ module NETSNMP
 
     def encode: (_ToAsn, salt: OpenSSL::ASN1::ASN1Data, engine_time: Integer, engine_boots: Integer) -> [OpenSSL::ASN1::ASN1Data, OpenSSL::ASN1::ASN1Data]
 
-    def decode: (OpenSSL::ASN1::ASN1Data | String der, salt: OpenSSL::ASN1::ASN1Data | String, engine_time: Integer, engine_boots: Integer) -> OpenSSL::ASN1::ASN1Data
+    def decode: (OpenSSL::ASN1::ASN1Data | String der, salt: OpenSSL::ASN1::ASN1Data | String, engine_time: Integer, engine_boots: Integer, ?security_level: Integer?) -> OpenSSL::ASN1::ASN1Data
 
     def sign: (String message) -> String?
 
-    def verify: (String stream, String salt) -> void
+    def verify: (String stream, String salt, ?security_level: Integer?) -> void
 
     def must_revalidate?: () -> bool
 

data/sig/session.rbs

@@ -1,5 +1,7 @@
 module NETSNMP
   class Session
+    prepend Loggable
+
     @transport: _Transport
     @version: 0 | 1 | 3
     @community: String?

data/spec/client_spec.rb

@@ -67,6 +67,24 @@ RSpec.describe NETSNMP::Client do
         WALK
       end
       let(:set_oid_result) { 43 }
+
+      context "when the returned value is a hex-string" do
+        let(:protocol_options) do
+          {
+            version: "2c",
+            community: "foreignformats/winxp1"
+          }
+        end
+        let(:hex_get_oid) { "1.3.6.1.2.1.25.3.7.1.3.10.1" }
+        let(:hex_get_result) { "\x01\x00\x00\x00" }
+        let(:hex_get_output) { "01 00 00 00" }
+        let(:value) { subject.get(oid: hex_get_oid) }
+
+        it "returns the string, which outputs the hex-representation" do
+          expect(value).to eq(hex_get_result)
+          expect(value.inspect).to include(hex_get_output)
+        end
+      end
     end
   end
 

data/spec/spec_helper.rb

@@ -10,7 +10,6 @@ end
 
 if defined?(SimpleCov)
   SimpleCov.start do
-    minimum_coverage 85
     add_filter ".bundle"
     add_filter "/spec/"
   end

data/spec/varbind_spec.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 RSpec.describe NETSNMP::Varbind do
+  using NETSNMP::StringExtensions
+
   describe "#to_der" do
     it { expect(described_class.new(".1.3.6.1.2.1.1.1.0").to_der).to eq("0\f\006\b+\006\001\002\001\001\001\000\005\000".b) }
 
@@ -25,7 +27,7 @@ RSpec.describe NETSNMP::Varbind do
           gauge = 127
           varbind = described_class.new(".1.3.6.1.2.1.1.3.0", type: :gauge, value: gauge)
           value_str = varbind.to_der[12..-1]
-          header = value_str[0].unpack("B8").first
+          header = value_str[0].unpack1("B8")
 
           # Class: Primitive Application
           expect(header[0..1]).to eq("01")
@@ -43,7 +45,7 @@ RSpec.describe NETSNMP::Varbind do
           gauge = 128
           varbind = described_class.new(".1.3.6.1.2.1.1.3.0", type: :gauge, value: gauge)
           value_str = varbind.to_der[12..-1]
-          header = value_str[0].unpack("B8").first
+          header = value_str[0].unpack1("B8")
 
           # Class: Primitive Application
           expect(header[0..1]).to eq("01")
@@ -61,7 +63,7 @@ RSpec.describe NETSNMP::Varbind do
           gauge = 805
           varbind = described_class.new(".1.3.6.1.2.1.1.3.0", type: :gauge, value: gauge)
           value_str = varbind.to_der[12..-1]
-          header = value_str[0].unpack("B8").first
+          header = value_str[0].unpack1("B8")
 
           # Class: Primitive Application
           expect(header[0..1]).to eq("01")

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: netsnmp
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Tiago Cardoso
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-01-16 00:00:00.000000000 Z
+date: 2021-02-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: parslet
@@ -41,6 +41,8 @@ files:
 - lib/netsnmp/encryption/des.rb
 - lib/netsnmp/encryption/none.rb
 - lib/netsnmp/errors.rb
+- lib/netsnmp/extensions.rb
+- lib/netsnmp/loggable.rb
 - lib/netsnmp/message.rb
 - lib/netsnmp/mib.rb
 - lib/netsnmp/mib/parser.rb
@@ -54,6 +56,7 @@ files:
 - lib/netsnmp/varbind.rb
 - lib/netsnmp/version.rb
 - sig/client.rbs
+- sig/loggable.rbs
 - sig/message.rbs
 - sig/mib.rbs
 - sig/mib/parser.rbs
@@ -101,21 +104,21 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements:
 - net-snmp
-rubygems_version: 3.1.4
+rubygems_version: 3.2.3
 signing_key:
 specification_version: 4
 summary: SNMP Client library
 test_files:
-- spec/timeticks_spec.rb
-- spec/spec_helper.rb
-- spec/session_spec.rb
 - spec/client_spec.rb
+- spec/handlers/celluloid_spec.rb
 - spec/mib_spec.rb
 - spec/oid_spec.rb
-- spec/varbind_spec.rb
-- spec/support/request_examples.rb
-- spec/support/celluloid.rb
 - spec/pdu_spec.rb
 - spec/security_parameters_spec.rb
+- spec/session_spec.rb
+- spec/spec_helper.rb
+- spec/support/celluloid.rb
+- spec/support/request_examples.rb
+- spec/timeticks_spec.rb
 - spec/v3_session_spec.rb
-- spec/handlers/celluloid_spec.rb
+- spec/varbind_spec.rb