Search documentation of snmpkit

# SnmpKit.SnmpLib.Security.Auth (snmpkit v1.2.0)

Authentication protocols for SNMPv3 User Security Model.

Implements HMAC-based authentication protocols as specified in RFC 3414 and RFC 7860, providing message integrity and authentication for SNMPv3 communications.

## Supported Protocols

- HMAC-MD5 (RFC 3414) - 16-byte digest, legacy support
- HMAC-SHA-1 (RFC 3414) - 20-byte digest, legacy support
- HMAC-SHA-224 (RFC 7860) - 28-byte digest
- HMAC-SHA-256 (RFC 7860) - 32-byte digest, recommended
- HMAC-SHA-384 (RFC 7860) - 48-byte digest
- HMAC-SHA-512 (RFC 7860) - 64-byte digest, highest security

## Security Considerations

- MD5 and SHA-1 are deprecated for new implementations
- SHA-256 or higher is recommended for production use
- Authentication keys must be properly derived using key derivation functions
- Truncated MACs maintain security properties when properly implemented

## Protocol Selection Guidelines

- SHA-256: Recommended for most deployments (good security/performance balance)
- SHA-512: High security environments with adequate processing power
- SHA-384: Alternative to SHA-512 with smaller digest size
- MD5/SHA-1: Legacy compatibility only, not recommended for new deployments

## Usage Examples

### Message Authentication

    # Authenticate outgoing message
    auth_key = derived_authentication_key
    message = snmp_message_data
    {:ok, auth_params} = SnmpKit.SnmpLib.Security.Auth.authenticate(:sha256, auth_key, message)

    # Verify incoming message
    :ok = SnmpKit.SnmpLib.Security.Auth.verify(:sha256, auth_key, message, auth_params)

### Protocol Capabilities

    # Get protocol information
    info = SnmpKit.SnmpLib.Security.Auth.protocol_info(:sha256)
    # Returns: %{digest_size: 32, truncated_size: 12, secure: true, ...}

    # List all supported protocols
    protocols = SnmpKit.SnmpLib.Security.Auth.supported_protocols()

# Summary

## Types

auth_key()
auth_params()
auth_protocol()
message_data()

## Functions

authenticate(protocol, auth_key, message)

Authenticates a message using the specified protocol and key.

authenticate_batch(protocol, auth_key, messages)

Authenticates multiple messages using the same protocol and key.

benchmark_protocol(protocol, auth_key, test_message, iterations \\ 1000)

Measures authentication performance for a given protocol.

protocol_info(protocol)

Returns information about a specific authentication protocol.

secure_protocol?(protocol)

Checks if a protocol is considered cryptographically secure.

secure_protocols()

Returns list of cryptographically secure protocols (excludes deprecated ones).

supported_protocols()

Returns list of all supported authentication protocols.

validate_key(protocol, key)

Validates that an authentication key is appropriate for the specified protocol.

verify(protocol, auth_key, message, provided_params)

Verifies message authentication using provided authentication parameters.

verify_batch(protocol, auth_key, messages, auth_params_list)

Verifies authentication for multiple messages in batch.

# Types

# auth_key()

    @type auth_key() :: binary()

# auth_params()

    @type auth_params() :: binary()

# auth_protocol()

    @type auth_protocol() :: :none | :md5 | :sha1 | :sha224 | :sha256 | :sha384 | :sha512

# message_data()

    @type message_data() :: binary()

# Functions

# authenticate(protocol, auth_key, message)

    @spec authenticate(auth_protocol(), auth_key(), message_data()) ::
      {:ok, auth_params()} | {:error, atom()}

Authenticates a message using the specified protocol and key.

Generates authentication parameters (truncated HMAC) for inclusion in the SNMPv3 message security parameters.

## Parameters

- `protocol`: Authentication protocol to use
- `auth_key`: Localized authentication key (derived from password)
- `message`: Complete message data to authenticate

## Returns

- `{:ok, auth_params}`: Authentication parameters for message
- `{:error, reason}`: Authentication failed

## Examples

    # SHA-256 authentication (recommended)
    {:ok, auth_params} = SnmpKit.SnmpLib.Security.Auth.authenticate(:sha256, auth_key, message)

    # Legacy MD5 authentication
    {:ok, auth_params} = SnmpKit.SnmpLib.Security.Auth.authenticate(:md5, auth_key, message)

