Skip to main content

3. Elements of Procedure

This section describes the security related procedures followed by an SNMP engine when processing SNMP messages according to the User-based Security Model.

3.1. Generating an Outgoing SNMP Message​

This section describes the procedure followed by an SNMP engine whenever it generates a message containing a management operation (like a request, a response, a notification, or a report) on behalf of a user, with a particular securityLevel.

  1. a) If any securityStateReference is passed (Response or Report message), then information concerning the user is extracted from the cachedSecurityData. The cachedSecurityData can now be discarded. The securityEngineID is set to the local snmpEngineID. The securityLevel is set to the value specified by the calling module.

    Otherwise,

    b) based on the securityName, information concerning the user at the destination snmpEngineID, specified by the securityEngineID, is extracted from the Local Configuration Datastore (LCD, usmUserTable). If information about the user is absent from the LCD, then an error indication (unknownSecurityName) is returned to the calling module.

  2. If the securityLevel specifies that the message is to be protected from disclosure, but the user does not support both an authentication and a privacy protocol then the message cannot be sent. An error indication (unsupportedSecurityLevel) is returned to the calling module.

  3. If the securityLevel specifies that the message is to be authenticated, but the user does not support an authentication protocol, then the message cannot be sent. An error indication (unsupportedSecurityLevel) is returned to the calling module.

  4. a) If the securityLevel specifies that the message is to be protected from disclosure, then the octet sequence representing the serialized scopedPDU is encrypted 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 primitive:

    statusInformation =       -- success or failure
      encryptData(
      IN    encryptKey        -- user's localized privKey
      IN    dataToEncrypt     -- serialized scopedPDU
      OUT   encryptedData     -- serialized encryptedPDU
      OUT   privParameters    -- serialized privacy parameters
            )

    • statusInformation indicates if the encryption process was successful or not.

    • encryptKey the user's localized private privKey is the secret key that can be used by the encryption algorithm.

    • dataToEncrypt the serialized scopedPDU is the data to be encrypted.

    • encryptedData the encryptedPDU represents the encrypted scopedPDU, encoded as an OCTET STRING.

    • privParameters the privacy parameters, encoded as an OCTET STRING.

    If the privacy module returns failure, then the message cannot be sent and an error indication (encryptionError) is returned to the calling module.

    If the privacy module returns success, then the returned privParameters are put into the msgPrivacyParameters field of the securityParameters and the encryptedPDU serves as the payload of the message being prepared.

    Otherwise,

    b) If the securityLevel specifies that the message is not to be be protected from disclosure, then a zero-length OCTET STRING is encoded into the msgPrivacyParameters field of the securityParameters and the plaintext scopedPDU serves as the payload of the message being prepared.

  5. The securityEngineID is encoded as an OCTET STRING into the msgAuthoritativeEngineID field of the securityParameters. Note that an empty (zero length) securityEngineID is OK for a Request message, because that will cause the remote (authoritative) SNMP engine to return a Report PDU with the proper securityEngineID included in the msgAuthoritativeEngineID in the securityParameters of that returned Report PDU.

  6. a) If the securityLevel specifies that the message is to be authenticated, then the current values of snmpEngineBoots and snmpEngineTime corresponding to the securityEngineID from the LCD are used.

    Otherwise,

    b) If this is a Response or Report message, then the current value of snmpEngineBoots and snmpEngineTime corresponding to the local snmpEngineID from the LCD are used.

    Otherwise,

    c) If this is a Request message, then a zero value is used for both snmpEngineBoots and snmpEngineTime. This zero value gets used if snmpEngineID is empty.

    The values are encoded as INTEGER respectively into the msgAuthoritativeEngineBoots and msgAuthoritativeEngineTime fields of the securityParameters.

  7. The userName is encoded as an OCTET STRING into the msgUserName field of the securityParameters.

  8. a) If the securityLevel specifies that the message is to be authenticated, 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 =
      authenticateOutgoingMsg(
      IN  authKey               -- the user's localized authKey
      IN  wholeMsg              -- unauthenticated message
      OUT authenticatedWholeMsg -- authenticated complete message
          )

    • 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.

    • wholeMsg the complete serialized message to be authenticated.

    • authenticatedWholeMsg the same as the input given to the authenticateOutgoingMsg service, but with msgAuthenticationParameters properly filled in.

    If the authentication module returns failure, then the message cannot be sent and an error indication (authenticationFailure) is returned to the calling module.

    If the authentication module returns success, then the msgAuthenticationParameters field is put into the securityParameters and the authenticatedWholeMsg represents the serialization of the authenticated message being prepared.

    Otherwise,

    b) If the securityLevel specifies that the message is not to be authenticated then a zero-length OCTET STRING is encoded into the msgAuthenticationParameters field of the securityParameters. The wholeMsg is now serialized and then represents the unauthenticated message being prepared.

  9. The completed message with its length is returned to the calling module with the statusInformation set to success.

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.

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 and optionally a value for securityLevel, and values for contextEngineID or contextName for the counter. In addition, the securityStateReference data is returned if any such information is available at the point where the error is detected.

  1. If the received securityParameters is not the serialization (according to the conventions of [RFC3417]) of an OCTET STRING formatted according to the UsmSecurityParameters defined in section 2.4, then the snmpInASNParseErrs counter [RFC3418] is incremented, and an error indication (parseError) is returned to the calling module. Note that 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.

  2. 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 are:

    msgUserName

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

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

    or

    b) 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, b) should be chosen to facilitate engineID discovery. Otherwise the choice between a) and b) is an implementation issue.

  4. 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 and an error indication (unknownSecurityName) together with the OID and value of the incremented counter is returned to the calling module.

  5. If the information about the user indicates that it does not support the securityLevel requested by the caller, then the usmStatsUnsupportedSecLevels counter is incremented and an error indication (unsupportedSecurityLevel) together with the OID and value of the incremented counter is returned to the calling module.

  6. 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
           )

    • 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.

    • 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.

    If the authentication module returns failure, then the message cannot be trusted, so the usmStatsWrongDigests counter is incremented and 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.

  7. 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.

    a) 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:

    - the local value of snmpEngineBoots is 2147483647;

    - the value of the msgAuthoritativeEngineBoots field differs from the local value of snmpEngineBoots; or,

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

    If the message is considered to be outside of the Time Window then the usmStatsNotInTimeWindows counter is incremented and 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

    b) 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:

    1) 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, and

       - the latestReceivedEngineTime to the value of the value of the msgAuthoritativeEngineTime field.

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

       - the local notion of the value of snmpEngineBoots is 2147483647;

       - the value of the msgAuthoritativeEngineBoots field is less than the local notion of the value of snmpEngineBoots; or,

       - 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 the message is considered to be outside of the Time Window then an error indication (notInTimeWindow) is returned to the calling module.

       Note that this means that a too old (possibly replayed) message has been detected and is deemed unauthentic.

       Note that this procedure allows for the value of msgAuthoritativeEngineBoots in the message to be greater than the local notion of the value of snmpEngineBoots to allow for received messages to be accepted as authentic when received from an authoritative SNMP engine that has re-booted since the receiving SNMP engine last (re-)synchronized.

  8. a) If the securityLevel indicates that the message was protected from disclosure, then the OCTET STRING representing the encryptedPDU is decrypted according to the user's privacy protocol to obtain an unencrypted serialized scopedPDU value. To do so a call is made to the privacy module that implements the user's privacy protocol according to the abstract 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     -- serialized decrypted scopedPDU
            )

    • statusInformation indicates if the decryption process was successful or not.

    • decryptKey the user's localized private privKey is the secret key that can be used by the decryption algorithm.

    • privParameters the msgPrivacyParameters, encoded as an OCTET STRING.

    • encryptedData the encryptedPDU represents the encrypted scopedPDU, encoded as an OCTET STRING.

    • decryptedData the serialized scopedPDU if decryption is successful.

    If the privacy module returns failure, then the message can not be processed, so the usmStatsDecryptionErrors counter is incremented and 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 the message payload to be returned to the calling module.

    Otherwise,

    b) The scopedPDU component is assumed to be in plain text and is the message payload to be returned to the calling module.

  9. The maxSizeResponseScopedPDU is calculated. This is the maximum size allowed for a scopedPDU for a possible Response message. Provision is made for a message header that allows the same securityLevel as the received Request.

  10. The securityName for the user is retrieved from the usmUserTable.

  11. The security data is cached as cachedSecurityData, so that a possible response to this message can and will use the same authentication and privacy secrets. Information to be saved/cached is as follows:

    msgUserName, usmUserAuthProtocol, usmUserAuthKey usmUserPrivProtocol, usmUserPrivKey

  12. The statusInformation is set to success and a return is made to the calling module passing back the OUT parameters as specified in the processIncomingMsg primitive.

Last updated on