Skip to main content

Appendix A. Guidelines for Model Designers

Appendix A. Guidelines for Model Designers​

This appendix provides guidelines for designers of Security Models, Message Processing Models, Access Control Models, and SNMP Applications. These guidelines are informative and are intended to assist implementors in creating components that work properly within the SNMP architecture.

A.1. Security Model Design Requirements​

A Security Model must provide mechanisms for authentication, privacy, and timeliness checking. This section describes the requirements for Security Models.

A.1.1. Threats​

Security Models must address the following threats:

  1. Modification of Information: An unauthorized entity altering messages in transit

    • A Security Model must provide data integrity services to detect such modification

  2. Masquerade: An unauthorized entity assuming the identity of an authorized entity

    • A Security Model must provide authentication services to verify identity

  3. Message Stream Modification: Reordering, delaying, or replaying messages

    • A Security Model must provide timeliness checking to detect such attacks

  4. Disclosure: Releasing message contents to an unauthorized entity

    • A Security Model may optionally provide confidentiality services through encryption

A.1.2. Security Processing​

A Security Model must implement the following abstract service primitives:

  1. generateRequestMsg: Apply security processing to outgoing request and notification messages

    • Input: scopedPDU, security parameters
    • Output: secured message ready for transmission
    • Processing:
      • Apply authentication (if required by security level)
      • Apply encryption (if required by security level)
      • Add security parameters to message
      • Ensure message is protected according to securityLevel

  2. processIncomingMsg: Process security of incoming messages

    • Input: received message
    • Output: extracted scopedPDU, security parameters
    • Processing:
      • Verify authentication (if message claims to be authenticated)
      • Decrypt message (if message is encrypted)
      • Check timeliness (to prevent replay attacks)
      • Extract scopedPDU
      • Cache security state if response may be needed

  3. generateResponseMsg: Apply security processing to outgoing response messages

    • Input: scopedPDU, cached security state
    • Output: secured response message
    • Processing:
      • Retrieve security parameters from cached state
      • Apply same security level as request
      • Apply authentication (if required)
      • Apply encryption (if required)

A.1.3. Validate the security-stamp in a received message​

A Security Model must validate that:

  1. Authentication is valid: If the message claims to be authenticated, verify the authentication code

    • Use appropriate cryptographic verification (e.g., HMAC verification)
    • Reject messages with invalid authentication

  2. Message is timely: Verify that the message is not a replay

    • Check message timing parameters
    • Maintain state to detect replays
    • Reject messages outside the time window

  3. Privacy is applied correctly: If the message is encrypted, verify it can be decrypted

    • Attempt decryption using appropriate keys
    • Verify decryption was successful
    • Reject messages that cannot be decrypted

  4. Security level matches requirements: Verify that the actual security applied matches what was requested

    • Check that authNoPriv messages are authenticated but not encrypted
    • Check that authPriv messages are both authenticated and encrypted
    • Check that noAuthNoPriv messages are neither authenticated nor encrypted

A.1.4. Security MIBs​

A Security Model should define a MIB module that allows:

  1. Configuration of security parameters: Users, keys, authentication protocols, privacy protocols
  2. Monitoring of security: Counters for authentication failures, decryption errors, etc.
  3. Remote configuration: Secure mechanisms for configuring security remotely

The User-based Security Model (USM) defines the SNMP-USER-BASED-SM-MIB for this purpose.

A.1.5. Cached Security Data​

When processing an incoming request that may require a response, a Security Model must cache security state information. This cached data allows the response to be secured using the same security parameters as the request.

Cached security data typically includes:

  • Security parameters from the request
  • Keys used for authentication and/or encryption
  • Timing parameters
  • Any other state needed to generate a response

The Security Model must:

  1. Generate a securityStateReference: A unique identifier for the cached state
  2. Return the securityStateReference to the Message Processing Model
  3. Retrieve the cached state when generateResponseMsg is called
  4. Release the cached state after the response is generated or when explicitly released

Cached state may be implicitly released when:

  • A response is successfully generated
  • An error occurs and no response will be sent
  • A timeout occurs

Cached state may be explicitly released using the stateRelease primitive.

