Skip to main content

4. Abstract Service Interfaces

4. Abstract Service Interfaces​

This section describes the abstract service interfaces between the major components of the SNMP architecture. These interfaces are defined using abstract primitives, which represent the information that must be passed between components without specifying how it is passed.

The abstract service interfaces are organized into several categories:

  • Dispatcher Primitives: Interfaces between applications and the Dispatcher
  • Message Processing Subsystem Primitives: Interfaces between the Dispatcher and Message Processing Models
  • Access Control Subsystem Primitives: Interfaces between applications and the Access Control Subsystem
  • Security Subsystem Primitives: Interfaces between Message Processing Models and Security Models

4.1. Dispatcher Primitives​

The Dispatcher provides services to applications for sending and receiving SNMP messages. It acts as the central point for routing messages and PDUs.

4.1.1. Generate Outgoing Request or Notification​

Applications use the sendPdu primitive to request that the Dispatcher send an SNMP message containing a PDU.

Primitive:

statusInformation =
  sendPdu(
    IN  transportDomain
    IN  transportAddress
    IN  messageProcessingModel
    IN  securityModel
    IN  securityName
    IN  securityLevel
    IN  contextEngineID
    IN  contextName
    IN  pduVersion
    IN  PDU
    IN  expectResponse
    IN  sendPduHandle
    OUT destTransportDomain
    OUT destTransportAddress
  )

Parameters:

  • transportDomain: The transport protocol to use (e.g., UDP)
  • transportAddress: The destination address
  • messageProcessingModel: The message format to use
  • securityModel: The security model to use
  • securityName: The principal on whose behalf the message is sent
  • securityLevel: The security level (noAuthNoPriv, authNoPriv, or authPriv)
  • contextEngineID: The context engine ID
  • contextName: The context name
  • pduVersion: The PDU version
  • PDU: The PDU to send
  • expectResponse: Whether a response is expected
  • sendPduHandle: A handle to identify this request
  • destTransportDomain: (OUT) The actual transport domain used
  • destTransportAddress: (OUT) The actual transport address used
  • statusInformation: (OUT) Success or error indication

4.1.2. Process Incoming Request or Notification PDU​

The Dispatcher uses the processPdu primitive to deliver an incoming request or notification PDU to an application.

Primitive:

processPdu(
  IN  messageProcessingModel
  IN  securityModel
  IN  securityName
  IN  securityLevel
  IN  contextEngineID
  IN  contextName
  IN  pduVersion
  IN  PDU
  IN  maxSizeResponseScopedPDU
  IN  stateReference
)

Parameters:

  • messageProcessingModel: The message format used
  • securityModel: The security model used
  • securityName: The principal on whose behalf the message was sent
  • securityLevel: The security level applied to the message
  • contextEngineID: The context engine ID
  • contextName: The context name
  • pduVersion: The PDU version
  • PDU: The received PDU
  • maxSizeResponseScopedPDU: The maximum size for a response
  • stateReference: Reference to cached state information

4.1.3. Generate Outgoing Response​

Applications use the returnResponsePdu primitive to request that the Dispatcher send a response message.

Primitive:

result =
  returnResponsePdu(
    IN  messageProcessingModel
    IN  securityModel
    IN  securityName
    IN  securityLevel
    IN  contextEngineID
    IN  contextName
    IN  pduVersion
    IN  PDU
    IN  maxSizeResponseScopedPDU
    IN  stateReference
    IN  statusInformation
  )

Parameters:

  • messageProcessingModel: The message format to use (from processPdu)
  • securityModel: The security model to use (from processPdu)
  • securityName: The principal (from processPdu)
  • securityLevel: The security level (from processPdu)
  • contextEngineID: The context engine ID (from processPdu)
  • contextName: The context name (from processPdu)
  • pduVersion: The PDU version (from processPdu)
  • PDU: The response PDU to send
  • maxSizeResponseScopedPDU: Maximum size for the response (from processPdu)
  • stateReference: State information (from processPdu)
  • statusInformation: Status information about the processing of the request
  • result: (OUT) Success or error indication

4.1.4. Process Incoming Response PDU​

The Dispatcher uses the processResponsePdu primitive to deliver a response PDU to an application.

Primitive:

processResponsePdu(
  IN  messageProcessingModel
  IN  securityModel
  IN  securityName
  IN  securityLevel
  IN  contextEngineID
  IN  contextName
  IN  pduVersion
  IN  PDU
  IN  statusInformation
  IN  sendPduHandle
)

Parameters:

  • messageProcessingModel: The message format used
  • securityModel: The security model used
  • securityName: The principal
  • securityLevel: The security level applied
  • contextEngineID: The context engine ID
  • contextName: The context name
  • pduVersion: The PDU version
  • PDU: The received response PDU
  • statusInformation: Status information about message processing
  • sendPduHandle: The handle from the original sendPdu request

4.1.5. Registering Responsibility for Handling SNMP PDUs​

Applications must register with the Dispatcher to receive certain types of PDUs.

Primitive for registration:

statusInformation =
  registerContextEngineID(
    IN  contextEngineID
    IN  pduType
  )

