Merge pull request #23 from n-rodriguez/feat/p2-v3-resync

feat(p2): v3 usmStats Report detection and auto-resync/retry

Author: stakach

spec/v3_report_spec.cr

@@ -0,0 +1,47 @@
+require "./helper"
+
+# Build a Report V3::Message carrying a usmStats varbind + engine params.
+private def report_message(stat_oid, engine_id = "8000000001020304", boots = 7, time = 42_000)
+  pdu = SNMP::PDU.new(request_id: 1, varbinds: [SNMP::VarBind.new(stat_oid)])
+  scoped = SNMP::V3::ScopedPDU.new(SNMP::Request::Report, pdu, engine_id)
+  params = SNMP::V3::SecurityParams.new("user", engine_id, boots, time)
+  SNMP::V3::Message.new(scoped, params, security_model: SNMP::V3::SecurityModel::USM)
+end
+
+describe SNMP::V3::UsmStat do
+  it "maps a usmStats OID (with instance suffix) to its counter" do
+    SNMP::V3::UsmStat.from_oid?("1.3.6.1.6.3.15.1.1.2.0").should eq(SNMP::V3::UsmStat::NotInTimeWindow)
+    SNMP::V3::UsmStat.from_oid?("1.3.6.1.6.3.15.1.1.4.0").should eq(SNMP::V3::UsmStat::UnknownEngineID)
+    SNMP::V3::UsmStat.from_oid?("1.3.6.1.2.1.1.1.0").should be_nil
+  end
+
+  it "marks only notInTimeWindow / unknownEngineID as resyncable" do
+    SNMP::V3::UsmStat::NotInTimeWindow.resyncable?.should be_true
+    SNMP::V3::UsmStat::UnknownEngineID.resyncable?.should be_true
+    SNMP::V3::UsmStat::WrongDigest.resyncable?.should be_false
+  end
+end
+
+describe SNMP::V3::Message do
+  it "recognises a Report PDU and its usmStats counter" do
+    msg = report_message("1.3.6.1.6.3.15.1.1.2.0")
+    msg.report?.should be_true
+    msg.usm_stat.should eq(SNMP::V3::UsmStat::NotInTimeWindow)
+  end
+
+  it "is not a report for an ordinary response" do
+    session = SNMP::V3::Session.new("user")
+    session.get("1.3.6.1.2.1.1.1.0").report?.should be_false
+  end
+end
+
+describe SNMP::V3::Session do
+  it "resyncs engine id / boots / time from a Report" do
+    session = SNMP::V3::Session.new("user")
+    session.resync_from(report_message("1.3.6.1.6.3.15.1.1.4.0", engine_id: "800000abcd", boots: 9, time: 12_345))
+
+    session.engine_id.should eq("800000abcd")
+    session.engine_boots.should eq(9)
+    session.engine_time.should eq(12_345)
+  end
+end

src/snmp/client.cr

@@ -81,25 +81,11 @@ class SNMP::Client
   end
 
   private def get(oid : String, sock : UDPSocket) : SNMP::Message
-    check_validation_probe(sock)
-
-    message = session.get(oid)
-    message = session.prepare(message) if message.is_a?(SNMP::V3::Message)
-
-    sock.write_bytes message
-    sock.flush
-    session.parse(sock.read_bytes(ASN1::BER))
+    request(sock) { session.get(oid) }
   end
 
   private def get(oids : Enumerable(String), sock : UDPSocket) : SNMP::Message
-    check_validation_probe(sock)
-
-    message = session.get(oids)
-    message = session.prepare(message) if message.is_a?(SNMP::V3::Message)
-
-    sock.write_bytes message
-    sock.flush
-    session.parse(sock.read_bytes(ASN1::BER))
+    request(sock) { session.get(oids) }
   end
 
   def get_next(oid : String) : SNMP::Message
@@ -126,25 +112,11 @@ class SNMP::Client
   end
 
   private def get_next(oid : String, sock : UDPSocket) : SNMP::Message
