Skip to main content

2.5. Services provided by the User-based Security Model

2.5. Services provided by the User-based Security Model​

This section describes the services provided by the User-based Security Model with their inputs and outputs.

The services are described as primitives of an abstract service interface and the inputs and outputs are described as abstract data elements as they are passed in these abstract service primitives.

2.5.1. Services for Generating an Outgoing SNMP Message​

When the Message Processing (MP) Subsystem invokes the User-based Security module to secure an outgoing SNMP message, it must use the appropriate service as provided by the Security module. These two services are provided:

1) Service to Generate a Request Message​

The abstract service primitive is:

statusInformation =            -- success or errorIndication
  generateRequestMsg(
  IN   messageProcessingModel  -- typically, SNMP version
  IN   globalData              -- message header, admin data
  IN   maxMessageSize          -- of the sending SNMP entity
  IN   securityModel           -- for the outgoing message
  IN   securityEngineID        -- authoritative SNMP entity
  IN   securityName            -- on behalf of this principal
  IN   securityLevel           -- Level of Security requested
  IN   scopedPDU               -- message (plaintext) payload
  OUT  securityParameters      -- filled in by Security Module
  OUT  wholeMsg                -- complete generated message
  OUT  wholeMsgLength          -- length of generated message
       )

2) Service to Generate a Response Message​

The abstract service primitive is:

statusInformation =            -- success or errorIndication
  generateResponseMsg(
  IN   messageProcessingModel  -- typically, SNMP version
  IN   globalData              -- message header, admin data
  IN   maxMessageSize          -- of the sending SNMP entity
  IN   securityModel           -- for the outgoing message
  IN   securityEngineID        -- authoritative SNMP entity
  IN   securityName            -- on behalf of this principal
  IN   securityLevel           -- Level of Security requested
  IN   scopedPDU               -- message (plaintext) payload
  IN   securityStateReference  -- reference to security state
                               -- information from original
                               -- request
  OUT  securityParameters      -- filled in by Security Module
  OUT  wholeMsg                -- complete generated message
  OUT  wholeMsgLength          -- length of generated message
       )

Abstract Data Elements​

The abstract data elements passed as parameters in the abstract service primitives are as follows:

statusInformation​

An indication of whether the encoding and securing of the message was successful. If not it is an indication of the problem.

messageProcessingModel​

The SNMP version number for the message to be generated. This data is not used by the User-based Security module.

globalData​

The message header (i.e., its administrative information). This data is not used by the User-based Security module.

maxMessageSize​

The maximum message size as included in the message. This data is not used by the User-based Security module.

securityParameters​

These are the security parameters. They will be filled in by the User-based Security module.

securityModel​

The securityModel in use. Should be User-based Security Model. This data is not used by the User-based Security module.

securityEngineID​

The snmpEngineID of the authoritative SNMP engine. When creating a Request message, this could be a zero-length OCTET STRING if the securityEngineID is not yet known (discovery phase).

securityName​

Together with the securityLevel and securityEngineID, this identifies which row in the usmUserTable should be used for securing the message.

securityLevel​

The requested securityLevel. One of: noAuthNoPriv, authNoPriv, or authPriv.

scopedPDU​

The message payload. The scopedPDU contains the contextEngineID, contextName, and the PDU.

securityStateReference​

A handle/reference to cachedSecurityData. This is used when generating Response or Report messages to retrieve security information from the original Request message.

wholeMsg​

The complete serialized message ready for transmission.

wholeMsgLength​

The length of the wholeMsg in octets.

2.5.2. Services for Processing an Incoming SNMP Message​

When the Message Processing (MP) Subsystem invokes the User-based Security module to process an incoming SNMP message, it must use the appropriate service as provided by the Security module. The service provided is:

statusInformation =             -- errorIndication or success
  processIncomingMsg(
  IN   messageProcessingModel   -- typically, SNMP version
  IN   maxMessageSize           -- of the receiving SNMP entity
  IN   securityParameters       -- for the received message
  IN   securityModel            -- for the received message
  IN   securityLevel            -- Level of Security
  IN   wholeMsg                 -- as received on the wire
  IN   wholeMsgLength           -- length as received on the wire
  OUT  securityEngineID         -- authoritative SNMP entity
  OUT  securityName             -- identification of the principal
  OUT  scopedPDU                -- message (plaintext) payload
  OUT  maxSizeResponseScopedPDU -- maximum size of Response PDU
  OUT  securityStateReference   -- reference to security state
       )

Abstract Data Elements for Processing​

The abstract data elements passed as parameters are as follows:

statusInformation​

An indication of whether the message processing was successful. If not, it is an indication of the error and may include the OID and value of the error counter that was incremented.

messageProcessingModel​

The SNMP version number of the received message. This is not used by USM.

maxMessageSize​

The maximum message size for the received message. This is used for calculating maxSizeResponseScopedPDU.

securityParameters​

The security parameters from the received message.

securityModel​

The security model identifier from the received message. Should be 3 for USM.

securityLevel​

The security level from the received message: noAuthNoPriv, authNoPriv, or authPriv.

wholeMsg​

The complete message as received.

wholeMsgLength​

The length of the received message in octets.

securityEngineID (OUT)​

The msgAuthoritativeEngineID extracted from the securityParameters.

securityName (OUT)​

The msgUserName extracted from the securityParameters.

scopedPDU (OUT)​

The decrypted and authenticated scopedPDU extracted from the message.

maxSizeResponseScopedPDU (OUT)​

The maximum size of a scopedPDU that can be sent in a Response message. This is calculated based on the received maxMessageSize and the size of the security parameters.

securityStateReference (OUT)​

A reference to cached security data. This is used later when generating a Response or Report message to the received message.

Service Primitive Usage​

These abstract service primitives define the interface between the Message Processing Subsystem and the User-based Security Model. The actual implementation details are specified in Section 3 (Elements of Procedure).

Last updated on