Crate snmp_usm

Implementation of the User-based Security Model (USM) for SNMPv3

SNMP USM provides SNMP message level security according to RFC 3414 and RFC 3826. It implements primitives that can be used by a security subsystem.

Implemented features of USM:

• HMAC-MD5-96 Authentication Protocol
• HMAC-SHA-96 Authentication Protocol
• Timeliness verification
• DES encryption
• AES encryption

Authentication and Privacy

When privacy is used with authentication, the privacy key must use the same message-digest algorithm as the authentication key. As an example, if the AuthKey is constructed with a LocalizedKey specialized with the MD5 message-digest algorithm, then the PrivKey must be constructed with a LocalizedKey specialized with the MD5 message-digest algorithm.

Authentication and time synchronization

If authenticated communication is required, then the discovery process should also establish time synchronization with the authoritative SNMP engine. This may be accomplished by sending an authenticated Request message with the value of msgAuthoritativeEngineID set to the previously learned snmpEngineID and with the values of msgAuthoritativeEngineBoots and msgAuthoritativeEngineTime set to zero.

Examples

A fictional message processing subsystem is used to clarify the examples.

use snmp_usm::{
    Aes128PrivKey, AuthKey, LocalizedMd5Key, PrivKey, SecurityParams, WithLocalizedKey
};

// The password and engine ID are supplied by the security subsystem.
let localized_key = LocalizedMd5Key::new(&passwd, &engine_id);

let priv_key = Aes128PrivKey::with_localized_key(localized_key.clone());
// The security parameters are constructed from the local authoritative engine data.
let (encrypted_scoped_pdu, salt) = priv_key.encrypt(scoped_pdu, &security_params, 0);

// The message processing service would set the encrypted scoped PDU for the outgoing message.
// out_msg.set_encrypted_scoped_pdu(encrypted_scoped_pdu);

security_params
    .set_username(b"username")
    .set_priv_params(&salt)
    .set_auth_params_placeholder();
let encoded_security_params = security_params.encode();

// The message processing service would set the security parameters of the outgoing message and
// encode it.
// out_msg.set_security_params(&encoded_security_params);
// let out_msg = out_msg.encode();

let auth_key = AuthKey::new(localized_key);

// Authenticate the outgoing message.
auth_key.auth_out_msg(&mut out_msg)?;

// Authenticate an incoming message.
auth_key.auth_in_msg(&mut in_msg, local_engine_id, local_engine_boots, local_engine_time)?;

Structs

Aes128PrivKey	Privacy key used for AES-128 encryption.
AuthKey	Authentication key used to check data integrity and data origin.
DesPrivKey	Privacy key used for DES encryption.
LocalizedKey	Localized key used to verify the identity of users, verify the integrity of messages and encrypt messages.
Md5	The MD5 hasher
SecurityParams	Security parameters used by the User-based Security Model.
Sha1	Structure representing the state of a SHA-1 computation

Enums

SecurityError

The error type for security related operations.

Traits

Digest	Convenience wrapper around Update, BlockInput, FixedOutput, Reset, Default, and Clone traits. Useful as trait bound where a digest algorithm is needed.
PrivKey	A trait for privacy keys.
WithLocalizedKey	Trait implemented by types created with a localized key.

Type Definitions

LocalizedMd5Key	Type alias for a localized key specialized with the MD5 message-digest algorithm.
LocalizedSha1Key	Type alias for a localized key specialized with the SHA-1 message-digest algorithm.
Md5AuthKey	Type alias for an authentication key specialized with the MD5 message-digest algorithm.
SecurityResult	Type alias for the result of a security operation.
Sha1AuthKey	Type alias for an authentication key specialized with SHA-1 message-digest algorithm.