@spec derive_auth_key(auth_protocol(), password(), engine_id()) ::
  {:ok, derived_key()} | {:error, atom()}

Derives authentication key from password and engine ID.

Implements RFC 3414 key localization algorithm for authentication protocols. The derived key is specific to the combination of password, protocol, and engine ID.

Parameters

• protocol: Authentication protocol (:md5, :sha1, :sha256, etc.)
• password: User password (minimum 8 characters recommended)
• engine_id: Authoritative engine ID (5-32 bytes)

Returns

• {:ok, key}: Successfully derived authentication key
• {:error, reason}: Key derivation failed

Examples

# SHA-256 authentication key (recommended)
{:ok, key} = SnmpKit.SnmpLib.Security.Keys.derive_auth_key(
  :sha256, "my_secure_password", engine_id
)

# Legacy MD5 key derivation
{:ok, key} = SnmpKit.SnmpLib.Security.Keys.derive_auth_key(
  :md5, "legacy_password", engine_id
)

@spec derive_auth_keys_multi([auth_protocol()], password(), engine_id()) ::
  {:ok, %{required(auth_protocol()) => derived_key()}} | {:error, atom()}

Derives multiple authentication keys for different protocols from the same password.

Useful when supporting multiple authentication protocols simultaneously.

Examples

protocols = [:sha256, :sha384, :sha512]
{:ok, keys} = SnmpKit.SnmpLib.Security.Keys.derive_auth_keys_multi(protocols, password, engine_id)
# Returns: %{sha256: key1, sha384: key2, sha512: key3}

@spec derive_priv_key(priv_protocol(), password(), engine_id()) ::
  {:ok, derived_key()} | {:error, atom()}

Derives privacy key from password and engine ID.

Privacy keys are derived using a combination of authentication key derivation and protocol-specific key expansion techniques.

Parameters

• protocol: Privacy protocol (:des, :aes128, :aes192, :aes256)
• password: User password for privacy
• engine_id: Authoritative engine ID

Returns

• {:ok, key}: Successfully derived privacy key
• {:error, reason}: Key derivation failed

Examples

# AES-256 privacy key (recommended)
{:ok, key} = SnmpKit.SnmpLib.Security.Keys.derive_priv_key(
  :aes256, "privacy_password", engine_id
)

# DES privacy key (legacy)
{:ok, key} = SnmpKit.SnmpLib.Security.Keys.derive_priv_key(
  :des, "legacy_privacy_password", engine_id
)

@spec derive_priv_key_from_auth(priv_protocol(), derived_key(), engine_id()) ::
  {:ok, derived_key()} | {:error, atom()}

Derives privacy key from an existing authentication key.

More efficient when both authentication and privacy keys are needed, as it avoids repeating the expensive key localization process.

Examples

# First derive authentication key
{:ok, auth_key} = derive_auth_key(:sha256, password, engine_id)

# Then derive privacy key from auth key
{:ok, priv_key} = SnmpKit.SnmpLib.Security.Keys.derive_priv_key_from_auth(
  :aes256, auth_key, engine_id
)

@spec export_key(derived_key(), auth_protocol() | priv_protocol(), engine_id()) ::
  map()

Exports derived key in a secure format for storage or transmission.

The exported format includes metadata for proper key reconstruction while maintaining security properties.

@spec generate_secure_password(pos_integer()) :: password()

Generates a cryptographically secure random password.

Examples

password = SnmpKit.SnmpLib.Security.Keys.generate_secure_password(16)
# Returns: "K7mN9pQ2rT8vW3xZ" (example)

@spec secure_compare(derived_key(), derived_key()) :: boolean()

Securely compares two derived keys to prevent timing attacks.

Examples

true = SnmpKit.SnmpLib.Security.Keys.secure_compare(key1, key1)
false = SnmpKit.SnmpLib.Security.Keys.secure_compare(key1, key2)

@spec secure_wipe(derived_key()) :: :ok

Securely wipes sensitive key material from memory.

Note: This provides best-effort memory clearing but cannot guarantee complete removal due to Erlang VM memory management.

@spec validate_imported_key(derived_key(), map()) :: :ok | {:error, atom()}

Validates imported key against expected parameters.

@spec validate_password_strength(password()) ::
  :ok | {:error, atom()} | {:warning, atom()}

Validates password strength according to SNMPv3 security guidelines.

Requirements

• Minimum 8 characters (RFC recommendation)
• Should contain mix of character types for security
• Should not be based on dictionary words

Examples

:ok = SnmpKit.SnmpLib.Security.Keys.validate_password_strength("strong_password_123")
{:error, :too_short} = SnmpKit.SnmpLib.Security.Keys.validate_password_strength("weak")
{:warning, :weak_complexity} = SnmpKit.SnmpLib.Security.Keys.validate_password_strength("password")