Search documentation of snmpkit

# SnmpKit.SnmpLib.Security (snmpkit v1.3.17)

SNMPv3 Security Framework - Phase 5.1A Implementation

Provides comprehensive SNMPv3 User Security Model (USM) implementation including authentication and privacy protocols for secure SNMP communications.

## Features

- User Security Model (USM) with complete RFC 3414 compliance
- Authentication Protocols: MD5, SHA-1, SHA-256, SHA-384, SHA-512
- Privacy Protocols: DES, AES-128, AES-192, AES-256
- Key Derivation: Password-based and localized key generation
- Security Parameters: Boot counter, time synchronization, message validation
- Error Handling: Comprehensive security error classification and recovery

## Architecture

The security framework is built on a modular architecture:

- `SnmpKit.SnmpLib.Security.USM` - User Security Model implementation
- `SnmpKit.SnmpLib.Security.Auth` - Authentication protocol handlers
- `SnmpKit.SnmpLib.Security.Priv` - Privacy protocol handlers
- `SnmpKit.SnmpLib.Security.Keys` - Key derivation and management

## Usage Examples

### Basic SNMPv3 Authentication

    # Create authenticated user
    {:ok, user} = SnmpKit.SnmpLib.Security.create_user("admin",
      auth_protocol: :sha256,
      auth_password: "secure_password",
      engine_id: "engine123"
    )

    # Authenticate message
    {:ok, auth_params} = SnmpKit.SnmpLib.Security.authenticate_message(user, message)

### Privacy (Encryption) Support

    # Create user with privacy
    {:ok, user} = SnmpKit.SnmpLib.Security.create_user("secure_admin",
      auth_protocol: :sha256,
      auth_password: "auth_password",
      priv_protocol: :aes256,
      priv_password: "priv_password"
    )

    # Encrypt message
    {:ok, encrypted} = SnmpKit.SnmpLib.Security.encrypt_message(user, message)

### Engine ID Management

    # Generate engine ID
    engine_id = SnmpKit.SnmpLib.Security.generate_engine_id("192.168.1.1")

    # Discover remote engine
    {:ok, remote_engine} = SnmpKit.SnmpLib.Security.discover_engine("10.0.0.1")

## Security Considerations

- All key material is stored securely in memory
- Authentication and privacy keys are derived using RFC-compliant algorithms
- Time-based authentication prevents replay attacks
- Boot counter management ensures message freshness
- Comprehensive input validation prevents security bypasses

# Summary

## Types

auth_protocol()
engine_id()
priv_protocol()
security_level()
security_name()
security_params()
security_user()
user_config()

## Functions

authenticate_message(user, message)

Authenticates an SNMP message using the user's authentication protocol.

build_security_params(user, auth_params \\ <<>>, priv_params \\ <<>>)

Builds security parameters for inclusion in SNMPv3 messages.

create_user(security_name, config)

Creates a new SNMPv3 security user with specified authentication and privacy settings.

decrypt_message(user, ciphertext, priv_params)

Decrypts message data using the user's privacy protocol.

discover_engine(host, opts \\ [])

Discovers the engine ID of a remote SNMP agent.

encrypt_message(user, plaintext)

Encrypts message data using the user's privacy protocol.

generate_engine_id(identifier)

Generates a unique engine ID for an SNMP entity.

get_security_level(user)

Determines the security level for a message based on user configuration.

info()

Returns comprehensive information about security capabilities and status.

update_engine_time(user, engine_boots, engine_time)

Updates engine time and boot counter for time synchronization.

update_user(user, new_config)

Updates security user credentials and regenerates keys.

validate_security_params(user, params)

Validates security parameters from received messages.

validate_user(user, auth_password, priv_password \\ "")

Validates user credentials against stored authentication data.

verify_authentication(user, message, auth_params)

Verifies message authentication using provided authentication parameters.

# Types

# auth_protocol()

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

# engine_id()

    @type engine_id() :: binary()

# priv_protocol()

    @type priv_protocol() :: :none | :des | :aes128 | :aes192 | :aes256

# security_level()

    @type security_level() :: :no_auth_no_priv | :auth_no_priv | :auth_priv

# security_name()

    @type security_name() :: binary()

# security_params()

    @type security_params() :: %{
      authoritative_engine_id: engine_id(),
      authoritative_engine_boots: non_neg_integer(),
      authoritative_engine_time: non_neg_integer(),
      user_name: security_name(),
      authentication_parameters: binary(),
      privacy_parameters: binary()
    }

