3.2. Processing an Incoming SNMP Message

3.2. Processing an Incoming SNMP Message

This section describes the procedure followed by an SNMP engine whenever it receives a message containing a management operation on behalf of a user, with a particular securityLevel.

General Notes

To simplify the elements of procedure, the release of state information is not always explicitly specified. As a general rule, if state information is available when a message gets discarded, the state information should also be released.

Also, an error indication can return:

• An OID and value for an incremented counter
• Optionally a value for securityLevel
• Values for contextEngineID or contextName for the counter
• The securityStateReference data if any such information is available at the point where the error is detected

Step 1: Parse securityParameters

If the received securityParameters is not the serialization (according to the conventions of RFC 3417) of an OCTET STRING formatted according to the UsmSecurityParameters defined in section 2.4, then:

• The snmpInASNParseErrs counter (RFC 3418) is incremented
• An error indication (parseError) is returned to the calling module

Note: We return without the OID and value of the incremented counter, because in this case there is not enough information to generate a Report PDU.

Step 2: Extract Security Parameters

The values of the security parameter fields are extracted from the securityParameters.

• The securityEngineID to be returned to the caller is the value of the msgAuthoritativeEngineID field
• The cachedSecurityData is prepared and a securityStateReference is prepared to reference this data

Values to be cached:

• msgUserName
• msgAuthoritativeEngineID
• msgAuthoritativeEngineBoots
• msgAuthoritativeEngineTime
• msgAuthenticationParameters
• msgPrivacyParameters

Step 3: Check msgAuthoritativeEngineID

If the value of the msgAuthoritativeEngineID field in the securityParameters is unknown then:

Option a) Discovery Mode (Non-authoritative Engine)

A non-authoritative SNMP engine that performs discovery may optionally create a new entry in its Local Configuration Datastore (LCD) and continue processing.

Option b) Return Error

The usmStatsUnknownEngineIDs counter is incremented, and an error indication (unknownEngineID) together with the OID and value of the incremented counter is returned to the calling module.

Note: In the event that a zero-length, or other illegally sized msgAuthoritativeEngineID is received, option b) should be chosen to facilitate engineID discovery. Otherwise the choice between a) and b) is an implementation issue.

Step 4: Lookup User Information

Information about the value of the msgUserName and msgAuthoritativeEngineID fields is extracted from the Local Configuration Datastore (LCD, usmUserTable).

If no information is available for the user, then:

• The usmStatsUnknownUserNames counter is incremented
• An error indication (unknownSecurityName) together with the OID and value of the incremented counter is returned to the calling module

Step 5: Check Security Level Support

If the information about the user indicates that it does not support the securityLevel requested by the caller, then:

• The usmStatsUnsupportedSecLevels counter is incremented
• An error indication (unsupportedSecurityLevel) together with the OID and value of the incremented counter is returned to the calling module

Step 6: Authenticate Message (if required)

If the securityLevel specifies that the message is to be authenticated, then the message is authenticated according to the user's authentication protocol.

To do so a call is made to the authentication module that implements the user's authentication protocol according to the abstract service primitive:

statusInformation =          -- success or failure
  authenticateIncomingMsg(
  IN   authKey               -- the user's localized authKey
  IN   authParameters        -- as received on the wire
  IN   wholeMsg              -- as received on the wire
  OUT  authenticatedWholeMsg -- checked for authentication
       )

Parameters:

• statusInformation: Indicates if authentication was successful or not

• authKey: The user's localized private authKey is the secret key that can be used by the authentication algorithm

• authParameters: The msgAuthenticationParameters as received in the message

• wholeMsg: The complete serialized message to be authenticated

• authenticatedWholeMsg: The same as the input given to the authenticateIncomingMsg service, but after authentication has been checked

Error Handling:

If the authentication module returns failure, then the message cannot be trusted, so:

• The usmStatsWrongDigests counter is incremented
• An error indication (authenticationFailure) together with the OID and value of the incremented counter is returned to the calling module

If the authentication module returns success, then the message is authentic and can be trusted so processing continues.

Step 7: Check Time Window (for authenticated messages)

If the securityLevel indicates an authenticated message, then the local values of snmpEngineBoots, snmpEngineTime and latestReceivedEngineTime corresponding to the value of the msgAuthoritativeEngineID field are extracted from the Local Configuration Datastore.

7a) Authoritative Engine (msgAuthoritativeEngineID == local snmpEngineID)

If the extracted value of msgAuthoritativeEngineID is the same as the value of snmpEngineID of the processing SNMP engine (meaning this is the authoritative SNMP engine), then if any of the following conditions is true, then the message is considered to be outside of the Time Window:

1. The local value of snmpEngineBoots is 2147483647 (maximum value reached)

2. The value of the msgAuthoritativeEngineBoots field differs from the local value of snmpEngineBoots

3. The value of the msgAuthoritativeEngineTime field differs from the local notion of snmpEngineTime by more than +/- 150 seconds

If outside Time Window:

• The usmStatsNotInTimeWindows counter is incremented
• An error indication (notInTimeWindow) together with the OID, the value of the incremented counter, and an indication that the error must be reported with a securityLevel of authNoPriv, is returned to the calling module

