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

Wire-format details

• msgAuthenticationParameters is the HMAC computed over the entire serialized message with the parameter field itself zeroed (RFC 3414 6.3.1 / 7.3.1). On decode the MAC is recomputed over the bytes actually received, never over a re-encoding, so any peer's BER choices are accepted.
• Encrypted messages carry the ciphertext in an OCTET STRING msgData; the MAC covers that OCTET STRING, exactly as transmitted.
• AES/DES IVs are derived from msgAuthoritativeEngineBoots/Time and the 8-octet salt in msgPrivacyParameters (RFC 3414 8.1.1.1, RFC 3826 3.1.2.1).
• Decoded messages expose the received USM parameters under :security_parameters (see SnmpKit.SnmpLib.Security.security_params/0) and the raw octets under :msg_security_parameters.