puresnmp_plugins.security.usm module

This module implements the SNMPv3 “User Security Model” as defined in RFC 3414

exception puresnmp_plugins.security.usm.AuthenticationError

Bases: USMError

This error is raised whenever something goes wrong during authentication

exception puresnmp_plugins.security.usm.DecryptionError

Bases: USMError

This error is raised whenever something goes wrong during decryption

class puresnmp_plugins.security.usm.DiscoData(authoritative_engine_id: bytes, authoritative_engine_boots: int, authoritative_engine_time: int, unknown_engine_ids: int)

Bases: object

Helper class to wrap data received from a SNMPv3 discovery message.

authoritative_engine_boots: int

The number of boots of the remote device (encryption timeliness)

authoritative_engine_id: bytes

The engine-id of the remote device

authoritative_engine_time: int

The time-ticks since last boot of the remote device (encryption timeliness)

unknown_engine_ids: int

The number of requests received with an unknown client-engine-id

exception puresnmp_plugins.security.usm.EncryptionError

Bases: USMError

This error is raised whenever something goes wrong during encryption

exception puresnmp_plugins.security.usm.USMError

Bases: SnmpError

Generic exception for errors cased by the USM module

class puresnmp_plugins.security.usm.USMSecurityParameters(authoritative_engine_id: bytes, authoritative_engine_boots: int, authoritative_engine_time: int, user_name: bytes, auth_params: bytes, priv_params: bytes)

Bases: object

This class wraps the various values for the USM

as_snmp_type() → Sequence

Convert this instance into a plain SNMP (x690) object.

auth_params: bytes
authoritative_engine_boots: int
authoritative_engine_id: bytes
authoritative_engine_time: int
static decode(data: bytes) → USMSecurityParameters

Construct a USMSecurityParameters instance from pure bytes

static from_snmp_type(seq: Sequence) → USMSecurityParameters

Construct a USMSecurityParameters instance from an SNMP/X690 Sequence

pretty(depth: int = 0) → str

Return a value for CLI display

priv_params: bytes
user_name: bytes
exception puresnmp_plugins.security.usm.UnknownUser

Bases: USMError

This error is raised when a message is processed that is not consistent with the user-name passed in the credentials.

exception puresnmp_plugins.security.usm.UnsupportedSecurityLevel

Bases: USMError

This error is raised when the data included in the credentials is invalid or incomplete.

class puresnmp_plugins.security.usm.UserSecurityModel

Bases: SecurityModel[PlainMessage, PlainMessage | EncryptedMessage]

Implementation of the use-security model as defined by puresnmp.security.SecurityModel

generate_request_message(message: PlainMessage, security_engine_id: bytes, credentials: Credentials) → PlainMessage | EncryptedMessage

Take a plain unprocessed message and applies security to the message as defined by the concrete security model.

It returns the processed message including security modifications. Further processing is provided by the “message-processing-model” to prepare it for sending out to the network.

The kind of processing applied to the message depends on the credential type.

Parameters:

  • message – The original message

  • security_engine_id – The engine-id of the receiving SNMP engine

  • credentials – A credential object giving information on what kind of operations are needed on the message.

process_incoming_message(message: PlainMessage | EncryptedMessage, credentials: Credentials) → PlainMessage

Takes a message which included potential security modifications (like encryption) and “undoes” these modifications in order to make the message usable again.

Returns an unprocessed message.

The kind of processing applied to the message depends on the credential type.

Parameters:

  • message – The original message

  • credentials – A credential object giving information on what kind of operations are needed on the message.

async send_discovery_message(transport_handler: Callable[[bytes], Awaitable[bytes]]) → DiscoData

Send a discovery message to the remote engine.

Parameters:

handler – A callable that is responsible to send data to the remote engine. This callable should already be aware of how to connect. It takes the bytes to be sent to the remote and should return the response bytes without any processing.

set_engine_timing(engine_id: bytes, engine_boots: int, engine_time: int) → None

Update the security model with timing information of the remote-engine.

The timing information is required by SNMPv3 to authenticat/encrypt messages.boots

puresnmp_plugins.security.usm.apply_authentication(unauthed_message: PlainMessage | EncryptedMessage, credentials: V3, security_engine_id: bytes) → PlainMessage | EncryptedMessage

Add authentication-information to an SNMPv3 message

Parameters:

  • unauthed_message – Either an encrypted or plain message that we want to update with authentication information.

  • credentials – The user-credentials

  • security_engine_id – The engine-id of the remote device

Returns:

A message (of the same type) with authentication information added to and security_parameters of the message.

puresnmp_plugins.security.usm.apply_encryption(message: PlainMessage, credentials: V3, security_name: bytes, security_engine_id: bytes, engine_boots: int, engine_time: int) → PlainMessage | EncryptedMessage

Derive a new encrypted message from a plain message given user-credentials and target-engine information.

Parameters:

  • message – The unencrypted message

  • credentials – The SNMPv3 credentials to be applied to the message

  • security_name – The username used in the request

  • security_engine_id – The engine-id of the remote device

  • engine_boots – Encryption timeliness data as received from the discovery process

  • engine_time – Encryption timeliness data as received from the discovery process

Returns:

Either an encrypted message, or a plain-message (depending on credential type)

puresnmp_plugins.security.usm.create() → UserSecurityModel

Creates a new instance of the USM

puresnmp_plugins.security.usm.decrypt_message(message: PlainMessage | EncryptedMessage, credentials: V3) → PlainMessage

Decrypt a message using the given credentials

puresnmp_plugins.security.usm.reset_digest(message: Message) → Message

Replace the current message-digest in a message with zeroes.

As the digest is embedded inside the message, it needs to be zeroed out when deriving the digest from a message. Otherwise the digest of the same message would change, because the digest changes.

Parameters:

message – The message (with or without digest)

Returns:

A new message with zeroed digest

puresnmp_plugins.security.usm.validate_usm_message(message: PlainMessage) → None

If the message contains known error-indicators, raise an appropriate exception.

Raises:

SnmpError – If an error was found

puresnmp_plugins.security.usm.verify_authentication(message: Message, credentials: V3, security_params: USMSecurityParameters) → None

Verify authenticity of the message using the credentials.

Raises:

AuthenticationError – If the message is not authentic