-    check_validation_probe(sock)
-
-    message = session.get_next(oid)
-    message = session.prepare(message) if message.is_a?(SNMP::V3::Message)
-
-    sock.write_bytes message
-    sock.flush
-    session.parse(sock.read_bytes(ASN1::BER))
+    request(sock) { session.get_next(oid) }
   end
 
   private def get_next(oids : Enumerable(String), sock : UDPSocket) : SNMP::Message
-    check_validation_probe(sock)
-
-    message = session.get_next(oids)
-    message = session.prepare(message) if message.is_a?(SNMP::V3::Message)
-
-    sock.write_bytes message
-    sock.flush
-    session.parse(sock.read_bytes(ASN1::BER))
+    request(sock) { session.get_next(oids) }
   end
 
   # GetBulk: one round-trip returning up to *max_repetitions* successors per
@@ -160,14 +132,7 @@ class SNMP::Client
   end
 
   private def get_bulk(oids : Enumerable(String), sock : UDPSocket, non_repeaters, max_repetitions) : SNMP::Message
-    check_validation_probe(sock)
-
-    message = session.get_bulk(oids, non_repeaters, max_repetitions)
-    message = session.prepare(message) if message.is_a?(SNMP::V3::Message)
-
-    sock.write_bytes message
-    sock.flush
-    session.parse(sock.read_bytes(ASN1::BER))
+    request(sock) { session.get_bulk(oids, non_repeaters, max_repetitions) }
   end
 
   # Set a single OID to *value* (a typed SNMP value, a Crystal primitive, or a
@@ -194,25 +159,11 @@ class SNMP::Client
   end
 
   private def set(oid : String, value, sock : UDPSocket) : SNMP::Message
-    check_validation_probe(sock)
-
-    message = session.set(oid, value)
-    message = session.prepare(message) if message.is_a?(SNMP::V3::Message)
-
-    sock.write_bytes message
-    sock.flush
-    session.parse(sock.read_bytes(ASN1::BER))
+    request(sock) { session.set(oid, value) }
   end
 
   private def set(values : Hash(String, _), sock : UDPSocket) : SNMP::Message
-    check_validation_probe(sock)
-
-    message = session.set(values)
-    message = session.prepare(message) if message.is_a?(SNMP::V3::Message)
-
-    sock.write_bytes message
-    sock.flush
-    session.parse(sock.read_bytes(ASN1::BER))
+    request(sock) { session.set(values) }
   end
 
   def walk(oid : String) : Array(SNMP::Message)
@@ -290,4 +241,38 @@ class SNMP::Client
       session.validate sock.read_bytes(ASN1::BER)
     end
   end
+
+  # Build a fresh request, send it, and return the parsed response — transparently
+  # recovering from a recoverable v3 usmStats Report (notInTimeWindow /
+  # unknownEngineID) by resyncing the engine params and retrying exactly once.
+  # A non-recoverable Report, or a Report that survives the retry, raises
+  # `Security::ReportError`. The block is re-invoked on retry so the rebuilt
+  # request carries the freshly synced engine boots/time/id.
+  private def request(sock, &build : -> SNMP::Message) : SNMP::Message
+    check_validation_probe(sock)
+    response = transceive(sock, build.call)
+
+    sess = session
+    if response.is_a?(SNMP::V3::Message) && response.report? && sess.is_a?(SNMP::V3::Session)
+      stat = response.usm_stat
+      if stat.try(&.resyncable?)
+        sess.resync_from(response)
+        response = transceive(sock, build.call)
+      end
+
+      if response.is_a?(SNMP::V3::Message) && response.report?
+        raise SNMP::V3::Security::ReportError.new(
+          "agent returned a usmStats Report (#{response.usm_stat || "unknown"})", response.usm_stat)
+      end
+    end
+
+    response
+  end
+
+  private def transceive(sock, message : SNMP::Message) : SNMP::Message
+    payload = message.is_a?(SNMP::V3::Message) ? session.prepare(message) : message
+    sock.write_bytes payload
+    sock.flush
+    session.parse(sock.read_bytes(ASN1::BER))
+  end
 end

