idnits 2.17.1 draft-ietf-snmpv3-v3mpc-model-05.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Cannot find the required boilerplate sections (Copyright, IPR, etc.) in this document. Expected boilerplate is as follows today (2024-04-26) according to https://trustee.ietf.org/license-info : IETF Trust Legal Provisions of 28-dec-2009, Section 6.a: This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 2: Copyright (c) 2024 IETF Trust and the persons identified as the document authors. All rights reserved. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 3: This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** Missing expiration date. The document expiration date should appear on the first and last page. ** The document seems to lack a 1id_guidelines paragraph about Internet-Drafts being working documents. ** The document seems to lack a 1id_guidelines paragraph about 6 months document validity -- however, there's a paragraph with a matching beginning. Boilerplate error? ** The document seems to lack a 1id_guidelines paragraph about the list of current Internet-Drafts. ** The document seems to lack a 1id_guidelines paragraph about the list of Shadow Directories. ** The document is more than 15 pages and seems to lack a Table of Contents. == No 'Intended status' indicated for this document; assuming Proposed Standard Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** The document seems to lack separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. ** The abstract seems to contain references ([SNMP-ARCH]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. Miscellaneous warnings: ---------------------------------------------------------------------------- == The document doesn't use any RFC 2119 keywords, yet seems to have RFC 2119 boilerplate text. -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (9 October 1997) is 9696 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Missing Reference: 'RFC1157' is mentioned on line 178, but not defined == Missing Reference: 'Current' is mentioned on line 1742, but not defined == Unused Reference: 'RFC1902' is defined on line 1668, but no explicit reference was found in the text == Unused Reference: 'RFC1908' is defined on line 1687, but no explicit reference was found in the text == Unused Reference: 'RFC2119' is defined on line 1692, but no explicit reference was found in the text == Unused Reference: 'SNMP-USM' is defined on line 1700, but no explicit reference was found in the text == Unused Reference: 'SNMP-ACM' is defined on line 1705, but no explicit reference was found in the text == Unused Reference: 'SNMP-APPL' is defined on line 1710, but no explicit reference was found in the text ** Downref: Normative reference to an Historic RFC: RFC 1901 ** Obsolete normative reference: RFC 1902 (Obsoleted by RFC 2578) ** Obsolete normative reference: RFC 1905 (Obsoleted by RFC 3416) ** Obsolete normative reference: RFC 1906 (Obsoleted by RFC 3417) ** Obsolete normative reference: RFC 1907 (Obsoleted by RFC 3418) ** Obsolete normative reference: RFC 1908 (Obsoleted by RFC 2576) -- Possible downref: Non-RFC (?) normative reference: ref. 'SNMP-ARCH' -- Possible downref: Non-RFC (?) normative reference: ref. 'SNMP-USM' -- Possible downref: Non-RFC (?) normative reference: ref. 'SNMP-ACM' -- Possible downref: Non-RFC (?) normative reference: ref. 'SNMP-APPL' Summary: 16 errors (**), 0 flaws (~~), 10 warnings (==), 6 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 INTERNET-DRAFT J. Case 3 SNMP Research, Inc. 4 D. Harrington 5 Cabletron Systems, Inc. 6 R. Presuhn 7 BMC Software, Inc. 8 B. Wijnen 9 IBM T. J. Watson Research 10 9 October 1997 12 Message Processing and Dispatching for the 13 Simple Network Management Protocol (SNMP) 14 16 Status of this Memo 18 This document is an Internet-Draft. Internet-Drafts are working 19 documents of the Internet Engineering Task Force (IETF), its areas, 20 and its working groups. Note that other groups may also distribute 21 working documents as Internet-Drafts. 23 Internet-Drafts are draft documents valid for a maximum of six months 24 and may be updated, replaced, or obsoleted by other documents at any 25 time. It is inappropriate to use Internet-Drafts as reference 26 material or to cite them other than as ``work in progress.'' 28 To learn the current status of any Internet-Draft, please check the 29 ``1id-abstracts.txt'' listing contained in the Internet-Drafts Shadow 30 Directories on ftp.is.co.za (Africa), nic.nordu.net (Europe), 31 munnari.oz.au (Pacific Rim), ds.internic.net (US East Coast), or 32 ftp.isi.edu (US West Coast). 34 Abstract 36 This document describes the Message Processing and Dispatching for 37 SNMP messages within the SNMP architecture [SNMP-ARCH]. It defines 38 the procedures for dispatching potentially multiple versions of SNMP 39 messages to the proper SNMP Message Processing Models, and for 40 dispatching PDUs to SNMP applications. This document also describes 41 one Message Processing Model - the SNMPv3 Message Processing Model. 43 1. Introduction 45 The Architecture for describing Internet Management Frameworks 46 [SNMP-ARCH] describes that an SNMP engine is composed of: 48 1) a Dispatcher 49 2) a Message Processing Subsystem, 50 3) a Security Subsystem, and 51 4) an Access Control Subsystem. 53 Applications make use of the services of these subsystems. 55 It is important to understand the SNMP architecture and its 56 terminology to understand where the Message Processing Subsystem and 57 Dispatcher described in this document fit into the architecture and 58 interact with other subsystems within the architecture. The reader 59 is expected to have read and understood the description of the SNMP 60 architecture, defined in [SNMP-ARCH]. 62 The Dispatcher in the SNMP engine sends and receives SNMP messages. 63 It also dispatches SNMP PDUs to SNMP applications. When an SNMP 64 message needs to be prepared or when data needs to be extracted from 65 an SNMP message, the Dispatcher delegates these tasks to a message 66 version-specific Message Processing Model within the Message 67 Processing Subsystem. 69 A Message Processing Model is responsibile for processing a SNMP 70 version-specific message and for coordinating the interaction with 71 the Security Subsystem to ensure proper security is applied to the 72 SNMP message being handled. 74 Interactions between the Dispatcher, the Message Processing 75 Subsystem, and applications are modelled using abstract data elements 76 and abstract service interface primitives defined by the SNMP 77 architecture. 79 Similarly, interactions between the Message Processing Subsystem and 80 the Security Subsystem are modelled using abstract data elements and 81 abstract service interface primitives as defined by the SNMP 82 architecture. 84 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 85 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 86 document are to be interpreted as described in RFC 2119. 88 2. Overview 90 The following illustration depicts the Message Processing in relation 91 to SNMP applications, the Security Subsystem and Transport Mappings. 93 +-------------------------------------------------------------------+ 94 | SNMP Entity | 95 | | 96 | +---------------------------------------------------------------+ | 97 | | Applications | | 98 | | +-----------+ +--------------+ | | 99 | | | Command | | Notification | | | 100 | | | Generator | | Originator | +-----------+ +--------------+| | 101 | | +-----------+ +--------------+ | Proxy | | Other | | 102 | | +-----------+ +--------------+ | Forwarder | |Application(s)|| | 103 | | | Command | | Notification | +-----------+ +--------------+| | 104 | | | Responder | | Receiver | | | 105 | | +-----------+ +--------------+ | | 106 | +---------------------------------------------------------------+ | 107 | ^ ^ ^ ^ | 108 | | | | | | 109 | v v v v | 110 | +--------+-------+---------------+-----------+ | 111 | ^ | 112 | | +---------------------+ +-----------------+ | 113 | | | Message Processing | | Security | | 114 | Dispatcher v | Subsystem | | Subsystem | | 115 | +------------------+ | +------------+ | | | | 116 | | PDU Dispatcher | | +->| v1MP * |<--->| +-------------+ | | 117 | | | | | +------------+ | | | Other | | | 118 | | | | | +------------+ | | | Security | | | 119 | | | | +->| v2cMP * |<--->| | Model | | | 120 | | Message | | | +------------+ | | +-------------+ | | 121 | | Dispatcher <-------->+ | | | | 122 | | | | | +------------+ | | +-------------+ | | 123 | | | | +->| v3MP * |<--->| | User-based | | | 124 | | Transport | | | +------------+ | | | Security | | | 125 | | Mapping | | | +------------+ | | | Model | | | 126 | | (e.g RFC1906) | | +->| otherMP * |<--->| +-------------+ | | 127 | +------------------+ | +------------+ | | | | 128 | ^ +---------------------+ +-----------------+ | 129 | | | 130 +----------|--------------------------------------------------------+ 131 v 132 +------------------+ 133 | Network | 134 +------------------+ 136 2.1. The Dispatcher. 138 The Dispatcher is a key piece of an SNMP engine. There is only one in 139 an SNMP engine, and its job is to dispatch tasks to the multiple ver- 140 sion-specific Message Processing Models, and to dispatch PDUs to var- 141 ious applications. 143 For outgoing messages, an application provides a PDU to be sent, plus 144 the data needed to prepare and send the message, and the application 145 specifies which version-specific Message Processing Model will be 146 used to prepare the message with the desired security processing. 147 Once the message is prepared, the Dispatcher sends the message. 149 For incoming messages, the Dispatcher determines the SNMP version of 150 the incoming message and passes the message to the version-specific 151 Message Processing Model to extract the components of the message and 152 to coordinate the processing of security services for the message. 153 After version-specific processing, the PDU Dispatcher determines 154 which application, if any, should receive the PDU for processing and 155 forwards it accordingly. 157 The Dispatcher, while sending and receiving SNMP messages, collects 158 statistics about SNMP messages and the behavior of the SNMP engine in 159 managed objects to make them accessible to remote SNMP entities. 160 This document defines these managed objects, the MIB module which 161 contains them, and how these managed objects might be used to provide 162 useful management. 164 2.2. Message Processing Subsystem 166 The SNMP Message Processing Subsystem is the part of an SNMP engine 167 which interacts with the Dispatcher to handle the version-specific 168 SNMP messages. It contains one or more Message Processing Models. 170 This document describes one Message Processing Model, the SNMPv3 171 Message Processing Model, in Section 6. The SNMPv3 Message Processing 172 Model is defined in a separate section to show that multiple 173 (independent) Message Processing Models can exist at the same time 174 and that such Models can be described in different documents. The 175 SNMPv3 Message Processing Model can be replaced or supplemented with 176 other Message Processing Models in the future. Two Message Processing 177 Models which are expected to be developed in the future are the 178 SNMPv1 message format [RFC1157] and the SNMPv2c message format 179 [RFC1901]. Others may be developed as needed. 181 3. Elements of Message Processing and Dispatching 183 See [SNMP-ARCH] for the definitions of 184 contextEngineID 185 contextName 186 scopedPDU 187 maxSizeResponseScopedPDU 188 securityModel 189 securityName 190 securityLevel 191 messageProcessingModel 193 For incoming messages, a version-specific message processing module 194 provides these values to the Dispatcher. For outgoing messages, an 195 application provides these values to the Dispatcher. 197 For some version-specific processing, the values may be extracted 198 from received messages; for other versions, the values may be 199 determined by algorithm, or by an implementation-defined mechanism. 200 The mechanism by which the value is determined is irrelevant to the 201 Dispatcher. 203 The following additional or expanded definitions are for use within 204 the Dispatcher. 206 3.1. messageProcessingModel 208 The value of messageProcessingModel identifies a Message Processing 209 Model. A Message Processing Model describes the version-specific 210 procedures for extracting data from messages, generating messages, 211 calling upon a securityModel to apply its security services to mes- 212 sages, for converting data from a version-specific message format in- 213 to a generic format usable by the Dispatcher, and for converting data 214 from Dispatcher format into a version-specific message format. 216 3.2. pduVersion 218 The value of pduVersion represents a specific version of protocol 219 operation and its associated PDU formats, such as SNMPv1 or SNMPv2 220 [RFC1905]. The values of pduVersion are specific to the version of 221 the PDU contained in a message, and the PDUs processed by 222 applications. The Dispatcher does not use the value of pduVersion 223 directly. 225 An application specifies the pduVersion when it requests the PDU 226 Dispatcher to send a PDU to another SNMP engine. The Dispatcher 227 passes the pduVersion to a Message Processing Model, so it knows how 228 to handle the PDU properly. 230 For incoming messages, pduVersion is provided to the Dispatcher by a 231 version-specific Message Processing module. The PDU Dispatcher passes 232 the pduVersion to the application so it knows how to handle the PDU 233 properly. For example, a command responder application needs to know 234 whether to use [RFC1905] elements of procedure and syntax instead of 235 those specified for SNMPv1. 237 3.3. pduType 239 A value of pduType represents a specific type of protocol operation. 240 The values of pduType are specific to the version of the PDU 241 contained in a message. 243 Applications register to support particular pduTypes for particular 244 contextEngineIDs. 246 For incoming messages, pduType is provided to the Dispatcher by a 247 version-specific Message Processing module. It is subsequently used 248 to dispatch the PDU to the application which registered for the 249 pduType for the contextEngineID of the associated scopedPDU. 251 3.4. sendPduHandle 253 This handle is generated for coordinating the processing of requests 254 and responses between the SNMP engine and an application. The handle 255 must be unique across all version-specific Message Processing Models, 256 and is of local significance only. 258 4. Dispatcher Elements of Procedure 260 This section describes the procedures followed by the Dispatcher when 261 generating and processing SNMP messages. 263 4.1. Sending an SNMP Message to the Network 265 This section describes the procedure followed by an SNMP engine 266 whenever it sends an SNMP message. 268 4.1.1. Sending a Request or Notification 270 The following procedures are followed by the Dispatcher when an 271 application wants to send an SNMP PDU to another (remote) 272 application, i.e., to initiate a communication by originating a 273 message, such as one containing a request or a trap. 275 1) The application requests this using the abstract service 276 primitive: 278 statusInformation = -- sendPduHandle if success 279 -- errorIndication if failure 280 sendPdu( 281 IN transportDomain -- transport domain to be used 282 IN transportAddress -- destination network address 283 IN messageProcessingModel -- typically, SNMP version 284 IN securityModel -- Security Model to use 285 IN securityName -- on behalf of this principal 286 IN securityLevel -- Level of Security requested 287 IN contextEngineID -- data from/at this entity 288 IN contextName -- data from/in this context 289 IN pduVersion -- the version of the PDU 290 IN PDU -- SNMP Protocol Data Unit 291 IN expectResponse -- TRUE or FALSE 292 ) 294 2) If the messageProcessingModel value does not represent a Message 295 Processing Model known to the Dispatcher, then an errorIndication 296 (implementation-dependent) is returned to the calling application. 297 No further processing is performed. 299 3) The Dispatcher generates a sendPduHandle to coordinate subsequent 300 processing. 302 4) The Message Dispatcher sends the request to the version-specific 303 Message Processing module identified by messageProcessingModel 304 using the abstract service primitive: 306 statusInformation = - success or error indication 307 prepareOutgoingMessage( 308 IN transportDomain -- as specified by application 309 IN transportAddress -- as specified by application 310 IN messageProcessingModel -- as specified by application 311 IN securityModel -- as specified by application 312 IN securityName -- as specified by application 313 IN securityLevel -- as specified by application 314 IN contextEngineID -- as specified by application 315 IN contextName -- as specified by application 316 IN pduVersion -- the version of the PDU 317 IN PDU -- as specified by application 318 IN expectResponse -- as specified by application 319 IN sendPduHandle -- as determined in step 3. 320 OUT destTransportDomain -- destination transport domain 321 OUT destTransportAddress -- destination transport address 322 OUT outgoingMessage -- the message to send 323 OUT outgoingMessageLength -- the message length 324 ) 326 5) If the statusInformation indicates an error, the errorIndication 327 is returned to the calling application. No further processing is 328 performed. 330 6) If the statusInformation indicates success, the sendPduHandle is 331 returned to the application, and the outgoingMessage is sent via 332 the transport specified by the transportDomain to the address 333 specified by the transportAddress. 335 Outgoing Message Processing is complete. 337 4.1.2. Sending a Response to the Network 339 The following procedure is followed when an application wants to 340 return a response back to the originator of an SNMP Request. 342 1) An application can request this using the abstract service 343 primitive: 345 returnResponsePDU( 346 IN messageProcessingModel -- typically, SNMP version 347 IN securityModel -- Security Model in use 348 IN securityName -- on behalf of this principal 349 IN securityLevel -- same as on incoming request 350 IN contextEngineID -- data from/at this SNMP entity 351 IN contextName -- data from/in this context 352 IN pduVersion -- the version of the PDU 353 IN PDU -- SNMP Protocol Data Unit 354 IN maxSizeResponseScopedPDU -- maximum size of Response PDU 355 IN stateReference -- reference to state information 356 -- as presented with the request 357 IN statusInformation -- success or errorIndication 358 ) -- (error counter OID and value 359 -- when errorIndication) 361 2) The Message Dispatcher sends the request to the appropriate 362 Message Processing Model indicated by the received value of 363 messageProcessingModel using the abstract service primitive: 365 result = -- SUCCESS or errorIndication 366 prepareResponseMessage( 367 IN messageProcessingModel -- specified by application 368 IN securityModel -- specified by application 369 IN securityName -- specified by application 370 IN securityLevel -- specified by application 371 IN contextEngineID -- specified by application 372 IN contextName -- specified by application 373 IN pduVersion -- specified by application 374 IN PDU -- specified by application 375 IN maxSizeResponseScopedPDU -- specified by application 376 IN stateReference -- specified by application 377 IN statusInformation -- specified by application 378 OUT destTransportDomain -- destination transport domain 379 OUT destTransportAddress -- destination transport address 380 OUT outgoingMessage -- the message to send 381 OUT outgoingMessageLength -- the message length 382 ) 384 3) If the result is an errorIndication, the errorIndication is 385 returned to the calling application. No further processing is 386 performed. 388 4) If the result is success, the outgoingMessage is sent over the 389 transport specified by the transportDomain to the address 390 specified by the transportAddress. 392 Message Processing is complete. 394 4.2. Receiving an SNMP Message from the Network 396 This section describes the procedure followed by an SNMP engine 397 whenever it receives an SNMP message. 399 Please note, that for the sake of clarity and to prevent the text 400 from being even longer and more complicated, some details were 401 omitted from the steps below. In particular, The elements of 402 procedure do not always explicitly indicate when state information 403 needs to be released. The general rule is that if state information 404 is available when a message is to be "discarded without further 405 processing", then the state information must also be released at that 406 same time. 408 4.2.1. Message Dispatching of received SNMP Messages 410 1) The snmpInPkts counter [RFC1907] is incremented. 412 2) The version of the SNMP message is determined in an 413 implementation-dependent manner. If the packet cannot be 414 sufficiently parsed to determine the version of the SNMP message, 415 then the snmpInASNParseErrs [RFC1907] counter is incremented, and 416 the message is discarded without further processing. If the 417 version is not supported, then the snmpInBadVersions [RFC1907] 418 counter is incremented, and the message is discarded without 419 further processing. 421 3) The origin transportDomain and origin transportAddress are 422 determined. 424 4) The message is passed to the version-specific Message Processing 425 Model which returns the abstract data elements required by the 426 Dispatcher. This is performed using the abstract service 427 primitive: 429 result = -- SUCCESS or errorIndication 430 prepareDataElements( 431 IN transportDomain -- origin as determined in step 3. 432 IN transportAddress -- origin as determined in step 3. 433 IN wholeMsg -- as received from the network 434 IN wholeMsgLength -- as received from the network 435 OUT messageProcessingModel -- typically, SNMP version 436 OUT securityModel -- Security Model to use 437 OUT securityName -- on behalf of this principal 438 OUT securityLevel -- Level of Security requested 439 OUT contextEngineID -- data from/at this entity 440 OUT contextName -- data from/in this context 441 OUT pduVersion -- the version of the PDU 442 OUT PDU -- SNMP Protocol Data Unit 443 OUT pduType -- SNMP PDU type 444 OUT sendPduHandle -- handle for a matched request 445 OUT maxSizeResponseScopedPDU -- maximum size of Response PDU 446 OUT statusInformation -- success or errorIndication 447 -- (error counter OID and value 448 -- when errorIndication) 449 OUT stateReference -- reference to state information 450 -- to be used for a possible 451 ) -- Response 453 5) If the result is a FAILURE errorIndication, the message is 454 discarded without further processing. 456 6) At this point, the abstract data elements have been prepared and 457 processing continues as described in Section 4.2.2, PDU 458 Dispatching for Incoming Messages. 460 4.2.2. PDU Dispatching for Incoming Messages 462 The elements of procedure for the dispatching of PDUs depends on the 463 value of sendPduHandle. If the value of sendPduHandle is , 464 then this is a request or notification and the procedures specified 465 in Section 4.2.2.1 apply. If the value of snmpPduHandle is not 466 , then this is a response and the procedures specified in 467 Section 4.2.2.2 apply. 469 4.2.2.1. PDU Dispatching for Incoming Messages: Requests and 470 Notifications 472 The following procedures are followed for the dispatching of PDUs 473 when the value of sendPduHandle is , indicating this is a 474 request or notification. 476 1) The combination of contextEngineID and pduType is used to 477 determine which application has registered for this request or 478 notification. 480 2) If no application has registered for the combination, then 482 a) The snmpUnknownPDUHandlers counter is incremented. 484 b) A Response message is generated using the abstract service 485 primitive: 487 result = -- SUCCESS or FAILURE 488 prepareResponseMessage( 489 IN messageProcessingModel -- as provided by MP module 490 IN securityModel -- as provided by MP module 491 IN securityName -- as provided by MP module 492 IN securityLevel -- as provided by MP module 493 IN contextEngineID -- as provided by MP module 494 IN contextName -- as provided by MP module 495 IN pduVersion -- as provided by MP module 496 IN PDU -- as provided by MP module 497 IN maxSizeResponseScopedPDU -- as provided by MP module 498 IN stateReference -- as provided by MP module 499 IN statusInformation -- errorIndication plus 500 -- snmpUnknownPDUHandlers OID 501 -- value pair. 502 OUT transportDomain -- destination transportDomain 503 OUT transportAddress -- destination transportAddress 504 OUT outgoingMessage -- the message to send 505 OUT outgoingMessageLength -- its length 506 ) 508 c) If the result is SUCCESS, then the prepared message is sent to 509 the originator of the request as identified by the 510 transportDomain and transportAddress. 512 d) The incoming message is discarded without further processing. 513 Message Processing for this message is complete. 515 3) The PDU is dispatched to the application, using the abstract 516 service primitive: 518 processPdu( -- process Request/Notification 519 IN messageProcessingModel -- as provided by MP module 520 IN securityModel -- as provided by MP module 521 IN securityName -- as provided by MP module 522 IN securityLevel -- as provided by MP module 523 IN contextEngineID -- as provided by MP module 524 IN contextName -- as provided by MP module 525 IN pduVersion -- as provided by MP module 526 IN PDU -- as provided by MP module 527 IN maxSizeResponseScopedPDU -- as provided by MP module 528 IN stateReference -- as provided by MP module 529 -- needed when sending response 530 ) 532 Message processing for this message is complete. 534 4.2.2.2. PDU Dispatching for Incoming Messages: Responses 536 The following procedures are followed for the dispatching of PDUs 537 when the value of sendPduHandle is not , indicating this is a 538 response. 540 1) The value of sendPduHandle is used to determine, in an 541 implementation-defined manner, which application is waiting for 542 a response PDU associated with this sendPduHandle. 544 2) If no waiting application is found, the message is discarded 545 without further processing, and the stateReference is released. 546 The snmpUnknownPDUHandlers counter is incremented. Message 547 Processing is complete for this message. 549 3) Any cached information, including stateReference, about the 550 message is discarded. 552 4) The response is dispatched to the application using the 553 abstract service primitive: 555 processResponsePdu( -- process Response PDU 556 IN messageProcessingModel -- provided by the MP module 557 IN securityModel -- provided by the MP module 558 IN securityName -- provided by the MP module 559 IN securityLevel -- provided by the MP module 560 IN contextEngineID -- provided by the MP module 561 IN contextName -- provided by the MP module 562 IN pduVersion -- provided by the MP module 563 IN PDU -- provided by the MP module 564 IN statusInformation -- provided by the MP module 565 IN sendPduHandle -- provided by the MP module 566 ) 568 Message Processing is complete for this message. 570 4.3. Application Registration for Handling PDU types 572 Applications that want to process certain PDUs must register with the 573 PDU Dispatcher. Applications specify the combination of 574 contextEngineID and pduType(s) for which they want to take 575 responsibility 577 1) An application registers according to the abstract interface 578 primitive: 580 statusInformation = -- success or errorIndication 581 registerContextEngineID( 582 IN contextEngineID -- take responsibility for this one 583 IN pduType -- the pduType(s) to be registered 584 ) 586 Note: implementations may provide a means of requesting 587 registration for simultaneous multiple contextEngineID values, 588 e.g., all contextEngineID values, and may also provide means for 589 requesting simultaneous registration for multiple values of 590 pduType. 592 2) The parameters may be checked for validity; if they are not, then 593 an errorIndication (invalidParameter) is returned to the 594 application. 596 3) Each combination of contextEngineID and pduType can be registered 597 only once. If another application has already registered for the 598 specified combination, then an errorIndication (alreadyRegistered) 599 is returned to the application. 601 4) Otherwise, the registration is saved so that SNMP PDUs can be 602 dispatched to this application. 604 4.4. Application Unregistration for Handling PDU Types 606 Applications that no longer want to process certain PDUs must 607 unregister with the PDU Dispatcher. 609 1) An application unregisters using the abstract service primitive: 611 unregisterContextEngineID( 612 IN contextEngineID -- give up responsibility for this 613 IN pduType -- the pduType(s) to be unregistered 614 ) 615 Note: implementations may provide means for requesting 616 unregistration for simultaneous multiple contextEngineID values, 617 e.g., all contextEngineID values, and may also provide means for 618 requesting simultaneous unregistration for multiple values of 619 pduType. 621 2) If the contextEngineID and pduType combination has been 622 registered, then the registration is deleted. 624 If no such registration exists, then the request is ignored. 626 5. Definitions 628 5.1. Definitions for SNMP Message Processing and Dispatching 630 SNMP-MPD-MIB DEFINITIONS ::= BEGIN 632 IMPORTS 633 MODULE-COMPLIANCE, OBJECT-GROUP FROM SNMPv2-CONF 634 MODULE-IDENTITY, OBJECT-TYPE, 635 snmpModules, Counter32 FROM SNMPv2-SMI; 637 snmpMPDMIB MODULE-IDENTITY 638 LAST-UPDATED "9710090000Z" -- 9 October 1997 639 ORGANIZATION "SNMPv3 Working Group" 640 CONTACT-INFO "WG-email: snmpv3@tis.com 641 Subscribe: majordomo@tis.com 642 In message body: subscribe snmpv3 644 Chair: Russ Mundy 645 Trusted Information Systems 646 postal: 3060 Washington Road 647 Glenwood, MD 21738 648 USA 649 email: mundy@tis.com 650 phone: +1 301-854-6889 651 Co-editor: Jeffrey Case 652 SNMP Research, Inc. 653 postal: 3001 Kimberlin Heights Road 654 Knoxville, TN 37920-9716 655 USA 656 email: case@snmp.com 657 phone: +1 423-573-1434 659 Co-editor Dave Harrington 660 Cabletron Systems, Inc. 661 postal: Post Office Box 5005 662 MailStop: Durham 663 35 Industrial Way 664 Rochester, NH 03867-5005 665 USA 666 email: dbh@cabletron.com 667 phone: +1 603-337-7357 669 Co-editor: Randy Presuhn 670 BMC Software, Inc. 671 postal: 1190 Saratoga Ave, Suite 190 672 San Jose, CA 95120 673 USA 674 email: rpresuhn@bmc.com 675 phone: +1 408-556-0720 677 Co-editor: Bert Wijnen 678 IBM T. J. Watson Research 679 postal: Schagen 33 680 3461 GL Linschoten 681 Netherlands 682 email: wijnen@vnet.ibm.com 683 phone: +31 348-432-794 685 " 686 DESCRIPTION "The MIB for Message Processing and Dispatching" 687 ::= { snmpModules 8 } -- check if assignment is OK 689 -- Administrative assignments *************************************** 691 snmpMPDAdmin OBJECT IDENTIFIER ::= { snmpMPDMIB 1 } 692 snmpMPDMIBObjects OBJECT IDENTIFIER ::= { snmpMPDMIB 2 } 693 snmpMPDMIBConformance OBJECT IDENTIFIER ::= { snmpMPDMIB 3 } 695 -- Statistics for SNMP Messages ************************************* 697 snmpMPDStats OBJECT IDENTIFIER ::= { snmpMPDMIBObjects 1 } 698 snmpUnknownSecurityModels OBJECT-TYPE 699 SYNTAX Counter32 700 MAX-ACCESS read-only 701 STATUS current 702 DESCRIPTION "The total number of packets received by the SNMP 703 engine which were dropped because they referenced a 704 securityModel that was not known to or supported by 705 the SNMP engine. 706 " 707 ::= { snmpMPDStats 1 } 709 snmpInvalidMsgs OBJECT-TYPE 710 SYNTAX Counter32 711 MAX-ACCESS read-only 712 STATUS current 713 DESCRIPTION "The total number of packets received by the SNMP 714 engine which were dropped because there were invalid 715 or inconsistent components in the SNMP message. 716 " 717 ::= { snmpMPDStats 2 } 719 snmpUnknownPDUHandlers OBJECT-TYPE 720 SYNTAX Counter32 721 MAX-ACCESS read-only 722 STATUS current 723 DESCRIPTION "The total number of packets received by the SNMP 724 engine which were dropped because the PDU contained 725 in the packet could not be passed to an application 726 responsible for handling the pduType, e.g. no SNMP 727 application had registered for the proper 728 combination of the contextEngineID and the pduType. 729 " 730 ::= { snmpMPDStats 3 } 732 -- Conformance information ****************************************** 734 snmpMPDMIBCompliances OBJECT IDENTIFIER ::= {snmpMPDMIBConformance 1} 735 snmpMPDMIBGroups OBJECT IDENTIFIER ::= {snmpMPDMIBConformance 2} 737 -- Compliance statements 739 snmpMPDCompliance MODULE-COMPLIANCE 740 STATUS current 741 DESCRIPTION "The compliance statement for SNMP entities which 742 implement the SNMP-MPD-MIB. 743 " 745 MODULE -- this module 746 MANDATORY-GROUPS { snmpMPDGroup } 748 ::= { snmpMPDMIBCompliances 1 } 750 snmpMPDGroup OBJECT-GROUP 751 OBJECTS { 752 snmpUnknownSecurityModels, 753 snmpInvalidMsgs, 754 snmpUnknownPDUHandlers 755 } 756 STATUS current 757 DESCRIPTION "A collection of objects providing for remote 758 monitoring of the SNMP Message Processing and 759 Dispatching process. 760 " 761 ::= { snmpMPDMIBGroups 1 } 763 END 765 6. The SNMPv3 Message Format 767 This section defines the SNMPv3 message format and the corresponding 768 SNMP version 3 Message Processing Model (v3MP). 770 SNMPv3MessageSyntax DEFINITIONS IMPLICIT TAGS ::= BEGIN 772 SNMPv3Message ::= SEQUENCE { 773 -- identify the layout of the SNMPv3Message 774 -- this element is in same position as in SNMPv1 775 -- and SNMPv2c, allowing recognition 776 msgVersion INTEGER { snmpv3 (3) }, 777 -- administrative parameters 778 msgGlobalData HeaderData, 780 -- security model-specific parameters 781 -- format defined by Security Model 782 msgSecurityParameters OCTET STRING, 784 msgData ScopedPduData 785 } 787 HeaderData ::= SEQUENCE { 788 msgID INTEGER (0..2147483647), 789 msgMaxSize INTEGER (484..2147483647), 791 msgFlags OCTET STRING (SIZE(1)), 792 -- .... ...1 authFlag 793 -- .... ..1. privFlag 794 -- .... .1.. reportableFlag 795 -- 796 -- Please observe: 797 -- .... ..00 is OK, means noAuthNoPriv 798 -- .... ..01 is OK, means authNoPriv 799 -- .... ..10 reserved, must NOT be used. 800 -- .... ..11 is OK, means authPriv 802 msgSecurityModel INTEGER (0..2147483647) 803 } 805 ScopedPduData ::= CHOICE { 806 plaintext ScopedPDU, 807 encryptedPDU OCTET STRING -- encrypted scopedPDU value 808 } 810 ScopedPDU ::= SEQUENCE { 811 contextEngineID OCTET STRING, 812 contextName OCTET STRING, 813 data ANY -- e.g., PDUs as defined in RFC1905 814 } 815 END 817 6.1. msgVersion 819 The msgVersion field is set to snmpv3(3) and identifies the message 820 as an SNMP version 3 Message. 822 6.2. msgID 824 The msgID is used between two SNMP entities to coordinate request 825 messages and responses, and by the v3MP to coordinate the processing 826 of the message by different subsystem models within the architecture. 828 Values for msgID should be generated in a manner that avoids re-use 829 of any outstanding values. Doing so provides protection against some 830 replay attacks. One possible implementation strategy would be to use 831 the low-order bits of snmpEngineBoots [SNMP-ARCH] as the high-order 832 portion of the msgID value and a monotonically increasing integer for 833 the low-order portion of msgID. 835 Note that the request-id in a PDU is used by SNMP applications to 836 identify the PDU; the msgID is used by the engine to identify the 837 message which carries a PDU. The engine may need to identify the 838 message even if decrypting of the PDU (and request-id) fails. No 839 assumption should be made that the value of the msgID and the value 840 of the request-id are equivalent. 842 6.3. msgMaxSize 844 The msgMaxSize field of the message conveys the maximum message size 845 supported by the sender of the message, i.e., the maximum message 846 size that the sender can accept when another SNMP engine sends an 847 SNMP message (be it a response or any other message) to the sender of 848 this message. 850 When an SNMP message is being generated, the msgMaxSize is provided 851 by the SNMP engine which generates the message. At the receiving 852 SNMP engine, the msgMaxSize is used to determine how big the Response 853 to a Request message can be. 855 6.4. msgFlags 857 The msgFlags field of the message contains several bit fields which 858 control processing of the message. 860 When the reportableFlag is one, a Report PDU must be returned to the 861 sender under those conditions which can cause the generation of 862 Report PDUs. When the reportableFlag is zero, then a Report PDU must 863 not be sent. The reportableFlag must always be zero when the message 864 contains a Report PDU, a response-type PDU (such as a Response PDU), 865 or an unacknowledged notification-type PDU (such as an SNMPv2-trap 866 PDU). The reportableFlag must always be one for a request-type PDU 867 (such as a Get PDU) and an acknowledged notification-type PDU (such 868 as an Inform PDU). 870 If the reportableFlag is set to one for a message containing a Report 871 PDU, a response-type PDU (such as a Response PDU), or an 872 unacknowledged notification-type PDU (such as an SNMPv2-trap PDU), 873 then the receiver of that message must process it as though the 874 reportableFlag had been set to zero. 876 If the reportableFlag is set to zero for a message containing a 877 request-type PDU (such as a Get PDU) or an acknowledged notification- 878 type PDU (such as an Inform PDU), then the receiver of that message 879 must process it as though the reportableFlag had been set to one. 881 Report PDUs are engine-to-engine communications and are processed 882 directly by the SNMPv3 Message Processing Model, and are generally 883 not passed to applications for processing, unlike all other PDU 884 types. 886 Note that the reportableFlag is a secondary aid in determining 887 whether a Report PDU must be sent. It is only used in cases where 888 the PDU portion of a message cannot be decoded, due to, for example, 889 an incorrect ecryption key. If the PDU can be decoded, the PDU type 890 forms the basis for decisions on sending Report PDUs. 892 The authFlag and privFlag portions of the msgFlags field are set by 893 the sender to indicate the securityLevel that was applied to the 894 message before it was sent on the wire. The receiver of the message 895 must apply the same securityLevel when the message is received and 896 the contents are being processed. 898 There are three securityLevels, namely noAuthNoPriv, which is less 899 than authNoPriv, which is in turn less than authPriv. See the SNMP 900 architecture document [SNMP-ARCH] for details about the 901 securityLevel. 903 a) authFlag 905 If the authFlag is set to one, then the securityModel used by the 906 SNMP engine which sent the message must identify the securityName 907 on whose behalf the SNMP message was generated and must provide, 908 in a securityModel-specific manner, sufficient data for the 909 receiver of the message to be able to authenticate that 910 identification. In general, this authentication will allow the 911 receiver to determine with reasonable certainty that the message 912 was: 914 - sent on behalf of the principal associated with the 915 securityName, 917 - was not redirected, 919 - was not modified in transit, and 921 - was not replayed. 923 If the authFlag is zero, then the securityModel used by the SNMP 924 engine which sent the message must identify the securityName on 925 whose behalf the SNMP message was generated but it does not need 926 to provide sufficient data for the receiver of the message to 927 authenticate the identification, as there is no need to 928 authenticate the message in this case. 930 b) privFlag 932 If the privFlag is set, then the securityModel used by the SNMP 933 engine which sent the message must also protect the scopedPDU in 934 an SNMP message from disclosure, i.e., must encrypt/decrypt the 935 scopedPDU. If the privFlag is zero, then the securityModel in use 936 does not need to protect the data from disclosure. 938 It is an explicit requirement of the SNMP architecture that if 939 privacy is selected, then authentication is also required. That 940 means that if the privFlag is set, then the authFlag must also be 941 set to one. 943 The combination of the authFlag and the privFlag comprises a Level 944 of Security as follows: 945 authFlag zero, privFlag zero -> securityLevel is noAuthNoPriv 946 authFlag zero, privFlag one -> invalid combination 947 authFlag one, privFlag zero -> securityLevel is authNoPriv 948 authFlag one, privFlag one -> securityLevel is authPriv 950 6.5. msgSecurityModel 952 The v3MP supports the concurrent existence of multiple Security 953 Models to provide security services for SNMPv3 messages. The 954 msgSecurityModel field in an SNMPv3 Message identifies which Security 955 Model was used by the sender to generate the message and therefore 956 which securityModel must be used by the receiver to perform security 957 processing for the message. The mapping to the appropriate 958 securityModel implementation within an SNMP engine is accomplished in 959 an implementation-dependent manner. 961 6.6. msgSecurityParameters 963 The msgSecurityParameters field of the SNMPv3 Message is used for 964 communication between the Security Model modules in the sending and 965 receiving SNMP engines. The data in the msgSecurityParameters field 966 is used exclusively by the Security Model, and the contents and 967 format of the data is defined by the Security Model. This OCTET 968 STRING is not interpreted by the v3MP, but is passed to the local 969 implementation of the Security Model indicated by the 970 msgSecurityModel field in the message. 972 6.7. scopedPduData 974 The scopedPduData field represents either the plain text scopedPDU if 975 the privFlag in the msgFlags is zero, or it represents an 976 encryptedPDU (encoded as an OCTET STRING) which must be decrypted by 977 the securityModel in use to produce a plaintext scopedPDU. 979 6.8. scopedPDU 981 The scopedPDU contains information to identify an administratively 982 unique context and a PDU. The object identifiers in the PDU refer to 983 managed objects which are (expected to be) accessible within the 984 specified context. 986 6.8.1. contextEngineID 988 The contextEngineID in the SNMPv3 message, uniquely identifies, 989 within an administrative domain, an SNMP entity that may realize an 990 instance of a context with a particular contextName. 992 For incoming messages, the contextEngineID is used to determine to 993 which application the scopedPDU will be sent for processing. 995 For outgoing messages, the v3MP sets the contextEngineID to the value 996 provided by the application in the request for a message to be sent. 998 6.8.2. contextName 1000 The contextName field in an SNMPv3 message, in conjunction with the 1001 contextEngineID field, identifies the particular context associated 1002 with the management information contained in the PDU portion of the 1003 message. The contextName is unique within the SNMP entity specified 1004 by the contextEngineID, which may realize the managed objects 1005 referenced within the PDU. An application which originates a message 1006 provides the value for the contextName field and this value may be 1007 used during processing by an application at the receiving SNMP 1008 Engine. 1010 6.8.3. data 1012 The data field of the SNMPv3 Message contains the PDU. Among other 1013 things, the PDU contains the PDU type that is used by the v3MP to 1014 determine the type of the incoming SNMP message. The v3MP specifies 1015 that the PDU must be one of those specified in [RFC1905]. 1017 7. Elements of Procedure for v3MP 1019 This section describes the procedures followed by an SNMP engine when 1020 generating and processing SNMP messages according to the SNMPv3 1021 Message Processing Model. 1023 Please note, that for the sake of clarity and to prevent the text 1024 from being even longer and more complicated, some details were 1025 omitted from the steps below. 1027 a) Some steps specify that when some error conditions are 1028 encountered when processing a received message, a message 1029 containing a Report PDU is generated and the received message 1030 is discarded without further processing. However, a Report-PDU 1031 must not be generated unless the reportableFlag is set in the 1032 received message. 1034 b) The elements of procedure do not always explicitly indicate 1035 when state information needs to be released. The general rule 1036 is that if state information is available when a message is to 1037 be "discarded without further processing", then the state 1038 information must also be released at that same time. 1040 7.1. Prepare an Outgoing SNMP Message 1042 This section describes the procedure followed to prepare an SNMPv3 1043 message from the data elements passed by the Message Dispatcher. 1045 1) The Message Dispatcher may request that an SNMPv3 message 1046 containing a GetRequest-PDU, GetNextRequest-PDU, GetBulkRequest- 1047 PDU, SetRequest-PDU, InformRequest-PDU, or SNMPv2-Trap-PDU be 1048 prepared for sending. 1050 a) It makes such a request according to the abstract service 1051 primitive: 1053 statusInformation = -- success or errorIndication 1054 prepareOutgoingMessage( 1055 IN transportDomain -- requested transport domain 1056 IN transportAddress -- requested destination address 1057 IN messageProcessingModel -- typically, SNMP version 1058 IN securityModel -- Security Model to use 1059 IN securityName -- on behalf of this principal 1060 IN securityLevel -- Level of Security requested 1061 IN contextEngineID -- data from/at this entity 1062 IN contextName -- data from/in this context 1063 IN pduVersion -- version of the PDU 1064 IN PDU -- SNMP Protocol Data Unit 1065 IN expectResponse -- TRUE or FALSE 1066 IN sendPduHandle -- the handle for matching 1067 -- incoming responses 1068 OUT destTransportDomain -- destination transport domain 1069 OUT destTransportAddress -- destination transport address 1070 OUT outgoingMessage -- the message to send 1071 OUT outgoingMessageLength -- the length of the message 1072 ) 1074 b) A unique msgID is generated. The number used for msgID should 1075 not have been used recently, and must not be the same as was 1076 used for any outstanding request. 1078 * SNMPv3 does not use the values of expectResponse or 1079 pduVersion. 1081 2) The Message Dispatcher may request that an SNMPv3 message 1082 containing a Response-PDU or Report-PDU be prepared for sending. 1084 a) It makes such a request according to the abstract service 1085 primitive: 1087 result = -- SUCCESS or FAILURE 1088 prepareResponseMessage( 1089 IN messageProcessingModel -- typically, SNMP version 1090 IN securityModel -- same as on incoming request 1091 IN securityName -- same as on incoming request 1092 IN securityLevel -- same as on incoming request 1093 IN contextEngineID -- data from/at this SNMP entity 1094 IN contextName -- data from/in this context 1095 IN pduVersion -- version of the PDU 1096 IN PDU -- SNMP Protocol Data Unit 1097 IN maxSizeResponseScopedPDU -- maximum size of Response PDU 1098 IN stateReference -- reference to state 1099 -- information presented with 1100 -- the request 1101 IN statusInformation -- success or errorIndication 1102 -- error counter OID and value 1103 -- when errorIndication 1104 OUT transportDomain -- destination transport domain 1105 OUT transportAddress -- destination transport address 1106 OUT outgoingMessage -- the message to send 1107 OUT outgoingMessageLength -- the length of the message 1108 ) 1110 b) The cached information for the original request is retrieved 1111 via the stateReference, including 1113 - msgID, 1114 - contextEngineID, 1115 - contextName, 1116 - securityModel, 1117 - securityName, 1118 - securityLevel, 1119 - securityStateReference, 1120 - reportableFlag, 1121 - transportDomain, and 1122 - transportAddress. 1124 The SNMPv3 Message Processing Model does not allow cached data 1125 to be overridden, except by error indications as detailed in 1126 (3) below. 1128 3) If statusInformation contains values for an OID/value combination 1129 (potentially also containing a securityLevel value, 1130 contextEngineID value, or contextName value), then 1131 a) If reportableFlag is zero, then the original message is 1132 discarded, and no further processing is done. A result of 1133 FAILURE is returned. SNMPv3 Message Processing is complete. 1135 b) If a PDU is provided, it is the PDU from the original request. 1136 If possible, extract the request-id. 1138 c) A Report PDU is prepared: 1140 1) the varBindList is set to contain the OID and value from the 1141 statusInformation 1143 2) error-status is set to 0 1145 3) error-index is set to 0. 1147 4) request-id is set to the value extracted in step b) 1148 Otherwise, request-id is set to 0 1150 d) The errorIndication in statusInformation may be accompanied by 1151 a securityLevel value, a contextEngineID value, or a 1152 contextName value. 1154 1) If statusInformation contains a value for securityLevel, 1155 then securityLevel is set to that value, otherwise it is set 1156 to noAuthNoPriv. 1158 2) If statusInformation contains a value for contextEngineID, 1159 then contextEngineID is set to that value, otherwise it is 1160 set to the value of this entity's snmpEngineID. 1162 3) If statusInformation contains a value for contextName, then 1163 contextName is set to that value, otherwise it is set to the 1164 default context of "" (zero-length string). 1166 e) PDU is set to refer to the new Report-PDU. The old PDU is 1167 discarded. 1169 f) Processing continues with step 6) below. 1171 4) If contextEngineID is not yet determined, then the contextEngineID 1172 is determined, in an implementation-dependent manner, possibly 1173 using the transportDomain and transportAddress. 1175 5) If the contextName is not yet determined, the contextName is set 1176 to the default context. 1178 6) A scopedPDU is prepared from the contextEngineID, contextName, and 1179 PDU. 1181 7) msgGlobalData is constructed as follows 1183 a) The msgVersion field is set to snmpv3(3). 1185 b) msgID is set as determined in step 1 or 2 above. 1187 c) msgMaxSize is set to an implementation-dependent value. 1189 d) msgFlags are set as follows: 1191 - If securityLevel specifies noAuthNoPriv, then authFlag and 1192 privFlag are both set to zero. 1194 - If securityLevel specifies authNoPriv, then authFlag is set 1195 to one and privFlag is set to zero. 1197 - If securityLevel specifies authPriv, then authFlag is set to 1198 one and privFlag is set to one. 1200 - If the PDU is a Response-PDU, Report-PDU or SNMPv2-Trap-PDU, 1201 then the reportableFlag is set to zero. 1203 - If the PDU is a GetRequest-PDU, GetNextRequest-PDU, 1204 GetBulkRequest-PDU, SetRequest-PDU, or InformRequest-PDU 1205 then the reportableFlag is set to one. 1207 - All other msgFlags bits are set to zero. 1209 e) msgSecurityModel is set to the value of securityModel 1211 8) If the PDU is a Response-PDU or Report-PDU, then 1212 a) The specified Security Model is called to generate the message 1213 according to the primitive: 1215 statusInformation = 1216 generateResponseMsg( 1217 IN messageProcessingModel -- SNMPv3 Message Processing 1218 -- Model 1219 IN globalData -- msgGlobalData from step 7 1220 IN maxMessageSize -- from msgMaxSize (step 7c) 1221 IN securityModel -- as determined in step 7e 1222 IN securityEngineID -- the value of snmpEngineID 1223 IN securityName -- on behalf of this principal 1224 IN securityLevel -- for the outgoing message 1225 IN scopedPDU -- as prepared in step 6) 1226 IN securityStateReference -- as determined in step 2 1227 OUT securityParameters -- filled in by Security Module 1228 OUT wholeMsg -- complete generated message 1229 OUT wholeMsgLength -- length of generated message 1230 ) 1232 If, upon return from the Security Model, the statusInformation 1233 includes an errorIndication, then any cached information about 1234 the outstanding request message is discarded, and an 1235 errorIndication is returned, so it can be returned to the 1236 calling application. SNMPv3 Message Processing is complete. 1238 b) A SUCCESS result is returned. SNMPv3 Message Processing is 1239 complete. 1241 9) If the PDU is a GetRequest-PDU, GetNextRequest-PDU, 1242 GetBulkRequest-PDU, SetRequest-PDU, InformRequest-PDU, or or 1243 SNMPv2-Trap-PDU, then 1245 a) If the PDU is an SNMPv2-Trap-PDU, then securityEngineID is set 1246 to the value of this entity's snmpEngineID. 1248 Otherwise, the snmpEngineID of the target entity is determined, 1249 in an implementation-dependent manner, possibly using 1250 transportDomain and transportAddress. The value of 1251 securityEngineID is set to the value of the target entity's 1252 snmpEngineID. 1254 b) The specified Security Model is called to generate the message 1255 according to the primitive: 1257 statusInformation = 1258 generateRequestMsg( 1259 IN messageProcessingModel -- SNMPv3 Message Processing Model 1260 IN globalData -- msgGlobalData, from step 7 1261 IN maxMessageSize -- from msgMaxSize in step 7 c) 1262 IN securityModel -- as provided by caller 1263 IN securityEngineID -- authoritative SNMP entity 1264 IN securityName -- as provided by caller 1265 IN securityLevel -- as provided by caller 1266 IN snmpEngineID -- as determined in step 9 a) 1267 IN scopedPDU -- as prepared in step 6 1268 OUT securityParameters -- filled in by Security Module 1269 OUT wholeMsg -- complete generated message 1270 OUT wholeMsgLength -- length of the generated message 1271 ) 1273 If, upon return from the Security Model, the statusInformation 1274 includes an errorIndication, then the message is discarded, and 1275 the errorIndication is returned, so it can be returned to the 1276 calling application, and no further processing is done. 1277 SNMPv3 Message Processing is complete. 1279 c) Information about the outgoing message is cached, and a 1280 stateReference is created (implementation-specific). 1281 Information to be cached includes the values of: 1283 - sendPduHandle 1284 - msgID 1285 - snmpEngineID 1286 - securityModel 1287 - securityName 1288 - securityLevel 1289 - contextEngineID 1290 - contextName 1292 d) A SUCCESS result is returned. SNMPv3 Message Processing is 1293 complete. 1295 7.2. Prepare Data Elements from an Incoming SNMP Message 1297 This section describes the procedure followed to extract data from an 1298 SNMPv3 message, and to prepare the data elements required for further 1299 processing of the message by the Message Dispatcher. 1301 1) The message is passed in from the Message Dispatcher according to 1302 the abstract service primitive: 1304 result = -- SUCCESS or errorIndication 1305 prepareDataElements( 1306 IN transportDomain -- origin transport domain 1307 IN transportAddress -- origin transport address 1308 IN wholeMsg -- as received from the network 1309 IN wholeMsgLength -- as received from the network 1310 OUT messageProcessingModel -- typically, SNMP version 1311 OUT securityModel -- Security Model to use 1312 OUT securityName -- on behalf of this principal 1313 OUT securityLevel -- Level of Security requested 1314 OUT contextEngineID -- data from/at this entity 1315 OUT contextName -- data from/in this context 1316 OUT pduVersion -- version of the PDU 1317 OUT PDU -- SNMP Protocol Data Unit 1318 OUT pduType -- SNMP PDU type 1319 OUT sendPduHandle -- handle for matched request 1320 OUT maxSizeResponseScopedPDU -- maximum size of Response PDU 1321 OUT statusInformation -- success or errorIndication 1322 -- error counter OID and value 1323 -- when errorIndication 1324 OUT stateReference -- reference to state information 1325 -- to be used for a possible 1326 ) -- Response 1328 2) If the received message is not the serialization (according to 1329 the conventions of [RFC1906]) of an SNMPv3Message value, then the 1330 snmpInASNParseErrs counter [RFC1907] is incremented, the message 1331 is discarded without further processing, and a FAILURE result is 1332 returned. SNMPv3 Message Processing is complete. 1334 3) The values for msgVersion, msgID, msgMaxSize, msgFlags, 1335 msgSecurityModel, msgSecurityParameters, and msgData are 1336 extracted from the message. 1338 4) If the value of the msgSecurityModel component does not match a 1339 supported securityModel, then the snmpUnknownSecurityModels 1340 counter is incremented, a Report PDU is generated, the message is 1341 discarded without further processing, and a FAILURE result is 1342 returned. SNMPv3 Message Processing is complete. 1344 5) The securityLevel is determined from the authFlag and the 1345 privFlag bits of the msgFlags component as follows: 1347 a) If the authFlag is not set and the privFlag is not set, then 1348 securityLevel is set to noAuthNoPriv. 1350 b) If the authFlag is set and the privFlag is not set, then 1351 securityLevel is set to authNoPriv. 1353 c) If the authFlag is set and the privFlag is set, then 1354 securityLevel is set to authPriv. 1356 d) If the authFlag is not set and privFlag is set, then the 1357 snmpInvalidMsgs counter is incremented, a Report PDU is 1358 generated, the message is discarded without further 1359 processing, and a FAILURE result is returned. SNMPv3 Message 1360 Processing is complete. 1362 6) The security module implementing the Security Model as specified 1363 by the securityModel component is called for authentication and 1364 privacy services. This is done according to the abstract service 1365 primitive: 1367 statusInformation = -- errorIndication or success 1368 -- error counter OID and 1369 -- value if error 1370 processIncomingMsg( 1371 IN messageProcessingModel -- SNMPv3 Message Processing Model 1372 IN expectResponse -- TRUE or FALSE 1373 IN maxMessageSize -- of the sending SNMP entity 1374 IN securityParameters -- for the received message 1375 IN securityModel -- for the received message 1376 IN securityLevel -- Level of Security 1377 IN wholeMsg -- as received on the wire 1378 IN wholeMsgLength -- length as received on the wire 1379 OUT securityEngineID -- authoritative SNMP entity 1380 OUT securityName -- identification of the principal 1381 OUT scopedPDU, -- message (plaintext) payload 1382 OUT maxSizeResponseScopedPDU -- maximum size of Response PDU 1383 OUT securityStateReference -- reference to security state 1384 ) -- information, needed for 1385 -- response 1387 If an errorIndication is returned by the security module, then 1389 a) If statusInformation contains values for an OID/value pair, 1390 then a Report PDU is generated. 1392 1) If the scopedPDU has been returned from ProcessIncomingMsg 1393 then determine contextEngineID, contextName, and PDU. 1395 2) Information about the message is cached and a 1396 stateReference is created (implementation-specific). 1397 Information to be cached includes the values of: 1399 msgVersion, 1400 msgID, 1401 securityLevel, 1402 msgFlags, 1403 msgMaxSize, 1404 securityModel, 1405 maxSizeResponseScopedPDU, 1406 securityStateReference 1408 3) Request that a Report-PDU be prepared and sent, according 1409 to the abstract service primitive: 1411 result = -- SUCCESS or FAILURE 1412 returnResponsePDU( 1413 IN messageProcessingModel -- SNMPv3(3) 1414 IN securityModel -- same as on incoming request 1415 IN securityName -- from ProcessIncomingMsg 1416 IN securityLevel -- same as on incoming request 1417 IN contextEngineID -- from step 6 a) 1) 1418 IN contextName -- from step 6 a) 1) 1419 IN pduVersion -- SNMPv2-PDU 1420 IN PDU -- from step 6 a) 1) 1421 IN maxSizeResponseScopedPDU -- from ProcessIncomingMsg 1422 IN stateReference -- from step 6 a) 2) 1423 IN statusInformation -- from ProcessIncomingMsg 1424 OUT transportDomain -- destination's transport 1425 -- domain 1426 OUT transportAddress -- destination's transport 1427 -- address 1428 OUT outgoingMessage -- the message to send 1429 OUT outgoingMessageLength -- the length of the message 1430 ) 1432 b) The incoming message is discarded without further processing, 1433 and a FAILURE result is returned. SNMPv3 Message Processing is 1434 complete. 1436 7) The scopedPDU is parsed to extract the contextEngineID, the 1437 contextName and the PDU. If any parse error occurs, then the 1438 snmpInASNParseErrs counter [RFC1907] is incremented, the security 1439 state information is discarded, the message is discarded without 1440 further processing, and a FAILURE result is returned. SNMPv3 1441 Message Processing is complete. 1443 8) The pduVersion is set to an SNMPv2-PDU. 1445 9) The pduType is determined, in an implementation-dependent manner, 1446 to be: 1448 - a GetRequest-PDU, 1449 - a GetNextRequest-PDU, 1450 - a GetBulkRequest-PDU, 1451 - a SetRequest-PDU, 1452 - an InformRequest-PDU, 1453 - an SNMPv2-Trap-PDU, 1454 - a Response-PDU, or 1455 - a Report-PDU. 1457 10) If the pduType is a Response-PDU or Report-PDU, then 1459 a) The value of the msgID component is used to find the cached 1460 information for a corresponding outstanding Request message. 1461 If no such outstanding Request message is found, then the 1462 security state information is discarded, the message is 1463 discarded without further processing, and a FAILURE result is 1464 returned. SNMPv3 Message Processing is complete. 1466 b) sendPduHandle is retrieved from the cached information. 1468 Otherwise, sendPduHandle is set to , an implementation 1469 defined value. 1471 11) If the pduType is a Report-PDU, then 1473 a) statusInformation is created using the contents of the 1474 Report-PDU, in an implementation-dependent manner. This 1475 statusInformation will be forwarded to the application 1476 associated with the sendPduHandle. 1478 b) Any cached information about the outstanding Request message 1479 message is discarded. 1481 c) The security state information for this incoming message is 1482 discarded. 1484 d) stateReference is set to 1486 e) A SUCCESS result is returned. SNMPv3 Message Processing is 1487 complete. 1489 12) If the pduType is a Response-PDU, then 1491 a) The cached data for the outstanding request, referred to by 1492 stateReference, is retrieved, including 1494 - snmpEngineID 1495 - securityModel 1496 - securityName 1497 - securityLevel 1498 - contextEngineID 1499 - contextName 1501 b) If the values extracted from the incoming message differ from 1502 the cached data, then the security state information is 1503 discarded, any cached information about the outstanding 1504 Request message is discarded, the incoming message is 1505 discarded without further processing, and a FAILURE result is 1506 returned. SNMPv3 Message Processing is complete. 1508 c) Otherwise, any cached information about the outstanding 1509 Request message is discarded, and stateReference is set to 1510 . 1512 d) A SUCCESS result is returned. SNMPv3 Message Processing is 1513 complete. 1515 13) If the pduType is a GetRequest-PDU, GetNextRequest-PDU, 1516 GetBulkRequest-PDU, SetRequest-PDU, or InformRequest-PDU, then 1518 a) If the value of securityEngineID is not equal to the value of 1519 snmpEngineID, then the security state information is 1520 discarded, any cached information about the outstanding 1521 Request message is discarded, the incoming message is 1522 discarded without further processing, and a FAILURE result is 1523 returned. SNMPv3 Message Processing is complete. 1525 b) Information about the message is cached and a stateReference 1526 is created (implementation-specific). Information to be 1527 cached includes the values of: 1529 msgVersion, 1530 msgID, 1531 securityLevel, 1532 msgFlags, 1533 msgMaxSize, 1534 securityModel, 1535 maxSizeResponseScopedPDU, 1536 securityStateReference 1538 c) A SUCCESS result is returned. SNMPv3 Message Processing is 1539 complete. 1541 14) If the pduType is an SNMPv2-Trap-PDU, then A SUCCESS result is 1542 returned. SNMPv3 Message Processing is complete. 1544 8. Security Considerations 1546 The Dispatcher coordinates the processing of messages to provide a 1547 level of security for management messages and to direct the SNMP PDUs 1548 to the proper SNMP application(s). 1550 A Message Processing Model, and in particular the V3MP defined in 1551 this document, interacts as part of the Message Processing with 1552 Security Models in the Security Subsystem via the abstract service 1553 interface primitives defined in [SNMP-ARCH] and elaborated above. 1555 The level of security actually provided is primarily determined by 1556 the specific Security Model implementation(s) and the specific SNMP 1557 application implementation(s) incorporated into this framework. 1558 Applications have access to data which is not secured. Applications 1559 should take reasonable steps to protect the data from disclosure, and 1560 when they send data across the network, they should obey the 1561 securityLevel and call upon the services of an Access Control Model 1562 as they apply access control. 1564 The values for the msgID element used in communication between SNMP 1565 entities must be chosen to avoid replay attacks. The values do not 1566 need to be unpredictable; it is sufficient that they not repeat. 1568 9. Editors' Addresses 1570 Co-editor: Jeffrey Case 1571 SNMP Research, Inc. 1572 postal: 3001 Kimberlin Heights Road 1573 Knoxville, TN 37920-9716 1574 USA 1575 email: case@snmp.com 1576 phone: +1 423-573-1434 1578 Co-editor Dave Harrington 1579 Cabletron Systems, Inc 1580 postal: Post Office Box 5005 1581 Mail Stop: Durham 1582 35 Industrial Way 1583 Rochester, NH 03867-5005 1584 USA 1585 email: dbh@cabletron.com 1586 phone: +1 603-337-7357 1587 Co-editor: Randy Presuhn 1588 BMC Software, Inc. 1589 postal: 1190 Saratoga Avenue 1590 Suite 130 1591 San Jose, CA 95129 1592 USA 1593 email: rpresuhn@bmc.com 1594 phone: +1 408-556-0720 1596 Co-editor: Bert Wijnen 1597 IBM T. J. Watson Research 1598 postal: Schagen 33 1599 3461 GL Linschoten 1600 Netherlands 1601 email: wijnen@vnet.ibm.com 1602 phone: +31 348-432-794 1604 10. Acknowledgements 1606 This document is the result of the efforts of the SNMPv3 Working 1607 Group. Some special thanks are in order to the following SNMPv3 WG 1608 members: 1610 Dave Battle (SNMP Research, Inc.) 1611 Uri Blumenthal (IBM T.J. Watson Research Center) 1612 Jeff Case (SNMP Research, Inc.) 1613 John Curran (BBN) 1614 T. Max Devlin (Hi-TECH Connections) 1615 John Flick (Hewlett Packard) 1616 David Harrington (Cabletron Systems Inc.) 1617 N.C. Hien (IBM T.J. Watson Research Center) 1618 Dave Levi (SNMP Research, Inc.) 1619 Louis A Mamakos (UUNET Technologies Inc.) 1620 Paul Meyer (Secure Computing Corporation) 1621 Keith McCloghrie (Cisco Systems) 1622 Russ Mundy (Trusted Information Systems, Inc.) 1623 Bob Natale (ACE*COMM Corporation) 1624 Mike O'Dell (UUNET Technologies Inc.) 1625 Dave Perkins (DeskTalk) 1626 Peter Polkinghorne (Brunel University) 1627 Randy Presuhn (BMC Software, Inc.) 1628 David Reid (SNMP Research, Inc.) 1629 Shawn Routhier (Epilogue) 1630 Juergen Schoenwaelder (TU Braunschweig) 1631 Bob Stewart (Cisco Systems) 1632 Bert Wijnen (IBM T.J. Watson Research Center) 1634 The document is based on recommendations of the IETF Security and 1635 Administrative Framework Evolution for SNMP Advisory Team. Members 1636 of that Advisory Team were: 1638 David Harrington (Cabletron Systems Inc.) 1639 Jeff Johnson (Cisco Systems) 1640 David Levi (SNMP Research Inc.) 1641 John Linn (Openvision) 1642 Russ Mundy (Trusted Information Systems) chair 1643 Shawn Routhier (Epilogue) 1644 Glenn Waters (Nortel) 1645 Bert Wijnen (IBM T. J. Watson Research Center) 1647 As recommended by the Advisory Team and the SNMPv3 Working Group 1648 Charter, the design incorporates as much as practical from previous 1649 RFCs and drafts. As a result, special thanks are due to the authors 1650 of previous designs known as SNMPv2u and SNMPv2*: 1652 Jeff Case (SNMP Research, Inc.) 1653 David Harrington (Cabletron Systems Inc.) 1654 David Levi (SNMP Research, Inc.) 1655 Keith McCloghrie (Cisco Systems) 1656 Brian O'Keefe (Hewlett Packard) 1657 Marshall T. Rose (Dover Beach Consulting) 1658 Jon Saperia (BGS Systems Inc.) 1659 Steve Waldbusser (International Network Services) 1660 Glenn W. Waters (Bell-Northern Research Ltd.) 1662 11. References 1664 [RFC1901] The SNMPv2 Working Group, Case, J., McCloghrie, K., Rose, M., 1665 and S., Waldbusser, "Introduction to Community-based SNMPv2", RFC 1666 1901, January 1996. 1668 [RFC1902] The SNMPv2 Working Group, Case, J., McCloghrie, K., Rose, M., 1669 and S., Waldbusser, "Structure of Management Information for 1670 Version 2 of the Simple Network Management Protocol (SNMPv2)", RFC 1671 1902, January 1996. 1673 [RFC1905] The SNMPv2 Working Group, Case, J., McCloghrie, K., Rose, M., 1674 and S., Waldbusser, "Protocol Operations for Version 2 of the 1675 Simple Network Management Protocol (SNMPv2)", RFC 1905, January 1676 1996. 1678 [RFC1906] The SNMPv2 Working Group, Case, J., McCloghrie, K., Rose, M., 1679 and S. Waldbusser, "Transport Mappings for Version 2 of the Simple 1680 Network Management Protocol (SNMPv2)", RFC 1906, January 1996. 1682 [RFC1907] The SNMPv2 Working Group, Case, J., McCloghrie, K., Rose, M., 1683 and S. Waldbusser, "Management Information Base for Version 2 of 1684 the Simple Network Management Protocol (SNMPv2)", RFC 1907 January 1685 1996. 1687 [RFC1908] The SNMPv2 Working Group, Case, J., McCloghrie, K., Rose, M., 1688 and S. Waldbusser, "Coexistence between Version 1 and Version 2 of 1689 the Internet-standard Network Management Framework", RFC 1908, 1690 January 1996. 1692 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1693 Requirement Levels", RFC 2119, BCP 14, March 1997. 1695 [SNMP-ARCH] The SNMPv3 Working Group, Harrington, D., Presuhn, R., 1696 Wijnen, B., "An Architecture for describing SNMP Management 1697 Frameworks", , September 1698 1997. 1700 [SNMP-USM] The SNMPv3 Working Group, Blumenthal, U., Wijnen, B., "The 1701 User-Based Security Model for Version 3 of the Simple Network 1702 Management Protocol (SNMPv3)", , 1703 September 1997. 1705 [SNMP-ACM] The SNMPv3 Working Group, Wijnen, B., Presuhn, R., 1706 McCloghrie, K., "View-based Access Control Model for the Simple 1707 Network Management Protocol (SNMP)", 1708 , September 1997. 1710 [SNMP-APPL] The SNMPv3 Working Group, Levi, D. B., Meyer, P., Stewart, 1711 B., "SNMPv3 Applications", , 1712 September 1997. 1714 12. Issues 1716 The revision history in this section will be deleted when this 1717 material is submitted for last call. The remaining material in this 1718 section will be deleted in the transition from internet-draft to RFC. 1720 12.1. Open Issues 1722 The following open issues need to be resolved. 1724 - The more precise specification of the handling of the 1725 reportableFlag begs the question of what an engine is supposed 1726 to do when it receives a message with an illegal combination of 1727 the reportableFlag and PDU type. 1729 The paragraph beginning with "Report PDUs are engine-to-engine 1730 communications...." has been deleted. The old text was a bit 1731 of an overspecification, but in the past the first part of that 1732 paragraph has proven valuable in explaining to people just what 1733 report PDUs are for. 1735 12.2. Resolved Issues 1737 12.3. Change Log 1739 The following change log records major changes. The version 1740 identifiers are for the convenience of the document's editors. 1742 [Current] 1744 - updated clause 7.1 to allow context override for error 1745 indications 1747 - removed old change logs and resolved issues 1749 - updated draft identifiers in references section 1750 Table of Contents 1752 1. Introduction ................................................... 2 1754 2. Overview ....................................................... 2 1756 2.1. The Dispatcher. ............................................. 4 1758 2.2. Message Processing Subsystem ................................. 4 1760 3. Elements of Message Processing and Dispatching ................. 4 1762 3.1. messageProcessingModel ....................................... 5 1764 3.2. pduVersion ................................................... 5 1766 3.3. pduType ...................................................... 6 1768 3.4. sendPduHandle ................................................ 6 1770 4. Dispatcher Elements of Procedure ............................... 7 1772 4.1. Sending an SNMP Message to the Network ....................... 7 1774 4.1.1. Sending a Request or Notification .......................... 7 1776 4.1.2. Sending a Response to the Network .......................... 8 1778 4.2. Receiving an SNMP Message from the Network ................... 10 1780 4.2.1. Message Dispatching of received SNMP Messages .............. 10 1782 4.2.2. PDU Dispatching for Incoming Messages ...................... 11 1784 4.2.2.1. PDU Dispatching for Incoming Messages: Requests and 1785 Notifications ..................................................... 11 1787 4.2.2.2. PDU Dispatching for Incoming Messages: Responses ........ 13 1789 4.3. Application Registration for Handling PDU types .............. 14 1791 4.4. Application Unregistration for Handling PDU Types ............ 15 1792 5. Definitions .................................................... 15 1794 5.1. Definitions for SNMP Message Processing and Dispatching ...... 15 1796 6. The SNMPv3 Message Format ...................................... 19 1798 6.1. msgVersion ................................................... 20 1800 6.2. msgID ........................................................ 20 1802 6.3. msgMaxSize ................................................... 20 1804 6.4. msgFlags ..................................................... 20 1806 6.5. msgSecurityModel ............................................. 22 1808 6.6. msgSecurityParameters ........................................ 23 1810 6.7. scopedPduData ................................................ 23 1812 6.8. scopedPDU .................................................... 23 1814 6.8.1. contextEngineID ............................................ 23 1816 6.8.2. contextName ................................................ 23 1818 6.8.3. data ....................................................... 24 1820 7. Elements of Procedure for v3MP ................................. 24 1822 7.1. Prepare an Outgoing SNMP Message ............................. 24 1824 7.2. Prepare Data Elements from an Incoming SNMP Message .......... 30 1826 8. Security Considerations ........................................ 36 1828 9. Editors' Addresses ............................................. 36 1830 10. Acknowledgements .............................................. 37 1832 11. References .................................................... 38 1834 12. Issues ........................................................ 40 1836 12.1. Open Issues ................................................. 40 1838 12.2. Resolved Issues ............................................. 40 1839 12.3. Change Log .................................................. 40