SnmpKit.SnmpLib.Security.Priv (snmpkit v0.5.0)

Privacy (encryption) protocols for SNMPv3 User Security Model.

Implements encryption protocols as specified in RFC 3414 and RFC 3826, providing message confidentiality for SNMPv3 communications.

Supported Protocols

DES-CBC (RFC 3414) - 56-bit key, legacy support
AES-128 (RFC 3826) - 128-bit key, good security
AES-192 (RFC 3826) - 192-bit key, enhanced security
AES-256 (RFC 3826) - 256-bit key, maximum security

Security Considerations

DES is deprecated and should only be used for legacy compatibility
AES-128 provides adequate security for most applications
AES-256 is recommended for high-security environments
All encryption uses CBC mode with random initialization vectors
Privacy requires authentication (cannot use privacy without authentication)

Protocol Selection Guidelines

AES-256: Recommended for high-security environments
AES-128: Good balance of security and performance for most deployments
DES: Legacy compatibility only, not recommended for new deployments

Technical Details

Key Derivation

Privacy keys are derived from privacy passwords using the same engine ID and algorithm as authentication keys, but with different key usage.

Initialization Vectors

Each encryption operation uses a unique initialization vector (IV) to ensure that identical plaintexts produce different ciphertexts.

Padding

Block ciphers use PKCS#7 padding to handle messages that don't align with block boundaries.

Usage Examples

Message Encryption

# Encrypt message with AES-256
priv_key = derived_privacy_key
auth_key = derived_authentication_key  # Required for IV generation
plaintext = "confidential SNMP data"

{:ok, {ciphertext, priv_params}} = SnmpKit.SnmpLib.Security.Priv.encrypt(
  :aes256, priv_key, auth_key, plaintext
)

# Decrypt message
{:ok, decrypted} = SnmpKit.SnmpLib.Security.Priv.decrypt(
  :aes256, priv_key, auth_key, ciphertext, priv_params
)

Protocol Information

# Get encryption protocol details
info = SnmpKit.SnmpLib.Security.Priv.protocol_info(:aes256)
# Returns: %{algorithm: :aes_256_cbc, key_size: 32, block_size: 16, ...}

Summary

Types

auth_key()

ciphertext()

initialization_vector()

plaintext()

priv_key()

priv_params()

priv_protocol()

Functions

benchmark_protocol(protocol, priv_key, auth_key, test_plaintext, iterations \\ 1000)

Measures encryption/decryption performance for a given protocol.

decrypt(protocol, priv_key, auth_key, ciphertext, priv_params)

Decrypts ciphertext using the specified privacy protocol.

decrypt_batch(protocol, priv_key, auth_key, encrypted_list)

Decrypts multiple ciphertexts in batch.

encrypt(protocol, priv_key, auth_key, plaintext)

Encrypts plaintext using the specified privacy protocol.

encrypt_batch(protocol, priv_key, auth_key, plaintexts)

Encrypts multiple plaintexts using the same protocol and key.

protocol_info(protocol)

Returns information about a specific privacy 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 privacy protocols.

validate_key(protocol, key)

Validates that a privacy key is appropriate for the specified protocol.

Types

auth_key()

@type auth_key() :: binary()

ciphertext()

@type ciphertext() :: binary()

initialization_vector()

@type initialization_vector() :: binary()

plaintext()

@type plaintext() :: binary()

priv_key()

@type priv_key() :: binary()

priv_params()

@type priv_params() :: binary()

priv_protocol()

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

Functions

benchmark_protocol(protocol, priv_key, auth_key, test_plaintext, iterations \\ 1000)

@spec benchmark_protocol(
  priv_protocol(),
  priv_key(),
  auth_key(),
  plaintext(),
  pos_integer()
) :: map()

Measures encryption/decryption performance for a given protocol.

decrypt(protocol, priv_key, auth_key, ciphertext, priv_params)

@spec decrypt(priv_protocol(), priv_key(), auth_key(), ciphertext(), priv_params()) ::
  {:ok, plaintext()} | {:error, atom()}

Decrypts ciphertext using the specified privacy protocol.