7b) Non-Authoritative Engine (msgAuthoritativeEngineID != local snmpEngineID)

If the extracted value of msgAuthoritativeEngineID is not the same as the value snmpEngineID of the processing SNMP engine (meaning this is not the authoritative SNMP engine), then:

7b.1) Update Time Information (if newer)

If at least one of the following conditions is true:

• The extracted value of the msgAuthoritativeEngineBoots field is greater than the local notion of the value of snmpEngineBoots; OR

• The extracted value of the msgAuthoritativeEngineBoots field is equal to the local notion of the value of snmpEngineBoots, AND the extracted value of msgAuthoritativeEngineTime field is greater than the value of latestReceivedEngineTime

Then the LCD entry corresponding to the extracted value of the msgAuthoritativeEngineID field is updated, by setting:

• The local notion of the value of snmpEngineBoots to the value of the msgAuthoritativeEngineBoots field
• The local notion of the value of snmpEngineTime to the value of the msgAuthoritativeEngineTime field
• The latestReceivedEngineTime to the value of the msgAuthoritativeEngineTime field

7b.2) Check Time Window

If any of the following conditions is true, then the message is considered to be outside of the Time Window:

1. The local notion of the value of snmpEngineBoots is 2147483647

2. The value of the msgAuthoritativeEngineBoots field is less than the local notion of the value of snmpEngineBoots

3. The value of the msgAuthoritativeEngineBoots field is equal to the local notion of the value of snmpEngineBoots AND the value of the msgAuthoritativeEngineTime field is more than 150 seconds less than the local notion of the value of snmpEngineTime

If outside Time Window:

• The usmStatsNotInTimeWindows counter is incremented
• An error indication (notInTimeWindow) together with the OID and value of the incremented counter is returned to the calling module

Step 8: Decrypt Message (if required)

If the securityLevel indicates that the message is protected from disclosure (privacy), then the OCTET STRING representing the encryptedPDU is decrypted according to the user's privacy protocol.

To do so a call is made to the privacy module that implements the user's privacy protocol according to the abstract service primitive:

statusInformation =         -- success or failure
  decryptData(
  IN    decryptKey          -- the user's localized privKey
  IN    privParameters      -- as received on the wire
  IN    encryptedData       -- encryptedPDU as received
  OUT   decryptedData       -- decrypted scopedPDU
        )

Parameters:

• statusInformation: Indicates if the decryption process was successful or not

• decryptKey: The user's localized private privKey is the secret key used by the decryption algorithm

• privParameters: The msgPrivacyParameters as received in the message

• encryptedData: The encryptedPDU from the message

• decryptedData: The decrypted scopedPDU

Error Handling:

If the privacy module returns failure, then the message cannot be processed, so:

• The usmStatsDecryptionErrors counter is incremented
• An error indication (decryptionError) together with the OID and value of the incremented counter is returned to the calling module

If the privacy module returns success, then the decrypted scopedPDU is used for further processing.

Step 9: Return Results

The following values are returned to the calling Message Processing module:

• securityEngineID: The msgAuthoritativeEngineID
• securityName: The msgUserName
• scopedPDU: Either the decrypted scopedPDU (if privacy) or the plaintext scopedPDU
• maxSizeResponseScopedPDU: Calculated based on the message size constraints
• securityStateReference: Reference to the cached security data

Processing Flow Summary

1. Parse securityParameters
2. Extract security parameter fields
3. Check msgAuthoritativeEngineID (unknown -> error or create entry)
4. Lookup user in LCD (unknown user -> error)
5. Check security level support (unsupported -> error)
6. Authenticate message (if authNoPriv or authPriv)
   └─> Verify MAC/digest (wrong -> error)
7. Check time window (if authenticated)
   └─> For authoritative: validate boots and time
   └─> For non-authoritative: update time info if newer, then validate
   └─> Outside window -> error
8. Decrypt message (if authPriv)
   └─> Decrypt encryptedPDU (failed -> error)
9. Return securityEngineID, securityName, scopedPDU, etc.

Error Conditions Summary

Error	Counter	Condition
parseError	snmpInASNParseErrs	Invalid securityParameters format
unknownEngineID	usmStatsUnknownEngineIDs	Unknown msgAuthoritativeEngineID
unknownSecurityName	usmStatsUnknownUserNames	User not found in LCD
unsupportedSecurityLevel	usmStatsUnsupportedSecLevels	User doesn't support requested level
authenticationFailure	usmStatsWrongDigests	Authentication check failed
notInTimeWindow	usmStatsNotInTimeWindows	Message outside 150-second window
decryptionError	usmStatsDecryptionErrors	Decryption failed

Implementation Notes

1. State Management: Implementations should properly manage and release securityStateReference data

2. Report Generation: Many errors result in Report PDUs being sent back to the sender with appropriate error counters

3. Time Synchronization: Non-authoritative engines automatically update their time information when receiving messages with newer time values from authoritative engines

4. Discovery: Non-authoritative engines can optionally learn about new engines by creating LCD entries during discovery

5. Security Level in Reports: The notInTimeWindow error must be reported with securityLevel authNoPriv (not authPriv) to allow the sender to receive and process the report