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
Functions
Measures encryption/decryption performance for a given protocol.
Decrypts ciphertext using the specified privacy protocol.
Decrypts multiple ciphertexts in batch.
Encrypts plaintext using the specified privacy protocol.
Encrypts multiple plaintexts using the same protocol and key.
Returns information about a specific privacy protocol.
Checks if a protocol is considered cryptographically secure.
Returns list of cryptographically secure protocols (excludes deprecated ones).
Returns list of all supported privacy protocols.
Validates that a privacy key is appropriate for the specified protocol.
Types
Functions
@spec benchmark_protocol( priv_protocol(), priv_key(), auth_key(), plaintext(), pos_integer() ) :: map()
Measures encryption/decryption performance for a given protocol.
@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 encryptionpriv_key: Privacy key (same as used for encryption)auth_key: Authentication key (used for IV validation)ciphertext: Encrypted datapriv_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@spec decrypt_batch(priv_protocol(), priv_key(), auth_key(), [ {ciphertext(), priv_params()} ]) :: [ :ok | {:error, atom()} ]
Decrypts multiple ciphertexts in batch.
@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"
)@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@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"}@spec secure_protocol?(priv_protocol()) :: boolean()
Checks if a protocol is considered cryptographically secure.
@spec secure_protocols() :: [priv_protocol()]
Returns list of cryptographically secure protocols (excludes deprecated ones).
@spec supported_protocols() :: [priv_protocol()]
Returns list of all supported privacy protocols.
@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)