Search documentation of snmpkit

# SnmpKit.SnmpLib.PDU.V3Encoder (snmpkit v1.2.0)

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

# Summary

## Types

scoped_pdu()
security_params()
security_user()
v3_message()

## Functions

create_discovery_message(msg_id \\ :rand.uniform(2_147_483_647))

Creates a discovery message for engine ID discovery.

decode_message(data, user \\ nil)

Decodes a SNMPv3 message with security processing.

encode_message(message, user \\ nil)

Encodes a SNMPv3 message with security processing.

# Types

# scoped_pdu()

    @type scoped_pdu() :: SnmpKit.SnmpLib.PDU.Constants.scoped_pdu()

# security_params()

    @type security_params() :: SnmpKit.SnmpLib.Security.security_params()

# security_user()

    @type security_user() :: SnmpKit.SnmpLib.Security.security_user()

# v3_message()

    @type v3_message() :: SnmpKit.SnmpLib.PDU.Constants.v3_message()

# Functions

# create_discovery_message(msg_id \\ :rand.uniform(2_147_483_647))

    @spec create_discovery_message(non_neg_integer()) :: v3_message()

Creates a discovery message for engine ID discovery.

# decode_message(data, user \\ nil)

    @spec decode_message(binary(), security_user() | nil) ::
      {:ok, v3_message()} | {:error, atom()}

Decodes a SNMPv3 message with security processing.

## Parameters

- `data` - Binary SNMPv3 message data
- `user` - Security user configuration (optional for discovery messages)

## Returns

- `{:ok, message}` on success
- `{:error, reason}` on failure

# encode_message(message, user \\ nil)

    @spec encode_message(v3_message(), security_user() | nil) ::
      {:ok, binary()} | {:error, atom()}

Encodes a SNMPv3 message with security processing.

## Parameters

- `message` - SNMPv3 message structure
- `user` - Security user configuration (optional for discovery messages)

## Returns

- `{:ok, binary()}` on success
- `{:error, reason}` on failure

## Examples

    {:ok, encoded} = encode_message(snmpv3_message, security_user)
    {:ok, discovery_msg} = encode_message(discovery_message, nil)