# authenticate_batch(protocol, auth_key, messages)

    @spec authenticate_batch(auth_protocol(), auth_key(), [message_data()]) ::
      {:ok, [auth_params()]} | {:error, atom()}

Authenticates multiple messages using the same protocol and key.

More efficient than individual authentication calls when processing multiple messages with the same authentication configuration.

## Examples

    messages = [msg1, msg2, msg3]
    {:ok, auth_params_list} = SnmpKit.SnmpLib.Security.Auth.authenticate_batch(:sha256, auth_key, messages)

# benchmark_protocol(protocol, auth_key, test_message, iterations \\ 1000)

    @spec benchmark_protocol(auth_protocol(), auth_key(), message_data(), pos_integer()) ::
      map()

Measures authentication performance for a given protocol.

Useful for performance tuning and protocol selection in high-throughput environments.

## Examples

    stats = SnmpKit.SnmpLib.Security.Auth.benchmark_protocol(:sha256, test_key, test_message, 1000)
    # Returns timing and throughput statistics

# protocol_info(protocol)

    @spec protocol_info(auth_protocol()) :: map() | nil

Returns information about a specific authentication protocol.

## Examples

    iex> SnmpKit.SnmpLib.Security.Auth.protocol_info(:sha256)
    %{algorithm: :sha256, digest_size: 32, truncated_size: 16, secure: true, rfc: "RFC 7860"}

    iex> SnmpKit.SnmpLib.Security.Auth.protocol_info(:md5)
    %{algorithm: :md5, digest_size: 16, truncated_size: 12, secure: false, rfc: "RFC 3414"}

# secure_protocol?(protocol)

    @spec secure_protocol?(auth_protocol()) :: boolean()

Checks if a protocol is considered cryptographically secure.

## Examples

    iex> SnmpKit.SnmpLib.Security.Auth.secure_protocol?(:sha256)
    true

    iex> SnmpKit.SnmpLib.Security.Auth.secure_protocol?(:md5)
    false

# secure_protocols()

    @spec secure_protocols() :: [auth_protocol()]

Returns list of cryptographically secure protocols (excludes deprecated ones).

## Examples

    iex> SnmpKit.SnmpLib.Security.Auth.secure_protocols()
    [:sha224, :sha256, :sha384, :sha512]

# supported_protocols()

    @spec supported_protocols() :: [auth_protocol()]

Returns list of all supported authentication protocols.

## Examples

    iex> SnmpKit.SnmpLib.Security.Auth.supported_protocols()
    [:none, :md5, :sha1, :sha224, :sha256, :sha384, :sha512]

# validate_key(protocol, key)

    @spec validate_key(auth_protocol(), auth_key()) :: :ok | {:error, atom()}

Validates that an authentication key is appropriate for the specified protocol.

Checks key length requirements and provides warnings for weak protocols.

## Examples

    :ok = SnmpKit.SnmpLib.Security.Auth.validate_key(:sha256, auth_key)
    {:error, :key_too_short} = SnmpKit.SnmpLib.Security.Auth.validate_key(:sha512, short_key)

# verify(protocol, auth_key, message, provided_params)

    @spec verify(auth_protocol(), auth_key(), message_data(), auth_params()) ::
      :ok | {:error, atom()}

Verifies message authentication using provided authentication parameters.

Recomputes the expected authentication parameters and compares them with the provided parameters using constant-time comparison.

## Parameters

- `protocol`: Authentication protocol used
- `auth_key`: Localized authentication key
- `message`: Message data that was authenticated
- `provided_params`: Authentication parameters from received message

## Returns

- `:ok`: Authentication verification successful
- `{:error, reason}`: Verification failed

## Examples

    # Verify SHA-256 authentication
    :ok = SnmpKit.SnmpLib.Security.Auth.verify(:sha256, auth_key, message, auth_params)

    # Failed verification
    {:error, :authentication_mismatch} = SnmpKit.SnmpLib.Security.Auth.verify(:md5, wrong_key, message, auth_params)

# verify_batch(protocol, auth_key, messages, auth_params_list)

    @spec verify_batch(auth_protocol(), auth_key(), [message_data()], [auth_params()]) ::
      [
        :ok | {:error, atom()}
      ]

Verifies authentication for multiple messages in batch.

## Examples

    results = SnmpKit.SnmpLib.Security.Auth.verify_batch(:sha256, auth_key, messages, auth_params_list)
    # Returns: [:ok, :ok, {:error, :authentication_mismatch}]