SNMPv3 message encoding and decoding with User Security Model (USM) support.

This module implements the SNMPv3 message format as specified in RFC 3412 and RFC 3414, providing authentication and privacy protection for SNMP communications.

SNMPv3 Message Structure

SNMPv3 messages have a complex hierarchical structure:

SNMPv3Message ::= SEQUENCE {
    msgVersion INTEGER (0..2147483647),
    msgGlobalData HeaderData,
    msgSecurityParameters OCTET STRING,
    msgData ScopedPduData
}

HeaderData ::= SEQUENCE {
    msgID INTEGER (0..2147483647),
    msgMaxSize INTEGER (484..2147483647),
    msgFlags OCTET STRING (SIZE(1)),
    msgSecurityModel INTEGER (1..2147483647)
}

ScopedPduData ::= CHOICE {
    plaintext ScopedPDU,
    encryptedPDU OCTET STRING
}

ScopedPDU ::= SEQUENCE {
    contextEngineID OCTET STRING,
    contextName OCTET STRING,
    data ANY
}

Security Processing

The module integrates with the security subsystem to provide:

• Message authentication using HMAC algorithms
• Message encryption using AES/DES algorithms
• Time synchronization and engine discovery
• Replay attack protection

Usage Examples

Encoding a SNMPv3 Message

# Create security user
user = %{
  security_name: "testuser",
  auth_protocol: :sha256,
  priv_protocol: :aes128,
  auth_key: derived_auth_key,
  priv_key: derived_priv_key,
  engine_id: "local_engine"
}

# Create SNMPv3 message
message = %{
  version: 3,
  msg_id: 12345,
  msg_max_size: 65507,
  msg_flags: %{auth: true, priv: true, reportable: true},
  msg_security_model: 3,
  msg_security_parameters: "",  # Will be generated
  msg_data: %{
    context_engine_id: "target_engine",
    context_name: "",
    pdu: pdu
  }
}

# Encode with security
{:ok, encoded} = SnmpKit.SnmpLib.PDU.V3Encoder.encode_message(message, user)

Decoding a SNMPv3 Message

{:ok, decoded} = SnmpKit.SnmpLib.PDU.V3Encoder.decode_message(binary_data, user)

Security Notes

• Authentication is required for privacy (encryption)
• Engine discovery must be performed before authenticated communication
• Time synchronization is required to prevent replay attacks
• Message IDs should be unique to prevent duplicate processing