Message Processing Model for version 3 of the Simple Network Management Protocol (SNMPv3) 11 July 1997 J. Case SNMP Research Inc. case@snmp.com D. Harrington Cabletron Systems, Inc. dbh@cabletron.com B. Wijnen IBM T. J. Watson Research wijnen@vnet.ibm.com Status of this Memo This document is an Internet-Draft. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet-Drafts. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet- Drafts as reference material or to cite them other than as ``work in progress.'' To learn the current status of any Internet-Draft, please check the ``1id-abstracts.txt'' listing contained in the Internet- Drafts Shadow Directories on ds.internic.net (US East Coast), nic.nordu.net (Europe), ftp.isi.edu (US West Coast), or munnari.oz.au (Pacific Rim). Abstract This document describes the SNMP version 3 Message Processing Model for use in the SNMP architecture [SNMP-ARCH]. It defines the SNMP version 3 message format, and the procedures for coordinating the processing of a message in SNMPv3 format. Case/Harrington/Wijnen Expires December 1997 [Page 1] \ Draft SNMPv3 Message Processing Model July 1997 0. Issues . Message ::= instead of snmpV3Message ::= ? is this ok? . verify the abstract service primitives once more... names of primitives and parameters seem to keep changing. . Do we need to expand in section 2.2.2.x . Do we want the MIB to be a logical extension of the SNMPv2 MIB? Instead of having our own snmpV3MIB, we could import snmp and snmpMIBObjects from the SNMPv2-MIB (RFC1907) and then start assinging the counter from { snmp 33 } onwards. We could then also import snmpMIBCompliances and snmpMIBGroups from SNMPv2-MIB and define the snmpV3Compliance and snmpV3Group under those existing Registration points. Since we link SNMPv3 MP with RFC1902-1908 anyways, this actually seems better to me. . Someone needs to check elements of procedures. . acknowledgements needs expansion . snmpUnknownPduHandlers needs to be included in elements of procedure . should we have one complete snmpV3AllCompliance that includes the snmpCompliance from RFC1907? see MIB below. Or we could keep two and have snmpV2andV3Compliance . must we return the original Request PDU, so the application can determine the request that led to an errorIndication? Conceptually the SNMP engine needs to also cache the outgoing requests when it caches info about a outgoing Request message. Should we describe what processResponsePDU() returns in that circumstance. . do we want to define snmpCommunityGroup here or under coexistence? . should version-selection and application multiplexing elements of procedure be described in MP document or Architecture document? This is especially problematic considering snmpInPkts and snmpInBadVersions counters. Case/Harrington/Wijnen Expires December 1997 [Page 2] \ Draft SNMPv3 Message Processing Model July 1997 0.1. Change Log [version 3.4] . engine, not Message Processing, interacts with network . editorial changes . registration is per PDU type . fields in MsgFlags modified and discussed . Changes as to address comments by dbh . Changes to get Primitives inline with latest list . ran MIB through SMICng . updated picture in Overview . update primitives to match editors' discussions . updates addresses to international format . removed editors' notes as appropriate . converted editors' notes into Issues as appropriate . modified text as per editors' discussions . posted to snmpv3 mailing list [version 3.3] . spelling changes . elements of procedure expanded . changes snmpMPCxxxx to snmpV3xxxx in MIB [version 3.2] . updated change log [version 3.1] . changes as a result of 2nd interim meeting . adopt to new abstract service interface primitives . use new agreed upon names for things . add a new overview of Message Processing Subsystem . Remove MP Model selection descriptions . Remove Multiplexing layer descriptions . Rewrite all the elements of procedure . Redo the SNMPv3-MIB . Removed security threats section. . Did a quick spell check on AIX . Message Processing and Control changed to Message Processing . change orangelets to applications . stats counters should be in the module where they make sense . statistics counters moved between documents on a case-by-case basic, according to where they make the most sense . modified to match consitent terminology . improved pictures . added elements of procedure . changed snmpv3Message to Message . modified naming of msgFlags . securityParameters size limitation removed . removed limits on lengths of contextEngineID and contextName . new names for the application types . more bullets to make it easier to read . primitives have consistent format with expanded comments . glossary (not filled in) removed [version 3.0] Case/Harrington/Wijnen Expires December 1997 [Page 3] \ Draft SNMPv3 Message Processing Model July 1997 . published as draft-ietf-snmpv3-mpc-model-01.txt [version 2.1] . ?? not sure if there were any changes [version 2.0] . changes as a result of 1st interim meeting . some new wording in introduction . rewording in overview with a drawing . added reportFlag to msgFlags . describe overall MPC model: MPC Selection mechanism . describe overall MPC model: MPC Multiplexing Layer . describe v3MPC model. . added the abstract interface definitions for interacting with SNMPv3 USEC Model . added the abstract interface definitions for interacting with applications . added MIB definitions for error Counters (statistics) . removed references to LPM and Access Control [version 1.2] . add text regarding security threats . add text regarding access control . remove text regarding agent installation of views . removed Naming-Scope . removed discussion of MPC determining to which application a message/request should be forwarded. . added Issues section . added sending a notification for an application . spell-check, renumber, paginate [version 1.1] . separated architecture from Message Processing and Control Model for SNMPv3 . clarified snmpV3Message definition . rewrote introduction and overviews . wrote transport mappings . documented snmpV3Message format . changed Quality of Service (QoS) to Level of Security (LoS) . changed end-user to security entity . Tried to clarify MMS of engine versus MMS of message. . change security entity to securityIdentity [version 1.0] . Initial document, with SNMPng architecture and MPCv3 merged. Case/Harrington/Wijnen Expires December 1997 [Page 4] \ Draft SNMPv3 Message Processing Model July 1997 1. Introduction The Architecture for describing Internet Management Frameworks [SNMP-ARCH] is composed of multiple subsystems: 1) a Message Processing Subsystem, 2) a Security Subsystem, 3) an Access Control Subsystem, Applications make use of the services of these subsystems. It is important to understand the SNMP architecture and its terminology to understand where the version-specific Message Processing Model described in this document fits into the architecture and interacts with other subsystems within the architecture. The reader is expected to have read and understood the description of the SNMP architecture, as defined in [SNMP-ARCH]. The Message Processing Subsystem of an SNMP engine interacts with the SNMP engine, interacts with the Security Subsystem and interacts with applications. It uses data elements defined by the SNMPv3 Message Processing Model, within the constraints of the architecture, and interacts with other models within the constraints of the architecture. A Message Processing Model has the responsibility for coordinating the sending and receiving of SNMP messages via the SNMP engine, and for coordinating the interaction with other subsystems to acquire the desired services for the processing of an SNMP message. It is the purpose of this document to define the specific SNMPv3 Message Processing Model. Other (future) documents can add specific models for Message Processing of other SNMP versions (like a v1MP and/or a v2cMP) which then fit into the overall SNMP architecture. Case/Harrington/Wijnen Expires December 1997 [Page 5] \ Draft SNMPv3 Message Processing Model July 1997 2. Overview The following illustration depicts the Message Processing in relation to SNMP applications, the Security Subsystem and Transport Mappings. +--------------------------------------------------------------------+ | SNMP Entity | | | | +----------------------------------------------------------------+ | | | Applications | | | | +------------+ +--------------+ | | | | | Command | | Notification | | | | | | Generator | | Originator | +-----------+ +-------------+ | | | | +------------+ +--------------+ | Proxy | | Other | | | | | +------------+ +--------------+ | Forwarder | | Application | | | | | | Command | | Notification | +-----------+ +-------------+ | | | | | Responder | | Receiver | | | | | +------------+ +--------------+ | | | +----------------------------------------------------------------+ | | ^ ^ ^ ^ | | | | | | | | | | | | | | v v v v | | +----------------------------------------------------------------+ | | | Message | Message Processing Abstract Service Interface | | | | | Processing +-----------------------------------------------+ | | | | Subsystem ^ ^ ^ ^ | | | | | | | | | | | +--------------+ | | | | | | | +------------+ | | | | | | | | | Security | | | | | | | | | | Subsystem | | | | | | | | | | | | v v v v | | | |+----------+| | +------+ +---------+ +--------+ +-----------+ | | | ||User-based||<->| v3MP | | v2cMP * | | v1MP * |..| otherMP * | | | | ||Security || | +------+ +---------+ +--------+ +-----------+ | | | ||Model || | ^ ^ ^ ^ | | | |+----------+| | | | | | | | | | | +----|---------|-----------|------------|---------+ | | +------------+ | | | | | | v v v v | | +----------------------------------------------------------+ | | | Message Processing Model selection (incoming only) | | | +----------------------------------------------------------+ | | ^ | | | | | v | | +-----------------------------------------------------------+ | | | TRANSPORT MAPPING (for example RFC1906) | | +--------------------------------------------------------------------+ Case/Harrington/Wijnen Expires December 1997 [Page 6] \ Draft SNMPv3 Message Processing Model July 1997 2.1. Message Processing Subsystem The SNMP Message Processing Subsystem is part of an SNMP engine within an SNMP entity. It can possibly handle multiple SNMP Message formats (like the SNMPv1 [RFC1157], SNMPv2c [RFC1901] and SNMPv3 message formats). The Message Processing Model selection mechanism receives and sends messages from/to the network. For incoming messages, the SNMP engine determines the specific message format of an incoming SNMP message and then selects the corresponding version-specific Message Processing module to further process the SNMP message. For outgoing messages, an application specifies which SNMP message format must be used and based on that the SNMP engine selects the corresponding version-specific Message Processing module, within the Message Processing Subsystem, to generate and send the message. The details of how the SNMP engine selects the proper version-specific Message Processing module are implementation dependent. This document defines the SNMP version3 Message Processing (v3MP) Model and the corresponding SNMPv3 message format. The SNMP engine and the Message Processing Subsystem, while sending and receiving SNMP messages, collect statistics about SNMP messages and the behavior of the SNMP engine. These statistics are maintained in managed objects to make them accessible to remote SNMP entities. For example, the snmpInPkts counter [RFC1907] counts all incoming SNMP packets regardless of the message format. The details on how this is done in a system that supports multiple message formats is outside the scope of this document. This document defines the v3MP managed objects, and the MIB module which contains them. This document also describes how these managed objects might be used to provide useful network management. The v3MP Model is designed to guarantee certain behaviors and to meet a particular set of requirements. These goals are met by controlling the processing of messages, sometimes by defining a fixed behavior that must be adhered to by a conforming implementation of this model, sometimes by defining options which can be specified by the user to cause processing to meet optional requirements. This document describes how the internal interactions are coordinated and constrained by the v3MP Model. 2.2. Message Processing External Interfaces The SNMPv3 Message Processing Model is a specification of a model of Message Processing within the Message Processing Subsystem, which interacts with other subsystems, requesting services from, and performing services for, those other subsystems. Case/Harrington/Wijnen Expires December 1997 [Page 7] \ Draft SNMPv3 Message Processing Model July 1997 2.2.1. Message Processing Interface to Security Subsystem An SNMPv3 Message Processing module interacts with one or more SNMP Security Models to ensure that the proper security measures (authentication, timeliness checking, en/decryption) are applied to the SNMP messages being sent and received. It uses the abstract service interface to the Security Model, as defined by the SNMP architecture, to request services from such a security module. 2.2.2. Message Processing Abstract Service Interface When an application wants to send an SNMP PDU, it does so according to the abstract service interface of the Message Processing Subsystem, as defined by the SNMP architecture [SNMP-ARCH]. 2.2.2.1. Sending an SNMP Request or Notification The Message Processing Subsystem provides the following primitive for an application to send an SNMP Request or Notification to another SNMP entity: sendPdu( transportDomain -- transport domain to be used transportAddress -- destination network address messageProcessingModel -- typically, SNMP version securityModel -- Security Model to use securityName -- on behalf of this principal LoS -- Level of Security requested contextEngineID -- data from/at this entity contextName -- data from/in this context PDU -- SNMP Protocol Data Unit expectResponse -- TRUE or FALSE ) Case/Harrington/Wijnen Expires December 1997 [Page 8] \ Draft SNMPv3 Message Processing Model July 1997 2.2.2.2. Registering Responsibility for Handling SNMP PDUs An application may want to take responsibility for handling a specific set of SNMP operations, for a specific contextEngineID. Applications register/unregister responsibility for a specific contextEngineID, for specific pduTypes, with the Application Multiplexor according to these primitives: statusInformation = -- success or errorIndication registerContextEngineID( contextEngineID -- take responsibility for this one pduType -- the pduType(s) to be registered ) unregisterContextEngineID( contextEngineID -- give up responsibility for this one pduType -- the pduType(s) to be unregistered ) 2.2.2.3. Processing an incoming SNMP Request or Notification Once an incoming message has passed the version-specific Message Processing (v3MP) and is ready for processing by an application, then the message is passed to the proper application. The Application Multiplexor determines the PDU type and contextEngineID for the scopedPDU, then determines which application has registered to handle that PDU type and contextEngineID. The Application Multiplexor uses the following primitive to pass an incoming SNMP Response PDU to an application: processPdu( -- process Request/Notification PDU contextEngineID -- data from/at this SNMP entity contextName -- data from/in this context PDU -- SNMP Protocol Data Unit maxSizeResponseScopedPDU -- maximum size of the Response PDU securityModel -- Security Model in use securityName -- on behalf of this principal LoS -- Level of Security stateReference -- reference to state information ) -- needed when sending a response 2.2.2.4. Sending an SNMP Response The Message Processing Subsystem provides the following primitive for an application to return an SNMP Response PDU to a processed SNMP Request or Notification: returnResponsePdu( contextEngineID -- data from/at this SNMP entity contextName -- data from/in this context Case/Harrington/Wijnen Expires December 1997 [Page 9] \ Draft SNMPv3 Message Processing Model July 1997 PDU -- SNMP Protocol Data Unit maxSizeResponseScopedPDU -- maximum size of the Response PDU securityModel -- same as on incoming request securityName -- same as on incoming request LoS -- same as on incoming request stateReference -- reference to state information -- as presented with the request statusInformation -- success or errorIndication ) -- error counter OID/value if error 2.2.2.5. Processing an incoming SNMP Response The Message Processing Subsystem provides the following primitive to pass an incoming SNMP Response PDU to an application: processResponsePdu( -- process Response PDU contextEngineID -- data from/at this SNMP entity contextName -- data from/in this context PDU -- SNMP Protocol Data Unit LoS -- Level of Security statusInformation -- success or errorIndication ) Case/Harrington/Wijnen Expires December 1997 [Page 10] \ Draft SNMPv3 Message Processing Model July 1997 3. The SNMPv3 Message Format This is the format of an SNMP message for the SNMPv3 Message Processing Model. DEFINITIONS ::= BEGIN Message ::= SEQUENCE { -- administrative parameters (globalData) version INTEGER { snmpv3 (3) }, msgID INTEGER (0..2147483647), mms INTEGER (484..2147483647), msgFlags OCTET STRING (SIZE(1)), -- .... ...1 authFlag -- .... ..1. privFlag -- .... .1.. reportableFlag -- .... 1... reportFlag -- -- Please observe: -- .... ..00 is OK, means noAuthNoPriv -- .... ..01 is OK, means authNoPriv -- .... ..10 reserved, must NOT be used. -- .... ..11 is OK, means authPriv securityModel INTEGER (0..2147483647), -- security model-specific parameters -- format defined by Security Model securityParameters OCTET STRING -- local-processing model-specific data data scopedPduData } scopedPduData ::= CHOICE { plaintext scopedPDU, encryptedPDU OCTET STRING -- encrypted value } scopedPDU ::= SEQUENCE { contextEngineID OCTET STRING contextName OCTET STRING data ANY -- e.g. PDUs as defined in RFC1905 } END Case/Harrington/Wijnen Expires December 1997 [Page 11] \ Draft SNMPv3 Message Processing Model July 1997 3.1. version The version field is set to snmpv3(3) and identifies the message as an SNMP version 3 Message. 3.2. msgID The msgID is used between two SNMP entities to coordinate request messages and responses, and by the v3MP to coordinate the processing of the message by different subsystem models within the architecture. Note that the request-id in the PDU is used by SNMP applications to identify the request; the msgID is used by the engine to identify the message which carries a request. The engine may need to identify the message even if the decryption of the request (and request-id) fails. No assumption should be made that the value of the msgID and the value of the request-id are equivalent. 3.3. mms The maximum message size supported by the sender of the message. That is the maximum message size that the sender can accept when another SNMP engine sends an SNMP message (be it a response or any other message) to the sender of this message. When an SNMP message is being generated, the mms is provided by the SNMP engine which generates the message. At the receiving SNMP engine the mms is used to determine how big the Response to a Request message can be made. 3.4. msgFlags The msgFlags field contains flags to control the processing of the message. a) reportableFlag If the reportableFlag is set, then Report PDUs are allowed to be returned to the sender under those conditions which cause the generation of Report PDUs. If the reportableFlag is zero, then a Report PDU must not be sent. The reportableFlag should always be zero when the message is a Report PDU, a Response PDU, or an SNMPv2-trap PDU. b) reportFlag ReportPDUs are engine-to-engine communications and are processed directly by the Message Processing model, and are not passed to applications for processing, unlike all other PDU types. The reportFlag is set for a Report PDU so the Message Processing Model can easily recognize a Report PDU. Case/Harrington/Wijnen Expires December 1997 [Page 12] \ Draft SNMPv3 Message Processing Model July 1997 The authFlag and privFlag in the msgFlags are used to indicate the Level of Security (LoS) that has been applied to the message before sending it on the wire. The same Level of Security should be applied when the message is received and when the contents of the message is being processed. There are 3 Levels of Security, namely noAuthNoPriv, which is lower than authNoPriv, which is in turn lower than authPriv. See the SNMP architecture document [SNMP-ARCH] for details about the Level of Security. a) authFlag If the authFlag is set, then the securityModel in use, must identify the securityName on whose behalf an SNMP message is being processed or generated and must authenticate such identification. In addition , the contents of the message must be authenticated to ensure that: - the message was not modified in transit - the message was not replayed - the message was not redirected If the authFlag is not set, then the securityModel in use must identify the securityName on whose behalf a request is being processed or generated, but it does not need to authenticate such identification. Also there is no need to authenticate the message in this case. b) privFlag If the privFlag is set, then the securityModel in use, must also protect the scopedPDU in an SNMP message from disclosure, i.e. must encrypt/decrypt the scopedPDU. If the privFlag is zero, then the securityModel in use does not need to protect the data from disclosure. It is an explicit requirement of the SNMP architecture that if privacy is selected, then authentication is also required. That means that if the privFlag is set, then the authFlag should also be set. The combination of the authFlag and the privFlag comprises a Level of Security (LoS) as follows: authFlag zero and privFlag one -> invalid combination authFlag zero and privFlag zero -> LoS is noAuthNoPriv authFlag one and privFlag zero -> LoS is authNoPriv authFlag one and privFlag one -> LoS is authPriv Case/Harrington/Wijnen Expires December 1997 [Page 13] \ Draft SNMPv3 Message Processing Model July 1997 3.5. securityModel The v3MP supports the concurrent existence of multiple security models to provide security services for SNMPv3 messages. The securityModel identifies which security model should be used to provide security processing for the message. The mapping to the appropriate implementation within an SNMP engine is done in an implementation dependent manner. 3.6. securityParameters The securityParameters filed is used for communication between the Security Model modules in the sending and receiving SNMP engines. This data is used exclusively by the security model, and the contents and format of the data is defined by the Security Model. This OCTET STRING is not interpreted by the v3MP, but is passed to the local implementation of the Security Model indicated by the securityModel field in the message. 3.7. scopedPduData The scopedPduData represents either the plain text scopedPDU if the privFlag in the msgFlags is zero, or it represents an encryptedPDU which must be decrypted by the securityModel in use to produce a plaintext scopedPDU. Case/Harrington/Wijnen Expires December 1997 [Page 14] \ Draft SNMPv3 Message Processing Model July 1997 3.8. scopedPDU The scopedPDU contains information to identify an administratively unique context and a PDU. The object identifiers in the PDU refer to managed objects which are (expected to be) accessible within the specified context. 3.8.1. contextEngineID The contextEngineID in the SNMPv3 message, uniquely identifies, within an administrative domain, an SNMP entity that may realize an instance of a context with a particular contextName. For incoming messages, the cpontextID is used to determine to which application the scopedPDU should be sent for processing. For outgoing messages, the v3MP just sets the contextEngineID as provided by the application that requests for a message to be sent. 3.8.2. contextName This is a locally unique name for a context, within the SNMP entity specified by the contextEngineID, which may realize the managed objects referenced within the PDU. An application uses the contextName during processing. The v3MP, for outgoing messages, just set the contextName as provided by the application that requests for a message to be sent. 3.8.3. data The data contains the PDU. The PDU contains the PDU type that is also used by the v3MP to determine the type of incoming SNMP message. The v3MP specifies that the PDU must be one of those specified in [RFC1905]. Case/Harrington/Wijnen Expires December 1997 [Page 15] \ Draft SNMPv3 Message Processing Model July 1997 4. Elements of Procedure This section describes the procedures followed by an SNMP engine when processing SNMP messages according to the SNMPv3 Message Processing Model. 4.1. Receiving an SNMP Message from the Network This section describes the procedure followed by an SNMP engine whenever it receives an SNMP message. Please note that some steps might be done in the SNMP engine itself, specifically if the implementations supports multiple Message Processing Models. Yet the complete procedure is described here, so that for a single-version implementation, the complete elements of procedure are in one place. Please note, that in order to not make the procedures too complicated, we do not always explicitly say when state information needs to be released. The general rule is, that if state information is available when a message gets discarded for further processing, that at that time the state information must also be released. 1) The snmpInPkts counter [RFC1907] is incremented. That is if such has not been done yet by a possible Message Processing Model selection process in the SNMP engine. 2) If the received message is not the serialization (according to the conventions of [RFC1906]) of a Message value, then the snmpInASNParseErrs counter [RFC1907] is incremented, and the message is discarded without further processing. 3) The values for the various message components are extracted from the message. 4) If the value of the version component has a value other than 3 then the message is either processed according to some other version-specific Message Processing Model, or the snmpInBadVersions counter [RFC1907] is incremented (that is if not yet done by a possible Message Processing Model selection process in the SNMP engine), and the message is discarded without further processing. 5) If the value of the securityModel component does not match a supported securityModel, then the snmpUnknownSecurityModels counter is incremented, a Report PDU is generated and the message is discarded without further processing. 6) The Level of Security (LoS) is determined from the msgFlags component as follows: a) if neither the authFlag nor the privFlag is set, then the LoS is set to noAuthNoPriv. Case/Harrington/Wijnen Expires December 1997 [Page 16] \ Draft SNMPv3 Message Processing Model July 1997 Otherwise, b) If the authFlag is set and the privFlag is zero, then the LoS is set to authNoPriv. Otherwise, c) If the authFlag is set and the privFlag is set, then the LoS is set to authPriv. Otherwise, d) The snmpInvalidMsgFlags counter is incremented, a Report PDU is generated and the message is discarded without further processing. 7) The security module implementing the Security Model as specified by the securityModel component is called for authentication and privacy services. This is done according to the abstract service primitive: processMsg( messageProcessingModel -- typically, SNMP version msgID -- of the received message mms -- of the sending SNMP entity msgFlags -- for the received message securityParameters -- for the received message securityModel -- for the received message LoS -- Level of Security wholeMsg -- as received on the wire wholeMsgLength -- length as received on the wire ) The security module returns the results according to the abstract service interface primitive: returnProcessedMsg( securityName -- identification of the principal scopedPDU, -- message (plaintext) payload maxSizeResponseScopedPDU -- maximum size of a Response PDU securityStateReference -- reference to security state -- information, needed for response statusInformation -- errorIndication or success ) -- error counter OID/value if error If an errorIndication is returned by the security module, then a Report PDU is generated with the returned errorCounter in the varBindList, and the message is discarded without further processing. Case/Harrington/Wijnen Expires December 1997 [Page 17] \ Draft SNMPv3 Message Processing Model July 1997 8) If the reportFlag in the msgFlags component is set, then the scopedPDU is parsed. a) If the PDU is not a Report PDU, then the message is discarded without further processing. This also means that any possible security state information is discarded. Otherwise, b) The errorCounter is inspected to determine the cause for the Report PDU. The value of the msgID component is used to determine from the list of outstanding SNMP messages, which application is to be posted with an errorIndication. If no such outstanding SNMP message is found, then the message is discarded without further processing. This also means that any possible security state information is discarded. Otherwise, c) The application is informed according to the abstract service primitive: processResponsePdu( -- process Response PDU contextEngineID -- data from/at this SNMP entity contextName -- data from/in this context PDU -- SNMP Protocol Data Unit LoS -- Level of Security statusInformation -- success or errorIndication ) Any cached information about the message, generated by this SNMP engine, with the same msgID as the value of the msgID component is discarded. This includes any possible security state information. Processing of the message is complete as far as the Message Processing module is concerned. 9) The scopedPDU is parsed to extract the contextEngineID, the contextName and the PDU. If any parse error occurs, then the snmpInASNParseErrs counter [RFC1907] is incremented, a report PDU is generated, and the message is discarded without further processing. This also means that any possible security state information is discarded. Case/Harrington/Wijnen Expires December 1997 [Page 18] \ Draft SNMPv3 Message Processing Model July 1997 10) The message type is determined (how is an implementation issue) to be either a Response message or a Request or Notification message. a) If this is a Response message, then the value of the msgID component is used to determine from the list of outstanding SNMP messages, which application is to process the Response PDU. 1) If no such outstanding SNMP message is found, then the message is discarded without further processing. This also means that any possible security state information is discarded. Otherwise, 2) The Response PDU is passed to the application according to the abstract service primitive: processResponsePdu( -- process Response PDU contextEngineID -- data from/at this SNMP entity contextName -- data from/in this context PDU -- SNMP Protocol Data Unit LoS -- Level of Security statusInformation -- success or errorIndication ) Any cached information about the message, generated by this SNMP engine, with the same msgID as the value of the msgID component is discarded. This includes any possible security state information. Processing of the message is complete as far as the Message Processing module is concerned. Otherwise, b) If this is a Request message or a Notification message, then it is determined which application should process the message. This is based on the PDU type and the list of applications and their registered contextEngineIDs. 1) If no such application can be found because none registered for the contextEngineID, then the snmpUnknownContextEngineIDs counter is incremented, a Report PDU is generated, and the message is discarded without further processing. This also means that any possible security state information is discarded. Otherwise, 2) If no such application can be found for other reasons, then the snmpUnknownApplications counter is incremented, a Report PDU is generated, and the message is discarded Case/Harrington/Wijnen Expires December 1997 [Page 19] \ Draft SNMPv3 Message Processing Model July 1997 without further processing. This also means that any possible security state information is discarded. Otherwise, 3) Information about the message is cached and a stateReference is created (implementation specific). Information to be cached includes: value version component, value msgID component, value of LoS, value of msgFlags component, value of mms component, value of securityModel component, value of maxSizeResponseScopedPDU, securityStateReference 11) The SNMP PDU is passed to the selected application according to the abstract service interface primitive: processPdu( -- process Request/Notification PDU contextEngineID -- data from/at this SNMP entity contextName -- data from/in this context PDU -- SNMP Protocol Data Unit maxSizeResponseScopedPDU -- maximum size of the Response PDU securityModel -- Security Model in use securityName -- on behalf of this principal LoS -- Level of Security stateReference -- reference to state information ) -- needed when sending a response Processing of the message is complete. The application processes the PDU and when done will return a Response PDU using the abstract service interface primitive: returnResponsePdu( contextEngineID -- data from/at this SNMP entity contextName -- data from/in this context PDU -- SNMP Protocol Data Unit maxSizeResponseScopedPDU -- maximum size of the Response PDU securityModel -- same as on incoming request securityName -- same as on incoming request LoS -- same as on incoming request stateReference -- reference to state information -- as presented with the request statusInformation -- success or errorIndication ) -- error counter OID/value if error Case/Harrington/Wijnen Expires December 1997 [Page 20] \ Draft SNMPv3 Message Processing Model July 1997 The v3MP procedures for this returned Response PDU are described in section 4.2. 4.2. Sending an SNMP Message to the Network This section describes the procedure followed by an SNMP engine whenever it must send an SNMP message. There are three ways that can cause a message to be sent: - An application wants an SNMP PDU to be sent to another (remote) application. The application can request this according to the abstract service primitive: sendPdu( transportDomain -- transport domain to be used transportAddress -- destination network address messageProcessingModel -- typically, SNMP version securityModel -- Security Model to use securityName -- on behalf of this principal LoS -- Level of Security requested contextEngineID -- data from/at this entity contextName -- data from/in this context PDU -- SNMP Protocol Data Unit expectResponse -- TRUE or FALSE ) - An application wants a response to be sent back to the originator of an SNMP Request. This means that this is the resulting response of step 11) of section 4.1. - A Report PDU needs to be send as the result of a v3MP internal detection of a problem, or as the result of a security module or an application returning statusInformation which contains an errorIndication and the OID and value of an (incremented) error counter. The following elements of procedures are followed to generate the SNMP message according to the SNMPv3 message format. 1) a) If the request to send a message is caused by the sendPdu primitive, then: 1) If the messageProcessingModel has a value other than 3, then the request is either processed according to some other version-specific Message Processing Model, or an error (implementation specific) is returned to the calling application. Otherwise, Case/Harrington/Wijnen Expires December 1997 [Page 21] \ Draft SNMPv3 Message Processing Model July 1997 2) The parameters are verified to be valid and supported by the SNMPv3 Message Processing module. If not, then an error (implementation specific) is returned to the calling application. Otherwise, 3) All parameters are valid; use these values in the process: - expectResponse switch as passed by application. - a unique msgID is generated. It is best to use unpredictable numbers for the msgID. - msgFlags are set as follows: - if LoS specifies noAuthNoPriv, then authFlag and privFlag are both set to zero. - if LoS specifies authNoPriv, then authFlag is set to one and privFlag is set to zero. - If LoS specifies authPriv, then authFlag is set to one and privFlag is set to one. - If expectResponse is TRUE, then the reportableFlag is set to one otherwise it is set to zero. - All other msgFlags bits are set to zero. - the transportDomain and transportAddress as passed by the application. Otherwise, b) If the request to send a message is caused by the returnResponsePdu primitive, then: 1) The parameters are verified to be valid and are in accordance with the cached state information pointed to by the stateReference parameter. If not, then an (implementation specific) error is returned to the calling application. Otherwise: 2) If the statusInformation indicates an error that should cause a Report PDU, then a Report PDU is constructed with a varBindList that contains the OID and value of the increment error counter that was returned; continue with step 1.c. Otherwise, 3) If the statusInformation indicates noError then this is a Response PDU and all parameters are valid; then use these values in the process: - expectResponse switch is FALSE. - msgID as is obtained via stateReference - msgFlags are set as follows: - if LoS specifies noAuthNoPriv, then authFlag and Case/Harrington/Wijnen Expires December 1997 [Page 22] \ Draft SNMPv3 Message Processing Model July 1997 privFlag are both set to zero. - if LoS specifies authNoPriv, then authFlag is set to one and privFlag is set to zero. - If LoS specifies authPriv, then authFlag is set to one and privFlag is set to one. - All other msgFlags bits are set to zero. - the transportDomain and transportAddress as saved in the state information. c) If the request to send a message is caused by a Report PDU, then the internal v3MP process passes the proper parameters that are needed in the following steps: - expectResponse switch is FALSE. - msgID as in the received message or from the state information - msgFlags are set as follows: - If the Report PDU is cause by a notInTimeWindow error then the authFlag is set to one, otherwise it is set to zero. - The reportFlag is set to one. - all other msgFlags bits are set to zero. - the transportDomain and transportAddress as in the received message or as saved in the state information. 2) The version component of the message is set to snmpv3 (3). 3) The mms is set to an implementation defined value within the range allowed by the definition of mms in section 3. 4) The msgFlags are set as specified in step 1. 5) The securityModel is set to the securityModel as specified or as obtained from the state information. 6) An SNMP message is to be generated by the security module. The securityModel is used to determine which Security Model to use. a) If the expectResponse switch is TRUE, then an SNMP Response message is to be generated. The security module is called according to the abstract service interface primitive: generateResponseMsg( messageProcessingModel -- typically, SNMP version msgID -- for the outgoing message mms -- of the sending SNMP entity msgFlags -- for the outgoing message securityParameters -- filled in by Security Module securityModel -- for the outgoing message scopedPDU -- message (plaintext) payload securityStateReference -- reference to security state Case/Harrington/Wijnen Expires December 1997 [Page 23] \ Draft SNMPv3 Message Processing Model July 1997 -- information, as received in ) -- processPdu primitive Otherwise, b) If the expectResponse switch is FALSE, then an SNMP Response message is to be generated. The security module is called according to the abstract service interface primitive: generateRequestMsg( messageProcessingModel -- typically, SNMP version msgID -- for the outgoing message mms -- of the sending SNMP entity msgFlags -- for the outgoing message securityParameters -- filled in by Security Module securityModel -- for the outgoing message securityName -- on behalf of this principal LoS -- Level of Security requested snmpEngineID -- authoritative SNMP entity scopedPDU -- message (plaintext) payload ) 7) Upon completion of the security processing, the security module returns a completed message according to the abstract service interface primitive: returnGeneratedMsg( wholeMsg -- complete generated message wholeMsgLength -- length of the generated message statusInformation -- errorIndication or success ) a) If the statusInformation returns an errorIndication, then an errorIndication is returned to the calling application or v3MP internal function. Otherwise, b) The generated message is sent over the transport specified by the transportDomain to the address specified by the transportAddress. Processing is complete as far as the Message Processing module is concerned. 4.3. Application Registration for Handling PDU types Applications that want to process certain PDUs must register with the Message Processing Subsystem and specify which contextEngineID and which PDU types they want to take responsibility for. Case/Harrington/Wijnen Expires December 1997 [Page 24] \ Draft SNMPv3 Message Processing Model July 1997 The following procedures are followed for this registration process. 1) An application registers according to the abstract interface primitive: statusInformation = -- success or errorIndication registerContextEngineID( contextEngineID -- take responsibility for this one pduType -- the pduType(s) to be registered ) 2) The parameters are checked to be valid; if not an errorIndication (invalidParameter) is returned to the application. 3) a) If the contextEngineID is equal to the snmpEngineID of the processing SNMP engine, then only one application can register for each pduType. 1) If another application already registered, then an errorIndication (alreadyRegistered) is returned to the application. Otherwise, 2) The registration is saved so that SNMP messages with a payload that matches the registered contextEngineID and pduType(s) can be dispatched to this application. b) If the contextEngineID is not equal to the snmpEngineID of the processing SNMP engine, then the registration is saved so that SNMP messages with a payload that matches the registered contextEngineID and pduType(s) can be dispatched to this application. 4.3. Application Unregistration for Handling Payloads (PDUs) Applications that no longer want to process certain PDUs must unregister with the Message Processing Subsystem and specify which contextEngineID and which PDU types they no longer want to take responsibility for. The following procedures are followed for this unregistration process. 1) An application unregisters according to the abstract interface primitive: unregisterContextEngineID( contextEngineID -- give up responsibility for this one Case/Harrington/Wijnen Expires December 1997 [Page 25] \ Draft SNMPv3 Message Processing Model July 1997 pduType -- the pduType(s) to be unregistered ) 2) The parameters are checked to be valid; if not the request is ignored. 3) a) If the contextEngineID and pduType combination have indeed been registered, then the registration is deleted. b) If nu such registration exists, then the request is ignored. Case/Harrington/Wijnen Expires December 1997 [Page 26] \ Draft SNMPv3 Message Processing Model July 1997 5. Definitions 5.1. Definitions for the SNMPv3 Message Processing Model SNMPv3-MIB DEFINITIONS ::= BEGIN IMPORTS MODULE-COMPLIANCE, OBJECT-GROUP FROM SNMPv2-CONF MODULE-IDENTITY, OBJECT-TYPE, snmpModules, Counter32 FROM SNMPv2-SMI; snmpV3MIB MODULE-IDENTITY LAST-UPDATED "9707110000Z" -- 11 July 1997, midnight ORGANIZATION "SNMPv3 Working Group" CONTACT-INFO "WG-email: snmpv3@tis.com Subscribe: majordomo@tis.com In message body: subscribe snmpv3 Chair: Russ Mundy Trusted Information Systems postal: 3060 Washington Rd Glenwood MD 21738 USA email: mundy@tis.com phone: +1-301-854-6889 Co-editor: Dr. Jeffrey Case SNMP Research, Inc. postal: 3001 Kimberlain Heights Rd Knoxville, TN 37920-9716 USA email: case@snmp.com phone: +1-615-573-1434 Co-editor Dave Harrington Cabletron Systems, Inc postal: Post Office Box 5005 MailStop: Durham 35 Industrial Way Rochester NH 03867-5005 USA email: dbh@cabletron.com phone: +1- 603-337-7357 Co-editor: Bert Wijnen IBM T. J. Watson Research postal: Schagen 33 3461 GL Linschoten Netherlands email: wijnen@vnet.ibm.com phone: +31-348-432-794 Case/Harrington/Wijnen Expires December 1997 [Page 27] \ Draft SNMPv3 Message Processing Model July 1997 " DESCRIPTION "The MIB for the SNMPv3 Message Processing Model" ::= { snmpModules 8 } -- check if assignment is OK -- Administrative assignments **************************************** snmpV3Admin OBJECT IDENTIFIER ::= { snmpV3MIB 1 } snmpV3MIBObjects OBJECT IDENTIFIER ::= { snmpV3MIB 2 } snmpV3MIBConformance OBJECT IDENTIFIER ::= { snmpV3MIB 3 } -- Statistics for SNMPv3 Message Processing Model ******************** snmpV3Stats OBJECT IDENTIFIER ::= { snmpV3MIBObjects 1 } snmpUnknownSecurityModels OBJECT-TYPE SYNTAX Counter32 MAX-ACCESS read-only STATUS current DESCRIPTION "The total number of packets received by the SNMP engine which were dropped because they referenced a securityModel that was not known to or supported by the SNMP engine, e.g. was not registered by any application. " ::= { snmpV3Stats 1 } snmpInvalidMsgFlags OBJECT-TYPE SYNTAX Counter32 MAX-ACCESS read-only STATUS current DESCRIPTION "The total number of packets received by the SNMP engine which were dropped because the msgFlags component of the message specified invalid flags. " ::= { snmpV3Stats 2 } snmpUnknownContextEngineIDs OBJECT-TYPE SYNTAX Counter32 MAX-ACCESS read-only STATUS current DESCRIPTION "The total number of packets received by the SNMP engine which were dropped because they referenced a contextEngineID that was not known to the SNMP engine e.g. was not registered by any application. " ::= { snmpV3Stats 3 } snmpUnknownApplications OBJECT-TYPE SYNTAX Counter32 MAX-ACCESS read-only Case/Harrington/Wijnen Expires December 1997 [Page 28] \ Draft SNMPv3 Message Processing Model July 1997 STATUS current DESCRIPTION "The total number of packets received by the SNMP engine which were dropped because they could not be passed to an application for undefined reasons. " ::= { snmpV3Stats 4 } snmpUnknownPduHandlers OBJECT-TYPE SYNTAX Counter32 MAX-ACCESS read-only STATUS current DESCRIPTION "The total number of packets received by the SNMP engine which were dropped because they referenced a contextEngineID that was known, but no application has registered for the received pduType (yet). " ::= { snmpV3Stats 5 } -- Conformance information ******************************************* snmpV3MIBCompliances OBJECT IDENTIFIER ::= { snmpV3MIBConformance 1 } snmpV3MIBGroups OBJECT IDENTIFIER ::= { snmpV3MIBConformance 2 } -- Compliance statements snmpV3Compliance MODULE-COMPLIANCE STATUS current DESCRIPTION "The compliance statement for SNMP entities which implement the SNMPv3-MIB. " MODULE -- this module MANDATORY-GROUPS { snmpV3Group } ::= { snmpV3MIBCompliances 1 } snmpV3AllCompliance MODULE-COMPLIANCE STATUS current DESCRIPTION "The compliance statement for SNMP entities which implement the SNMPv2-MIB and the SNMPv3-MIB. " MODULE -- this module MANDATORY-GROUPS { -- must import following before we can reference them -- snmpGroup, snmpSetGroup, systemGroup, -- snmpBasicNotificationsGroup, snmpV3Group } Case/Harrington/Wijnen Expires December 1997 [Page 29] \ Draft SNMPv3 Message Processing Model July 1997 ::= { snmpV3MIBCompliances 2 } snmpV2cAndV3Compliance MODULE-COMPLIANCE STATUS current DESCRIPTION "The compliance statement for SNMP entities which implement the SNMPv2-MIB and the SNMPv3-MIB. " MODULE -- this module MANDATORY-GROUPS { -- must import following before we can reference them -- snmpGroup, snmpSetGroup, systemGroup, -- snmpBasicNotificationsGroup, snmpV3Group } -- GROUP snmpCommunityGroup -- DESCRIPTION "This group is mandatory for SNMP entities that -- support Community-based authentication. -- " ::= { snmpV3MIBCompliances 3 } snmpV3Group OBJECT-GROUP OBJECTS { snmpUnknownSecurityModels, snmpUnknownContextEngineIDs, snmpInvalidMsgFlags, snmpUnknownApplications, snmpUnknownPduHandlers } STATUS current DESCRIPTION "A collection of objects providing for remote monitoring of an implementation of the SNMPv3 Message Processing Model. " ::= { snmpV3MIBGroups 1 } END Case/Harrington/Wijnen Expires December 1997 [Page 30] \ Draft SNMPv3 Message Processing Model July 1997 6. Security Consideration The SNMPv3 Message Processing Model coordinates the processing of messages to provide a level of security for network management messages and to direct the SNMP Message payload to the proper SNMP application(s). The level of security actually provided is primarily determined by the specific Security Model implementation(s) and the specific SNMP application implementation(s) incorporated into this framework. Applications have access to data which is not secured. Applications should take reasonable steps to protect the data from disclosure, and when they send data across the network, they should obey the LoS and call upon an Access Control Model services to apply access control. Case/Harrington/Wijnen Expires December 1997 [Page 31] \ Draft SNMPv3 Message Processing Model July 1997 7. References [RFC1901] The SNMPv2 Working Group, Case, J., McCloghrie, K., Rose, M., and S., Waldbusser, "Introduction to Community-based SNMPv2", RFC 1901, January 1996. [RFC1902] The SNMPv2 Working Group, Case, J., McCloghrie, K., Rose, M., and S., Waldbusser, "Structure of Management Information for Version 2 of the Simple Network Management Protocol (SNMPv2)", RFC 1905, January 1996. [RFC1905] The SNMPv2 Working Group, Case, J., McCloghrie, K., Rose, M., and S., Waldbusser, "Protocol Operations for Version 2 of the Simple Network Management Protocol (SNMPv2)", RFC 1905, January 1996. [RFC1906] The SNMPv2 Working Group, Case, J., McCloghrie, K., Rose, M., and S. Waldbusser, "Transport Mappings for Version 2 of the Simple Network Management Protocol (SNMPv2)", RFC 1906, January 1996. [RFC1907] The SNMPv2 Working Group, Case, J., McCloghrie, K., Rose, M., and S. Waldbusser, "Management Information Base for Version 2 of the Simple Network Management Protocol (SNMPv2)", RFC 1907 January 1996. [RFC1908] The SNMPv2 Working Group, Case, J., McCloghrie, K., Rose, M., and S. Waldbusser, "Coexistence between Version 1 and Version 2 of the Internet-standard Network Management Framework", RFC 1908, January 1996. [SNMP-ARCH] The SNMPv3 Working Group, Harrington, D., Wijnen, B., "An Architecture for describing Internet Management Frameworks", draft-ietf-snmpv3-next-gen-arch-03.txt, July 1997. [SNMPv3-ACM] The SNMPv3 Working Group, Wijnen, B., Presuhn, R., McCloghrie, K., "View-based Access Control Model for the Simple Network Management Protocol (SNMP)", draft-ietf-snmpv3-acm-01.txt, July 1997. [SNMPv3-USM] The SNMPv3 Working Group, Blumenthal, U., Wijnen, B. "User-Based Security Model for version 3 of the Simple Network Management Protocol (SNMPv3)", draft-ietf-snmpv3-usm-00.txt, July 1997. Case/Harrington/Wijnen Expires December 1997 [Page 32] \ Draft SNMPv3 Message Processing Model July 1997 8. Editor's Addresses Co-editor: Dr. Jeffrey Case SNMP Research, Inc. postal: 3001 Kimberlain Heights Rd Knoxville, TN 37920-9716 USA email: case@snmp.com phone: +1-615-573-1434 Co-editor Dave Harrington Cabletron Systems, Inc postal: Post Office Box 5005 MailStop: Durham 35 Industrial Way Rochester NH 03867-5005 USA email: dbh@cabletron.com phone: +1-603-337-7357 Co-editor: Bert Wijnen IBM T. J. Watson Research postal: Schagen 33 3461 GL Linschoten Netherlands email: wijnen@vnet.ibm.com phone: +31-348-432-794 Case/Harrington/Wijnen Expires December 1997 [Page 33] \ Draft SNMPv3 Message Processing Model July 1997 9. Acknowledgements This document builds on the work of the SNMP Security and Administrative Framework Evolution team, comprised of David Harrington (Cabletron Systems Inc.) Jeff Johnson (Cisco) David Levi (SNMP Research Inc.) John Linn (Openvision) Russ Mundy (Trusted Information Systems) chair Shawn Routhier (Epilogue) Glenn Waters (Nortel) Bert Wijnen (IBM T.J. Watson Research) Case/Harrington/Wijnen Expires December 1997 [Page 34] \ Draft SNMPv3 Message Processing Model July 1997 Table of Contents 0. Issues 2 0.1. Change Log 3 1. Introduction 5 2. Overview 6 2.1. Message Processing Subsystem 7 2.2. Message Processing External Interfaces 7 2.2.1. Message Processing Interface to Security Subsystem 8 2.2.2. Message Processing Abstract Service Interface 8 2.2.2.1. Sending an SNMP Request or Notification 8 2.2.2.2. Registering Responsibility for Handling SNMP PDUs 9 2.2.2.3. Processing an incoming SNMP Request or Notification 9 2.2.2.4. Sending an SNMP Response 9 2.2.2.5. Processing an incoming SNMP Response 10 3. The SNMPv3 Message Format 11 3.1. version 12 3.2. msgID 12 3.3. mms 12 3.4. msgFlags 12 3.5. securityModel 14 3.6. securityParameters 14 3.7. scopedPduData 14 3.8. scopedPDU 15 3.8.1. contextEngineID 15 3.8.2. contextName 15 3.8.3. data 15 4. Elements of Procedure 16 4.1. Receiving an SNMP Message from the Network 16 10) The message type is determined (how is an implementation issue) 19 11) The SNMP PDU is passed to the selected application according to 20 4.2. Sending an SNMP Message to the Network 21 4.3. Application Registration for Handling PDU types 24 4.3. Application Unregistration for Handling Payloads (PDUs) 25 5. Definitions 27 5.1. Definitions for the SNMPv3 Message Processing Model 27 6. Security Consideration 31 7. References 32 8. Editor's Addresses 33 9. Acknowledgements 34 Case/Harrington/Wijnen Expires December 1997 [Page 35]