Primitive for unregistration:

unregisterContextEngineID(
  IN  contextEngineID
  IN  pduType
)

Parameters:

  • contextEngineID: The context engine ID to register for
  • pduType: The type of PDU to receive (Get, GetNext, GetBulk, Set, Trap, InformRequest, etc.)
  • statusInformation: (OUT) Success or error indication

Only one application can register for a given combination of contextEngineID and pduType at a time.

4.2. Message Processing Subsystem Primitives​

The Message Processing Subsystem provides services to the Dispatcher for preparing messages and extracting data from messages.

4.2.1. Prepare Outgoing SNMP Request or Notification Message​

The Dispatcher uses the prepareOutgoingMessage primitive to request that a Message Processing Model prepare a message for transmission.

Primitive:

statusInformation =
  prepareOutgoingMessage(
    IN  transportDomain
    IN  transportAddress
    IN  messageProcessingModel
    IN  securityModel
    IN  securityName
    IN  securityLevel
    IN  contextEngineID
    IN  contextName
    IN  pduVersion
    IN  PDU
    IN  expectResponse
    IN  sendPduHandle
    OUT destTransportDomain
    OUT destTransportAddress
    OUT outgoingMessage
    OUT outgoingMessageLength
  )

Parameters:

  • Input parameters are the same as for sendPdu
  • outgoingMessage: (OUT) The prepared message ready for transmission
  • outgoingMessageLength: (OUT) The length of the message
  • statusInformation: (OUT) Success or error indication

The Message Processing Model:

  1. Creates a scopedPDU from the contextEngineID, contextName, and PDU
  2. Calls the Security Model to apply security processing
  3. Wraps the secured message in the appropriate message format
  4. Returns the complete message ready for transmission

4.2.2. Prepare an Outgoing SNMP Response Message​

The Dispatcher uses the prepareResponseMessage primitive to request that a Message Processing Model prepare a response message for transmission.

Primitive:

result =
  prepareResponseMessage(
    IN  messageProcessingModel
    IN  securityModel
    IN  securityName
    IN  securityLevel
    IN  contextEngineID
    IN  contextName
    IN  pduVersion
    IN  PDU
    IN  maxSizeResponseScopedPDU
    IN  stateReference
    IN  statusInformation
    OUT destTransportDomain
    OUT destTransportAddress
    OUT outgoingMessage
    OUT outgoingMessageLength
  )

Parameters:

  • Input parameters include the state information from the original request
  • outgoingMessage: (OUT) The prepared response message
  • outgoingMessageLength: (OUT) The length of the message
  • result: (OUT) Success or error indication

The Message Processing Model:

  1. Retrieves cached information using the stateReference
  2. Creates a scopedPDU from the contextEngineID, contextName, and PDU
  3. Calls the Security Model to apply security processing
  4. Wraps the secured message in the appropriate message format
  5. Returns the complete message ready for transmission
  6. Releases the cached state information

4.2.3. Prepare Data Elements from an Incoming SNMP Message​

The Dispatcher uses the prepareDataElements primitive to request that a Message Processing Model extract data from a received message.

Primitive:

result =
  prepareDataElements(
    IN  transportDomain
    IN  transportAddress
    IN  wholeMsg
    IN  wholeMsgLength
    OUT messageProcessingModel
    OUT securityModel
    OUT securityName
    OUT securityLevel
    OUT contextEngineID
    OUT contextName
    OUT pduVersion
    OUT PDU
    OUT pduType
    OUT sendPduHandle
    OUT maxSizeResponseScopedPDU
    OUT statusInformation
    OUT stateReference
  )

Parameters:

  • transportDomain: The transport protocol the message arrived on
  • transportAddress: The source address
  • wholeMsg: The received message
  • wholeMsgLength: The length of the message
  • All OUT parameters contain the extracted data elements
  • result: (OUT) Success or error indication

The Message Processing Model:

  1. Parses the message format
  2. Calls the Security Model to process security
  3. Extracts the scopedPDU
  4. Parses the scopedPDU to extract contextEngineID, contextName, and PDU
  5. Caches state information if the message requires a response
  6. Returns all extracted data elements

4.3. Access Control Subsystem Primitives​

The Access Control Subsystem provides services to applications for determining whether access to a managed object should be allowed.

Primitive:

statusInformation =
  isAccessAllowed(
    IN  securityModel
    IN  securityName
    IN  securityLevel
    IN  viewType
    IN  contextName
    IN  variableName
  )

Parameters:

  • securityModel: The security model in use
  • securityName: The principal attempting the access
  • securityLevel: The security level of the message
  • viewType: The type of access (read, write, or notify)
  • contextName: The context being accessed
  • variableName: The OID of the managed object
  • statusInformation: (OUT) Allowed or denied

The Access Control Model determines whether the specified operation should be allowed based on its configured policy.

4.4. Security Subsystem Primitives​

The Security Subsystem provides services to Message Processing Models for applying and checking security.

4.4.1. Generate a Request or Notification Message​

