Skip to main content

1.6. Abstract Service Interfaces

1.6. Abstract Service Interfaces​

The User-based Security Model is designed to integrate with the SNMPv3 architecture through well-defined abstract service interfaces. These interfaces allow the USM to work independently of other subsystems while providing necessary security services.

Security Model Interface​

The USM implements the Security Model interface defined in RFC 3411. This interface consists of two primary primitives:

1. generateRequestMsg​

Purpose: Process an outgoing SNMP message by adding security-related information.

Inputs:

  • messageProcessingModel: The SNMP version (3 for SNMPv3)
  • globalData: Global message header information
  • maxMessageSize: Maximum message size supported
  • securityModel: Security model identifier (3 for USM)
  • securityEngineID: The authoritative SNMP engine's identifier
  • securityName: The principal on whose behalf the message is being generated
  • securityLevel: The desired security level (noAuthNoPriv, authNoPriv, or authPriv)
  • scopedPDU: The message payload to be secured

Outputs:

  • securityParameters: USM-specific security parameters (engineID, engineBoots, engineTime, userName, authentication parameters, privacy parameters)
  • wholeMsg: The complete secured message ready for transmission
  • statusInformation: Success or error indication

Processing:

  1. Validate inputs
  2. Retrieve user's authentication and privacy keys
  3. Increment and include engineBoots and engineTime
  4. Apply privacy protocol if securityLevel includes privacy
  5. Calculate authentication digest if securityLevel includes authentication
  6. Assemble the complete message

2. processIncomingMsg​

Purpose: Process an incoming SNMP message by verifying security-related information.

Inputs:

  • messageProcessingModel: The SNMP version
  • maxMessageSize: Maximum message size supported
  • securityParameters: The received USM security parameters
  • securityModel: Security model identifier
  • securityLevel: The expected security level
  • wholeMsg: The complete received message
  • securityEngineID: The authoritative engine's identifier (from message)

Outputs:

  • securityName: The authenticated principal
  • scopedPDU: The decrypted and verified message payload
  • maxSizeResponseScopedPDU: Maximum size for response
  • securityStateReference: Reference for generating responses
  • statusInformation: Success or error indication

Processing:

  1. Parse securityParameters
  2. Verify msgAuthoritativeEngineID matches local engine (for command responders)
  3. Verify userName exists in usmUserTable
  4. Check time window (engineBoots and engineTime)
  5. Decrypt message if privacy was applied
  6. Verify authentication digest if authentication was applied
  7. Extract and return scopedPDU

Integration with Message Processing Subsystem​

The Message Processing Subsystem invokes the USM through these interfaces at specific points in message processing:

For Outgoing Messages:

Application → Dispatcher → Message Processing → Security Model (USM) → Transport

For Incoming Messages:

Transport → Dispatcher → Message Processing → Security Model (USM) → Application

Interaction with Access Control​

The USM provides the authenticated securityName to the Access Control Subsystem (VACM), which uses it to determine authorization:

  1. USM authenticates the user and provides securityName
  2. VACM uses securityName, securityModel, and securityLevel to determine access rights
  3. VACM grants or denies access based on configured policies

This separation ensures that:

  • USM focuses on: "Who are you?" (Authentication) and "Is the message intact?" (Integrity)
  • VACM focuses on: "What are you allowed to do?" (Authorization)

Error Handling and Reports​

When the USM detects a security error, it may generate a Report-PDU:

Common Error Scenarios:

  1. Unknown Engine ID: usmStatsUnknownEngineIDs counter incremented

    • Used during discovery process
    • Report contains the local engine's engineID

  2. Time Window Violation: usmStatsNotInTimeWindows counter incremented

    • Used during time synchronization
    • Report contains current engineBoots and engineTime

  3. Authentication Failure: usmStatsWrongDigests counter incremented

    • Indicates incorrect password/key or message tampering
    • Report sent at same security level as received message

  4. Decryption Failure: usmStatsDecryptionErrors counter incremented

    • Indicates incorrect privacy key or message corruption
    • Report sent at same security level as received message

  5. Unknown User: usmStatsUnknownUserNames counter incremented

    • Indicates userName not in usmUserTable
    • Report sent without authentication

Service Primitive Sequences​

Discovery Sequence​

1. Application sends request with empty engineID
2. USM generates message with securityLevel = noAuthNoPriv
3. Authoritative engine receives message
4. USM detects unknown engineID
5. USM generates Report with usmStatsUnknownEngineIDs
6. Application receives Report, learns engineID

Time Synchronization Sequence​

1. Application sends request with cached engineID, zero engineBoots/Time
2. USM generates authenticated message
3. Authoritative engine receives message
4. USM detects time window violation
5. USM generates Report with usmStatsNotInTimeWindows and current time values
6. Application receives Report, updates cached time values
7. Application retries original request with synchronized time

Authenticated Communication Sequence​

1. Application sends request
2. USM generates authenticated message with current engineBoots/Time
3. USM calculates authentication digest
4. Authoritative engine receives message
5. USM verifies time window
6. USM verifies authentication digest
7. USM extracts scopedPDU
8. Application processes request
9. Application generates response
10. USM generates authenticated response message
11. Non-authoritative engine receives response
12. USM verifies authentication digest
13. USM extracts scopedPDU
14. Application processes response

Asynchronous vs. Synchronous Operation​

The abstract service interfaces are designed to support both:

Synchronous Operation:

  • Application waits for response
  • Typical for command generator/responder model

Asynchronous Operation:

  • Application does not wait
  • Typical for notification originator/receiver model

The USM does not dictate the operational model; it simply provides security services regardless of how the application chooses to operate.

Last updated on