SnmpKit.SnmpLib.Security.Auth (snmpkit v2.0.1)

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

auth_params_size(protocol)

Length in octets of msgAuthenticationParameters for a protocol.

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.

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.

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

auth_params_size(protocol)

@spec auth_params_size(auth_protocol()) :: non_neg_integer()

Length in octets of msgAuthenticationParameters for a protocol.

This is the truncated HMAC size (RFC 3414 6.3.1 / 7.3.1, RFC 7860 4.2) and also the size of the zero placeholder that must occupy the field while the MAC is computed.

iex> SnmpKit.SnmpLib.Security.Auth.auth_params_size(:sha256)
24
iex> SnmpKit.SnmpLib.Security.Auth.auth_params_size(:none)
0

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)

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: 24, max_key_size: 64, secure: true, rfc: "RFC 7860"}

iex> SnmpKit.SnmpLib.Security.Auth.protocol_info(:md5)
%{algorithm: :md5, digest_size: 16, truncated_size: 12, max_key_size: 64, 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)