Message Processing Models use the generateRequestMsg primitive to request that the Security Subsystem apply security processing to an outgoing request or notification message.

Primitive:

statusInformation =
  generateRequestMsg(
    IN  messageProcessingModel
    IN  globalData
    IN  maxMessageSize
    IN  securityModel
    IN  securityEngineID
    IN  securityName
    IN  securityLevel
    IN  scopedPDU
    OUT securityParameters
    OUT wholeMsg
    OUT wholeMsgLength
  )

Parameters:

  • messageProcessingModel: The message format being used
  • globalData: Message-format-specific header data
  • maxMessageSize: Maximum message size supported
  • securityModel: The security model to use
  • securityEngineID: The authoritative engine ID
  • securityName: The principal
  • securityLevel: The desired security level
  • scopedPDU: The scoped PDU to secure
  • securityParameters: (OUT) Security-model-specific parameters
  • wholeMsg: (OUT) The complete secured message
  • wholeMsgLength: (OUT) The length of the message
  • statusInformation: (OUT) Success or error indication

4.4.2. Process Incoming Message​

Message Processing Models use the processIncomingMsg primitive to request that the Security Subsystem process an incoming message.

Primitive:

statusInformation =
  processIncomingMsg(
    IN  messageProcessingModel
    IN  maxMessageSize
    IN  securityParameters
    IN  securityModel
    IN  securityLevel
    IN  wholeMsg
    IN  wholeMsgLength
    OUT securityEngineID
    OUT securityName
    OUT scopedPDU
    OUT maxSizeResponseScopedPDU
    OUT securityStateReference
  )

Parameters:

  • messageProcessingModel: The message format being used
  • maxMessageSize: Maximum message size supported
  • securityParameters: Security-model-specific parameters from the message
  • securityModel: The security model indicated in the message
  • securityLevel: The desired security level
  • wholeMsg: The received message
  • wholeMsgLength: The length of the message
  • securityEngineID: (OUT) The authoritative engine ID
  • securityName: (OUT) The principal
  • scopedPDU: (OUT) The extracted and verified scoped PDU
  • maxSizeResponseScopedPDU: (OUT) Maximum size for a response
  • securityStateReference: (OUT) Reference to cached security state
  • statusInformation: (OUT) Success or error indication

The Security Model:

  1. Verifies the message is authentic (if authentication is required)
  2. Decrypts the message (if privacy is required)
  3. Checks message timeliness (to prevent replay attacks)
  4. Extracts the scopedPDU
  5. Caches security state if a response may be needed
  6. Returns all extracted data

4.4.3. Generate a Response Message​

Message Processing Models use the generateResponseMsg primitive to request that the Security Subsystem apply security processing to an outgoing response message.

Primitive:

statusInformation =
  generateResponseMsg(
    IN  messageProcessingModel
    IN  globalData
    IN  maxMessageSize
    IN  securityModel
    IN  securityEngineID
    IN  securityName
    IN  securityLevel
    IN  scopedPDU
    IN  securityStateReference
    OUT securityParameters
    OUT wholeMsg
    OUT wholeMsgLength
  )

Parameters:

  • Similar to generateRequestMsg, but includes securityStateReference
  • securityStateReference: Cached state from the original request
  • Other parameters are similar to generateRequestMsg

The Security Model uses the cached security state to apply the same security processing to the response as was used for the request.

4.5. Common Primitives​

4.5.1. Release State Reference Information​

Components use the stateRelease primitive to release cached state information.

Primitive:

stateRelease(
  IN  stateReference
)

Parameters:

  • stateReference: The reference to the cached state to be released

This primitive is used to free resources when cached state information is no longer needed. It is typically called when:

  • A response has been sent
  • An error occurred and no response will be sent
  • A timeout occurred waiting for a response

4.6. Scenario Diagrams​

This section provides scenario diagrams showing the flow of primitives for common operations.

4.6.1. Command Generator or Notification Originator​

The following diagram shows the flow when an application initiates a request or notification:

Application          Dispatcher       Message Processing    Security
                                      Model                 Model

sendPdu ----------->
                     prepareOutgoing
                     Message -------->
                                      generateRequestMsg -->
                                                            (apply security)
                                      <------------------
                     <--------------
                     (send message to network)

(later, response arrives)

                     (receive message from network)
                     prepareData
                     Elements ------->
                                      processIncomingMsg -->
                                                            (check security)
                                      <------------------
                     <--------------
processResponsePdu <-

4.6.2. Scenario Diagram for a Command Responder Application​

The following diagram shows the flow when an application responds to a request:

Application          Dispatcher       Message Processing    Security
                                      Model                 Model

                     (receive message from network)
                     prepareData
                     Elements ------->
                                      processIncomingMsg -->
                                                            (check security)
                                      <------------------
                     <--------------
processPdu <--------

                     (application processes request)

returnResponsePdu ->
                     prepareResponse
                     Message -------->
                                      generateResponseMsg ->
                                                            (apply security)
                                      <------------------
                     <--------------
                     (send message to network)

These diagrams illustrate the modular design of the architecture and the clean separation of concerns between different subsystems.

Last updated on