SnmpKit.SnmpSim.Core.UsmAgent (snmpkit v2.0.1)

Agent-side SNMPv3 User-based Security Model for simulated devices (RFC 3414): engine identity, boots and time, per-user localized keys, authentication and privacy on both directions, and the usmStats reports that drive a manager's discovery and time synchronisation.

A device gets one of these when started with v3_users::

SnmpKit.Sim.start_device(profile,
  port: 1161,
  v3_users: [
    %{name: "guest"},
    %{name: "ops", auth: :sha256, auth_password: "authpass"},
    %{name: "admin", auth: :sha256, auth_password: "authpass", priv: :aes128, priv_password: "privpass"}
  ]
)

Each user's auth may be :md5, :sha1, :sha256, :sha384 or :sha512 and priv may be :des, :aes128, :aes192 or :aes256; a request must use at least the user's security level.

Summary

Types

t()

Functions

decode_request(packet, agent)

Decodes an incoming SNMPv3 datagram. Returns {:request, pdu, ctx} for a request the device should answer (encode the reply with encode_response/3), {:report, packet} for a USM report to send back as-is, or {:error, reason} to drop it.

derive_engine_id(device_id)

RFC 3411 engine id (format 4, text) derived from a device id.

encode_response(response_pdu, ctx, agent)

Encodes the device's response PDU for the request context returned by decode_request/2.

engine_time(usm_agent)

The agent's engine time in seconds since its boot.

new(opts)

Builds the agent state. Options: :v3_users (list of maps or keyword lists with name, auth, auth_password, priv, priv_password), :engine_id (binary; derived from :device_id when absent), :engine_boots (default 1).

Types

t()

@type t() :: %SnmpKit.SnmpSim.Core.UsmAgent{
  engine_boots: non_neg_integer(),
  engine_id: binary(),
  started_at: integer(),
  stats: map(),
  users: %{required(String.t()) => map()}
}

Functions

decode_request(packet, agent)

@spec decode_request(binary(), t()) ::
  {:request, map(), map()} | {:report, binary()} | {:error, term()}

Decodes an incoming SNMPv3 datagram. Returns {:request, pdu, ctx} for a request the device should answer (encode the reply with encode_response/3), {:report, packet} for a USM report to send back as-is, or {:error, reason} to drop it.

derive_engine_id(device_id)

@spec derive_engine_id(String.t()) :: binary()

RFC 3411 engine id (format 4, text) derived from a device id.

encode_response(response_pdu, ctx, agent)

@spec encode_response(map(), map(), t()) :: {:ok, binary()} | {:error, term()}

Encodes the device's response PDU for the request context returned by decode_request/2.

engine_time(usm_agent)

@spec engine_time(t()) :: non_neg_integer()

The agent's engine time in seconds since its boot.

new(opts)

@spec new(keyword()) :: {:ok, t()} | {:error, term()}

Builds the agent state. Options: :v3_users (list of maps or keyword lists with name, auth, auth_password, priv, priv_password), :engine_id (binary; derived from :device_id when absent), :engine_boots (default 1).