Parameters

protocol: Privacy protocol used for encryption
priv_key: Privacy key (same as used for encryption)
auth_key: Authentication key (used for IV validation)
ciphertext: Encrypted data
priv_params: Privacy parameters from encryption (contains IV)

Returns

{:ok, plaintext}: Decryption successful
{:error, reason}: Decryption failed

Examples

# AES-256 decryption
{:ok, plaintext} = SnmpKit.SnmpLib.Security.Priv.decrypt(
  :aes256, priv_key, auth_key, ciphertext, priv_params
)

# Handle decryption errors
case SnmpKit.SnmpLib.Security.Priv.decrypt(:des, priv_key, auth_key, ciphertext, priv_params) do
  {:ok, plaintext} -> process_plaintext(plaintext)
  {:error, :decryption_failed} -> handle_corruption()
  {:error, :invalid_padding} -> handle_padding_error()
end

decrypt_batch(protocol, priv_key, auth_key, encrypted_list)

@spec decrypt_batch(priv_protocol(), priv_key(), auth_key(), [
  {ciphertext(), priv_params()}
]) :: [
  :ok | {:error, atom()}
]

Decrypts multiple ciphertexts in batch.

encrypt(protocol, priv_key, auth_key, plaintext)

@spec encrypt(priv_protocol(), priv_key(), auth_key(), plaintext()) ::
  {:ok, {ciphertext(), priv_params()}} | {:error, atom()}

Encrypts plaintext using the specified privacy protocol.

Parameters

protocol: Privacy protocol to use (:des, :aes128, :aes192, :aes256)
priv_key: Privacy key (must be correct length for protocol)
auth_key: Authentication key (used for IV generation in some protocols)
plaintext: Data to encrypt

Returns

{:ok, {ciphertext, priv_params}}: Encryption successful
{:error, reason}: Encryption failed

Examples

# AES-256 encryption (recommended)
{:ok, {ciphertext, priv_params}} = SnmpKit.SnmpLib.Security.Priv.encrypt(
  :aes256, priv_key, auth_key, "secret data"
)

# DES encryption (legacy)
{:ok, {ciphertext, priv_params}} = SnmpKit.SnmpLib.Security.Priv.encrypt(
  :des, priv_key, auth_key, "legacy data"
)

encrypt_batch(protocol, priv_key, auth_key, plaintexts)

@spec encrypt_batch(priv_protocol(), priv_key(), auth_key(), [plaintext()]) ::
  {:ok, [{ciphertext(), priv_params()}]} | {:error, atom()}

Encrypts multiple plaintexts using the same protocol and key.

Each plaintext gets a unique IV, ensuring security even for identical plaintexts.

Examples

plaintexts = ["data1", "data2", "data3"]
{:ok, encrypted_list} = SnmpKit.SnmpLib.Security.Priv.encrypt_batch(:aes256, priv_key, auth_key, plaintexts)
# Returns list of {ciphertext, priv_params} tuples

protocol_info(protocol)

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

Returns information about a specific privacy protocol.

Examples

iex> SnmpKit.SnmpLib.Security.Priv.protocol_info(:aes256)
%{algorithm: :aes_256_cbc, key_size: 32, block_size: 16, iv_size: 16, secure: true, rfc: "RFC 3826"}

iex> SnmpKit.SnmpLib.Security.Priv.protocol_info(:des)
%{algorithm: :des_cbc, key_size: 8, block_size: 8, iv_size: 8, secure: false, rfc: "RFC 3414"}

secure_protocol?(protocol)

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

Checks if a protocol is considered cryptographically secure.

secure_protocols()

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

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

supported_protocols()

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

Returns list of all supported privacy protocols.

validate_key(protocol, key)

@spec validate_key(priv_protocol(), priv_key()) :: :ok | {:error, atom()}

Validates that a privacy key is appropriate for the specified protocol.

Examples

:ok = SnmpKit.SnmpLib.Security.Priv.validate_key(:aes256, key_32_bytes)
{:error, :key_wrong_size} = SnmpKit.SnmpLib.Security.Priv.validate_key(:aes128, key_32_bytes)