A.2. Message Processing Model Design Requirements​

A Message Processing Model defines a message format and the procedures for processing messages in that format. This section describes the requirements for Message Processing Models.

A.2.1. Receiving an SNMP Message from the Network​

When a message is received from the network, the Dispatcher determines which Message Processing Model should process it (based on the message version or format). The Message Processing Model must implement the prepareDataElements primitive.

prepareDataElements processing:

  1. Parse the message format: Extract the various components from the message

    • Message header
    • Security parameters
    • Scoped PDU or payload

  2. Determine security model: Identify which Security Model was used

    • Usually indicated in the message header

  3. Call the Security Model: Invoke processIncomingMsg to:

    • Verify authentication
    • Decrypt the message
    • Check timeliness
    • Extract the scoped PDU

  4. Parse the scoped PDU: Extract:

    • contextEngineID
    • contextName
    • PDU

  5. Cache state if needed: If this is a request that may require a response:

    • Cache information needed to generate the response
    • Generate a stateReference
    • Associate the stateReference with the cached data

  6. Return the extracted data elements: Return all necessary information to the Dispatcher:

    • messageProcessingModel
    • securityModel
    • securityName
    • securityLevel
    • contextEngineID
    • contextName
    • pduVersion
    • PDU
    • pduType
    • maxSizeResponseScopedPDU
    • stateReference
    • statusInformation

Error handling:

If any step fails, return appropriate error statusInformation to the Dispatcher. Do not pass malformed or unauthenticated messages to applications.

A.2.2. Sending an SNMP Message to the Network​

When sending a message, the Dispatcher calls either prepareOutgoingMessage (for requests and notifications) or prepareResponseMessage (for responses). The Message Processing Model must implement these primitives.

prepareOutgoingMessage processing:

  1. Create a scoped PDU: Combine contextEngineID, contextName, and PDU

  2. Call the Security Model: Invoke generateRequestMsg to:

    • Apply authentication (if required)
    • Apply encryption (if required)
    • Add security parameters

  3. Create the message: Wrap the secured payload in the appropriate message format

    • Add message header
    • Add version or format identifier
    • Add any message-specific fields

  4. Return the complete message: Return the formatted message ready for transmission:

    • outgoingMessage
    • outgoingMessageLength
    • statusInformation

prepareResponseMessage processing:

Similar to prepareOutgoingMessage, but:

  1. Retrieve cached state: Use the stateReference to retrieve cached information

  2. Create a scoped PDU: Combine contextEngineID, contextName, and PDU (from original request)

  3. Call the Security Model: Invoke generateResponseMsg with:

    • The scoped PDU
    • The securityStateReference (to use same security parameters as request)

  4. Create the response message: Wrap the secured payload in the appropriate format

  5. Release cached state: After successfully creating the response, release the cached state

  6. Return the complete response: Return the formatted response message

Error handling:

If any step fails, return appropriate error statusInformation. If a response cannot be generated, ensure cached state is released.

A.3. Application Design Requirements​

SNMP Applications use the services of the SNMP engine to perform management functions. This section describes requirements and guidelines for application design.

A.3.1. Applications that Initiate Messages​

Applications that initiate messages (Command Generators, Notification Originators) must:

  1. Determine destination: Identify the target SNMP engine

    • transportDomain
    • transportAddress
    • contextEngineID

  2. Determine security parameters:

    • securityModel
    • securityName
    • securityLevel

  3. Create the PDU: Build the protocol data unit with the desired operation and variables

  4. Call sendPdu: Invoke the Dispatcher's sendPdu primitive with:

    • Destination information
    • Security parameters
    • contextEngineID and contextName
    • PDU
    • expectResponse flag
    • sendPduHandle (to correlate later response)

  5. Handle the response: If expectResponse was TRUE, implement processResponsePdu to receive the response

Guidelines:

  • Configure destinations: Use configuration mechanisms (e.g., SNMP-TARGET-MIB) to manage destination information
  • Configure security: Use configuration mechanisms (e.g., SNMP-USER-BASED-SM-MIB) to manage security parameters
  • Handle errors: Properly handle statusInformation errors from sendPdu
  • Implement timeouts: If no response is received within a reasonable time, handle the timeout
  • Implement retries: Consider retransmitting if no response is received