# security_user()

    @type security_user() :: %{
      security_name: security_name(),
      auth_protocol: auth_protocol(),
      priv_protocol: priv_protocol(),
      auth_key: binary(),
      priv_key: binary(),
      engine_id: engine_id(),
      engine_boots: non_neg_integer(),
      engine_time: non_neg_integer()
    }

# user_config()

    @type user_config() :: [
      auth_protocol: auth_protocol(),
      auth_password: binary(),
      priv_protocol: priv_protocol(),
      priv_password: binary(),
      engine_id: engine_id()
    ]

# Functions

# authenticate_message(user, message)

    @spec authenticate_message(security_user(), binary()) ::
      {:ok, binary()} | {:error, atom()}

Authenticates an SNMP message using the user's authentication protocol.

Returns authentication parameters that should be included in the message.

# build_security_params(user, auth_params \\ <<>>, priv_params \\ <<>>)

    @spec build_security_params(security_user(), binary(), binary()) :: security_params()

Builds security parameters for inclusion in SNMPv3 messages.

# create_user(security_name, config)

    @spec create_user(security_name(), user_config()) ::
      {:ok, security_user()} | {:error, atom()}

Creates a new SNMPv3 security user with specified authentication and privacy settings.

## Parameters

- `security_name`: Unique identifier for the user
- `config`: User configuration including protocols and passwords

## Returns

- `{:ok, user}`: Successfully created security user
- `{:error, reason}`: Creation failed

## Examples

    # Authentication only user
    {:ok, user} = SnmpKit.SnmpLib.Security.create_user("monitor_user",
      auth_protocol: :sha256,
      auth_password: "monitoring_secret",
      engine_id: "local_engine"
    )

    # Full authentication and privacy user
    {:ok, admin} = SnmpKit.SnmpLib.Security.create_user("admin_user",
      auth_protocol: :sha512,
      auth_password: "admin_auth_pass",
      priv_protocol: :aes256,
      priv_password: "admin_priv_pass",
      engine_id: "management_engine"
    )

# decrypt_message(user, ciphertext, priv_params)

    @spec decrypt_message(security_user(), binary(), binary()) ::
      {:ok, binary()} | {:error, atom()}

Decrypts message data using the user's privacy protocol.

# discover_engine(host, opts \\ [])

    @spec discover_engine(
      binary(),
      keyword()
    ) :: {:ok, engine_id()} | {:error, atom()}

Discovers the engine ID of a remote SNMP agent.

This is typically done during the first communication with a remote agent to establish security context.

# encrypt_message(user, plaintext)

    @spec encrypt_message(security_user(), binary()) ::
      {:ok, {binary(), binary()}} | {:error, atom()}

Encrypts message data using the user's privacy protocol.

# generate_engine_id(identifier)

    @spec generate_engine_id(binary()) :: engine_id()

Generates a unique engine ID for an SNMP entity.

Engine IDs are used to uniquely identify SNMP engines and are required for SNMPv3 security operations.

# get_security_level(user)

    @spec get_security_level(security_user()) :: security_level()

Determines the security level for a message based on user configuration.

## Security Levels

- `:no_auth_no_priv` - No authentication, no privacy
- `:auth_no_priv` - Authentication only
- `:auth_priv` - Authentication and privacy

# info()

    @spec info() :: map()

Returns comprehensive information about security capabilities and status.

# update_engine_time(user, engine_boots, engine_time)

    @spec update_engine_time(security_user(), non_neg_integer(), non_neg_integer()) ::
      security_user()

Updates engine time and boot counter for time synchronization.

# update_user(user, new_config)

    @spec update_user(security_user(), user_config()) ::
      {:ok, security_user()} | {:error, atom()}

Updates security user credentials and regenerates keys.

# validate_security_params(user, params)

    @spec validate_security_params(security_user(), security_params()) ::
      :ok | {:error, atom()}

Validates security parameters from received messages.

# validate_user(user, auth_password, priv_password \\ "")

    @spec validate_user(security_user(), binary(), binary()) :: :ok | {:error, atom()}

Validates user credentials against stored authentication data.

# verify_authentication(user, message, auth_params)

    @spec verify_authentication(security_user(), binary(), binary()) ::
      :ok | {:error, atom()}

Verifies message authentication using provided authentication parameters.