src/snmp/v3/message.cr

@@ -2,6 +2,7 @@ require "./session"
 require "./security"
 require "./scoped_pdu"
 require "./security_params"
+require "./report"
 
 class SNMP::V3::Message < SNMP::Message
   def initialize(snmp : Array(ASN1::BER), security = nil)
@@ -76,6 +77,18 @@ class SNMP::V3::Message < SNMP::Message
   property security_params : SecurityParams
   property scoped_pdu : ScopedPDU
 
+  # True if this is a Report PDU (RFC 3412 6.2.6) — the agent's error report.
+  def report? : Bool
+    @request == Request::Report
+  end
+
+  # The usmStats counter this Report names, or nil if it is not a usmStats Report.
+  def usm_stat : UsmStat?
+    return nil unless report?
+    oid = @pdu.varbinds.first?.try(&.oid)
+    oid ? UsmStat.from_oid?(oid) : nil
+  end
+
   def engine_id
     @security_params.engine_id
   end

src/snmp/v3/report.cr

@@ -0,0 +1,30 @@
+module SNMP::V3
+  # Subtree of the RFC 3414 usmStats counters, reported to a manager via a
+  # Report PDU (e.g. after a time-window or engine-id mismatch).
+  USM_STATS_BASE = "1.3.6.1.6.3.15.1.1"
+
+  # The usmStats counters (RFC 3414 5). A Report PDU names exactly one.
+  enum UsmStat
+    UnsupportedSecLevel = 1
+    NotInTimeWindow     = 2
+    UnknownUserName     = 3
+    UnknownEngineID     = 4
+    WrongDigest         = 5
+    DecryptionError     = 6
+
+    # Map a reported OID (with or without its trailing `.0` instance) to the
+    # counter, or nil if it is not under the usmStats subtree.
+    def self.from_oid?(oid : String) : UsmStat?
+      return nil unless oid.starts_with?("#{USM_STATS_BASE}.")
+      arc = oid[(USM_STATS_BASE.size + 1)..].split('.', 2).first
+      num = arc.to_i?
+      num ? from_value?(num) : nil
+    end
+
+    # Recoverable by re-syncing the engine params and retrying the request once.
+    # The other counters signal a configuration error where a retry is futile.
+    def resyncable? : Bool
+      self == NotInTimeWindow || self == UnknownEngineID
+    end
+  end
+end

src/snmp/v3/security.cr

@@ -16,6 +16,17 @@ class SNMP::V3::Security
   class NotInTimeWindowError < AuthenticationError
   end
 
+  # Raised when the agent returns a usmStats Report PDU that cannot be recovered
+  # by a resync/retry (e.g. wrongDigest, unknownUserName), or when a resyncable
+  # Report is still returned after the retry.
+  class ReportError < Error
+    getter usm_stat : V3::UsmStat?
+
+    def initialize(message, @usm_stat = nil)
+      super(message)
+    end
+  end
+
   enum AuthProtocol
     MD5
     SHA # SHA-1

src/snmp/v3/session.cr

@@ -67,6 +67,18 @@ class SNMP::V3::Session
     validate probe
   end
 
+  # Re-sync the local engine identity / clock from an authoritative message
+  # (typically a usmStats Report), so a retried request carries fresh values.
+  # The engine id is only overwritten when the message actually carries one.
+  def resync_from(message : V3::Message)
+    engine_id = message.security_params.engine_id
+    @security.engine_id = @engine_id = engine_id unless engine_id.empty?
+    @engine_boots = message.security_params.engine_boots
+    @engine_time = message.security_params.engine_time
+    @timeliness = Time.monotonic.to_i
+    self
+  end
+
   # Enforce the RFC 3414 3.2.7 time window on an inbound authenticated message
   # and advance the local notion of the remote engine's (boots, time).
   #