A.3.2. Applications that Receive Responses​

Applications that receive responses must implement the processResponsePdu primitive.

processResponsePdu implementation:

  1. Correlate the response: Use the sendPduHandle to match the response to the original request

  2. Check statusInformation: Verify that message processing was successful

  3. Process the PDU: Extract and process the response data

    • Check error-status and error-index
    • Extract variable bindings
    • Perform application-specific processing

Guidelines:

  • Handle errors: Check for SNMP errors (e.g., noSuchName, tooBig, genErr)
  • Handle exceptions: Check for exception values (noSuchObject, noSuchInstance, endOfMibView)
  • Handle security errors: Be prepared for authentication or privacy failures
  • Clean up state: Release any resources associated with the request

A.3.3. Applications that Receive Asynchronous Messages​

Applications that receive asynchronous messages (Command Responders, Notification Receivers) must:

  1. Register with the Dispatcher: Call registerContextEngineID to register for:

    • Specific contextEngineID values
    • Specific PDU types

  2. Implement processPdu: Receive and process incoming PDUs

    • Validate contextEngineID and contextName
    • Process the PDU according to application semantics
    • Generate response (if required)

processPdu implementation:

  1. Validate the context: Ensure this application is responsible for the contextEngineID and contextName

  2. Check access control (if appropriate): Call isAccessAllowed for each variable in the PDU

  3. Process the request: Perform the requested operation

    • For GET: retrieve variable values
    • For SET: modify variable values
    • For GETNEXT: find lexicographically next variable
    • For GETBULK: retrieve multiple variables efficiently

  4. Build response PDU (if required): Create a response PDU with results

  5. Call returnResponsePdu (if required): Send the response back to the requester

Guidelines:

  • Validate input: Carefully validate all input to prevent security vulnerabilities
  • Implement access control: Apply appropriate access control to all operations
  • Handle errors gracefully: Return appropriate error responses for invalid requests
  • Respect maxSizeResponseScopedPDU: Ensure response does not exceed size limit
  • Use stateReference: Pass the stateReference from processPdu to returnResponsePdu unchanged

A.3.4. Applications that Send Responses​

Applications that send responses must use the returnResponsePdu primitive.

returnResponsePdu usage:

  1. Use parameters from processPdu: Pass through:

    • messageProcessingModel
    • securityModel
    • securityName
    • securityLevel
    • contextEngineID
    • contextName
    • pduVersion
    • maxSizeResponseScopedPDU
    • stateReference

  2. Create response PDU: Build the PDU containing results

  3. Call returnResponsePdu: Invoke the Dispatcher's returnResponsePdu primitive

Guidelines:

  • Don't modify security parameters: Use the same security parameters as the request
  • Respect size limits: Ensure the response fits within maxSizeResponseScopedPDU
  • Handle errors: If the response cannot be sent, handle the error appropriately
  • Release state: The stateReference will be released by the Dispatcher after sending the response

A.4. Access Control Model Design Requirements​

An Access Control Model determines whether access to a managed object should be allowed. This section describes the requirements for Access Control Models.

An Access Control Model must implement the isAccessAllowed primitive.

isAccessAllowed implementation:

  1. Determine the principal: Identify who is attempting the access

    • Use securityModel and securityName

  2. Determine the access type: Identify what type of access is requested

    • read: GET, GETNEXT, GETBULK
    • write: SET
    • notify: TRAP, INFORM

  3. Determine the target: Identify which object is being accessed

    • variableName (OID)
    • contextName

  4. Apply access control policy: Based on the configured policy, determine whether access should be allowed

  5. Return result: Return allowed or denied

Guidelines:

  • Define a MIB: Define a MIB module for configuring the access control policy
  • Support remote configuration: Allow the policy to be configured via SNMP
  • Default deny: If no explicit policy allows access, deny by default
  • Efficient implementation: Access control may be called many times per request; implement efficiently
  • Consistent policy: Ensure the policy is applied consistently

The View-based Access Control Model (VACM) defined in RFC 3415 is an example implementation.

Last updated on