@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)

@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)

@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

@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"}

@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

@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]

@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]

@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)

@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)

@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}]