idnits 2.17.1 draft-ietf-snmpv3-usm-v2-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Looks like you're using RFC 2026 boilerplate. This must be updated to follow RFC 3978/3979, as updated by RFC 4748. 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. == No 'Intended status' indicated for this document; assuming Proposed Standard == The page length should not exceed 58 lines per page, but there was 8 longer pages, the longest (page 2) being 114 lines == It seems as if not all pages are separated by form feeds - found 76 form feeds but 78 pages 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. == There are 1 instance of lines with non-RFC6890-compliant IPv4 addresses in the document. If these are example addresses, they should be changed. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the RFC 3978 Section 5.4 Copyright Line does not match the current year == Line 3352 has weird spacing: '...ageType any...' == Line 3375 has weird spacing: '... u_int pass...' == Line 3377 has weird spacing: '... u_int engi...' == Line 3424 has weird spacing: '... u_int pass...' == Line 3426 has weird spacing: '... u_int engi...' -- 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 (11 December 1997) is 9631 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. 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: 'SNMP-USM' is mentioned on line 149, but not defined == Missing Reference: 'SNMP-MP' is mentioned on line 745, but not defined == Missing Reference: 'Localized-key' is mentioned on line 3162, but not defined == Missing Reference: 'RFC1321' is mentioned on line 3360, but not defined -- Looks like a reference, but probably isn't: '64' on line 3381 -- Looks like a reference, but probably isn't: '72' on line 3430 == Unused Reference: 'BCP-11' is defined on line 3229, but no explicit reference was found in the text == Unused Reference: 'Localized-Key' is defined on line 3237, but no explicit reference was found in the text ** Obsolete normative reference: RFC 1903 (Obsoleted by RFC 2579) ** 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) ** Downref: Normative reference to an Informational RFC: RFC 2104 ** Obsolete normative reference: RFC 2028 (ref. 'BCP-11') (Obsoleted by RFC 9281) -- Unexpected draft version: The latest known version of draft-ietf-snmpv3-next-gen-arch is -06, but you're referring to -07. -- Possible downref: Non-RFC (?) normative reference: ref. 'Localized-Key' ** Downref: Normative reference to an Informational RFC: RFC 1321 (ref. 'MD5') -- Possible downref: Non-RFC (?) normative reference: ref. 'DES-NIST' -- Possible downref: Non-RFC (?) normative reference: ref. 'DES-ANSI' -- Possible downref: Non-RFC (?) normative reference: ref. 'DESO-NIST' -- Possible downref: Non-RFC (?) normative reference: ref. 'DESO-ANSI' -- Possible downref: Non-RFC (?) normative reference: ref. 'DESG-NIST' -- Possible downref: Non-RFC (?) normative reference: ref. 'DEST-NIST' -- Possible downref: Non-RFC (?) normative reference: ref. 'DESM-NIST' -- Possible downref: Non-RFC (?) normative reference: ref. 'SHA-NIST' Summary: 16 errors (**), 0 flaws (~~), 16 warnings (==), 15 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 INTERNET-DRAFT U. Blumenthal 3 IBM T. J. Watson Research 4 B. Wijnen 5 IBM T. J. Watson Research 6 11 December 1997 8 User-based Security Model (USM) for version 3 of the 9 Simple Network Management Protocol (SNMPv3) 10 12 Status of this Memo 14 This document is an Internet-Draft. Internet-Drafts are working 15 documents of the Internet Engineering Task Force (IETF), its areas, 16 and its working groups. Note that other groups may also distribute 17 working documents as Internet-Drafts. 19 Internet-Drafts are draft documents valid for a maximum of six months 20 and may be updated, replaced, or obsoleted by other documents at any 21 time. It is inappropriate to use Internet- Drafts as reference 22 material or to cite them other than as ``work in progress.'' 24 To learn the current status of any Internet-Draft, please check the 25 ``1id-abstracts.txt'' listing contained in the Internet- Drafts Shadow 26 Directories on ds.internic.net (US East Coast), nic.nordu.net (Europe), 27 ftp.isi.edu (US West Coast), or munnari.oz.au (Pacific Rim). 29 Copyright Notice 31 Copyright (C) The Internet Society (1997). All Rights Reserved. 33 Abstract 35 This document describes the User-based Security Model (USM) for SNMP 36 version 3 for use in the SNMP architecture [SNMP-ARCH]. It defines 37 the Elements of Procedure for providing SNMP message level security. 38 This document also includes a MIB for remotely monitoring/managing 39 the configuration parameters for this Security Model. 41 SNMPv3 Working Group Expires June 1998 [Page 1] 42 ^L 43 Table of Contents 45 1. Introduction 4 46 1.1. Threats 4 47 1.2. Goals and Constraints 6 48 1.3. Security Services 6 49 1.4. Module Organization 7 50 1.4.1. Timeliness Module 8 51 1.4.2. Authentication Protocol 8 52 1.4.3. Privacy Protocol 8 53 1.5. Protection against Message Replay, Delay and Redirection 8 54 1.5.1. Authoritative SNMP engine 8 55 1.5.2. Mechanisms 9 56 1.6. Abstract Service Interfaces. 10 57 1.6.1. User-based Security Model Primitives for Authentication 11 58 1.6.2. User-based Security Model Primitives for Privacy 11 59 2. Elements of the Model 13 60 2.1. User-based Security Model Users 13 61 2.2. Replay Protection 14 62 2.2.1. msgAuthoritativeEngineID 14 63 2.2.2. msgAuthoritativeEngineBoots and msgAuthoritativeEngineTime 14 64 2.2.3. Time Window 15 65 2.3. Time Synchronization 16 66 2.4. SNMP Messages Using this Security Model 17 67 2.5. Services provided by the User-based Security Model 18 68 2.5.1. Services for Generating an Outgoing SNMP Message 18 69 2.5.2. Services for Processing an Incoming SNMP Message 20 70 2.6. Key Localization Algorithm. 21 71 3. Elements of Procedure 23 72 3.1. Generating an Outgoing SNMP Message 23 73 3.2. Processing an Incoming SNMP Message 26 74 4. Discovery 32 75 5. Definitions 33 76 6. HMAC-MD5-96 Authentication Protocol 47 77 6.1. Mechanisms 47 78 6.1.1. Digest Authentication Mechanism 47 79 6.2. Elements of the Digest Authentication Protocol 48 80 6.2.1. Users 48 81 6.2.2. msgAuthoritativeEngineID 48 82 6.2.3. SNMP Messages Using this Authentication Protocol 48 83 6.2.4. Services provided by the HMAC-MD5-96 Authentication Module 49 84 6.2.4.1. Services for Generating an Outgoing SNMP Message 49 85 6.2.4.2. Services for Processing an Incoming SNMP Message 49 86 6.3. Elements of Procedure 50 87 6.3.1. Processing an Outgoing Message 50 88 6.3.2. Processing an Incoming Message 51 89 7. HMAC-SHA-96 Authentication Protocol 53 90 7.1. Mechanisms 53 91 7.1.1. Digest Authentication Mechanism 53 92 7.2. Elements of the HMAC-SHA-96 Authentication Protocol 54 93 7.2.1. Users 54 95 ^L 96 7.2.2. msgAuthoritativeEngineID 54 97 7.2.3. SNMP Messages Using this Authentication Protocol 54 98 7.2.4. Services provided by the HMAC-SHA-96 Authentication Module 55 99 7.2.4.1. Services for Generating an Outgoing SNMP Message 55 100 7.2.4.2. Services for Processing an Incoming SNMP Message 55 101 7.3. Elements of Procedure 56 102 7.3.1. Processing an Outgoing Message 56 103 7.3.2. Processing an Incoming Message 57 104 8. CBC-DES Symmetric Encryption Protocol 59 105 8.1. Mechanisms 59 106 8.1.1. Symmetric Encryption Protocol 59 107 8.1.1.1. DES key and Initialization Vector. 60 108 8.1.1.2. Data Encryption. 60 109 8.1.1.3. Data Decryption 61 110 8.2. Elements of the DES Privacy Protocol 61 111 8.2.1. Users 61 112 8.2.2. msgAuthoritativeEngineID 61 113 8.2.3. SNMP Messages Using this Privacy Protocol 62 114 8.2.4. Services provided by the DES Privacy Module 62 115 8.2.4.1. Services for Encrypting Outgoing Data 62 116 8.2.4.2. Services for Decrypting Incoming Data 63 117 8.3. Elements of Procedure. 63 118 8.3.1. Processing an Outgoing Message 63 119 8.3.2. Processing an Incoming Message 64 120 9. Intellectual Property 65 121 A.1. SNMP engine Installation Parameters 72 122 A.2. Password to Key Algorithm 73 123 A.2.1. Password to Key Sample Code for MD5 74 124 A.2.2. Password to Key Sample Code for SHA 75 125 A.3. Password to Key Sample Results 76 126 A.3.1. Password to Key Sample Results using MD5 76 127 A.3.2. Password to Key Sample Results using SHA 76 128 A.4. Sample encoding of msgSecurityParameters 77 129 B. Full Copyright Statement 77 130 1. Introduction 132 The Architecture for describing Internet Management Frameworks 133 [SNMP-ARCH] describes that an SNMP engine is composed of: 135 1) a Dispatcher 136 2) a Message Processing Subsystem, 137 3) a Security Subsystem, and 138 4) an Access Control Subsystem. 140 Applications make use of the services of these subsystems. 142 It is important to understand the SNMP architecture and the 143 terminology of the architecture to understand where the Security 144 Model described in this document fits into the architecture and 145 interacts with other subsystems within the architecture. The 146 reader is expected to have read and understood the description of 147 the SNMP architecture, as defined in [SNMP-ARCH]. 149 This memo [SNMP-USM] describes the User-based Security Model as it 150 is used within the SNMP Architecture. The main idea is that we use 151 the traditional concept of a user (identified by a userName) with 152 which to associate security information. 154 This memo describes the use of HMAC-MD5-96 and HMAC-SHA-96 as the 155 authentication protocols and the use of CBC-DES as the privacy 156 protocol. The User-based Security Model however allows for other 157 such protocols to be used instead of or concurrent with these 158 protocols. Therefore, the description of HMAC-MD5-96, HMAC-SHA-96 159 and CBC-DES are in separate sections to reflect their self-contained 160 nature and to indicate that they can be replaced or supplemented in 161 the future. 163 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 164 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 165 document are to be interpreted as described in [RFC2119]. 167 1.1. Threats 169 Several of the classical threats to network protocols are 170 applicable to the network management problem and therefore would 171 be applicable to any SNMP Security Model. Other threats are not 172 applicable to the network management problem. This section 173 discusses principal threats, secondary threats, and threats which 174 are of lesser importance. 176 The principal threats against which this SNMP Security Model 177 should provide protection are: 179 - Modification of Information 180 The modification threat is the danger that some unauthorized 182 SNMPv3 Working Group Expires June 1998 [Page 4] 183 entity may alter in-transit SNMP messages generated on behalf 184 of an authorized user in such a way as to effect unauthorized 185 management operations, including falsifying the value of an 186 object. 188 - Masquerade 189 The masquerade threat is the danger that management operations 190 not authorized for some user may be attempted by assuming the 191 identity of another user that has the appropriate authorizations. 193 Two secondary threats are also identified. The Security Model 194 defined in this memo provides limited protection against: 196 - Disclosure 197 The disclosure threat is the danger of eavesdropping on the 198 exchanges between managed agents and a management station. 199 Protecting against this threat may be required as a matter of 200 local policy. 202 - Message Stream Modification 203 The SNMP protocol is typically based upon a connection-less 204 transport service which may operate over any sub-network service. 205 The re-ordering, delay or replay of messages can and does occur 206 through the natural operation of many such sub-network services. 207 The message stream modification threat is the danger that 208 messages may be maliciously re-ordered, delayed or replayed to 209 an extent which is greater than can occur through the natural 210 operation of a sub-network service, in order to effect 211 unauthorized management operations. 213 There are at least two threats that an SNMP Security Model need 214 not protect against. The security protocols defined in this memo 215 do not provide protection against: 217 - Denial of Service 218 This SNMP Security Model does not attempt to address the broad 219 range of attacks by which service on behalf of authorized users 220 is denied. Indeed, such denial-of-service attacks are in many 221 cases indistinguishable from the type of network failures with 222 which any viable network management protocol must cope as a 223 matter of course. 224 - Traffic Analysis 225 This SNMP Security Model does not attempt to address traffic 226 analysis attacks. Indeed, many traffic patterns are predictable 227 - devices may be managed on a regular basis by a relatively small 228 number of management applications - and therefore there is no 229 significant advantage afforded by protecting against traffic 230 analysis. 232 SNMPv3 Working Group Expires June 1998 [Page 5] 233 1.2. Goals and Constraints 235 Based on the foregoing account of threats in the SNMP network 236 management environment, the goals of this SNMP Security Model 237 are as follows. 239 1) Provide for verification that each received SNMP message has 240 not been modified during its transmission through the network. 242 2) Provide for verification of the identity of the user on whose 243 behalf a received SNMP message claims to have been generated. 245 3) Provide for detection of received SNMP messages, which request 246 or contain management information, whose time of generation was 247 not recent. 249 4) Provide, when necessary, that the contents of each received 250 SNMP message are protected from disclosure. 252 In addition to the principal goal of supporting secure network 253 management, the design of this SNMP Security Model is also 254 influenced by the following constraints: 256 1) When the requirements of effective management in times of 257 network stress are inconsistent with those of security, the 258 design should prefer the former. 260 2) Neither the security protocol nor its underlying security 261 mechanisms should depend upon the ready availability of other 262 network services (e.g., Network Time Protocol (NTP) or key 263 management protocols). 265 3) A security mechanism should entail no changes to the basic 266 SNMP network management philosophy. 268 1.3. Security Services 270 The security services necessary to support the goals of this SNMP 271 Security Model are as follows: 273 - Data Integrity 274 is the provision of the property that data has not been altered 275 or destroyed in an unauthorized manner, nor have data sequences 276 been altered to an extent greater than can occur non-maliciously. 278 - Data Origin Authentication 279 is the provision of the property that the claimed identity of 280 the user on whose behalf received data was originated is 281 corroborated. 283 - Data Confidentiality 285 SNMPv3 Working Group Expires June 1998 [Page 6] 286 is the provision of the property that information is not made 287 available or disclosed to unauthorized individuals, entities, 288 or processes. 290 - Message timeliness and limited replay protection 291 is the provision of the property that a message whose generation 292 time is outside of a specified time window is not accepted. 293 Note that message reordering is not dealt with and can occur in 294 normal conditions too. 296 For the protocols specified in this memo, it is not possible to 297 assure the specific originator of a received SNMP message; rather, 298 it is the user on whose behalf the message was originated that is 299 authenticated. 301 For these protocols, it not possible to obtain data integrity 302 without data origin authentication, nor is it possible to obtain 303 data origin authentication without data integrity. Further, 304 there is no provision for data confidentiality without both data 305 integrity and data origin authentication. 307 The security protocols used in this memo are considered acceptably 308 secure at the time of writing. However, the procedures allow for 309 new authentication and privacy methods to be specified at a future 310 time if the need arises. 312 1.4. Module Organization 314 The security protocols defined in this memo are split in three 315 different modules and each has its specific responsibilities such 316 that together they realize the goals and security services 317 described above: 319 - The authentication module MUST provide for: 321 - Data Integrity, 323 - Data Origin Authentication 325 - The timeliness module MUST provide for: 327 - Protection against message delay or replay (to an extent 328 greater than can occur through normal operation) 330 - The privacy module MUST provide for 332 - Protection against disclosure of the message payload. 334 The timeliness module is fixed for the User-based Security Model 335 while there is provision for multiple authentication and/or 336 privacy modules, each of which implements a specific authentication 338 SNMPv3 Working Group Expires June 1998 [Page 7] 339 or privacy protocol respectively. 341 1.4.1. Timeliness Module 343 Section 3 (Elements of Procedure) uses the timeliness values in an 344 SNMP message to do timeliness checking. The timeliness check is 345 only performed if authentication is applied to the message. Since 346 the complete message is checked for integrity, we can assume that 347 the timeliness values in a message that passes the authentication 348 module are trustworthy. 350 1.4.2. Authentication Protocol 352 Section 6 describes the HMAC-MD5-96 authentication protocol which 353 is the first authentication protocol that MUST be supported with 354 the User-based Security Model. 355 Section 7 describes the HMAC-SHA-96 authentication protocol which 356 is another authentication protocol that SHOULD be supported with 357 the User-based Security Model. 358 In the future additional or replacement authentication protocols may 359 be defined as new needs arise. 361 The User-based Security Model prescribes that, if authentication 362 is used, then the complete message is checked for integrity in 363 the authentication module. 365 For a message to be authenticated, it needs to pass authentication 366 check by the authentication module and the timeliness check which 367 is a fixed part of this User-based Security model. 369 1.4.3. Privacy Protocol 371 Section 8 describes the CBC-DES Symmetric Encryption Protocol 372 which is the first privacy protocol to be used with the 373 User-based Security Model. In the future additional or 374 replacement privacy protocols may be defined as new needs arise. 376 The User-based Security Model prescribes that the scopedPDU 377 is protected from disclosure when a message is sent with privacy. 379 The User-based Security Model also prescribes that a message 380 needs to be authenticated if privacy is in use. 382 1.5. Protection against Message Replay, Delay and Redirection 384 1.5.1. Authoritative SNMP engine 386 In order to protect against message replay, delay and redirection, 387 one of the SNMP engines involved in each communication is 388 designated to be the authoritative SNMP engine. When an SNMP 389 message contains a payload which expects a response (for example 391 SNMPv3 Working Group Expires June 1998 [Page 8] 392 a Get, GetNext, GetBulk, Set or Inform PDU), then the receiver of 393 such messages is authoritative. When an SNMP message contains a 394 payload which does not expect a response (for example an 395 SNMPv2-Trap, Response or Report PDU), then the sender of such a 396 message is authoritative. 398 1.5.2. Mechanisms 400 The following mechanisms are used: 402 1) To protect against the threat of message delay or replay (to an 403 extent greater than can occur through normal operation), a set 404 of timeliness indicators (for the authoritative SNMP engine) are 405 included in each message generated. An SNMP engine evaluates 406 the timeliness indicators to determine if a received message is 407 recent. An SNMP engine may evaluate the timeliness indicators 408 to ensure that a received message is at least as recent as the 409 last message it received from the same source. 410 A non-authoritative SNMP engine uses received authentic messages 411 to advance its notion of the timeliness indicators at the remote 412 authoritative source. 414 An SNMP engine MUST also use a mechanism to match incoming 415 Responses to outstanding Requests and it MUST drop any Responses 416 that do not match an outstanding request. For example, a msgID 417 can be inserted in every message to cater for this functionality. 419 These mechanisms provide for the detection of authenticated 420 messages whose time of generation was not recent. 422 This protection against the threat of message delay or replay 423 does not imply nor provide any protection against unauthorized 424 deletion or suppression of messages. Also, an SNMP engine may 425 not be able to detect message reordering if all the messages 426 involved are sent within the Time Window interval. Other 427 mechanisms defined independently of the security protocol can 428 also be used to detect the re-ordering replay, deletion, or 429 suppression of messages containing Set operations (e.g., the 430 MIB variable snmpSetSerialNo [RFC1907]). 432 2) Verification that a message sent to/from one authoritative SNMP 433 engine cannot be replayed to/as-if-from another authoritative 434 SNMP engine. 436 Included in each message is an identifier unique to the 437 authoritative SNMP engine associated with the sender or intended 438 recipient of the message. 440 A Report, Response or Trap message sent by an authoritative SNMP 441 engine to one non-authoritative SNMP engine can potentially be 442 replayed to another non-authoritative SNMP engine. The latter 444 SNMPv3 Working Group Expires June 1998 [Page 9] 445 non-authoritative SNMP engine might (if it knows about the same 446 userName with the same secrets at the authoritative SNMP engine) 447 as a result update its notion of timeliness indicators of the 448 authoritative SNMP engine, but that is not considered a threat. 449 In this case, A Report or Response message will be discarded by 450 the Message Processing Model, because there should not be an 451 outstanding Request message. A Trap will possibly be accepted. 452 Again, that is not considered a threat, because the communication 453 was authenticated and timely. It is as if the authoritative SNMP 454 engine was configured to start sending Traps to the second SNMP 455 engine, which theoretically can happen without the knowledge of 456 the second SNMP engine anyway. Anyway, the second SNMP engine may 457 not expect to receive this Trap, but is allowed to see the 458 management information contained in it. 460 3) Detection of messages which were not recently generated. 462 A set of time indicators are included in the message, indicating 463 the time of generation. Messages without recent time indicators 464 are not considered authentic. In addition, an SNMP engine MUST 465 drop any Responses that do not match an outstanding request. This 466 however is the responsibility of the Message Processing Model. 468 This memo allows the same user to be defined on multiple SNMP 469 engines. Each SNMP engine maintains a value, snmpEngineID, 470 which uniquely identifies the SNMP engine. This value is included 471 in each message sent to/from the SNMP engine that is authoritative 472 (see section 1.5.1). On receipt of a message, an authoritative 473 SNMP engine checks the value to ensure that it is the intended 474 recipient, and a non-authoritative SNMP engine uses the value to 475 ensure that the message is processed using the correct state 476 information. 478 Each SNMP engine maintains two values, snmpEngineBoots and 479 snmpEngineTime, which taken together provide an indication of 480 time at that SNMP engine. Both of these values are included in 481 an authenticated message sent to/received from that SNMP engine. 482 On receipt, the values are checked to ensure that the indicated 483 timeliness value is within a Time Window of the current time. 484 The Time Window represents an administrative upper bound on 485 acceptable delivery delay for protocol messages. 487 For an SNMP engine to generate a message which an authoritative 488 SNMP engine will accept as authentic, and to verify that a message 489 received from that authoritative SNMP engine is authentic, such an 490 SNMP engine must first achieve timeliness synchronization with the 491 authoritative SNMP engine. See section 2.3. 493 1.6. Abstract Service Interfaces. 495 Abstract service interfaces have been defined to describe the 496 conceptual interfaces between the various subsystems within an SNMP 497 entity. Similarly a set of abstract service interfaces have been 498 defined within the User-based Security Model (USM) to describe the 499 conceptual interfaces between the generic USM services and the 500 self-contained authentication and privacy services. 502 These abstract service interfaces are defined by a set of primitives 503 that define the services provided and the abstract data elements that 504 must be passed when the services are invoked. This section lists the 505 primitives that have been defined for the User-based Security Model. 507 1.6.1. User-based Security Model Primitives for Authentication 509 The User-based Security Model provides the following internal 510 primitives to pass data back and forth between the Security Model 511 itself and the authentication service: 513 statusInformation = 514 authenticateOutgoingMsg( 515 IN authKey -- secret key for authentication 516 IN wholeMsg -- unauthenticated complete message 517 OUT authenticatedWholeMsg -- complete authenticated message 518 ) 520 statusInformation = 521 authenticateIncomingMsg( 522 IN authKey -- secret key for authentication 523 IN authParameters -- as received on the wire 524 IN wholeMsg -- as received on the wire 525 OUT authenticatedWholeMsg -- complete authenticated message 526 ) 528 1.6.2. User-based Security Model Primitives for Privacy 530 The User-based Security Model provides the following internal 531 primitives to pass data back and forth between the Security Model 532 itself and the privacy service: 534 statusInformation = 535 encryptData( 536 IN encryptKey -- secret key for encryption 537 IN dataToEncrypt -- data to encrypt (scopedPDU) 538 OUT encryptedData -- encrypted data (encryptedPDU) 539 OUT privParameters -- filled in by service provider 540 ) 542 statusInformation = 543 decryptData( 544 IN decryptKey -- secret key for decrypting 545 IN privParameters -- as received on the wire 546 IN encryptedData -- encrypted data (encryptedPDU) 547 OUT decryptedData -- decrypted data (scopedPDU) 548 ) 550 2. Elements of the Model 552 This section contains definitions required to realize the security 553 model defined by this memo. 555 2.1. User-based Security Model Users 557 Management operations using this Security Model make use of a 558 defined set of user identities. For any user on whose behalf 559 management operations are authorized at a particular SNMP engine, 560 that SNMP engine must have knowledge of that user. An SNMP engine 561 that wishes to communicate with another SNMP engine must also have 562 knowledge of a user known to that engine, including knowledge of 563 the applicable attributes of that user. 565 A user and its attributes are defined as follows: 567 userName 568 A string representing the name of the user. 570 securityName 571 A human-readable string representing the user in a format that 572 is Security Model independent. 574 authProtocol 575 An indication of whether messages sent on behalf of this user can 576 be authenticated, and if so, the type of authentication protocol 577 which is used. Two such protocols are defined in this memo: 578 - the HMAC-MD5-96 authentication protocol. 579 - the HMAC-SHA-96 authentication protocol. 581 authKey 582 If messages sent on behalf of this user can be authenticated, 583 the (private) authentication key for use with the authentication 584 protocol. Note that a user's authentication key will normally 585 be different at different authoritative SNMP engines. The authKey 586 is not accessible via SNMP. The length requirements of the authKey 587 are defined by the authProtocol in use. 589 authKeyChange and authOwnKeyChange 590 The only way to remotely update the authentication key. Does 591 that in a secure manner, so that the update can be completed 592 without the need to employ privacy protection. 594 privProtocol 595 An indication of whether messages sent on behalf of this user 596 can be protected from disclosure, and if so, the type of privacy 597 protocol which is used. One such protocol is defined in this 598 memo: the CBC-DES Symmetric Encryption Protocol. 600 privKey 601 If messages sent on behalf of this user can be en/decrypted, 602 the (private) privacy key for use with the privacy protocol. 603 Note that a user's privacy key will normally be different at 604 different authoritative SNMP engines. The privKey is not 605 accessible via SNMP. The length requirements of the privKey are 606 defined by the privProtocol in use. 608 privKeyChange and privOwnKeyChange 609 The only way to remotely update the encryption key. Does that 610 in a secure manner, so that the update can be completed without 611 the need to employ privacy protection. 613 2.2. Replay Protection 615 Each SNMP engine maintains three objects: 617 - snmpEngineID, which (at least within an administrative domain) 618 uniquely and unambiguously identifies an SNMP engine. 620 - snmpEngineBoots, which is a count of the number of times the 621 SNMP engine has re-booted/re-initialized since snmpEngineID 622 was last configured; and, 624 - snmpEngineTime, which is the number of seconds since the 625 snmpEngineBoots counter was last incremented. 627 Each SNMP engine is always authoritative with respect to these 628 objects in its own SNMP entity. It is the responsibility of a 629 non-authoritative SNMP engine to synchronize with the 630 authoritative SNMP engine, as appropriate. 632 An authoritative SNMP engine is required to maintain the values of 633 its snmpEngineID and snmpEngineBoots in non-volatile storage. 635 2.2.1. msgAuthoritativeEngineID 637 The msgAuthoritativeEngineID value contained in an authenticated 638 message is used to defeat attacks in which messages from one SNMP 639 engine to another SNMP engine are replayed to a different SNMP 640 engine. It represents the snmpEngineID at the authoritative SNMP 641 engine involved in the exchange of the message. 643 When an authoritative SNMP engine is first installed, it sets its 644 local value of snmpEngineID according to a enterprise-specific 645 algorithm (see the definition of the Textual Convention for 646 SnmpEngineID in the SNMP Architecture document [SNMP-ARCH]). 648 2.2.2. msgAuthoritativeEngineBoots and msgAuthoritativeEngineTime 650 The msgAuthoritativeEngineBoots and msgAuthoritativeEngineTime 651 values contained in an authenticated message are used to defeat 652 attacks in which messages are replayed when they are no longer 653 valid. They represent the snmpEngineBoots and snmpEngineTime 654 values at the authoritative SNMP engine involved in the exchange 655 of the message. 657 Through use of snmpEngineBoots and snmpEngineTime, there is no 658 requirement for an SNMP engine to have a non-volatile clock which 659 ticks (i.e., increases with the passage of time) even when the 660 SNMP engine is powered off. Rather, each time an SNMP engine 661 re-boots, it retrieves, increments, and then stores snmpEngineBoots 662 in non-volatile storage, and resets snmpEngineTime to zero. 664 When an SNMP engine is first installed, it sets its local values 665 of snmpEngineBoots and snmpEngineTime to zero. If snmpEngineTime 666 ever reaches its maximum value (2147483647), then snmpEngineBoots 667 is incremented as if the SNMP engine has re-booted and 668 snmpEngineTime is reset to zero and starts incrementing again. 670 Each time an authoritative SNMP engine re-boots, any SNMP engines 671 holding that authoritative SNMP engine's values of snmpEngineBoots 672 and snmpEngineTime need to re-synchronize prior to sending 673 correctly authenticated messages to that authoritative SNMP engine 674 (see Section 2.3 for (re-)synchronization procedures). Note, 675 however, that the procedures do provide for a notification to be 676 accepted as authentic by a receiving SNMP engine, when sent by an 677 authoritative SNMP engine which has re-booted since the receiving 678 SNMP engine last (re-)synchronized. 680 If an authoritative SNMP engine is ever unable to determine its 681 latest snmpEngineBoots value, then it must set its snmpEngineBoots 682 value to 2147483647. 684 Whenever the local value of snmpEngineBoots has the value 2147483647 685 it latches at that value and an authenticated message always causes 686 an notInTimeWindow authentication failure. 688 In order to reset an SNMP engine whose snmpEngineBoots value has 689 reached the value 2147483647, manual intervention is required. 690 The engine must be physically visited and re-configured, either 691 with a new snmpEngineID value, or with new secret values for the 692 authentication and privacy protocols of all users known to that 693 SNMP engine. Note that even if an SNMP engine re-boots once a second 694 that it would still take approximately 68 years before the max value 695 of 2147483647 would be reached. 697 2.2.3. Time Window 699 The Time Window is a value that specifies the window of time in 700 which a message generated on behalf of any user is valid. This 701 memo specifies that the same value of the Time Window, 150 seconds, 702 is used for all users. 704 2.3. Time Synchronization 706 Time synchronization, required by a non-authoritative SNMP engine 707 in order to proceed with authentic communications, has occurred 708 when the non-authoritative SNMP engine has obtained a local notion 709 of the authoritative SNMP engine's values of snmpEngineBoots and 710 snmpEngineTime from the authoritative SNMP engine. These values 711 must be (and remain) within the authoritative SNMP engine's Time 712 Window. So the local notion of the authoritative SNMP engine's 713 values must be kept loosely synchronized with the values stored 714 at the authoritative SNMP engine. In addition to keeping a local 715 copy of snmpEngineBoots and snmpEngineTime from the authoritative 716 SNMP engine, a non-authoritative SNMP engine must also keep one 717 local variable, latestReceivedEngineTime. This value records the 718 highest value of snmpEngineTime that was received by the 719 non-authoritative SNMP engine from the authoritative SNMP engine 720 and is used to eliminate the possibility of replaying messages 721 that would prevent the non-authoritative SNMP engine's notion of 722 the snmpEngineTime from advancing. 724 A non-authoritative SNMP engine must keep local notions of these 725 values for each authoritative SNMP engine with which it wishes to 726 communicate. Since each authoritative SNMP engine is uniquely 727 and unambiguously identified by its value of snmpEngineID, the 728 non-authoritative SNMP engine may use this value as a key in 729 order to cache its local notions of these values. 731 Time synchronization occurs as part of the procedures of receiving 732 an SNMP message (Section 3.2, step 7b). As such, no explicit time 733 synchronization procedure is required by a non-authoritative SNMP 734 engine. Note, that whenever the local value of snmpEngineID is 735 changed (e.g., through discovery) or when secure communications 736 are first established with an authoritative SNMP engine, the local 737 values of snmpEngineBoots and latestReceivedEngineTime should be 738 set to zero. This will cause the time synchronization to occur 739 when the next authentic message is received. 741 2.4. SNMP Messages Using this Security Model 743 The syntax of an SNMP message using this Security Model adheres 744 to the message format defined in the version-specific Message 745 Processing Model document (for example [SNMP-MP]). 747 The field msgSecurityParameters in SNMPv3 messages has a data type 748 of OCTET STRING. Its value is the BER serialization of the 749 following ASN.1 sequence: 751 USMSecurityParametersSyntax DEFINITIONS IMPLICIT TAGS ::= BEGIN 753 UsmSecurityParameters ::= 754 SEQUENCE { 755 -- global User-based security parameters 756 msgAuthoritativeEngineID OCTET STRING, 757 msgAuthoritativeEngineBoots INTEGER (0..2147483647), 758 msgAuthoritativeEngineTime INTEGER (0..2147483647), 759 msgUserName OCTET STRING (SIZE(1..32)), 760 -- authentication protocol specific parameters 761 msgAuthenticationParameters OCTET STRING, 762 -- privacy protocol specific parameters 763 msgPrivacyParameters OCTET STRING 764 } 765 END 767 The fields of this sequence are: 769 - The msgAuthoritativeEngineID specifies the snmpEngineID of the 770 authoritative SNMP engine involved in the exchange of the message. 772 - The msgAuthoritativeEngineBoots specifies the snmpEngineBoots 773 value at the authoritative SNMP engine involved in the exchange 774 of the message. 776 - The msgAuthoritativeEngineTime specifies the snmpEngineTime value 777 at the authoritative SNMP engine involved in the exchange of the 778 message. 780 - The msgUserName specifies the user (principal) on whose behalf 781 the message is being exchanged. 783 - The msgAuthenticationParameters are defined by the authentication 784 protocol in use for the message, as defined by the 785 usmUserAuthProtocol column in the user's entry in the usmUserTable. 787 - The msgPrivacyParameters are defined by the privacy protocol in 788 use for the message, as defined by the usmUserPrivProtocol column 789 in the user's entry in the usmUserTable). 791 See appendix A.4 for an example of the BER encoding of field 792 msgSecurityParameters. 794 2.5. Services provided by the User-based Security Model 796 This section describes the services provided by the User-based 797 Security Model with their inputs and outputs. 799 The services are described as primitives of an abstract service 800 interface and the inputs and outputs are described as abstract data 801 elements as they are passed in these abstract service primitives. 803 2.5.1. Services for Generating an Outgoing SNMP Message 805 When the Message Processing (MP) Subsystem invokes the User-based 806 Security module to secure an outgoing SNMP message, it must use 807 the appropriate service as provided by the Security module. These 808 two services are provided: 810 1) A service to generate a Request message. The abstract service 811 primitive is: 813 statusInformation = -- success or errorIndication 814 generateRequestMsg( 815 IN messageProcessingModel -- typically, SNMP version 816 IN globalData -- message header, admin data 817 IN maxMessageSize -- of the sending SNMP entity 818 IN securityModel -- for the outgoing message 819 IN securityEngineID -- authoritative SNMP entity 820 IN securityName -- on behalf of this principal 821 IN securityLevel -- Level of Security requested 822 IN scopedPDU -- message (plaintext) payload 823 OUT securityParameters -- filled in by Security Module 824 OUT wholeMsg -- complete generated message 825 OUT wholeMsgLength -- length of generated message 826 ) 828 2) A service to generate a Response message. The abstract service 829 primitive is: 831 statusInformation = -- success or errorIndication 832 generateResponseMsg( 833 IN messageProcessingModel -- typically, SNMP version 834 IN globalData -- message header, admin data 835 IN maxMessageSize -- of the sending SNMP entity 836 IN securityModel -- for the outgoing message 837 IN securityEngineID -- authoritative SNMP entity 838 IN securityName -- on behalf of this principal 839 IN securityLevel -- Level of Security requested 840 IN scopedPDU -- message (plaintext) payload 841 IN securityStateReference -- reference to security state 842 -- information from original 843 -- request 844 OUT securityParameters -- filled in by Security Module 845 OUT wholeMsg -- complete generated message 846 OUT wholeMsgLength -- length of generated message 847 ) 849 The abstract data elements passed as parameters in the abstract 850 service primitives are as follows: 852 statusInformation 853 An indication of whether the encoding and securing of the message 854 was successful. If not it is an indication of the problem. 855 messageProcessingModel 856 The SNMP version number for the message to be generated. 857 This data is not used by the User-based Security module. 858 globalData 859 The message header (i.e., its administrative information). This 860 data is not used by the User-based Security module. 861 maxMessageSize 862 The maximum message size as included in the message. 863 This data is not used by the User-based Security module. 864 securityParameters 865 These are the security parameters. They will be filled in 866 by the User-based Security module. 867 securityModel 868 The securityModel in use. Should be User-based Security Model. 869 This data is not used by the User-based Security module. 870 securityName 871 Together with the snmpEngineID it identifies a row in the 872 usmUserTable that is to be used for securing the message. 873 The securityName has a format that is independent of the 874 Security Model. In case of a response this parameter is 875 ignored and the value from the cache is used. 876 securityLevel 877 The Level of Security from which the User-based Security 878 module determines if the message needs to be protected from 879 disclosure and if the message needs to be authenticated. 880 In case of a response this parameter is ignored and the value 881 from the cache is used. 882 securityEngineID 883 The snmpEngineID of the authoritative SNMP engine to which a 884 Request message is to be sent. In case of a response it is 885 implied to be the processing SNMP engine's snmpEngineID and 886 so if it is specified, then it is ignored. 887 scopedPDU 888 The message payload. The data is opaque as far as the 889 User-based Security Model is concerned. 890 securityStateReference 891 A handle/reference to cachedSecurityData to be used when 892 securing an outgoing Response message. This is the exact same 893 handle/reference as it was generated by the User-based Security 894 module when processing the incoming Request message to which 895 this is the Response message. 896 wholeMsg 897 The fully encoded and secured message ready for sending on 898 the wire. 899 wholeMsgLength 900 The length of the encoded and secured message (wholeMsg). 902 Upon completion of the process, the User-based Security module 903 returns statusInformation. If the process was successful, the 904 completed message with privacy and authentication applied if such 905 was requested by the specified securityLevel is returned. If the 906 process was not successful, then an errorIndication is returned. 908 2.5.2. Services for Processing an Incoming SNMP Message 910 When the Message Processing (MP) Subsystem invokes the User-based 911 Security module to verify proper security of an incoming message, 912 it must use the service provided for an incoming message. The 913 abstract service primitive is: 915 statusInformation = -- errorIndication or success 916 -- error counter OID/value if error 917 processIncomingMsg( 918 IN messageProcessingModel -- typically, SNMP version 919 IN maxMessageSize -- of the sending SNMP entity 920 IN securityParameters -- for the received message 921 IN securityModel -- for the received message 922 IN securityLevel -- Level of Security 923 IN wholeMsg -- as received on the wire 924 IN wholeMsgLength -- length as received on the wire 925 OUT securityEngineID -- authoritative SNMP entity 926 OUT securityName -- identification of the principal 927 OUT scopedPDU, -- message (plaintext) payload 928 OUT maxSizeResponseScopedPDU -- maximum size of the Response PDU 929 OUT securityStateReference -- reference to security state 930 ) -- information, needed for response 932 The abstract data elements passed as parameters in the abstract 933 service primitives are as follows: 935 statusInformation 936 An indication of whether the process was successful or not. 937 If not, then the statusInformation includes the OID and the 938 value of the error counter that was incremented. 939 messageProcessingModel 940 The SNMP version number as received in the message. 941 This data is not used by the User-based Security module. 942 maxMessageSize 943 The maximum message size as included in the message. 945 The User-based Security module uses this value to calculate the 946 maxSizeResponseScopedPDU. 947 securityParameters 948 These are the security parameters as received in the message. 949 securityModel 950 The securityModel in use. 951 Should be the User-based Security Model. 952 This data is not used by the User-based Security module. 953 securityLevel 954 The Level of Security from which the User-based Security 955 module determines if the message needs to be protected from 956 disclosure and if the message needs to be authenticated. 957 wholeMsg 958 The whole message as it was received. 959 wholeMsgLength 960 The length of the message as it was received (wholeMsg). 961 securityEngineID 962 The snmpEngineID that was extracted from the field 963 msgAuthoritativeEngineID and that was used to lookup the secrets 964 in the usmUserTable. 965 securityName 966 The security name representing the user on whose behalf the 967 message was received. The securityName has a format that is 968 independent of the Security Model. 969 scopedPDU 970 The message payload. The data is opaque as far as the 971 User-based Security Model is concerned. 972 maxSizeResponseScopedPDU 973 The maximum size of a scopedPDU to be included in a possible 974 Response message. The User-base Security module calculates 975 this size based on the mms (as received in the message) and 976 the space required for the message header (including the 977 securityParameters) for such a Response message. 978 securityStateReference 979 A handle/reference to cachedSecurityData to be used when 980 securing an outgoing Response message. When the Message 981 Processing Subsystem calls the User-based Security module to 982 generate a response to this incoming message it must pass this 983 handle/reference. 985 Upon completion of the process, the User-based Security module 986 returns statusInformation and, if the process was successful, 987 the additional data elements for further processing of the message. 988 If the process was not successful, then an errorIndication, 989 possibly with a OID and value pair of an error counter that was 990 incremented. 992 2.6. Key Localization Algorithm. 994 A localized key is a secret key shared between a user U and one 995 authoritative SNMP engine E. Even though a user may have only one 996 password and therefore one key for the whole network, the actual 997 secrets shared between the user and each authoritative SNMP engine 998 will be different. This is achieved by key localization 999 [Localized-key]. 1001 First, if a user uses a password, then the user's password is 1002 converted into a key Ku using one of the two algorithms described 1003 in Appendices A.2.1 and A.2.2. 1005 To convert key Ku into a localized key Kul of user U at the 1006 authoritative SNMP engine E, one appends the snmpEngineID of the 1007 authoritative SNMP engine to the key Ku and then appends the key Ku 1008 to the result, thus enveloping the snmpEngineID within the two 1009 copies of user's key Ku. Then one runs a secure hash function 1010 (which one depends on the authentication protocol defined for this 1011 user U at authoritative SNMP engine E; this document defines two 1012 authentication protocols with their associated algorithms based on 1013 MD5 and SHA). The output of the hash-function is the localized key 1014 Kul for user U at the authoritative SNMP engine E. 1016 3. Elements of Procedure 1018 This section describes the security related procedures followed by 1019 an SNMP engine when processing SNMP messages according to the 1020 User-based Security Model. 1022 3.1. Generating an Outgoing SNMP Message 1024 This section describes the procedure followed by an SNMP engine 1025 whenever it generates a message containing a management operation 1026 (like a request, a response, a notification, or a report) on 1027 behalf of a user, with a particular securityLevel. 1029 1) a) If any securityStateReference is passed (Response message), 1030 then information concerning the user is extracted from the 1031 cachedSecurityData. The securityEngineID and the 1032 securityLevel are extracted from the cachedSecurityData. 1033 The cachedSecurityData can now be discarded. 1035 Otherwise, 1037 b) based on the securityName, information concerning the 1038 user at the destination snmpEngineID, specified by the 1039 securityEngineID, is extracted from the Local Configuration 1040 Datastore (LCD, usmUserTable). If information about the user 1041 is absent from the LCD, then an error indication 1042 (unknownSecurityName) is returned to the calling module. 1044 2) If the securityLevel specifies that the message is to be 1045 protected from disclosure, but the user does not support both 1046 an authentication and a privacy protocol then the message 1047 cannot be sent. An error indication (unsupportedSecurityLevel) 1048 is returned to the calling module. 1050 3) If the securityLevel specifies that the message is to be 1051 authenticated, but the user does not support an authentication 1052 protocol, then the message cannot be sent. An error indication 1053 (unsupportedSecurityLevel) is returned to the calling module. 1055 4) a) If the securityLevel specifies that the message is to be 1056 protected from disclosure, then the octet sequence 1057 representing the serialized scopedPDU is encrypted according 1058 to the user's privacy protocol. To do so a call is made to 1059 the privacy module that implements the user's privacy 1060 protocol according to the abstract primitive: 1062 statusInformation = -- success or failure 1063 encryptData( 1064 IN encryptKey -- user's localized privKey 1065 IN dataToEncrypt -- serialized scopedPDU 1066 OUT encryptedData -- serialized encryptedPDU 1067 OUT privParameters -- serialized privacy parameters 1068 ) 1070 statusInformation 1071 indicates if the encryption process was successful or not. 1072 encryptKey 1073 the user's localized private privKey is the secret key that 1074 can be used by the encryption algorithm. 1075 dataToEncrypt 1076 the serialized scopedPDU is the data that to be encrypted. 1077 encryptedData 1078 the encryptedPDU represents the encrypted scopedPDU, 1079 encoded as an OCTET STRING. 1080 privParameters 1081 the privacy parameters, encoded as an OCTET STRING. 1083 If the privacy module returns failure, then the message 1084 cannot be sent and an error indication (encryptionError) 1085 is returned to the calling module. 1087 If the privacy module returns success, then the returned 1088 privParameters are put into the msgPrivacyParameters field of 1089 the securityParameters and the encryptedPDU serves as the 1090 payload of the message being prepared. 1092 Otherwise, 1094 b) If the securityLevel specifies that the message is not to be 1095 protected from disclosure, then the NULL string is encoded 1096 as an OCTET STRING and put into the msgPrivacyParameters 1097 field of the securityParameters and the plaintext scopedPDU 1098 serves as the payload of the message being prepared. 1100 5) The snmpEngineID is encoded as an OCTET STRING into the 1101 msgAuthoritativeEngineID field of the securityParameters. 1102 Note that an empty (zero length) snmpEngineID is OK for a 1103 Request message, because that will cause the remote 1104 (authoritative) SNMP engine to return a Report PDU with the 1105 proper snmpEngineID included in the msgAuthoritativeEngineID in 1106 the securityParameters of that returned Report PDU. 1108 6) a) If the securityLevel specifies that the message is to be 1109 authenticated, then the current values of snmpEngineBoots 1110 and snmpEngineTime corresponding to the snmpEngineID from 1111 the LCD are used. 1113 Otherwise, 1115 b) If this is a Response message, then the current value of 1116 snmpEngineBoots and snmpEngineTime corresponding to the 1117 local snmpEngineID from the LCD are used. 1119 Otherwise, 1121 c) If this is a Request message, then a zero value is used 1122 for both snmpEngineBoots and snmpEngineTime. This zero 1123 value gets used if snmpEngineID is empty. 1125 The values are encoded as Unsigned32 and Integer32 respectively 1126 into the msgAuthoritativeEngineBoots and 1127 msgAuthoritativeEngineTime fields of the securityParameters. 1129 7) The userName is encoded as an OCTET STRING into the msgUserName 1130 field of the securityParameters. 1132 8) a) If the securityLevel specifies that the message is to be 1133 authenticated, the message is authenticated according to the 1134 user's authentication protocol. To do so a call is made to 1135 the authentication module that implements the user's 1136 authentication protocol according to the abstract service 1137 primitive: 1139 statusInformation = 1140 authenticateOutgoingMsg( 1141 IN authKey -- the user's localized authKey 1142 IN wholeMsg -- unauthenticated message 1143 OUT authenticatedWholeMsg -- authenticated complete message 1144 ) 1146 statusInformation 1147 indicates if authentication was successful or not. 1148 authKey 1149 the user's localized private authKey is the secret key that 1150 can be used by the authentication algorithm. 1151 wholeMsg 1152 the complete serialized message to be authenticated. 1153 authenticatedWholeMsg 1154 the same as the input given to the authenticateOutgoingMsg 1155 service, but with msgAuthenticationParameters properly 1156 filled in. 1158 If the authentication module returns failure, then the 1159 message cannot be sent and an error indication 1160 (authenticationFailure) is returned to the calling module. 1162 If the authentication module returns success, then the 1163 msgAuthenticationParameters field is put into the 1164 securityParameters and the authenticatedWholeMsg represents 1165 the serialization of the authenticated message being 1166 prepared. 1168 Otherwise, 1170 b) If the securityLevel specifies that the message is not to 1171 be authenticated then the NULL string is encoded as an 1172 OCTET STRING into the msgAuthenticationParameters field of 1173 the securityParameters. The wholeMsg is now serialized and 1174 then represents the unauthenticated message being prepared. 1176 9) The completed message with its length is returned to the 1177 calling module with the statusInformation set to success. 1179 3.2. Processing an Incoming SNMP Message 1181 This section describes the procedure followed by an SNMP engine 1182 whenever it receives a message containing a management operation 1183 on behalf of a user, with a particular securityLevel. 1185 To simplify the elements of procedure, the release of state 1186 information is not always explicitly specified. As a general rule, 1187 if state information is available when a message gets discarded, 1188 the state information should also be released. 1189 Also, when an error indication with an OID and value for an 1190 incremented counter is returned, then the available information 1191 (like securityStateReference) must be passed back to the caller 1192 so it can generate a Report PDU. 1194 1) If the received securityParameters is not the serialization 1195 (according to the conventions of [RFC1906]) of an OCTET STRING 1196 formatted according to the UsmSecurityParameters defined in 1197 section 2.4, then the snmpInASNParseErrs counter [RFC1907] is 1198 incremented, and an error indication (parseError) is returned 1199 to the calling module. 1200 Note that we return without the OID and value of the incremented 1201 counter, because in this case there is not enough information 1202 to generate a Report PDU. 1204 2) The values of the security parameter fields are extracted from 1205 the securityParameters. The securityEngineID to be returned to 1206 the caller is the value of the msgAuthoritativeEngineID field. 1207 The cachedSecurityData is prepared and a securityStateReference 1208 is prepared to reference this data. Values to be cached are: 1210 msgUserName 1211 securityEngineID 1212 securityLevel 1214 3) If the value of the msgAuthoritativeEngineID field in the 1215 securityParameters is unknown then: 1217 a) a non-authoritative SNMP engine that performs discovery may 1218 optionally create a new entry in its Local Configuration 1219 Datastore (LCD) and continue processing; 1220 or 1222 b) the usmStatsUnknownEngineIDs counter is incremented, and 1223 an error indication (unknownEngineID) together with the 1224 OID and value of the incremented counter is returned to 1225 the calling module. 1227 4) Information about the value of the msgUserName and 1228 msgAuthoritativeEngineID fields is extracted from the Local 1229 Configuration Datastore (LCD, usmUserTable). If no information 1230 is available for the user, then the usmStatsUnknownUserNames 1231 counter is incremented and an error indication 1232 (unknownSecurityName) together with the OID and value of the 1233 incremented counter is returned to the calling module. 1235 5) If the information about the user indicates that it does not 1236 support the securityLevel requested by the caller, then the 1237 usmStatsUnsupportedSecLevels counter is incremented and an 1238 error indication (unsupportedSecurityLevel) together with the 1239 OID and value of the incremented counter is returned to the 1240 calling module. 1242 6) If the securityLevel specifies that the message is to be 1243 authenticated, then the message is authenticated according to 1244 the user's authentication protocol. To do so a call is made 1245 to the authentication module that implements the user's 1246 authentication protocol according to the abstract service 1247 primitive: 1249 statusInformation = -- success or failure 1250 authenticateIncomingMsg( 1251 IN authKey -- the user's localized authKey 1252 IN authParameters -- as received on the wire 1253 IN wholeMsg -- as received on the wire 1254 OUT authenticatedWholeMsg -- checked for authentication 1255 ) 1257 statusInformation 1258 indicates if authentication was successful or not. 1259 authKey 1260 the user's localized private authKey is the secret key that 1261 can be used by the authentication algorithm. 1262 wholeMsg 1263 the complete serialized message to be authenticated. 1264 authenticatedWholeMsg 1265 the same as the input given to the authenticateIncomingMsg 1266 service, but after authentication has been checked. 1268 If the authentication module returns failure, then the message 1269 cannot be trusted, so the usmStatsWrongDigests counter is 1270 incremented and an error indication (authenticationFailure) 1271 together with the OID and value of the incremented counter is 1272 returned to the calling module. 1274 If the authentication module returns success, then the message 1275 is authentic and can be trusted so processing continues. 1277 7) If the securityLevel indicates an authenticated message, then 1278 the local values of snmpEngineBoots and snmpEngineTime 1279 corresponding to the value of the msgAuthoritativeEngineID 1280 field are extracted from the Local Configuration Datastore. 1282 a) If the extracted value of msgAuthoritativeEngineID is the 1283 same as the value of snmpEngineID of the processing SNMP 1284 engine (meaning this is the authoritative SNMP engine), 1285 then if any of the following conditions is true, then the 1286 message is considered to be outside of the Time Window: 1288 - the local value of snmpEngineBoots is 2147483647; 1290 - the value of the msgAuthoritativeEngineBoots field differs 1291 from the local value of snmpEngineBoots; or, 1293 - the value of the msgAuthoritativeEngineTime field differs 1294 from the local notion of snmpEngineTime by more than 1295 +/- 150 seconds. 1297 If the message is considered to be outside of the Time Window 1298 then the usmStatsNotInTimeWindows counter is incremented and 1299 an error indication (notInTimeWindow) together with the OID 1300 and value of the incremented counter is returned to the 1301 calling module. 1303 b) If the extracted value of msgAuthoritativeEngineID is not the 1304 same as the value snmpEngineID of the processing SNMP engine 1305 (meaning this is not the authoritative SNMP engine), then: 1307 1) if at least one of the following conditions is true: 1309 - the extracted value of the msgAuthoritativeEngineBoots 1310 field is greater than the local notion of the value of 1311 snmpEngineBoots; or, 1313 - the extracted value of the msgAuthoritativeEngineBoots 1314 field is equal to the local notion of the value of 1315 snmpEngineBoots, the extracted value of 1316 msgAuthoritativeEngineTime field is greater than the 1317 value of latestReceivedEngineTime, 1319 then the LCD entry corresponding to the extracted value 1320 of the msgAuthoritativeEngineID field is updated, by 1321 setting: 1323 - the local notion of the value of snmpEngineBoots to 1324 the value of the msgAuthoritativeEngineBoots field, 1325 - the local notion of the value of snmpEngineTime to 1326 the value of the msgAuthoritativeEngineTime field, 1327 and 1328 - the latestReceivedEngineTime to the value of the 1329 value of the msgAuthoritativeEngineTime field. 1331 2) if any of the following conditions is true, then the 1332 message is considered to be outside of the Time Window: 1334 - the local notion of the value of snmpEngineBoots is 1335 2147483647; 1337 - the value of the msgAuthoritativeEngineBoots field is 1338 less than the local notion of the value of 1339 snmpEngineBoots; or, 1341 - the value of the msgAuthoritativeEngineBoots field is 1342 equal to the local notion of the value of 1343 snmpEngineBoots and the value of the 1344 msgAuthoritativeEngineTime field is more than 150 1345 seconds less than the local notion of of the value of 1346 snmpEngineTime. 1348 If the message is considered to be outside of the Time 1349 Window then an error indication (notInTimeWindow) is 1350 returned to the calling module; 1352 Note that this means that a too old (possibly replayed) 1353 message has been detected and is deemed unauthentic. 1355 Note that this procedure allows for the value of 1356 msgAuthoritativeEngineBoots in the message to be greater 1357 than the local notion of the value of snmpEngineBoots to 1358 allow for received messages to be accepted as authentic 1359 when received from an authoritative SNMP engine that has 1360 re-booted since the receiving SNMP engine last 1361 (re-)synchronized. 1363 Note that this procedure does not allow for automatic 1364 time synchronization if the non-authoritative SNMP engine 1365 has a real out-of-sync situation whereby the authoritative 1366 SNMP engine is more than 150 seconds behind the 1367 non-authoritative SNMP engine. 1369 8) a) If the securityLevel indicates that the message was protected 1370 from disclosure, then the OCTET STRING representing the 1371 encryptedPDU is decrypted according to the user's privacy 1372 protocol to obtain an unencrypted serialized scopedPDU value. 1373 To do so a call is made to the privacy module that implements 1374 the user's privacy protocol according to the abstract 1375 primitive: 1377 statusInformation = -- success or failure 1378 decryptData( 1379 IN decryptKey -- the user's localized privKey 1380 IN privParameters -- as received on the wire 1381 IN encryptedData -- encryptedPDU as received 1382 OUT decryptedData -- serialized decrypted scopedPDU 1383 ) 1385 statusInformation 1386 indicates if the decryption process was successful or not. 1387 decryptKey 1388 the user's localized private privKey is the secret key that 1389 can be used by the decryption algorithm. 1390 privParameters 1391 the msgPrivacyParameters, encoded as an OCTET STRING. 1392 encryptedData 1393 the encryptedPDU represents the encrypted scopedPDU, 1394 encoded as an OCTET STRING. 1395 decryptedData 1396 the serialized scopedPDU if decryption is successful. 1398 If the privacy module returns failure, then the message can 1399 not be processed, so the usmStatsDecryptionErrors counter 1400 is incremented and an error indication (decryptionError) 1401 together with the OID and value of the incremented counter 1402 is returned to the calling module. 1404 If the privacy module returns success, then the decrypted 1405 scopedPDU is the message payload to be returned to the 1406 calling module. 1408 Otherwise, 1410 b) The scopedPDU component is assumed to be in plain text 1411 and is the message payload to be returned to the calling 1412 module. 1414 9) The maxSizeResponseScopedPDU is calculated. This is the 1415 maximum size allowed for a scopedPDU for a possible Response 1416 message. Provision is made for a message header that allows 1417 the same securityLevel as the received Request. 1419 10) The securityName for the user is retrieved from the 1420 usmUserTable. 1422 11) The security data is cached as cachedSecurityData, so that a 1423 possible response to this message can and will use the same 1424 authentication and privacy secrets, the same securityLevel and 1425 the same value for msgAuthoritativeEngineID. Information to be 1426 saved/cached is as follows: 1428 msgUserName, 1429 usmUserAuthProtocol, usmUserAuthKey 1430 usmUserPrivProtocol, usmUserPrivKey 1431 securityEngineID, securityLevel 1433 12) The statusInformation is set to success and a return is made to 1434 the calling module passing back the OUT parameters as specified 1435 in the processIncomingMsg primitive. 1437 4. Discovery 1439 The User-based Security Model requires that a discovery process 1440 obtains sufficient information about other SNMP engines in order 1441 to communicate with them. Discovery requires an non-authoritative 1442 SNMP engine to learn the authoritative SNMP engine's snmpEngineID 1443 value before communication may proceed. This may be accomplished by 1444 generating a Request message with a securityLevel of noAuthNoPriv, 1445 a msgUserName of "initial", a msgAuthoritativeEngineID value of zero 1446 length, and the varBindList left empty. 1447 The response to this message will be a Report message containing 1448 the snmpEngineID of the authoritative SNMP engine as the value of 1449 the msgAuthoritativeEngineID field within the msgSecurityParameters 1450 field. It contains a Report PDU with the usmStatsUnknownEngineIDs 1451 counter in the varBindList. 1453 If authenticated communication is required, then the discovery 1454 process should also establish time synchronization with the 1455 authoritative SNMP engine. This may be accomplished by sending an 1456 authenticated Request message with the value of 1457 msgAuthoritativeEngineID set to the newly learned snmpEngineID and 1458 with the values of msgAuthoritativeEngineBoots and 1459 msgAuthoritativeEngineTime set to zero. 1460 The response to this authenticated message will be a Report message 1461 containing the up to date values of the authoritative SNMP engine's 1462 snmpEngineBoots and snmpEngineTime as the value of the 1463 msgAuthoritativeEngineBoots and msgAuthoritativeEngineTime fields 1464 respectively. It also contains the usmStatsNotInTimeWindows counter 1465 in the varBindList of the Report PDU. The time synchronization then 1466 happens automatically as part of the procedures in section 3.2 1467 step 7b. See also section 2.3. 1469 5. Definitions 1471 SNMP-USER-BASED-SM-MIB DEFINITIONS ::= BEGIN 1473 IMPORTS 1474 MODULE-IDENTITY, OBJECT-TYPE, 1475 OBJECT-IDENTITY, 1476 snmpModules, Counter32 FROM SNMPv2-SMI 1477 TEXTUAL-CONVENTION, TestAndIncr, 1478 RowStatus, RowPointer, 1479 StorageType, AutonomousType FROM SNMPv2-TC 1480 MODULE-COMPLIANCE, OBJECT-GROUP FROM SNMPv2-CONF 1481 SnmpAdminString, SnmpEngineID, 1482 snmpAuthProtocols, snmpPrivProtocols FROM SNMP-FRAMEWORK-MIB; 1484 snmpUsmMIB MODULE-IDENTITY 1485 LAST-UPDATED "9711200000Z" -- 20 Nov 1997, midnight 1486 ORGANIZATION "SNMPv3 Working Group" 1487 CONTACT-INFO "WG-email: snmpv3@tis.com 1488 Subscribe: majordomo@tis.com 1489 In msg body: subscribe snmpv3 1491 Chair: Russ Mundy 1492 Trusted Information Systems 1493 postal: 3060 Washington Rd 1494 Glenwood MD 21738 1495 USA 1496 email: mundy@tis.com 1497 phone: +1-301-854-6889 1499 Co-editor Uri Blumenthal 1500 IBM T. J. Watson Research 1501 postal: 30 Saw Mill River Pkwy, 1502 Hawthorne, NY 10532 1503 USA 1504 email: uri@watson.ibm.com 1505 phone: +1-914-784-7964 1507 Co-editor: Bert Wijnen 1508 IBM T. J. Watson Research 1509 postal: Schagen 33 1510 3461 GL Linschoten 1511 Netherlands 1512 email: wijnen@vnet.ibm.com 1513 phone: +31-348-432-794 1514 " 1516 DESCRIPTION "The management information definitions for the 1517 SNMP User-based Security Model. 1518 " 1519 ::= { snmpModules xxx } -- get assignment from IANA 1521 -- Administrative assignments **************************************** 1523 usmMIBObjects OBJECT IDENTIFIER ::= { snmpUsmMIB 1 } 1524 usmMIBConformance OBJECT IDENTIFIER ::= { snmpUsmMIB 2 } 1526 -- Identification of Authentication and Privacy Protocols ************ 1528 usmNoAuthProtocol OBJECT-IDENTITY 1529 STATUS current 1530 DESCRIPTION "No Authentication Protocol." 1531 ::= { snmpAuthProtocols 1 } 1533 usmHMACMD5AuthProtocol OBJECT-IDENTITY 1534 STATUS current 1535 DESCRIPTION "The HMAC-MD5-96 Digest Authentication Protocol." 1536 REFERENCE "- H. Krawczyk, M. Bellare, R. Canetti HMAC: 1537 Keyed-Hashing for Message Authentication, 1538 RFC2104, Feb 1997. 1539 - Rivest, R., Message Digest Algorithm MD5, RFC1321. 1540 " 1541 ::= { snmpAuthProtocols 2 } 1543 usmHMACSHAAuthProtocol OBJECT-IDENTITY 1544 STATUS current 1545 DESCRIPTION "The HMAC-SHA-96 Digest Authentication Protocol." 1546 REFERENCE "- H. Krawczyk, M. Bellare, R. Canetti, HMAC: 1547 Keyed-Hashing for Message Authentication, 1548 RFC2104, Feb 1997. 1549 - Secure Hash Algorithm. NIST FIPS 180-1. 1550 " 1551 ::= { snmpAuthProtocols 3 } 1553 usmNoPrivProtocol OBJECT-IDENTITY 1554 STATUS current 1555 DESCRIPTION "No Privacy Protocol." 1556 ::= { snmpPrivProtocols 1 } 1558 usmDESPrivProtocol OBJECT-IDENTITY 1559 STATUS current 1560 DESCRIPTION "The CBC-DES Symmetric Encryption Protocol." 1561 REFERENCE "- Data Encryption Standard, National Institute of 1562 Standards and Technology. Federal Information 1563 Processing Standard (FIPS) Publication 46-1. 1564 Supersedes FIPS Publication 46, 1565 (January, 1977; reaffirmed January, 1988). 1567 - Data Encryption Algorithm, American National 1568 Standards Institute. ANSI X3.92-1981, 1569 (December, 1980). 1571 - DES Modes of Operation, National Institute of 1572 Standards and Technology. Federal Information 1573 Processing Standard (FIPS) Publication 81, 1574 (December, 1980). 1576 - Data Encryption Algorithm - Modes of Operation, 1577 American National Standards Institute. 1578 ANSI X3.106-1983, (May 1983). 1579 " 1580 ::= { snmpPrivProtocols 2 } 1582 -- Textual Conventions *********************************************** 1584 KeyChange ::= TEXTUAL-CONVENTION 1585 STATUS current 1586 DESCRIPTION 1587 "Every definition of an object with this syntax must identify 1588 a protocol P, a secret key K, and a hash algorithm H 1589 that produces output of L octets. 1591 The object's value is a manager-generated, partially-random 1592 value which, when modified, causes the value of the secret 1593 key K, to be modified via a one-way function. 1595 The value of an instance of this object is the concatenation 1596 of two components: first a 'random' component and then a 1597 'delta' component. 1599 The lengths of the random and delta components 1600 are given by the corresponding value of the protocol P; 1601 if P requires K to be a fixed length, the length of both the 1602 random and delta components is that fixed length; if P 1603 allows the length of K to be variable up to a particular 1604 maximum length, the length of the random component is that 1605 maximum length and the length of the delta component is any 1606 length less than or equal to that maximum length. 1607 For example, usmHMACMD5AuthProtocol requires K to be a fixed 1608 length of 16 octets and L - of 16 octets. 1609 usmHMACSHAAuthProtocol requires K to be a fixed length of 1610 20 octets and L - of 20 octets. Other protocols may define 1611 other sizes, as deemed appropriate. 1613 When a requestor wants to change the old key K to a new 1614 key keyNew on a remote entity, the 'random' component is 1615 obtained from either a true random generator, or from a 1616 pseudorandom generator, and the 'delta' component is 1617 computed as follows: 1619 - a temporary variable is initialized to the existing value 1620 of K; 1621 - if the length of the keyNew is greater than L octets, 1622 then: 1623 - the random component is appended to the value of the 1624 temporary variable, and the result is input to the 1625 the hash algorithm H to produce a digest value, and 1626 the temporary variable is set to this digest value; 1627 - the value of the temporary variable is XOR-ed with 1628 the first (next) L-octets (16 octets in case of MD5) 1629 of the keyNew to produce the first (next) L-octets 1630 (16 octets in case of MD5) of the 'delta' component. 1631 - the above two steps are repeated until the unused 1632 portion of the delta component is L octets or less, 1633 - the random component is appended to the value of the 1634 temporary variable, and the result is input to the 1635 hash algorithm H to produce a digest value; 1636 - this digest value, truncated if necessary to be the same 1637 length as the unused portion of the keyNew, is XOR-ed 1638 with the unused portion of the keyNew to produce the 1639 (final portion of the) 'delta' component. 1641 For example, using MD5 as the hash algorithm H: 1643 iterations = (lenOfDelta - 1)/16; /* integer division */ 1644 temp = keyOld; 1645 for (i = 0; i < iterations; i++) { 1646 temp = MD5 (temp || random); 1647 delta[i*16 .. (i*16)+15] = 1648 temp XOR keyNew[i*16 .. (i*16)+15]; 1649 } 1650 temp = MD5 (temp || random); 1651 delta[i*16 .. lenOfDelta-1] = 1652 temp XOR keyNew[i*16 .. lenOfDelta-1]; 1654 The 'random' and 'delta' components are then concatenated as 1655 described above, and the resulting octet string is sent to 1656 the receipient as the new value of an instance of this 1657 object. 1659 At the receiver side, when an instance of this object is set 1660 to a new value, then a new value of K is computed as follows: 1662 - a temporary variable is initialized to the existing value 1663 of K; 1664 - if the length of the delta component is greater than L 1665 octets, then: 1666 - the random component is appended to the value of the 1667 temporary variable, and the result is input to the 1668 the hash algorithm H to produce a digest value, and 1669 the temporary variable is set to this digest value; 1671 - the value of the temporary variable is XOR-ed with 1672 the first (next) L-octets (16 octets in case of MD5) 1673 of the delta component to produce the first (next) 1674 L-octets (16 octets in case of MD5) of the new value 1675 of K. 1676 - the above two steps are repeated until the unused 1677 portion of the delta component is L octets or less, 1678 - the random component is appended to the value of the 1679 temporary variable, and the result is input to the 1680 hash algorithm H to produce a digest value; 1681 - this digest value, truncated if necessary to be the same 1682 length as the unused portion of the delta component, is 1683 XOR-ed with the unused portion of the delta component to 1684 produce the (final portion of the) new value of K. 1686 For example, using MD5 as the hash algorithm H: 1688 iterations = (lenOfDelta - 1)/16; /* integer division */ 1689 temp = keyOld; 1690 for (i = 0; i < iterations; i++) { 1691 temp = MD5 (temp || random); 1692 keyNew[i*16 .. (i*16)+15] = 1693 temp XOR delta[i*16 .. (i*16)+15]; 1694 } 1695 temp = MD5 (temp || random); 1696 keyNew[i*16 .. lenOfDelta-1] = 1697 temp XOR delta[i*16 .. lenOfDelta-1]; 1699 The value of an object with this syntax, whenever it is 1700 retrieved by the management protocol, is always the zero 1701 length string. 1702 " 1703 SYNTAX OCTET STRING 1705 -- Statistics for the User-based Security Model ********************** 1707 usmStats OBJECT IDENTIFIER ::= { usmMIBObjects 1 } 1709 usmStatsUnsupportedSecLevels OBJECT-TYPE 1710 SYNTAX Counter32 1711 MAX-ACCESS read-only 1712 STATUS current 1713 DESCRIPTION "The total number of packets received by the SNMP 1714 engine which were dropped because they requested a 1715 securityLevel that was unknown to the SNMP engine 1716 or otherwise unavailable. 1717 " 1718 ::= { usmStats 1 } 1720 usmStatsNotInTimeWindows OBJECT-TYPE 1721 SYNTAX Counter32 1722 MAX-ACCESS read-only 1723 STATUS current 1724 DESCRIPTION "The total number of packets received by the SNMP 1725 engine which were dropped because they appeared 1726 outside of the authoritative SNMP engine's window. 1727 " 1728 ::= { usmStats 2 } 1730 usmStatsUnknownUserNames OBJECT-TYPE 1731 SYNTAX Counter32 1732 MAX-ACCESS read-only 1733 STATUS current 1734 DESCRIPTION "The total number of packets received by the SNMP 1735 engine which were dropped because they referenced a 1736 user that was not known to the SNMP engine. 1737 " 1738 ::= { usmStats 3 } 1740 usmStatsUnknownEngineIDs OBJECT-TYPE 1741 SYNTAX Counter32 1742 MAX-ACCESS read-only 1743 STATUS current 1744 DESCRIPTION "The total number of packets received by the SNMP 1745 engine which were dropped because they referenced an 1746 snmpEngineID that was not known to the SNMP engine. 1747 " 1748 ::= { usmStats 4 } 1750 usmStatsWrongDigests OBJECT-TYPE 1751 SYNTAX Counter32 1752 MAX-ACCESS read-only 1753 STATUS current 1754 DESCRIPTION "The total number of packets received by the SNMP 1755 engine which were dropped because they didn't 1756 contain the expected digest value. 1757 " 1758 ::= { usmStats 5 } 1760 usmStatsDecryptionErrors OBJECT-TYPE 1761 SYNTAX Counter32 1762 MAX-ACCESS read-only 1763 STATUS current 1764 DESCRIPTION "The total number of packets received by the SNMP 1765 engine which were dropped because they could not be 1766 decrypted. 1767 " 1768 ::= { usmStats 6 } 1770 -- The usmUser Group ************************************************ 1772 usmUser OBJECT IDENTIFIER ::= { usmMIBObjects 2 } 1774 usmUserSpinLock OBJECT-TYPE 1775 SYNTAX TestAndIncr 1776 MAX-ACCESS read-write 1777 STATUS current 1778 DESCRIPTION "An advisory lock used to allow several cooperating 1779 Command Generator Applications to coordinate their 1780 use of facilities to alter secrets in the 1781 usmUserTable. 1782 " 1783 ::= { usmUser 1 } 1785 -- The table of valid users for the User-based Security Model ******** 1787 usmUserTable OBJECT-TYPE 1788 SYNTAX SEQUENCE OF UsmUserEntry 1789 MAX-ACCESS not-accessible 1790 STATUS current 1791 DESCRIPTION "The table of users configured in the SNMP engine's 1792 Local Configuration Datastore (LCD)." 1793 ::= { usmUser 2 } 1795 usmUserEntry OBJECT-TYPE 1796 SYNTAX UsmUserEntry 1797 MAX-ACCESS not-accessible 1798 STATUS current 1799 DESCRIPTION "A user configured in the SNMP engine's Local 1800 Configuration Datastore (LCD) for the User-based 1801 Security Model. 1802 " 1803 INDEX { usmUserEngineID, 1804 usmUserName 1805 } 1806 ::= { usmUserTable 1 } 1808 UsmUserEntry ::= SEQUENCE 1809 { 1810 usmUserEngineID SnmpEngineID, 1811 usmUserName SnmpAdminString, 1812 usmUserSecurityName SnmpAdminString, 1813 usmUserCloneFrom RowPointer, 1814 usmUserAuthProtocol AutonomousType, 1815 usmUserAuthKeyChange KeyChange, 1816 usmUserOwnAuthKeyChange KeyChange, 1817 usmUserPrivProtocol AutonomousType, 1818 usmUserPrivKeyChange KeyChange, 1819 usmUserOwnPrivKeyChange KeyChange, 1820 usmUserPublic OCTET STRING, 1821 usmUserStorageType StorageType, 1822 usmUserStatus RowStatus 1823 } 1825 usmUserEngineID OBJECT-TYPE 1826 SYNTAX SnmpEngineID 1827 MAX-ACCESS not-accessible 1828 STATUS current 1829 DESCRIPTION "An SNMP engine's administratively-unique identifier. 1831 In a simple agent, this value is always that agent's 1832 own snmpEngineID value. 1834 The value can also take the value of the snmpEngineID 1835 of a remote SNMP engine with which this user can 1836 communicate. 1837 " 1838 ::= { usmUserEntry 1 } 1840 usmUserName OBJECT-TYPE 1841 SYNTAX SnmpAdminString (SIZE(1..32)) 1842 MAX-ACCESS not-accessible 1843 STATUS current 1844 DESCRIPTION "A human readable string representing the name of 1845 the user. 1847 This is the (User-based Security) Model dependent 1848 security ID. 1849 " 1850 ::= { usmUserEntry 2 } 1852 usmUserSecurityName OBJECT-TYPE 1853 SYNTAX SnmpAdminString 1854 MAX-ACCESS read-only 1855 STATUS current 1856 DESCRIPTION "A human readable string representing the user in 1857 Security Model independent format. 1859 The default transformation of the User-based Security 1860 Model dependent security ID to the securityName and 1861 vice versa is the identity function so that the 1862 securityName is the same as the userName. 1863 " 1864 ::= { usmUserEntry 3 } 1866 usmUserCloneFrom OBJECT-TYPE 1867 SYNTAX RowPointer 1868 MAX-ACCESS read-create 1869 STATUS current 1870 DESCRIPTION "A pointer to another conceptual row in this 1871 usmUserTable. The user in this other conceptual 1872 row is called the clone-from user. 1874 When a new user is created (i.e., a new conceptual 1875 row is instantiated in this table), the privacy and 1876 authentication parameters of the new user are cloned 1877 from its clone-from user. 1879 The first time an instance of this object is set by 1880 a management operation (either at or after its 1881 instantiation), the cloning process is invoked. 1882 Subsequent writes are successful but invoke no 1883 action to be taken by the receiver. 1884 The cloning process fails with an 'inconsistentName' 1885 error if the conceptual row representing the 1886 clone-from user is not in an active state when the 1887 cloning process is invoked. 1889 Cloning also causes the initial values of the secret 1890 authentication key and the secret encryption key of 1891 the new user to be set to the same value as the 1892 corresponding secret of the clone-from user. 1894 When this object is read, the ZeroDotZero OID 1895 is returned. 1896 " 1897 ::= { usmUserEntry 4 } 1899 usmUserAuthProtocol OBJECT-TYPE 1900 SYNTAX AutonomousType 1901 MAX-ACCESS read-create 1902 STATUS current 1903 DESCRIPTION "An indication of whether messages sent on behalf of 1904 this user to/from the SNMP engine identified by 1905 usmUserEngineID, can be authenticated, and if so, 1906 the type of authentication protocol which is used. 1908 An instance of this object is created concurrently 1909 with the creation of any other object instance for 1910 the same user (i.e., as part of the processing of 1911 the set operation which creates the first object 1912 instance in the same conceptual row). Once created, 1913 the value of an instance of this object can not be 1914 changed. 1916 If a set operation tries to set a value for an unknown 1917 or unsupported protocol, then a wrongValue error must 1918 be returned. 1919 " 1920 DEFVAL { usmHMACMD5AuthProtocol } 1921 ::= { usmUserEntry 5 } 1923 usmUserAuthKeyChange OBJECT-TYPE 1924 SYNTAX KeyChange -- typically (SIZE (0..32)) 1925 MAX-ACCESS read-create 1926 STATUS current 1927 DESCRIPTION "An object, which when modified, causes the secret 1928 authentication key used for messages sent on behalf 1929 of this user to/from the SNMP engine identified by 1930 usmUserEngineID, to be modified via a one-way 1931 function. 1933 The associated protocol is the usmUserAuthProtocol. 1934 The associated secret key is the user's secret 1935 authentication key (authKey). The associated hash 1936 algorithm is the algorithm used by the user's 1937 usmUserAuthProtocol. 1939 When creating a new user, it is an 'inconsistentName' 1940 error for a Set operation to refer to this object 1941 unless it is previously or concurrently initialized 1942 through a set operation on the corresponding value 1943 of usmUserCloneFrom. 1944 " 1945 DEFVAL { ''H } -- the empty string 1946 ::= { usmUserEntry 6 } 1948 usmUserOwnAuthKeyChange OBJECT-TYPE 1949 SYNTAX KeyChange -- typically (SIZE (0..32)) 1950 MAX-ACCESS read-create 1951 STATUS current 1952 DESCRIPTION "Behaves exactly as usmUserAuthKeyChange, with one 1953 notable difference: in order for the Set operation 1954 to succeed, the usmUserName of the operation 1955 requester must match the usmUserName that 1956 indexes the row which is targeted by this 1957 operation. 1959 The idea here is that access to this column can be 1960 public, since it will only allow a user to change 1961 his own secret authentication key (authKey). 1962 " 1963 DEFVAL { ''H } -- the empty string 1964 ::= { usmUserEntry 7 } 1966 usmUserPrivProtocol OBJECT-TYPE 1967 SYNTAX AutonomousType 1968 MAX-ACCESS read-create 1969 STATUS current 1970 DESCRIPTION "An indication of whether messages sent on behalf of 1971 this user to/from the SNMP engine identified by 1972 usmUserEngineID, can be protected from disclosure, 1973 and if so, the type of privacy protocol which is used. 1975 An instance of this object is created concurrently 1976 with the creation of any other object instance for 1977 the same user (i.e., as part of the processing of 1978 the set operation which creates the first object 1979 instance in the same conceptual row). Once created, 1980 the value of an instance of this object can not be 1981 changed. 1983 If a set operation tries to set a value for an unknown 1984 or unsupported protocol, then a wrongValue error must 1985 be returned. 1986 " 1987 DEFVAL { usmNoPrivProtocol } 1988 ::= { usmUserEntry 8 } 1990 usmUserPrivKeyChange OBJECT-TYPE 1991 SYNTAX KeyChange -- typically (SIZE (0..32)) 1992 MAX-ACCESS read-create 1993 STATUS current 1994 DESCRIPTION "An object, which when modified, causes the secret 1995 encryption key used for messages sent on behalf 1996 of this user to/from the SNMP engine identified by 1997 usmUserEngineID, to be modified via a one-way 1998 function. 2000 The associated protocol is the usmUserPrivProtocol. 2001 The associated secret key is the user's secret 2002 privacy key (privKey). The associated hash 2003 algorithm is the algorithm used by the user's 2004 usmUserAuthProtocol. 2006 When creating a new user, it is an 'inconsistentName' 2007 error for a set operation to refer to this object 2008 unless it is previously or concurrently initialized 2009 through a set operation on the corresponding value 2010 of usmUserCloneFrom. 2011 " 2012 DEFVAL { ''H } -- the empty string 2013 ::= { usmUserEntry 9 } 2015 usmUserOwnPrivKeyChange OBJECT-TYPE 2016 SYNTAX KeyChange -- typically (SIZE (0..32)) 2017 MAX-ACCESS read-create 2018 STATUS current 2019 DESCRIPTION "Behaves exactly as usmUserPrivKeyChange, with one 2020 notable difference: in order for the Set operation 2021 to succeed, the usmUserName of the operation 2022 requester must match the usmUserName that indexes 2023 the row which is targeted by this operation. 2025 The idea here is that access to this column can be 2026 public, since it will only allow a user to change 2027 his own secret privacy key (privKey). 2028 " 2029 DEFVAL { ''H } -- the empty string 2030 ::= { usmUserEntry 10 } 2032 usmUserPublic OBJECT-TYPE 2033 SYNTAX OCTET STRING (SIZE(0..32)) 2034 MAX-ACCESS read-create 2035 STATUS current 2036 DESCRIPTION "A publicly-readable value which is written as part 2037 of the procedure for changing a user's secret 2038 authentication and/or privacy key, and later read to 2039 determine whether the change of the secret was 2040 effected. 2041 " 2042 DEFVAL { ''H } -- the empty string 2043 ::= { usmUserEntry 11 } 2045 usmUserStorageType OBJECT-TYPE 2046 SYNTAX StorageType 2047 MAX-ACCESS read-create 2048 STATUS current 2049 DESCRIPTION "The storage type for this conceptual row. 2051 Conceptual rows having the value 'permanent' 2052 must allow write-access at a minimum to: 2054 - usmUserAuthKeyChange, usmUserOwnAuthKeyChange 2055 and usmUserPublic for a user who employs 2056 authentication, and 2057 - usmUserPrivKeyChange, usmUserOwnPrivKeyChange 2058 and usmUserPublic for a user who employs 2059 privacy. 2061 Note that any user who employs authentication or 2062 privacy must allow its secret(s) to be updated and 2063 thus cannot be 'readOnly'. 2064 " 2065 DEFVAL { nonVolatile } 2066 ::= { usmUserEntry 12 } 2068 usmUserStatus OBJECT-TYPE 2069 SYNTAX RowStatus 2070 MAX-ACCESS read-create 2071 STATUS current 2072 DESCRIPTION "The status of this conceptual row. 2074 Until instances of all corresponding columns are 2075 appropriately configured, the value of the 2076 corresponding instance of the usmUserStatus column 2077 is 'notReady'. 2079 In particular, a newly created row cannot be made 2080 active until the corresponding usmUserCloneFrom, 2081 usmUserAuthKeyChange, usmUserOwnAuthKeyChange, 2082 usmUserPrivKeyChange and usmUserOwnPrivKeyChange 2083 have all been set. 2085 The RowStatus TC [RFC1903] requires that this 2086 DESCRIPTION clause states under which circumstances 2087 other objects in this row can be modified: 2089 The value of this object has no effect on whether 2090 other objects in this conceptual row can be modified. 2091 " 2092 ::= { usmUserEntry 13 } 2094 -- Conformance Information ******************************************* 2096 usmMIBCompliances OBJECT IDENTIFIER ::= { usmMIBConformance 1 } 2097 usmMIBGroups OBJECT IDENTIFIER ::= { usmMIBConformance 2 } 2099 -- Compliance statements 2101 usmMIBCompliance MODULE-COMPLIANCE 2102 STATUS current 2103 DESCRIPTION "The compliance statement for SNMP engines which 2104 implement the SNMP-USER-BASED-SM-MIB. 2105 " 2107 MODULE -- this module 2108 MANDATORY-GROUPS { usmMIBBasicGroup } 2110 OBJECT usmUserAuthProtocol 2111 MIN-ACCESS read-only 2112 DESCRIPTION "Write access is not required." 2114 OBJECT usmUserPrivProtocol 2115 MIN-ACCESS read-only 2116 DESCRIPTION "Write access is not required." 2118 ::= { usmMIBCompliances 1 } 2120 -- Units of compliance 2121 usmMIBBasicGroup OBJECT-GROUP 2122 OBJECTS { 2123 usmStatsUnsupportedSecLevels, 2124 usmStatsNotInTimeWindows, 2125 usmStatsUnknownUserNames, 2126 usmStatsUnknownEngineIDs, 2127 usmStatsWrongDigests, 2128 usmStatsDecryptionErrors, 2129 usmUserSpinLock, 2130 usmUserSecurityName, 2131 usmUserCloneFrom, 2132 usmUserAuthProtocol, 2133 usmUserAuthKeyChange, 2134 usmUserOwnAuthKeyChange, 2135 usmUserPrivProtocol, 2136 usmUserPrivKeyChange, 2137 usmUserOwnPrivKeyChange, 2138 usmUserPublic, 2139 usmUserStorageType, 2140 usmUserStatus 2141 } 2142 STATUS current 2143 DESCRIPTION "A collection of objects providing for configuration 2144 of an SNMP engine which implements the SNMP 2145 User-based Security Model. 2146 " 2147 ::= { usmMIBGroups 1 } 2149 END 2150 6. HMAC-MD5-96 Authentication Protocol 2152 This section describes the HMAC-MD5-96 authentication protocol. 2153 This authentication protocol is the first defined for 2154 the User-based Security Model. It uses MD5 hash-function which 2155 is described in [MD5], in HMAC mode described in [RFC2104], 2156 truncating the output to 96 bits. 2158 This protocol is identified by usmHMACMD5AuthProtocol. 2160 Over time, other authentication protocols may be defined either 2161 as a replacement of this protocol or in addition to this protocol. 2163 6.1. Mechanisms 2165 - In support of data integrity, a message digest algorithm is 2166 required. A digest is calculated over an appropriate portion 2167 of an SNMP message and included as part of the message sent 2168 to the recipient. 2170 - In support of data origin authentication and data integrity, 2171 a secret value is prepended to SNMP message prior to computing the 2172 digest; the calculated digest is partially inserted into the SNMP 2173 message prior to transmission, and the prepended value is not 2174 transmitted. The secret value is shared by all SNMP engines 2175 authorized to originate messages on behalf of the appropriate user. 2177 6.1.1. Digest Authentication Mechanism 2179 The Digest Authentication Mechanism defined in this memo provides 2180 for: 2182 - verification of the integrity of a received message, i.e., the 2183 message received is the message sent. 2185 The integrity of the message is protected by computing a digest 2186 over an appropriate portion of the message. The digest is 2187 computed by the originator of the message, transmitted with the 2188 message, and verified by the recipient of the message. 2190 - verification of the user on whose behalf the message was generated. 2192 A secret value known only to SNMP engines authorized to 2193 generate messages on behalf of a user is used in HMAC mode 2194 (see [RFC2104]). It also recommends the hash-function output 2195 used as Message Authentication Code, to be truncated. 2197 This protocol uses the MD5 [MD5] message digest algorithm. 2198 A 128-bit MD5 digest is calculated in a special (HMAC) way over 2199 the designated portion of an SNMP message and the first 96 bits 2200 o this digest is included as part of the message sent to the 2201 recipient. The size of the digest carried in a message is 12 2202 octets. The size of the private authentication key (the secret) 2203 is 16 octets. For the details see section 6.3. 2205 6.2. Elements of the Digest Authentication Protocol 2207 This section contains definitions required to realize the 2208 authentication module defined in this section of this memo. 2210 6.2.1. Users 2212 Authentication using this authentication protocol makes 2213 use of a defined set of userNames. For any user on whose behalf a 2214 message must be authenticated at a particular SNMP engine, that 2215 SNMP engine must have knowledge of that user. An SNMP engine that 2216 wishes to communicate with another SNMP engine must also have 2217 knowledge of a user known to that engine, including knowledge of 2218 the applicable attributes of that user. 2220 A user and its attributes are defined as follows: 2222 2223 A string representing the name of the user. 2224 2225 A user's secret key to be used when calculating a digest. 2226 It MUST be 16 octets long for MD5. 2228 6.2.2. msgAuthoritativeEngineID 2230 The msgAuthoritativeEngineID value contained in an authenticated 2231 message specifies the authoritative SNMP engine for that particular 2232 message (see the definition of SnmpEngineID in the SNMP 2233 Architecture document [SNMP-ARCH]). 2235 The user's (private) authentication key is normally different at 2236 each authoritative SNMP engine and so the snmpEngineID is used 2237 to select the proper key for the authentication process. 2239 6.2.3. SNMP Messages Using this Authentication Protocol 2241 Messages using this authentication protocol carry a 2242 msgAuthenticationParameters field as part of the 2243 msgSecurityParameters. For this protocol, the 2244 msgAuthenticationParameters field is the serialized OCTET STRING 2245 representing the first 12 octets of the HMAC-MD5-96 output done 2246 over the wholeMsg. 2248 The digest is calculated over the wholeMsg so if a message is 2249 authenticated, that also means that all the fields in the message 2250 are intact and have not been tampered with. 2252 6.2.4. Services provided by the HMAC-MD5-96 Authentication Module 2254 This section describes the inputs and outputs that the HMAC-MD5-96 2255 Authentication module expects and produces when the User-based 2256 Security module calls the HMAC-MD5-96 Authentication module for 2257 services. 2259 6.2.4.1. Services for Generating an Outgoing SNMP Message 2261 The HMAC-MD5-96 authentication protocol assumes that the selection 2262 of the authKey is done by the caller and that the caller passes 2263 the secret key to be used. 2265 Upon completion the authentication module returns statusInformation 2266 and, if the message digest was correctly calculated, the wholeMsg 2267 with the digest inserted at the proper place. The abstract service 2268 primitive is: 2270 statusInformation = -- success or failure 2271 authenticateOutgoingMsg( 2272 IN authKey -- secret key for authentication 2273 IN wholeMsg -- unauthenticated complete message 2274 OUT authenticatedWholeMsg -- complete authenticated message 2275 ) 2277 The abstract data elements are: 2279 statusInformation 2280 An indication of whether the authentication process was 2281 successful. If not it is an indication of the problem. 2282 authKey 2283 The secret key to be used by the authentication algorithm. 2284 The length of this key MUST be 16 octets. 2285 wholeMsg 2286 The message to be authenticated. 2287 authenticatedWholeMsg 2288 The authenticated message (including inserted digest) on output. 2290 Note, that authParameters field is filled by the authentication 2291 module and this field should be already present in the wholeMsg 2292 before the Message Authentication Code (MAC) is generated. 2294 6.2.4.2. Services for Processing an Incoming SNMP Message 2296 The HMAC-MD5-96 authentication protocol assumes that the selection 2297 of the authKey is done by the caller and that the caller passes 2298 the secret key to be used. 2300 Upon completion the authentication module returns statusInformation 2301 and, if the message digest was correctly calculated, the wholeMsg 2302 as it was processed. The abstract service primitive is: 2304 statusInformation = -- success or failure 2305 authenticateIncomingMsg( 2306 IN authKey -- secret key for authentication 2307 IN authParameters -- as received on the wire 2308 IN wholeMsg -- as received on the wire 2309 OUT authenticatedWholeMsg -- complete authenticated message 2310 ) 2312 The abstract data elements are: 2314 statusInformation 2315 An indication of whether the authentication process was 2316 successful. If not it is an indication of the problem. 2317 authKey 2318 The secret key to be used by the authentication algorithm. 2319 The length of this key MUST be 16 octets. 2320 authParameters 2321 The authParameters from the incoming message. 2322 wholeMsg 2323 The message to be authenticated on input and the authenticated 2324 message on output. 2325 authenticatedWholeMsg 2326 The whole message after the authentication check is complete. 2328 6.3. Elements of Procedure 2330 This section describes the procedures for the HMAC-MD5-96 2331 authentication protocol. 2333 6.3.1. Processing an Outgoing Message 2335 This section describes the procedure followed by an SNMP engine 2336 whenever it must authenticate an outgoing message using the 2337 usmHMACMD5AuthProtocol. 2339 1) The msgAuthenticationParameters field is set to the 2340 serialization, according to the rules in [RFC1906], of an 2341 OCTET STRING containing 12 zero octets. 2343 2) From the secret authKey, two keys K1 and K2 are derived: 2345 a) extend the authKey to 64 octets by appending 48 zero 2346 octets; save it as extendedAuthKey 2347 b) obtain IPAD by replicating the octet 0x36 64 times; 2348 c) obtain K1 by XORing extendedAuthKey with IPAD; 2349 d) obtain OPAD by replicating the octet 0x5C 64 times; 2350 e) obtain K2 by XORing extendedAuthKey with OPAD. 2352 4) Prepend K1 to the wholeMsg and calculate MD5 digest over it 2353 according to [MD5]. 2355 5) Prepend K2 to the result of the step 4 and calculate MD5 digest 2356 over it according to [MD5]. Take the first 12 octets of the final 2357 digest - this is Message Authentication Code (MAC). 2359 6) Replace the msgAuthenticationParameters field with MAC obtained 2360 in the step 5. 2362 7) The authenticatedWholeMsg is then returned to the caller 2363 together with statusInformation indicating success. 2365 6.3.2. Processing an Incoming Message 2367 This section describes the procedure followed by an SNMP engine 2368 whenever it must authenticate an incoming message using the 2369 usmHMACMD5AuthProtocol. 2371 1) If the digest received in the msgAuthenticationParameters field 2372 is not 12 octets long, then an failure and an errorIndication 2373 (authenticationError) is returned to the calling module. 2375 2) The MAC received in the msgAuthenticationParameters field 2376 is saved. 2378 3) The digest in the msgAuthenticationParameters field is replaced 2379 by the 12 zero octets. 2381 4) From the secret authKey, two keys K1 and K2 are derived: 2383 a) extend the authKey to 64 octets by appending 48 zero 2384 octets; save it as extendedAuthKey 2385 b) obtain IPAD by replicating the octet 0x36 64 times; 2386 c) obtain K1 by XORing extendedAuthKey with IPAD; 2387 d) obtain OPAD by replicating the octet 0x5C 64 times; 2388 e) obtain K2 by XORing extendedAuthKey with OPAD. 2390 5) The MAC is calculated over the wholeMsg: 2392 a) prepend K1 to the wholeMsg and calculate the MD5 digest 2393 over it; 2394 b) prepend K2 to the result of step 5.a and calculate the 2395 MD5 digest over it; 2396 c) first 12 octets of the result of step 5.b is the MAC. 2398 The msgAuthenticationParameters field is replaced with the 2399 MAC value that was saved in step 2. 2401 6) Then the newly calculated MAC is compared with the MAC 2402 saved in step 2. If they do not match, then an failure 2403 and an errorIndication (authenticationFailure) is returned to 2404 the calling module. 2406 7) The authenticatedWholeMsg and statusInformation indicating 2407 success are then returned to the caller. 2409 7. HMAC-SHA-96 Authentication Protocol 2411 This section describes the HMAC-SHA-96 authentication protocol. 2412 This protocol uses the SHA hash-function which is described in 2413 [SHA-NIST], in HMAC mode described in [RFC2104], truncating 2414 the output to 96 bits. 2416 This protocol is identified by usmHMACSHAAuthProtocol. 2418 Over time, other authentication protocols may be defined either 2419 as a replacement of this protocol or in addition to this protocol. 2421 7.1. Mechanisms 2423 - In support of data integrity, a message digest algorithm is 2424 required. A digest is calculated over an appropriate portion 2425 of an SNMP message and included as part of the message sent 2426 to the recipient. 2428 - In support of data origin authentication and data integrity, 2429 a secret value is prepended to the SNMP message prior to 2430 computing the digest; the calculated digest is then partially 2431 inserted into the message prior to transmission. The prepended 2432 secret is not transmitted. The secret value is shared by all 2433 SNMP engines authorized to originate messages on behalf of the 2434 appropriate user. 2436 7.1.1. Digest Authentication Mechanism 2438 The Digest Authentication Mechanism defined in this memo provides 2439 for: 2441 - verification of the integrity of a received message, i.e., the 2442 the message received is the message sent. 2444 The integrity of the message is protected by computing a digest 2445 over an appropriate portion of the message. The digest is 2446 computed by the originator of the message, transmitted with the 2447 message, and verified by the recipient of the message. 2449 - verification of the user on whose behalf the message was generated. 2451 A secret value known only to SNMP engines authorized to 2452 generate messages on behalf of a user is used in HMAC mode 2453 (see [RFC2104]). It also recommends the hash-function output 2454 used as Message Authentication Code, to be truncated. 2456 This mechanism uses the SHA [SHA-NIST] message digest algorithm. 2457 A 160-bit SHA digest is calculated in a special (HMAC) way over 2458 the designated portion of an SNMP message and the first 96 bits 2459 of this digest is included as part of the message sent to the 2460 recipient. The size of the digest carried in a message is 12 2461 octets. The size of the private authentication key (the secret) 2462 is 20 octets. For the details see section 7.3. 2464 7.2. Elements of the HMAC-SHA-96 Authentication Protocol 2466 This section contains definitions required to realize the 2467 authentication module defined in this section of this memo. 2469 7.2.1. Users 2471 Authentication using this authentication protocol makes use 2472 of a defined set of userNames. For any user on whose behalf a 2473 message must be authenticated at a particular SNMP engine, that 2474 SNMP engine must have knowledge of that user. An SNMP engine that 2475 wishes to communicate with another SNMP engine must also have 2476 knowledge of a user known to that engine, including knowledge of 2477 the applicable attributes of that user. 2479 A user and its attributes are defined as follows: 2481 2482 A string representing the name of the user. 2483 2484 A user's secret key to be used when calculating a digest. 2485 It MUST be 20 octets long for SHA. 2487 7.2.2. msgAuthoritativeEngineID 2489 The msgAuthoritativeEngineID value contained in an authenticated 2490 message specifies the authoritative SNMP engine for that particular 2491 message (see the definition of SnmpEngineID in the SNMP 2492 Architecture document [SNMP-ARCH]). 2494 The user's (private) authentication key is normally different at 2495 each authoritative SNMP engine and so the snmpEngineID is used 2496 to select the proper key for the authentication process. 2498 7.2.3. SNMP Messages Using this Authentication Protocol 2500 Messages using this authentication protocol carry a 2501 msgAuthenticationParameters field as part of the 2502 msgSecurityParameters. For this protocol, the 2503 msgAuthenticationParameters field is the serialized 2504 OCTET STRING representing the first 12 octets of HMAC-SHA-96 2505 output done over the wholeMsg. 2507 The digest is calculated over the wholeMsg so if a message is 2508 authenticated, that also means that all the fields in the 2509 message are intact and have not been tampered with. 2511 7.2.4. Services provided by the HMAC-SHA-96 Authentication Module 2513 This section describes the inputs and outputs that the HMAC-SHA-96 2514 Authentication module expects and produces when the User-based 2515 Security module calls the HMAC-SHA-96 Authentication module 2516 for services. 2518 7.2.4.1. Services for Generating an Outgoing SNMP Message 2520 HMAC-SHA-96 authentication protocol assumes that the selection 2521 of the authKey is done by the caller and that the caller passes 2522 the secret key to be used. 2524 Upon completion the authentication module returns statusInformation 2525 and, if the message digest was correctly calculated, the wholeMsg 2526 with the digest inserted at the proper place. The abstract service 2527 primitive is: 2529 statusInformation = -- success or failure 2530 authenticateOutgoingMsg( 2531 IN authKey -- secret key for authentication 2532 IN wholeMsg -- unauthenticated complete message 2533 OUT authenticatedWholeMsg -- complete authenticated message 2534 ) 2536 The abstract data elements are: 2538 statusInformation 2539 An indication of whether the authentication process was 2540 successful. If not it is an indication of the problem. 2541 authKey 2542 The secret key to be used by the authentication algorithm. 2543 The length of this key MUST be 20 octets. 2544 wholeMsg 2545 The message to be authenticated. 2546 authenticatedWholeMsg 2547 The authenticated message (including inserted digest) on output. 2549 Note, that authParameters field is filled by the authentication 2550 module and this field should be already present in the wholeMsg 2551 before the Message Authentication Code (MAC) is generated. 2553 7.2.4.2. Services for Processing an Incoming SNMP Message 2555 HMAC-SHA-96 authentication protocol assumes that the selection 2556 of the authKey is done by the caller and that the caller passes 2557 the secret key to be used. 2559 Upon completion the authentication module returns statusInformation 2560 and, if the message digest was correctly calculated, the wholeMsg 2561 as it was processed. The abstract service primitive is: 2563 statusInformation = -- success or failure 2564 authenticateIncomingMsg( 2565 IN authKey -- secret key for authentication 2566 IN authParameters -- as received on the wire 2567 IN wholeMsg -- as received on the wire 2568 OUT authenticatedWholeMsg -- complete authenticated message 2569 ) 2571 The abstract data elements are: 2573 statusInformation 2574 An indication of whether the authentication process was 2575 successful. If not it is an indication of the problem. 2576 authKey 2577 The secret key to be used by the authentication algorithm. 2578 The length of this key MUST be 20 octets. 2579 authParameters 2580 The authParameters from the incoming message. 2581 wholeMsg 2582 The message to be authenticated on input and the authenticated 2583 message on output. 2584 authenticatedWholeMsg 2585 The whole message after the authentication check is complete. 2587 7.3. Elements of Procedure 2589 This section describes the procedures for the HMAC-SHA-96 2590 authentication protocol. 2592 7.3.1. Processing an Outgoing Message 2594 This section describes the procedure followed by an SNMP engine 2595 whenever it must authenticate an outgoing message using the 2596 usmHMACSHAAuthProtocol. 2598 1) The msgAuthenticationParameters field is set to the 2599 serialization, according to the rules in [RFC1906], of an 2600 OCTET STRING containing 12 zero octets. 2602 2) From the secret authKey, two keys K1 and K2 are derived: 2604 a) extend the authKey to 64 octets by appending 44 zero 2605 octets; save it as extendedAuthKey 2606 b) obtain IPAD by replicating the octet 0x36 64 times; 2607 c) obtain K1 by XORing extendedAuthKey with IPAD; 2608 d) obtain OPAD by replicating the octet 0x5C 64 times; 2609 e) obtain K2 by XORing extendedAuthKey with OPAD. 2611 4) Prepend K1 to the wholeMsg and calculate the SHA digest over it 2612 according to [SHA-NIST]. 2614 5) Prepend K2 to the result of the step 4 and calculate SHA digest 2615 over it according to [SHA-NIST]. Take the first 12 octets of the 2616 final digest - this is Message Authentication Code (MAC). 2618 6) Replace the msgAuthenticationParameters field with MAC obtained 2619 in the step 5. 2621 7) The authenticatedWholeMsg is then returned to the caller 2622 together with statusInformation indicating success. 2624 7.3.2. Processing an Incoming Message 2626 This section describes the procedure followed by an SNMP engine 2627 whenever it must authenticate an incoming message using the 2628 usmHMACSHAAuthProtocol. 2630 1) If the digest received in the msgAuthenticationParameters field 2631 is not 12 octets long, then an failure and an errorIndication 2632 (authenticationError) is returned to the calling module. 2634 2) The MAC received in the msgAuthenticationParameters field 2635 is saved. 2637 3) The digest in the msgAuthenticationParameters field is 2638 replaced by the 12 zero octets. 2640 4) From the secret authKey, two keys K1 and K2 are derived: 2642 a) extend the authKey to 64 octets by appending 44 zero 2643 octets; save it as extendedAuthKey 2644 b) obtain IPAD by replicating the octet 0x36 64 times; 2645 c) obtain K1 by XORing extendedAuthKey with IPAD; 2646 d) obtain OPAD by replicating the octet 0x5C 64 times; 2647 e) obtain K2 by XORing extendedAuthKey with OPAD. 2649 5) The MAC is calculated over the wholeMsg: 2651 a) prepend K1 to the wholeMsg and calculate the SHA digest 2652 over it; 2653 b) prepend K2 to the result of step 5.a and calculate the 2654 SHA digest over it; 2655 c) first 12 octets of the result of step 5.b is the MAC. 2657 The msgAuthenticationParameters field is replaced with the 2658 MAC value that was saved in step 2. 2660 6) The the newly calculated MAC is compared with the MAC saved in 2661 step 2. If they do not match, then a failure and an 2662 errorIndication (authenticationFailure) are returned to the 2663 calling module. 2665 7) The authenticatedWholeMsg and statusInformation indicating 2666 success are then returned to the caller. 2668 8. CBC-DES Symmetric Encryption Protocol 2670 This section describes the CBC-DES Symmetric Encryption Protocol. 2671 This protocol is the first privacy protocol defined for the 2672 User-based Security Model. 2674 This protocol is identified by usmDESPrivProtocol. 2676 Over time, other privacy protocols may be defined either 2677 as a replacement of this protocol or in addition to this protocol. 2679 8.1. Mechanisms 2681 - In support of data confidentiality, an encryption algorithm is 2682 required. An appropriate portion of the message is encrypted 2683 prior to being transmitted. The User-based Security Model 2684 specifies that the scopedPDU is the portion of the message 2685 that needs to be encrypted. 2687 - A secret value in combination with a timeliness value is used 2688 to create the en/decryption key and the initialization vector. 2689 The secret value is shared by all SNMP engines authorized to 2690 originate messages on behalf of the appropriate user. 2692 8.1.1. Symmetric Encryption Protocol 2694 The Symmetric Encryption Protocol defined in this memo provides 2695 support for data confidentiality. The designated portion of an 2696 SNMP message is encrypted and included as part of the message 2697 sent to the recipient. 2699 Two organizations have published specifications defining the DES: 2700 the National Institute of Standards and Technology (NIST) 2701 [DES-NIST] and the American National Standards Institute 2702 [DES-ANSI]. There is a companion Modes of Operation specification 2703 for each definition ([DESO-NIST] and [DESO-ANSI], respectively). 2705 The NIST has published three additional documents that implementors 2706 may find useful. 2708 - There is a document with guidelines for implementing and using 2709 the DES, including functional specifications for the DES and 2710 its modes of operation [DESG-NIST]. 2712 - There is a specification of a validation test suite for the DES 2713 [DEST-NIST]. The suite is designed to test all aspects of the 2714 DES and is useful for pinpointing specific problems. 2716 - There is a specification of a maintenance test for the DES 2718 [DESM-NIST]. The test utilizes a minimal amount of data and 2719 processing to test all components of the DES. It provides a 2720 simple yes-or-no indication of correct operation and is useful 2721 to run as part of an initialization step, e.g., when a computer 2722 re-boots. 2724 8.1.1.1. DES key and Initialization Vector. 2726 The first 8 octets of the 16-octet secret (private privacy key) are 2727 used as a DES key. Since DES uses only 56 bits, the Least 2728 Significant Bit in each octet is disregarded. 2730 The Initialization Vector for encryption is obtained using the 2731 following procedure. 2733 The last 8 octets of the 16-octet secret (private privacy key) 2734 are used as pre-IV. 2736 In order to ensure that the IV for two different packets encrypted 2737 by the same key, are not the same (i.e., the IV does not repeat) we 2738 need to "salt" the pre-IV with something unique per packet. 2739 An 8-octet string is used as the "salt". The concatenation 2740 of the generating SNMP engine's 32-bit snmpEngineBoots and a local 2741 32-bit integer, that the encryption engine maintains, is input to 2742 the "salt". The 32-bit integer is initialized to an arbitrary 2743 value at boot time. 2744 The 32-bit snmpEngineBoots is converted to the first 4 octets 2745 (Most Significant Byte first) of our "salt". The 32-bit integer 2746 is then converted to the last 4 octet (Most Significant Byte first) 2747 of our "salt". The resulting "salt" is then XOR-ed with the 2748 pre-IV. The 8-octet "salt" is then put into the privParameters 2749 field encoded as an OCTET STRING. The "salt" integer is then 2750 modified. We recommend that it be incremented by one and wrap 2751 when it reaches the maximum value. 2753 How exactly the value of the "salt" (and thus of the IV) varies, 2754 is an implementation issue, as long as the measures are taken to 2755 avoid producing a duplicate IV. 2757 The "salt" must be placed in the privParameters field to enable the 2758 receiving entity to compute the correct IV and to decrypt the 2759 message. 2761 8.1.1.2. Data Encryption. 2763 The data to be encrypted is treated as sequence of octets. Its 2764 length should be an integral multiple of 8 - and if it is not, the 2765 data is padded at the end as necessary. The actual pad value 2766 is irrelevant. 2768 The data is encrypted in Cipher Block Chaining mode. 2770 The plaintext is divided into 64-bit blocks. 2772 The plaintext for each block is XOR-ed with the ciphertext 2773 of the previous block, the result is encrypted and the output 2774 of the encryption is the ciphertext for the block. 2775 This procedure is repeated until there are no more plaintext 2776 blocks. 2778 For the very first block, the Initialization Vector is used 2779 instead of the ciphertext of the previous block. 2781 8.1.1.3. Data Decryption 2783 Before decryption, the encrypted data length is verified. 2784 If the length of the OCTET STRING to be decrypted is not an 2785 integral multiple of 8 octets, the decryption process is halted 2786 and an appropriate exception noted. When decrypting, the padding 2787 is ignored. 2789 The first ciphertext block is decrypted, the decryption output is 2790 XOR-ed with the Initialization Vector, and the result is the first 2791 plaintext block. 2793 For each subsequent block, the ciphertext block is decrypted, 2794 the decryption output is XOR-ed with the previous ciphertext 2795 block and the result is the plaintext block. 2797 8.2. Elements of the DES Privacy Protocol 2799 This section contains definitions required to realize the privacy 2800 module defined by this memo. 2802 8.2.1. Users 2804 Data en/decryption using this Symmetric Encryption Protocol makes 2805 use of a defined set of userNames. For any user on whose behalf 2806 a message must be en/decrypted at a particular SNMP engine, that 2807 SNMP engine must have knowledge of that user. An SNMP engine that 2808 wishes to communicate with another SNMP engine must also have 2809 knowledge of a user known to that SNMP engine, including knowledge 2810 of the applicable attributes of that user. 2812 A user and its attributes are defined as follows: 2814 2815 An octet string representing the name of the user. 2816 2817 A user's secret key to be used as input for the DES key and IV. 2818 The length of this key MUST be 16 octets. 2820 8.2.2. msgAuthoritativeEngineID 2821 The msgAuthoritativeEngineID value contained in an authenticated 2822 message specifies the authoritative SNMP engine for that particular 2823 message (see the definition of SnmpEngineID in the SNMP 2824 Architecture document [SNMP-ARCH]). 2826 The user's (private) privacy key is normally different at each 2827 authoritative SNMP engine and so the snmpEngineID is used to select 2828 the proper key for the en/decryption process. 2830 8.2.3. SNMP Messages Using this Privacy Protocol 2832 Messages using this privacy protocol carry a msgPrivacyParameters 2833 field as part of the msgSecurityParameters. For this protocol, the 2834 msgPrivacyParameters field is the serialized OCTET STRING 2835 representing the "salt" that was used to create the IV. 2837 8.2.4. Services provided by the DES Privacy Module 2839 This section describes the inputs and outputs that the DES Privacy 2840 module expects and produces when the User-based Security module 2841 invokes the DES Privacy module for services. 2843 8.2.4.1. Services for Encrypting Outgoing Data 2845 This DES privacy protocol assumes that the selection of the 2846 privKey is done by the caller and that the caller passes 2847 the secret key to be used. 2849 Upon completion the privacy module returns statusInformation 2850 and, if the encryption process was successful, the encryptedPDU 2851 and the msgPrivacyParameters encoded as an OCTET STRING. 2852 The abstract service primitive is: 2854 statusInformation = -- success of failure 2855 encryptData( 2856 IN encryptKey -- secret key for encryption 2857 IN dataToEncrypt -- data to encrypt (scopedPDU) 2858 OUT encryptedData -- encrypted data (encryptedPDU) 2859 OUT privParameters -- filled in by service provider 2860 ) 2862 The abstract data elements are: 2864 statusInformation 2865 An indication of the success or failure of the encryption 2866 process. In case of failure, it is an indication of the error. 2867 encryptKey 2868 The secret key to be used by the encryption algorithm. 2869 The length of this key MUST be 16 octets. 2870 dataToEncrypt 2871 The data that must be encrypted. 2872 encryptedData 2873 The encrypted data upon successful completion. 2874 privParameters 2875 The privParameters encoded as an OCTET STRING. 2877 8.2.4.2. Services for Decrypting Incoming Data 2879 This DES privacy protocol assumes that the selection of the 2880 privKey is done by the caller and that the caller passes 2881 the secret key to be used. 2883 Upon completion the privacy module returns statusInformation 2884 and, if the decryption process was successful, the scopedPDU 2885 in plain text. The abstract service primitive is: 2887 statusInformation = 2888 decryptData( 2889 IN decryptKey -- secret key for decryption 2890 IN privParameters -- as received on the wire 2891 IN encryptedData -- encrypted data (encryptedPDU) 2892 OUT decryptedData -- decrypted data (scopedPDU) 2893 ) 2895 The abstract data elements are: 2897 statusInformation 2898 An indication whether the data was successfully decrypted 2899 and if not an indication of the error. 2900 decryptKey 2901 The secret key to be used by the decryption algorithm. 2902 The length of this key MUST be 16 octets. 2903 privParameters 2904 The "salt" to be used to calculate the IV. 2905 encryptedData 2906 The data to be decrypted. 2907 decryptedData 2908 The decrypted data. 2910 8.3. Elements of Procedure. 2912 This section describes the procedures for the DES privacy protocol. 2914 8.3.1. Processing an Outgoing Message 2916 This section describes the procedure followed by an SNMP engine 2917 whenever it must encrypt part of an outgoing message using the 2918 usmDESPrivProtocol. 2920 1) The secret cryptKey is used to construct the DES encryption key, 2921 the "salt" and the DES pre-IV (as described in section 8.1.1.1). 2923 2) The privParameters field is set to the serialization according 2924 to the rules in [RFC1906] of an OCTET STRING representing the 2925 the "salt" string. 2927 3) The scopedPDU is encrypted (as described in section 8.1.1.2) 2928 and the encrypted data is serialized according to the rules 2929 in [RFC1906] as an OCTET STRING. 2931 4) The serialized OCTET STRING representing the encrypted 2932 scopedPDU together with the privParameters and statusInformation 2933 indicating success is returned to the calling module. 2935 8.3.2. Processing an Incoming Message 2937 This section describes the procedure followed by an SNMP engine 2938 whenever it must decrypt part of an incoming message using the 2939 usmDESPrivProtocol. 2941 1) If the privParameters field is not an 8-octet OCTET STRING, 2942 then an error indication (decryptionError) is returned to 2943 the calling module. 2945 2) The "salt" is extracted from the privParameters field. 2947 3) The secret cryptKey and the "salt" are then used to construct the 2948 DES decryption key and pre-IV (as described in section 8.1.1.1). 2950 4) The encryptedPDU is then decrypted (as described in 2951 section 8.1.1.3). 2953 5) If the encryptedPDU cannot be decrypted, then an error 2954 indication (decryptionError) is returned to the calling module. 2956 6) The decrypted scopedPDU and statusInformation indicating 2957 success are returned to the calling module. 2959 9. Intellectual Property 2961 The IETF takes no position regarding the validity or scope of any 2962 intellectual property or other rights that might be claimed to 2963 pertain to the implementation or use of the technology described in 2964 this document or the extent to which any license under such rights 2965 might or might not be available; neither does it represent that it 2966 has made any effort to identify any such rights. Information on the 2967 IETF's procedures with respect to rights in standards-track and 2968 standards-related documentation can be found in BCP-11. Copies of 2969 claims of rights made available for publication and any assurances of 2970 licenses to be made available, or the result of an attempt made to 2971 obtain a general license or permission for the use of such 2972 proprietary rights by implementors or users of this specification can 2973 be obtained from the IETF Secretariat. 2975 The IETF invites any interested party to bring to its attention any 2976 copyrights, patents or patent applications, or other proprietary 2977 rights which may cover technology that may be required to practice 2978 this standard. Please address the information to the IETF Executive 2979 Director. 2981 10. Acknowledgements 2983 This document is the result of the efforts of the SNMPv3 Working Group. 2984 Some special thanks are in order to the following SNMPv3 WG members: 2986 Dave Battle (SNMP Research, Inc.) 2987 Uri Blumenthal (IBM T.J. Watson Research Center) 2988 Jeff Case (SNMP Research, Inc.) 2989 John Curran (BBN) 2990 T. Max Devlin (Hi-TECH Connections) 2991 John Flick (Hewlett Packard) 2992 David Harrington (Cabletron Systems Inc.) 2993 N.C. Hien (IBM T.J. Watson Research Center) 2994 Dave Levi (SNMP Research, Inc.) 2995 Louis A Mamakos (UUNET Technologies Inc.) 2996 Paul Meyer (Secure Computing Corporation) 2997 Keith McCloghrie (Cisco Systems) 2998 Russ Mundy (Trusted Information Systems, Inc.) 2999 Bob Natale (ACE*COMM Corporation) 3000 Mike O'Dell (UUNET Technologies Inc.) 3001 Dave Perkins (DeskTalk) 3002 Peter Polkinghorne (Brunel University) 3003 Randy Presuhn (BMC Software, Inc.) 3004 David Reid (SNMP Research, Inc.) 3005 Shawn Routhier (Epilogue) 3006 Juergen Schoenwaelder (TU Braunschweig) 3007 Bob Stewart (Cisco Systems) 3008 Bert Wijnen (IBM T.J. Watson Research Center) 3010 The document is based on recommendations of the IETF Security and 3011 Administrative Framework Evolution for SNMP Advisory Team. 3012 Members of that Advisory Team were: 3014 David Harrington (Cabletron Systems Inc.) 3015 Jeff Johnson (Cisco Systems) 3016 David Levi (SNMP Research Inc.) 3017 John Linn (Openvision) 3018 Russ Mundy (Trusted Information Systems) chair 3019 Shawn Routhier (Epilogue) 3020 Glenn Waters (Nortel) 3021 Bert Wijnen (IBM T. J. Watson Research Center) 3023 As recommended by the Advisory Team and the SNMPv3 Working Group 3024 Charter, the design incorporates as much as practical from previous 3025 RFCs and drafts. As a result, special thanks are due to the authors 3026 of previous designs known as SNMPv2u and SNMPv2*: 3028 Jeff Case (SNMP Research, Inc.) 3029 David Harrington (Cabletron Systems Inc.) 3030 David Levi (SNMP Research, Inc.) 3031 Keith McCloghrie (Cisco Systems) 3032 Brian O'Keefe (Hewlett Packard) 3033 Marshall T. Rose (Dover Beach Consulting) 3034 Jon Saperia (BGS Systems Inc.) 3035 Steve Waldbusser (International Network Services) 3036 Glenn W. Waters (Bell-Northern Research Ltd.) 3038 11. Security Considerations 3040 11.1. Recommended Practices 3042 This section describes practices that contribute to the secure, 3043 effective operation of the mechanisms defined in this memo. 3045 - An SNMP engine must discard SNMP Response messages that do not 3046 correspond to any currently outstanding Request message. It is 3047 the responsibility of the Message Processing module to take care 3048 of this. For example it can use a msgID for that. 3050 An SNMP Command Generator Application must discard any Response 3051 PDU for which there is no currently outstanding Request PDU; 3052 for example for SNMPv2 [RFC1905] PDUs, the request-id component 3053 in the PDU can be used to correlate Responses to outstanding 3054 Requests. 3056 Although it would be typical for an SNMP engine and an SNMP 3057 Command Generator Application to do this as a matter of course, 3058 when using these security protocols it is significant due to 3059 the possibility of message duplication (malicious or otherwise). 3061 - If an SNMP engine uses a msgID for correlating Response messages 3062 to outstanding Request messages, then it MUST use different 3063 msgIDs in all such Request messages that it sends out during a 3064 Time Window (150 seconds) period. 3066 A Command Generator or Notification Originator Application MUST 3067 use different request-ids in all Request PDUs that it sends out 3068 during a TimeWindow (150 seconds) period. 3070 This must be done to protect against the possibility of message 3071 duplication (malicious or otherwise). 3073 For example, starting operations with a msgID and/or request-id 3074 value of zero is not a good idea. Initializing them with an 3075 unpredictable number (so they do not start out the same after 3076 each reboot) and then incrementing by one would be acceptable. 3078 - An SNMP engine should perform time synchronization using 3079 authenticated messages in order to protect against the 3080 possibility of message duplication (malicious or otherwise). 3082 - When sending state altering messages to a managed authoritative 3083 SNMP engine, a Command Generator Application should delay sending 3084 successive messages to that managed SNMP engine until a positive 3085 acknowledgement is received for the previous message or until 3086 the previous message expires. 3088 No message ordering is imposed by the SNMP. Messages may be 3089 received in any order relative to their time of generation and 3090 each will be processed in the ordered received. Note that when 3091 an authenticated message is sent to a managed SNMP engine, it 3092 will be valid for a period of time of approximately 150 seconds 3093 under normal circumstances, and is subject to replay during this 3094 period. Indeed, an SNMP engine and SNMP Command Generator 3095 Applications must cope with the loss and re-ordering of messages 3096 resulting from anomalies in the network as a matter of course. 3098 However, a managed object, snmpSetSerialNo [RFC1907], is 3099 specifically defined for use with SNMP Set operations in order 3100 to provide a mechanism to ensure that the processing of SNMP 3101 messages occurs in a specific order. 3103 - The frequency with which the secrets of a User-based Security 3104 Model user should be changed is indirectly related to the 3105 frequency of their use. 3107 Protecting the secrets from disclosure is critical to the overall 3108 security of the protocols. Frequent use of a secret provides a 3109 continued source of data that may be useful to a cryptanalyst in 3110 exploiting known or perceived weaknesses in an algorithm. 3111 Frequent changes to the secret avoid this vulnerability. 3113 Changing a secret after each use is generally regarded as the 3114 most secure practice, but a significant amount of overhead may 3115 be associated with that approach. 3117 Note, too, in a local environment the threat of disclosure may be 3118 less significant, and as such the changing of secrets may be less 3119 frequent. However, when public data networks are used as the 3120 communication paths, more caution is prudent. 3122 11.2 Defining Users 3124 The mechanisms defined in this document employ the notion of users 3125 on whose behalf messages are sent. How "users" are defined is 3126 subject to the security policy of the network administration. 3127 For example, users could be individuals (e.g., "joe" or "jane"), 3128 or a particular role (e.g., "operator" or "administrator"), or a 3129 combination (e.g., "joe-operator", "jane-operator" or "joe-admin"). 3130 Furthermore, a user may be a logical entity, such as an SNMP 3131 Application or a set of SNMP Applications, acting on behalf of an 3132 individual or role, or set of individuals, or set of roles, 3133 including combinations. 3135 Appendix A describes an algorithm for mapping a user "password" to 3136 a 16 octet value for use as either a user's authentication key or 3137 privacy key (or both). Note however, that using the same password 3138 (and therefore the same key) for both authentication and privacy 3139 is very poor security practice and should be strongly discouraged. 3140 Passwords are often generated, remembered, and input by a human. 3141 Human-generated passwords may be less than the 16 octets required 3142 by the authentication and privacy protocols, and brute force 3143 attacks can be quite easy on a relatively short ASCII character 3144 set. Therefore, the algorithm is Appendix A performs a 3145 transformation on the password. If the Appendix A algorithm is 3146 used, SNMP implementations (and SNMP configuration applications) 3147 must ensure that passwords are at least 8 characters in length. 3149 Because the Appendix A algorithm uses such passwords (nearly) 3150 directly, it is very important that they not be easily guessed. 3151 It is suggested that they be composed of mixed-case alphanumeric 3152 and punctuation characters that don't form words or phrases that 3153 might be found in a dictionary. Longer passwords improve the 3154 security of the system. Users may wish to input multiword 3155 phrases to make their password string longer while ensuring that 3156 it is memorable. 3158 Since it is infeasible for human users to maintain different 3159 passwords for every SNMP engine, but security requirements 3160 strongly discourage having the same key for more than one SNMP 3161 engine, the User-based Security Model employs a compromise 3162 proposed in [Localized-key]. It derives the user keys for the 3163 SNMP engines from user's password in such a way that it is 3164 practically impossible to either determine the user's password, 3165 or user's key for another SNMP engine from any combination of 3166 user's keys on SNMP engines. 3168 Note however, that if user's password is disclosed, then key 3169 localization will not help and network security may be compromised 3170 in this case. Therefore a user's password or non-localized key 3171 MUST NOT be stored on a managed device/node. Instead the 3172 localized key SHALL be stored (if at all) , so that, in case a 3173 device does get compromised, no other managed or managing devices 3174 get compromised. 3176 11.3. Conformance 3178 To be termed a "Secure SNMP implementation" based on the 3179 User-based Security Model, an SNMP implementation MUST: 3181 - implement one or more Authentication Protocol(s). The HMAC-MD5-96 3182 and HMAC-SHA-96 Authentication Protocols defined in this memo are 3183 examples of such protocols. 3185 - to the maximum extent possible, prohibit access to the secret(s) 3186 of each user about which it maintains information in a Local 3187 Configuration Datastore (LCD) under all circumstances except as 3188 required to generate and/or validate SNMP messages with respect 3189 to that user. 3191 - implement the key-localization mechanism. 3193 - implement the SNMP-USER-BASED-SM-MIB. 3195 In addition, an authoritative SNMP engine SHOULD provide initial 3196 configuration in accordance with Appendix A.1. 3198 Implementation of a Privacy Protocol (the DES Symmetric Encryption 3199 Protocol defined in this memo is one such protocol) is optional. 3201 12. References 3203 [RFC1903] The SNMPv2 Working Group, Case, J., McCloghrie, K., Rose, M., 3204 and S. Waldbusser, "Textual Conventions for Version 2 of the Simple 3205 Network Management Protocol (SNMPv2)", RFC 1903, January 1996. 3207 [RFC1905] The SNMPv2 Working Group, Case, J., McCloghrie, K., 3208 Rose, M., and S., Waldbusser, "Protocol Operations for 3209 Version 2 of the Simple Network Management Protocol (SNMPv2)", 3210 RFC 1905, January 1996. 3212 [RFC1906] The SNMPv2 Working Group, Case, J., McCloghrie, K., 3213 Rose, M., and S. Waldbusser, "Transport Mappings for 3214 Version 2 of the Simple Network Management Protocol (SNMPv2)", 3215 RFC 1906, January 1996. 3217 [RFC1907] The SNMPv2 Working Group, Case, J., McCloghrie, K., 3218 Rose, M., and S. Waldbusser, "Management Information Base for 3219 Version 2 of the Simple Network Management Protocol (SNMPv2)", 3220 RFC 1907 January 1996. 3222 [RFC2104] Network Working Group, H. Krawczyk, M. Bellare, R. Canetti, 3223 "HMAC: Keyed-Hashing for Message Authentication", RFC 2104, 3224 February 1997. 3226 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 3227 Requirement Levels", BCP 14, RFC 2119, March 1997. 3229 [BCP-11] Hovey, R., and S. Bradner, "The Organizations Involved in 3230 the IETF Standards Process", BCP 11, RFC 2028, October 1996. 3232 [SNMP-ARCH] The SNMPv3 Working Group, Harrington, D., Wijnen, B., 3233 Presuhn, R., "An Architecture for describing SNMP Management 3234 Frameworks", draft-ietf-snmpv3-next-gen-arch-07.txt, 3235 November 1997. 3237 [Localized-Key] U. Blumenthal, N. C. Hien, B. Wijnen 3238 "Key Derivation for Network Management Applications" 3239 IEEE Network Magazine, April/May issue, 1997. 3241 [MD5] Rivest, R., "Message Digest Algorithm MD5", 3242 RFC 1321, April 1992. 3244 [DES-NIST] Data Encryption Standard, National Institute of Standards 3245 and Technology. Federal Information Processing Standard (FIPS) 3246 Publication 46-1. Supersedes FIPS Publication 46, (January, 1977; 3247 reaffirmed January, 1988). 3249 [DES-ANSI] Data Encryption Algorithm, American National Standards 3250 Institute. ANSI X3.92-1981, (December, 1980). 3252 [DESO-NIST] DES Modes of Operation, National Institute of Standards and 3253 Technology. Federal Information Processing Standard (FIPS) 3254 Publication 81, (December, 1980). 3256 [DESO-ANSI] Data Encryption Algorithm - Modes of Operation, American 3257 National Standards Institute. ANSI X3.106-1983, (May 1983). 3259 [DESG-NIST] Guidelines for Implementing and Using the NBS Data 3260 Encryption Standard, National Institute of Standards and 3261 Technology. Federal Information Processing Standard (FIPS) 3262 Publication 74, (April, 1981). 3264 [DEST-NIST] Validating the Correctness of Hardware Implementations of 3265 the NBS Data Encryption Standard, National Institute of Standards 3266 and Technology. Special Publication 500-20. 3268 [DESM-NIST] Maintenance Testing for the Data Encryption Standard, 3269 National Institute of Standards and Technology. 3270 Special Publication 500-61, (August, 1980). 3272 [SHA-NIST] Secure Hash Algorithm. NIST FIPS 180-1, (April, 1995) 3273 http://csrc.nist.gov/fips/fip180-1.txt (ASCII) 3274 http://csrc.nist.gov/fips/fip180-1.ps (Postscript) 3276 13. Editors' Addresses 3278 Co-editor Uri Blumenthal 3279 IBM T. J. Watson Research 3280 postal: 30 Saw Mill River Pkwy, 3281 Hawthorne, NY 10532 3282 USA 3283 email: uri@watson.ibm.com 3284 phone: +1-914-784-7064 3286 Co-editor: Bert Wijnen 3287 IBM T. J. Watson Research 3288 postal: Schagen 33 3289 3461 GL Linschoten 3290 Netherlands 3291 email: wijnen@vnet.ibm.com 3292 phone: +31-348-432-794 3294 APPENDIX A - Installation 3296 A.1. SNMP engine Installation Parameters 3298 During installation, an authoritative SNMP engine SHOULD (in the 3299 meaning as defined in [RFC2119]) be configured with several initial 3300 parameters. These include: 3302 1) A security posture 3304 The choice of security posture determines if initial configuration 3305 is implemented and if so how. One of three possible choices 3306 is selected: 3308 minimum-secure, 3309 semi-secure, 3310 very-secure (i.e., no-initial-configuration) 3312 In the case of a very-secure posture, there is no initial 3313 configuration, and so the following steps are irrelevant. 3315 2) one or more secrets 3317 These are the authentication/privacy secrets for the first user 3318 to be configured. 3320 One way to accomplish this is to have the installer enter a 3321 "password" for each required secret. The password is then 3322 algorithmically converted into the required secret by: 3324 - forming a string of length 1,048,576 octets by repeating the 3325 value of the password as often as necessary, truncating 3326 accordingly, and using the resulting string as the input to 3327 the MD5 algorithm [MD5]. The resulting digest, termed 3328 "digest1", is used in the next step. 3330 - a second string is formed by concatenating digest1, the SNMP 3331 engine's snmpEngineID value, and digest1. 3332 This string is used as input to the MD5 algorithm [MD5]. 3334 The resulting digest is the required secret (see Appendix A.2). 3336 With these configured parameters, the SNMP engine instantiates 3337 the following usmUserEntry in the usmUserTable: 3339 no privacy support privacy support 3340 ------------------ --------------- 3341 usmUserEngineID localEngineID localEngineID 3342 usmUserName "initial" "initial" 3343 usmUserSecurityName "initial" "initial" 3344 usmUserCloneFrom ZeroDotZero ZeroDotZero 3345 usmUserAuthProtocol usmHMACMD5AuthProtocol usmHMACMD5AuthProtocol 3346 usmUserAuthKeyChange "" "" 3347 usmUserOwnAuthKeyChange "" "" 3348 usmUserPrivProtocol none usmDESPrivProtocol 3349 usmUserPrivKeyChange "" "" 3350 usmUserOwnPrivKeyChange "" "" 3351 usmUserPublic "" "" 3352 usmUserStorageType anyValidStorageType anyValidStorageType 3353 usmUserStatus active active 3355 A.2. Password to Key Algorithm 3357 A sample code fragment (section A.2.1) demonstrates the password to 3358 key algorithm which can be used when mapping a password to an 3359 authentication or privacy key using MD5. The reference source code 3360 of MD5 is available in [RFC1321]. 3362 Another sample code fragment (section A.2.2) demonstrates the 3363 password to key algorithm which can be used when mapping a password 3364 to an authentication or privacy key using SHA (documented in 3365 SHA-NIST). 3367 An example of the results of a correct implementation is provided 3368 (section A.3) which an implementor can use to check if his 3369 implementation produces the same result. 3371 A.2.1. Password to Key Sample Code for MD5 3373 void password_to_key_md5( 3374 u_char *password, /* IN */ 3375 u_int passwordlen, /* IN */ 3376 u_char *engineID, /* IN - pointer to snmpEngineID */ 3377 u_int engineLength /* IN - length of snmpEngineID */ 3378 u_char *key) /* OUT - pointer to caller 16-octet buffer */ 3379 { 3380 MD5_CTX MD; 3381 u_char *cp, password_buf[64]; 3382 u_long password_index = 0; 3383 u_long count = 0, i; 3385 MD5Init (&MD); /* initialize MD5 */ 3387 /**********************************************/ 3388 /* Use while loop until we've done 1 Megabyte */ 3389 /**********************************************/ 3390 while (count < 1048576) { 3391 cp = password_buf; 3392 for (i = 0; i < 64; i++) { 3393 /*************************************************/ 3394 /* Take the next octet of the password, wrapping */ 3395 /* to the beginning of the password as necessary.*/ 3396 /*************************************************/ 3397 *cp++ = password[password_index++ % passwordlen]; 3398 } 3399 MD5Update (&MD, password_buf, 64); 3400 count += 64; 3401 } 3402 MD5Final (key, &MD); /* tell MD5 we're done */ 3404 /*****************************************************/ 3405 /* Now localize the key with the engineID and pass */ 3406 /* through MD5 to produce final key */ 3407 /* May want to ensure that engineLength <= 32, */ 3408 /* otherwise need to use a buffer larger than 64 */ 3409 /*****************************************************/ 3410 memcpy(password_buf, key, 16); 3411 memcpy(password_buf+16, engineID, engineLength); 3412 memcpy(password_buf+engineLength, key, 16); 3414 MD5Init(&MD); 3415 MD5Update(&MD, password_buf, 32+engineLength); 3416 MD5Final(key, &MD); 3418 return; 3419 } 3420 A.2.2. Password to Key Sample Code for SHA 3422 void password_to_key_sha( 3423 u_char *password, /* IN */ 3424 u_int passwordlen, /* IN */ 3425 u_char *engineID, /* IN - pointer to snmpEngineID */ 3426 u_int engineLength /* IN - length of snmpEngineID */ 3427 u_char *key) /* OUT - pointer to caller 20-octet buffer */ 3428 { 3429 SHA_CTX SH; 3430 u_char *cp, password_buf[72]; 3431 u_long password_index = 0; 3432 u_long count = 0, i; 3434 SHAInit (&SH); /* initialize SHA */ 3436 /**********************************************/ 3437 /* Use while loop until we've done 1 Megabyte */ 3438 /**********************************************/ 3439 while (count < 1048576) { 3440 cp = password_buf; 3441 for (i = 0; i < 64; i++) { 3442 /*************************************************/ 3443 /* Take the next octet of the password, wrapping */ 3444 /* to the beginning of the password as necessary.*/ 3445 /*************************************************/ 3446 *cp++ = password[password_index++ % passwordlen]; 3447 } 3448 SHAUpdate (&SH, password_buf, 64); 3449 count += 64; 3450 } 3451 SHAFinal (key, &SH); /* tell SHA we're done */ 3453 /*****************************************************/ 3454 /* Now localize the key with the engineID and pass */ 3455 /* through SHA to produce final key */ 3456 /* May want to ensure that engineLength <= 32, */ 3457 /* otherwise need to use a buffer larger than 72 */ 3458 /*****************************************************/ 3459 memcpy(password_buf, key, 20); 3460 memcpy(password_buf+20, engineID, engineLength); 3461 memcpy(password_buf+engineLength, key, 20); 3463 SHAInit(&SH); 3464 SHAUpdate(&SH, password_buf, 40+engineLength); 3465 SHAFinal(key, &SH); 3467 return; 3468 } 3469 A.3. Password to Key Sample Results 3471 A.3.1. Password to Key Sample Results using MD5 3473 The following shows a sample output of the password to key 3474 algorithm for a 16-octet key using MD5. 3476 With a password of "maplesyrup" the output of the password to key 3477 algorithm before the key is localized with the SNMP engine's 3478 snmpEngineID is: 3480 '9f af 32 83 88 4e 92 83 4e bc 98 47 d8 ed d9 63'H 3482 After the intermediate key (shown above) is localized with the 3483 snmpEngineID value of: 3485 '00 00 00 00 00 00 00 00 00 00 00 02'H 3487 the final output of the password to key algorithm is: 3489 '52 6f 5e ed 9f cc e2 6f 89 64 c2 93 07 87 d8 2b'H 3491 A.3.2. Password to Key Sample Results using SHA 3493 The following shows a sample output of the password to key 3494 algorithm for a 20-octet key using SHA. 3496 With a password of "maplesyrup" the output of the password to key 3497 algorithm before the key is localized with the SNMP engine's 3498 snmpEngineID is: 3500 'f1 be a9 ae 66 7f 4f b6 34 1e 51 af 06 80 7e 91 e4 3b 01 ac'H 3502 After the intermediate key (shown above) is localized with the 3503 snmpEngineID value of: 3505 '00 00 00 00 00 00 00 00 00 00 00 02'H 3507 the final output of the password to key algorithm is: 3509 '8a a3 d9 9e 3e 30 56 f2 bf e3 a9 ee f3 45 d5 39 54 91 12 be'H 3511 A.4. Sample encoding of msgSecurityParameters 3513 The msgSecurityParameters in an SNMP message are represented as 3514 an OCTET STRING. This OCTET STRING should be considered opaque 3515 outside a specific Security Model. 3517 The User-based Security Model defines the contents of the OCTET 3518 STRING as a SEQUENCE (see section 2.4). 3520 Given these two properties, the following is an example of the 3521 msgSecurityParameters for the User-based Security Model, encoded 3522 as an OCTET STRING: 3524 04 3525 30 3526 04 3527 02 3528 02 3529 04 3530 04 0c 3531 04 08 3533 Here is the example once more, but now with real values (except 3534 for the digest in msgAuthenticationParameters and the salt in 3535 msgPrivacyParameters, which depend on variable data that we have 3536 not defined here): 3538 Hex Data Description 3539 -------------- ----------------------------------------------- 3540 04 39 OCTET STRING, length 57 3541 30 37 SEQUENCE, length 55 3542 04 0c 80000002 msgAuthoritativeEngineID: IBM 3543 01 IPv4 address 3544 09840301 9.132.3.1 3545 02 01 01 msgAuthoritativeEngineBoots: 1 3546 02 02 0101 msgAuthoritativeEngineTime: 257 3547 04 04 62657274 msgUserName: bert 3548 04 0c 01234567 msgAuthenticationParameters: sample value 3549 89abcdef 3550 fedcba98 3551 04 08 01234567 msgPrivacyParameters: sample value 3552 89abcdef 3554 B. Full Copyright Statement 3556 Copyright (C) The Internet Society (1997). All Rights Reserved. 3558 This document and translations of it may be copied and furnished to 3559 others, and derivative works that comment on or otherwise explain it 3560 or assist in its implementation may be prepared, copied, published 3561 and distributed, in whole or in part, without restriction of any 3562 kind, provided that the above copyright notice and this paragraph 3563 are included on all such copies and derivative works. However, this 3564 document itself may not be modified in any way, such as by removing 3565 the copyright notice or references to the Internet Society or other 3566 Internet organizations, except as needed for the purpose of 3567 developing Internet standards in which case the procedures for 3568 copyrights defined in the Internet Standards process must be 3569 followed, or as required to translate it into languages other than 3570 English. 3572 The limited permissions granted above are perpetual and will not be 3573 revoked by the Internet Society or its successors or assigns. 3575 This document and the information contained herein is provided on an 3576 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING 3577 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 3578 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION 3579 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF 3580 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.