idnits 2.17.1 draft-ietf-snmpv3-usm-03.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Cannot find the required boilerplate sections (Copyright, IPR, etc.) in this document. Found some kind of copyright notice around line 31 but it does not match any copyright boilerplate known by this tool. Expected boilerplate is as follows today (2024-04-19) according to https://trustee.ietf.org/license-info : IETF Trust Legal Provisions of 28-dec-2009, Section 6.a: This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 2: Copyright (c) 2024 IETF Trust and the persons identified as the document authors. All rights reserved. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 3: This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** Missing expiration date. The document expiration date should appear on the first and last page. ** The document seems to lack a 1id_guidelines paragraph about Internet-Drafts being working documents. ** The document seems to lack a 1id_guidelines paragraph about 6 months document validity -- however, there's a paragraph with a matching beginning. Boilerplate error? ** The document seems to lack a 1id_guidelines paragraph about the list of current Internet-Drafts. ** The document seems to lack a 1id_guidelines paragraph about the list of Shadow Directories. == 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 59 lines Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an Abstract section. ** 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.) ** There are 870 instances of too long lines in the document, the longest one being 12 characters in excess of 72. == There are 1 instance of lines with non-RFC6890-compliant IPv4 addresses in the document. If these are example addresses, they should be changed. ** The document seems to lack a both a reference to RFC 2119 and the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords -- however, there's a paragraph with a matching beginning. Boilerplate error? RFC 2119 keyword, line 179: '... MUST do explicit time synchron...' RFC 2119 keyword, line 207: '...n-localized keys SHOULD NOT be stored ...' RFC 2119 keyword, line 218: '...explain usage of SHOULD, MUST and such...' RFC 2119 keyword, line 221: '... for MD5 and DES MUST be 16 octets lon...' RFC 2119 keyword, line 222: '... SHA they MUST be 20 octets long...' (25 more instances...) Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the RFC 3978 Section 5.4 Copyright Line does not match the current year == Line 3581 has weird spacing: '...ageType any...' == Line 3604 has weird spacing: '... u_int pass...' == Line 3606 has weird spacing: '... u_int engi...' == Line 3653 has weird spacing: '... u_int pass...' == Line 3655 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.) -- Couldn't find a document date in the document -- date freshness check skipped. -- 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 section? 'SNMP-ARCH' on line 3456 looks like a reference -- Missing reference section? 'RFC2104' on line 3446 looks like a reference -- Missing reference section? 'SNMP-USM' on line 3461 looks like a reference -- Missing reference section? 'RFC2119' on line 3528 looks like a reference -- Missing reference section? 'RFC1907' on line 3441 looks like a reference -- Missing reference section? 'SNMP-MP' on line 999 looks like a reference -- Missing reference section? 'Localized-key' on line 3386 looks like a reference -- Missing reference section? 'RFC1906' on line 3436 looks like a reference -- Missing reference section? 'RFC1903' on line 3427 looks like a reference -- Missing reference section? 'MD5' on line 3561 looks like a reference -- Missing reference section? 'SHA-NIST' on line 3501 looks like a reference -- Missing reference section? 'DES-NIST' on line 3473 looks like a reference -- Missing reference section? 'DES-ANSI' on line 3478 looks like a reference -- Missing reference section? 'DESO-NIST' on line 3481 looks like a reference -- Missing reference section? 'DESO-ANSI' on line 3485 looks like a reference -- Missing reference section? 'DESG-NIST' on line 3488 looks like a reference -- Missing reference section? 'DEST-NIST' on line 3493 looks like a reference -- Missing reference section? 'DESM-NIST' on line 3497 looks like a reference -- Missing reference section? 'RFC1905' on line 3431 looks like a reference -- Missing reference section? 'BCP-11' on line 3453 looks like a reference -- Missing reference section? 'Localized-Key' on line 3466 looks like a reference -- Missing reference section? 'RFC1321' on line 3589 looks like a reference -- Missing reference section? '64' on line 3610 looks like a reference -- Missing reference section? '72' on line 3659 looks like a reference Summary: 10 errors (**), 0 flaws (~~), 9 warnings (==), 27 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 INTERNET-DRAFT U. Blumenthal 5 3 IBM T. J. Watson Research 5 4 B. Wijnen 5 5 IBM T. J. Watson Research 5 6 28 October 1997 5 8 User-based Security Model (USM) for version 3 of the 9 Simple Network Management Protocol (SNMPv3) 10 5 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 5 30 5 31 Copyright (C) The Internet Society (1997). All Rights Reserved. 5 32 5 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 April 1998 [Page 1] 42 Table of Contents 44 0. Issues and Change Log 4 45 0.1. Resolved Issues 4 46 0.2. Change Log 5 47 1. Introduction 9 48 1.1. Threats 9 49 1.2. Goals and Constraints 11 50 1.3. Security Services 11 51 1.4. Module Organization 12 52 1.4.1. Timeliness Module 13 53 1.4.2. Authentication Protocol 13 54 1.4.3. Privacy Protocol 13 55 1.5. Protection against Message Replay, Delay and Redirection 13 56 1.5.1. Authoritative SNMP engine 13 57 1.5.2. Mechanisms 14 58 1.6. Abstract Service Interfaces. 15 59 1.6.1. User-based Security Model Primitives for Authentication 16 60 1.6.2. User-based Security Model Primitives for Privacy 16 61 2. Elements of the Model 18 62 2.1. User-based Security Model Users 18 63 2.2. Replay Protection 19 64 2.2.1. msgAuthoritativeEngineID 19 65 2.2.2. msgAuthoritativeEngineBoots and msgAuthoritativeEngineTime 19 66 2.2.3. Time Window 20 67 2.3. Time Synchronization 21 68 2.4. SNMP Messages Using this Security Model 22 69 2.5. Services provided by the User-based Security Model 23 70 2.5.1. Services for Generating an Outgoing SNMP Message 23 71 2.5.2. Services for Processing an Incoming SNMP Message 25 72 2.6. Key Localization Algorithm. 26 73 3. Elements of Procedure 28 74 3.1. Generating an Outgoing SNMP Message 28 75 3.2. Processing an Incoming SNMP Message 31 76 4. Discovery 37 77 5. Definitions 38 78 6. HMAC-MD5-96 Authentication Protocol 51 79 6.1. Mechanisms 51 80 6.1.1. Digest Authentication Mechanism 51 81 6.2. Elements of the Digest Authentication Protocol 52 82 6.2.1. Users 52 83 6.2.2. msgAuthoritativeEngineID 52 84 6.2.3. SNMP Messages Using this Authentication Protocol 52 85 6.2.4. Services provided by the HMAC-MD5-96 Authentication Module 53 86 6.2.4.1. Services for Generating an Outgoing SNMP Message 53 87 6.2.4.2. Services for Processing an Incoming SNMP Message 53 88 6.3. Elements of Procedure 54 89 6.3.1. Processing an Outgoing Message 54 90 6.3.2. Processing an Incoming Message 55 91 7. HMAC-SHA-96 Authentication Protocol 57 92 7.1. Mechanisms 57 94 SNMPv3 Working Group Expires April 1998 [Page 2] 95 7.1.1. Digest Authentication Mechanism 57 96 7.2. Elements of the HMAC-SHA-96 Authentication Protocol 58 97 7.2.1. Users 58 98 7.2.2. msgAuthoritativeEngineID 58 99 7.2.3. SNMP Messages Using this Authentication Protocol 58 100 7.2.4. Services provided by the HMAC-SHA-96 Authentication Module 59 101 7.2.4.1. Services for Generating an Outgoing SNMP Message 59 102 7.2.4.2. Services for Processing an Incoming SNMP Message 59 103 7.3. Elements of Procedure 60 104 7.3.1. Processing an Outgoing Message 60 105 7.3.2. Processing an Incoming Message 61 106 8. CBC-DES Symmetric Encryption Protocol 63 107 8.1. Mechanisms 63 108 8.1.1. Symmetric Encryption Protocol 63 109 8.1.1.1. DES key and Initialization Vector. 64 110 8.1.1.2. Data Encryption. 64 111 8.1.1.3. Data Decryption 65 112 8.2. Elements of the DES Privacy Protocol 65 113 8.2.1. Users 65 114 8.2.2. msgAuthoritativeEngineID 65 115 8.2.3. SNMP Messages Using this Privacy Protocol 66 116 8.2.4. Services provided by the DES Privacy Module 66 117 8.2.4.1. Services for Encrypting Outgoing Data 66 118 8.2.4.2. Services for Decrypting Incoming Data 67 119 8.3. Elements of Procedure. 67 120 8.3.1. Processing an Outgoing Message 67 121 8.3.2. Processing an Incoming Message 68 122 9. Intellectual Property 69 123 A.1. SNMP engine Installation Parameters 76 124 A.2. Password to Key Algorithm 77 125 A.2.1. Password to Key Sample Code for MD5 78 126 A.2.2. Password to Key Sample Code for SHA 79 127 A.3. Password to Key Sample Results 80 128 A.3.1. Password to Key Sample Results using MD5 80 129 A.3.2. Password to Key Sample Results using SHA 80 130 A.4. Sample encoding of msgSecurityParameters 81 131 B. Full Copyright Statement 81 133 SNMPv3 Working Group Expires April 1998 [Page 3] 134 0. Issues and Change Log 136 When we go to RFC status, we will remove all the text of section 0. 4 138 0.1. Resolved Issues 139 - Is it OK to use MD5 for KeyChange Algorithm ?? 140 We changed the TC so that we use the hash-function that | 141 the user's authentication protocol (usmUserAuthProtocol) | 142 is based on instead of fixing it to MD5 | 143 - Improve acknowledgements and sync it up with other documents 144 Resolved by Russ. 145 - Should the USM define checking such that a received Response 146 messages used the same or better securityLevel than the Request 147 message that this is a response to. 148 In section 3.1 step 9, we return a completed outgoing message 149 to the calling module (Message Processing). We believe it is 150 the Message Processing Subsystem that should cache information 151 about outgoing messages regarding msgID and such so that a 152 possible Response Message can be mapped to an outstanding 153 request. At the same time that piece of code can then ensure 154 that the same securityModel and the same (or better??) 155 securityLevel has been used for the Response Message. So in 156 step 9 we do not save any cachedSecurityData for outgoing 157 messages. 158 Resolution. Statements have been added to state that this is 159 the responsibility of the calling Message Processing Model. 160 The v3MP has been changed to indeed do the check. 161 - At an authoritative SNMP engine we must be able to determine 162 if the msgAuthoritativeEngineID value used for Requests is the 163 local snmpEngineID. However, to do so we'd have to peek into 164 either the message or into the PDU. That is not clean. 165 Resolution. The USM must pass the securityEngineID that was 166 used for security purposes (i.e., the value extracted from | 167 the msgAuthoritativeEngineID) so that the MP can check it 168 when it determines that it is a Request. The MP document has 169 been updated to make the check. 170 - An authenticated incoming message at a non-authoritative SNMP 171 engine always allowed the notion snmpEngineTime to be updated 172 (as long as it was not older than what we had). This allowed 173 intruders to slow down our notion of time dramatically. 174 Resolution. Check the value not only to be greater than 175 latestReceivedEngineTime but also against out notion of 176 time to ensure it is not older than 150 seconds. This will 177 have a side-effect in that if an authoritative engine ever 178 gets more than 150 seconds behind, then the authoritative end 179 MUST do explicit time synchronization. 180 - Should we use Integers or OIDs for identifying protocols 181 Resolution. Consensus is to use OID. 183 SNMPv3 Working Group Expires April 1998 [Page 4] 184 0.2. Change Log 186 [version 3.5] October 28 version: 5 187 - fix typo's as reported by John Flick. 5 188 - remove usmAdmin 5 189 - Adjusted layout per RFC 2223. 5 190 - Added copyright statements required by RFC 2026. 5 191 - post as I-D: 5 193 [version 3.4] September 30 version: 4 194 - these changes are marked with a revision-code "4" in right margin 4 195 - editorial changes based on mail exchanges between Bert/Uri 4 196 - Quick spell check. 4 197 - SMICng compile the USM MIB to verify correct syntax. 4 198 - paginate 4 199 - post as I-D: 4 200 4 201 [version 3.3] Internal version exchanged between editors: 3 202 - these changes are marked with a revision-code "3" in right margin 3 203 - Added section 2.6 to explain algorithm for generating localized 3 204 key and added the word 'localized' at various places. 3 205 - Added appendix A.1.2 to show example code for SHA localized key 3 206 - Changed text at the end of section 11.2 to state that passwords 3 207 and non-localized keys SHOULD NOT be stored on managed devices. 3 208 - changed usmSecurityParameters so that Boots/Time values are now 3 209 represented as INTEGERS. 3 210 3 211 [version 3.2] September 29 version: | 212 - these changes are marked with a revision-code "|" in right margin | 213 - fix ASN.1 definition of securityParameters | 214 - specify that wrongValue must be returned if a SET tries to set | 215 an unknown or unsupported Authentication or Privacy protocol | 216 - add summary of USM internal ASIs now that they were removed from | 217 the architecture document. This is section 1.6. | 218 - add text to section 1 to explain usage of SHOULD, MUST and such. | 219 - tried to be more consistent in use of the terms Protocol, | 220 Mechanism and Algorithm. | 221 - defined that keys for MD5 and DES MUST be 16 octets long and for | 222 SHA they MUST be 20 octets long | 223 - described that key must be extended to 64 octets before applying | 224 HMAC-MD5 or HMAC-SHA algorithms. | 225 - Fixed writeup on key use. We no longer insert/append key but | 226 instead prepend it to the message before calculating the digest. | 227 - tried to be more consistent and always use the term octet(s) | 228 instead of byte(s). | 229 - placed a comma after each i.e. | 230 - Adapt Appendix samples to match rest of document(s). | 231 - SMICng compile the USM MIB to verify correct syntax. | 232 - Quick spell check. | 233 | 234 [version 3.1] September 25 version: | 236 SNMPv3 Working Group Expires April 1998 [Page 5] 237 - these changes are marked with a revision-code "|" in right margin | 238 - msgAuthoritativeEngineTime is an Integer32, not an Unsigned32 | 239 - msgUserName can be up to 32 octets long | 240 - changing authentication algorithm from MD5 to HMAC-MD5-96 and | 241 HMAC-SHA-96 [RFC2104] | 242 - Delete un-referenced references | 243 - roll back time synchronization procedure | 244 - address comments from mailing list | 245 - added section 7 to describe HMAC-SHA-96 and renumbered sections | 246 8-11 as a result. | 248 [version 2.2] 249 - formatting 250 - pagination 252 [version 2.1] - August 1 version 253 - Changed max size for usmUserName from 16 to 32. 254 For SnmpAdminString 16 is rather short. 255 - incorporate comments by Uri. 256 - Update References 257 - Update acknowledgement section 258 - remove expectResponse parameter. It was a bad idea 259 - renamed snmpEngineID parameter to securityEngineID to 260 reduce confusion with other uses of term snmpEngineID 261 - added an OUT parameter securityEngineID to processIncomingMsg 262 primitive, so that MP can check if correct snmpEngineID was 263 used for Request messages. 264 - added some more considerations about redirected Traps. 265 - state that MP is responsible for matching a Response or Report 266 to an outstanding Request and discard it if none found. 267 - Discussion about msgID and request-id changed into an example, 268 because it is SNMPv3 MP specific and the MP MUST handle it. 269 - Spell check 270 - SMICng MIB check 271 - Paginate 272 - Post to I-D repository and SNMPv3 mailing list as: 273 275 [version 2.0] - July 28 version 276 - Address comments by Juergen 277 - fix typos and editorial changes 278 - Other changes 279 - adapt to new (synchronous) abstract service primitives 280 - adapt to new field names in the messages 281 - adapt to new parameter names for abstract data type 282 - Address Dave Perkins comments 283 - modify definition of usmSecurityParameters 284 - Address Dave Levi's issue on checking msgAuthoritativeEngineID 285 properly to local snmpEngineID for incoming Request Messages 286 - Address Uri issue about slow-down of non-authoritative 287 engine's notion of time at remote SNMP engine. 289 SNMPv3 Working Group Expires April 1998 [Page 6] 290 - Address Uri issue about redirection of (authenticated) Traps. 291 Describe it is not a problem because they come from the 292 authoritative SNMP engine. 293 - Address comments by Arnoud Zwemmer about the fact that only 294 Report PDUs can slow down timeliness notion 296 [version 1.8] 297 - Add reference to RFC2119 about use of SHOULD and MUST 298 - paginate and generate table of contents 299 - posted as I-D on 15 July 1997 301 [version 1.7] 302 - Changed the KeyChange description so it allows for other 303 hash algorithms instead of MD5. If in the future the MD5 gets 304 replaced by another Authentication -- algorithm, then it seems 305 we also need to use that new algorithm to -- calculate the 306 digest during KeyChange. 307 - Updated the password to key code fragment to cater for the 308 variable length of the snmpEngineID. 309 - Added issue on cacheing of data on outgoing messages and one 310 on required review of timeliness handling. 312 [version 1.4 - version 1.6] 313 - Editorial changes because of internal review by authors 314 - Adapt to latest list of Primitive names and parameters 315 - Change USEC to USM 316 - Changes based on comments from Jeff Case. 317 - Checked MIB with SMICng 319 [version 1.3] 320 - Too many changes have taken place, so marking it was skipped 321 The most important changes are listed here. 322 However, changes that just split text on different lines 323 and changes like different capitalization of words/terms 324 has not been listed. Also changes to fit new terms and such 325 have not been listed. 326 - Split/Join some lines to ensure we stay within 72 columns 327 as required by RFC guidelines. 328 - Addressed Dave Perkins comments: 329 1) Section 1.3, last paragraph's, timeliness was left off. -done 330 2) Section 1.5.1, the operations need to be made general, since 331 additional one may be added later. - done 332 3) Section 1.5.2, the field "request-id" is used throughout 333 this section when it should be field "msgID" - done 334 4) The document must allow the value of engineID in the 335 security to be a zero length string. There are several 336 places that are affected by this change. An actual value is 337 never needed, since secrets are never the same on different 338 agents (see your paper). - done 339 5) Last sentence of description for object usmUserCloneFrom is 340 not correct, since the object has a OID data type - done 342 SNMPv3 Working Group Expires April 1998 [Page 7] 343 - Removed groupName from usmUserTable. 344 Now done in Access Control as agreed at 2nd interim 345 - Stats counters back in this document as agreed at 2nd interim 346 - Use AutonomousType for usmUserPrivProtocol and 347 usmUserAuthProtocol. Also use OBJECT-IDENTITY for the 348 protocol OIDs (John Flick). 349 - Changed "SNMPv3 engine" to "SNMP engine" at various places 350 - added appendix with sample encoding of securityParameters 351 - cleanup elements of procedure to use consistent terms 352 - fix up some problems in elements of procedure 353 - Do not use IMPLIED on usmUserTable as agreed at 2nd interim. 354 For one thing, SNMPv1 cannot handle it. 355 - cleanup section 2.3 and 3.3 step 7b based on comments by 356 Dave Levi. 358 [version 1.2] 359 - changed (simplified) time sync in section 3 item 7. 360 - added usmUserMiId 361 - cleaned up text 362 - defined IV "salt" generation 363 - removed Statistics counters (now in MPC) and Report PDU 364 generation (now in MPC) 365 - Removed auth and DES MIBs which are now merged into 366 User-based Security MIB 367 - specified where cachedSecurityData needs to be discarded 368 - added abstract service interface definitions 369 - removed section on error reporting (is MPC responsibility) 370 - removed auth/priv protocol definitions, they are in ARCH now 371 - removed MIB definitions for snmpEngineID, Time, Boots. They 372 are in ARCH now. 374 [version 1.1] 375 - removed . 376 - added , . 377 - added abstract function interface description of 378 inter-module communications. 379 - modified IV generation process to accommodate messages produced 380 faster than one-per-second (still open). 381 - always update the clock regardless of whether incoming message 382 was Report or not (if the message was properly authenticated 383 and its time-stamp is ahead of our notion of their clock). 385 [version 1.0] 386 - first version posted to the SNMPv3 editor's mailing list. 387 - based on v2adv slides, v2adv items and issues list and on 388 RFC1910 and SNMPv2u and SNMPv2* documents. 389 - various iterations were done by the authors via private email. 391 SNMPv3 Working Group Expires April 1998 [Page 8] 392 1. Introduction 394 The Architecture for describing Internet Management Frameworks 395 [SNMP-ARCH] describes that an SNMP engine is composed of: 397 1) a Dispatcher 398 2) a Message Processing Subsystem, 399 3) a Security Subsystem, and 400 4) an Access Control Subsystem. 402 Applications make use of the services of these subsystems. 404 It is important to understand the SNMP architecture and the 405 terminology of the architecture to understand where the Security 406 Model described in this document fits into the architecture and 407 interacts with other subsystems within the architecture. The 408 reader is expected to have read and understood the description of 409 the SNMP architecture, as defined in [SNMP-ARCH]. 411 This memo [SNMP-USM] describes the User-based Security Model as it 412 is used within the SNMP Architecture. The main idea is that we use 413 the traditional concept of a user (identified by a userName) with 414 which to associate security information. 416 This memo describes the use of HMAC-MD5-96 and HMAC-SHA-96 as the | 417 authentication protocols and the use of CBC-DES as the privacy | 418 protocol. The User-based Security Model however allows for other | 419 such protocols to be used instead of or concurrent with these | 420 protocols. Therefore, the description of HMAC-MD5-96, HMAC-SHA-96 | 421 and CBC-DES are in separate sections to reflect their self-contained | 422 nature and to indicate that they can be replaced or supplemented in | 423 the future. | 425 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", | 426 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this | 427 document are to be interpreted as described in [RFC2119]. | 429 1.1. Threats 431 Several of the classical threats to network protocols are 432 applicable to the network management problem and therefore would 433 be applicable to any SNMP Security Model. Other threats are not 434 applicable to the network management problem. This section 435 discusses principal threats, secondary threats, and threats which 436 are of lesser importance. 438 The principal threats against which this SNMP Security Model 439 should provide protection are: 441 - Modification of Information 442 The modification threat is the danger that some unauthorized 444 SNMPv3 Working Group Expires April 1998 [Page 9] 445 entity may alter in-transit SNMP messages generated on behalf 446 of an authorized user in such a way as to effect unauthorized 447 management operations, including falsifying the value of an 448 object. 450 - Masquerade 451 The masquerade threat is the danger that management operations 452 not authorized for some user may be attempted by assuming the 453 identity of another user that has the appropriate authorizations. 455 Two secondary threats are also identified. The Security Model 456 defined in this memo provides limited protection against: 458 - Disclosure 459 The disclosure threat is the danger of eavesdropping on the 460 exchanges between managed agents and a management station. 461 Protecting against this threat may be required as a matter of 462 local policy. 464 - Message Stream Modification 465 The SNMP protocol is typically based upon a connection-less 466 transport service which may operate over any sub-network service. 467 The re-ordering, delay or replay of messages can and does occur 468 through the natural operation of many such sub-network services. 469 The message stream modification threat is the danger that 470 messages may be maliciously re-ordered, delayed or replayed to 471 an extent which is greater than can occur through the natural 472 operation of a sub-network service, in order to effect 473 unauthorized management operations. 475 There are at least two threats that an SNMP Security Model need 476 not protect against. The security protocols defined in this memo 477 do not provide protection against: 479 - Denial of Service 480 This SNMP Security Model does not attempt to address the broad 481 range of attacks by which service on behalf of authorized users 482 is denied. Indeed, such denial-of-service attacks are in many 483 cases indistinguishable from the type of network failures with 484 which any viable network management protocol must cope as a 485 matter of course. 486 - Traffic Analysis 487 This SNMP Security Model does not attempt to address traffic 488 analysis attacks. Indeed, many traffic patterns are predictable 489 - devices may be managed on a regular basis by a relatively small 490 number of management applications - and therefore there is no 491 significant advantage afforded by protecting against traffic 492 analysis. 494 1.2. Goals and Constraints 496 Based on the foregoing account of threats in the SNMP network 497 management environment, the goals of this SNMP Security Model 498 are as follows. 500 1) Provide for verification that each received SNMP message has 501 not been modified during its transmission through the network. 503 2) Provide for verification of the identity of the user on whose 504 behalf a received SNMP message claims to have been generated. 506 3) Provide for detection of received SNMP messages, which request 507 or contain management information, whose time of generation was 508 not recent. 510 4) Provide, when necessary, that the contents of each received 511 SNMP message are protected from disclosure. 513 In addition to the principal goal of supporting secure network 514 management, the design of this SNMP Security Model is also 515 influenced by the following constraints: 517 1) When the requirements of effective management in times of 518 network stress are inconsistent with those of security, the 519 design should prefer the former. 521 2) Neither the security protocol nor its underlying security 522 mechanisms should depend upon the ready availability of other 523 network services (e.g., Network Time Protocol (NTP) or key 524 management protocols). 526 3) A security mechanism should entail no changes to the basic 527 SNMP network management philosophy. 529 1.3. Security Services 531 The security services necessary to support the goals of this SNMP 532 Security Model are as follows: 534 - Data Integrity 535 is the provision of the property that data has not been altered 536 or destroyed in an unauthorized manner, nor have data sequences 537 been altered to an extent greater than can occur non-maliciously. 539 - Data Origin Authentication 540 is the provision of the property that the claimed identity of 541 the user on whose behalf received data was originated is 542 corroborated. 544 - Data Confidentiality 545 is the provision of the property that information is not made 546 available or disclosed to unauthorized individuals, entities, 547 or processes. 549 - Message timeliness and limited replay protection 550 is the provision of the property that a message whose generation 551 time is outside of a specified time window is not accepted. 552 Note that message reordering is not dealt with and can occur in 553 normal conditions too. 555 For the protocols specified in this memo, it is not possible to 556 assure the specific originator of a received SNMP message; rather, 557 it is the user on whose behalf the message was originated that is 558 authenticated. 560 For these protocols, it not possible to obtain data integrity 561 without data origin authentication, nor is it possible to obtain 562 data origin authentication without data integrity. Further, 563 there is no provision for data confidentiality without both data 564 integrity and data origin authentication. 566 The security protocols used in this memo are considered acceptably 567 secure at the time of writing. However, the procedures allow for 568 new authentication and privacy methods to be specified at a future 569 time if the need arises. 571 1.4. Module Organization 573 The security protocols defined in this memo are split in three 574 different modules and each has its specific responsibilities such 575 that together they realize the goals and security services 576 described above: 578 - The authentication module MUST provide for: 580 - Data Integrity, 582 - Data Origin Authentication 584 - The timeliness module MUST provide for: 586 - Protection against message delay or replay (to an extent 587 greater than can occur through normal operation) 589 - The privacy module MUST provide for 591 - Protection against disclosure of the message payload. 593 The timeliness module is fixed for the User-based Security Model 594 while there is provision for multiple authentication and/or 595 privacy modules, each of which implements a specific authentication 596 or privacy protocol respectively. 598 1.4.1. Timeliness Module 600 Section 3 (Elements of Procedure) uses the timeliness values in an 601 SNMP message to do timeliness checking. The timeliness check is 602 only performed if authentication is applied to the message. Since 603 the complete message is checked for integrity, we can assume that 604 the timeliness values in a message that passes the authentication 605 module are trustworthy. 607 1.4.2. Authentication Protocol 609 Section 6 describes the HMAC-MD5-96 authentication protocol which | 610 is the first authentication protocol that MUST be supported with | 611 the User-based Security Model. | 612 Section 7 describes the HMAC-SHA-96 authentication protocol which | 613 is another authentication protocol that SHOULD be supported with | 614 the User-based Security Model. | 615 In the future additional or replacement authentication protocols may | 616 be defined as new needs arise. | 618 The User-based Security Model prescribes that, if authentication 619 is used, then the complete message is checked for integrity in 620 the authentication module. 622 For a message to be authenticated, it needs to pass authentication 623 check by the authentication module and the timeliness check which 624 is a fixed part of this User-based Security model. 626 1.4.3. Privacy Protocol 628 Section 8 describes the CBC-DES Symmetric Encryption Protocol | 629 which is the first privacy protocol to be used with the 630 User-based Security Model. In the future additional or 631 replacement privacy protocols may be defined as new needs arise. 633 The User-based Security Model prescribes that the scopedPDU 634 is protected from disclosure when a message is sent with privacy. 636 The User-based Security Model also prescribes that a message 637 needs to be authenticated if privacy is in use. 639 1.5. Protection against Message Replay, Delay and Redirection 641 1.5.1. Authoritative SNMP engine 643 In order to protect against message replay, delay and redirection, 644 one of the SNMP engines involved in each communication is 645 designated to be the authoritative SNMP engine. When an SNMP 646 message contains a payload which expects a response (for example 647 a Get, GetNext, GetBulk, Set or Inform PDU), then the receiver of 648 such messages is authoritative. When an SNMP message contains a 649 payload which does not expect a response (for example an 650 SNMPv2-Trap, Response or Report PDU), then the sender of such a 651 message is authoritative. 653 1.5.2. Mechanisms 655 The following mechanisms are used: 657 1) To protect against the threat of message delay or replay (to an 658 extent greater than can occur through normal operation), a set 659 of timeliness indicators (for the authoritative SNMP engine) are 660 included in each message generated. An SNMP engine evaluates 661 the timeliness indicators to determine if a received message is 662 recent. An SNMP engine may evaluate the timeliness indicators 663 to ensure that a received message is at least as recent as the 664 last message it received from the same source. 665 A non-authoritative SNMP engine uses received authentic messages 666 to advance its notion of the timeliness indicators at the remote 667 authoritative source. 669 An SNMP engine MUST also use a mechanism to match incoming 670 Responses to outstanding Requests and it MUST drop any Responses 671 that do not match an outstanding request. For example, a msgID 672 can be inserted in every message to cater for this functionality. 674 These mechanisms provide for the detection of authenticated 675 messages whose time of generation was not recent. 677 This protection against the threat of message delay or replay 678 does not imply nor provide any protection against unauthorized 679 deletion or suppression of messages. Also, an SNMP engine may 680 not be able to detect message reordering if all the messages 681 involved are sent within the Time Window interval. Other 682 mechanisms defined independently of the security protocol can 683 also be used to detect the re-ordering replay, deletion, or 684 suppression of messages containing Set operations (e.g., the 685 MIB variable snmpSetSerialNo [RFC1907]). 687 2) Verification that a message sent to/from one authoritative SNMP 688 engine cannot be replayed to/as-if-from another authoritative 689 SNMP engine. 691 Included in each message is an identifier unique to the 692 authoritative SNMP engine associated with the sender or intended 693 recipient of the message. 695 A Report, Response or Trap message sent by an authoritative SNMP 696 engine to one non-authoritative SNMP engine can potentially be 697 replayed to another non-authoritative SNMP engine. The latter 698 non-authoritative SNMP engine might (if it knows about the same 699 userName with the same secrets at the authoritative SNMP engine) 700 as a result update its notion of timeliness indicators of the 701 authoritative SNMP engine, but that is not considered a threat. 702 In this case, A Report or Response message will be discarded by 703 the Message Processing Model, because there should not be an 704 outstanding Request message. A Trap will possibly be accepted. 705 Again, that is not considered a threat, because the communication 706 was authenticated and timely. It is as if the authoritative SNMP 707 engine was configured to start sending Traps to the second SNMP 708 engine, which theoretically can happen without the knowledge of 709 the second SNMP engine anyway. Anyway, the second SNMP engine may 710 not expect to receive this Trap, but is allowed to see the 711 management information contained in it. 713 3) Detection of messages which were not recently generated. 715 A set of time indicators are included in the message, indicating 716 the time of generation. Messages without recent time indicators 717 are not considered authentic. In addition, an SNMP engine MUST 718 drop any Responses that do not match an outstanding request. This 719 however is the responsibility of the Message Processing Model. 721 This memo allows the same user to be defined on multiple SNMP 722 engines. Each SNMP engine maintains a value, snmpEngineID, 723 which uniquely identifies the SNMP engine. This value is included 724 in each message sent to/from the SNMP engine that is authoritative 725 (see section 1.5.1). On receipt of a message, an authoritative 726 SNMP engine checks the value to ensure that it is the intended 727 recipient, and a non-authoritative SNMP engine uses the value to 728 ensure that the message is processed using the correct state 729 information. 731 Each SNMP engine maintains two values, snmpEngineBoots and 732 snmpEngineTime, which taken together provide an indication of 733 time at that SNMP engine. Both of these values are included in 734 an authenticated message sent to/received from that SNMP engine. 735 On receipt, the values are checked to ensure that the indicated 736 timeliness value is within a Time Window of the current time. 737 The Time Window represents an administrative upper bound on 738 acceptable delivery delay for protocol messages. 740 For an SNMP engine to generate a message which an authoritative 741 SNMP engine will accept as authentic, and to verify that a message 742 received from that authoritative SNMP engine is authentic, such an 743 SNMP engine must first achieve timeliness synchronization with the 744 authoritative SNMP engine. See section 2.3. 746 1.6. Abstract Service Interfaces. | 747 | 748 Abstract service interfaces have been defined to describe the | 749 conceptual interfaces between the various subsystems within an SNMP | 750 entity. Similarly a set of abstract service interfaces have been | 751 defined within the User-based Security Model (USM) to describe the | 752 conceptual interfaces between the generic USM services and the | 753 self-contained authentication and privacy services. | 754 | 755 These abstract service interfaces are defined by a set of primitives | 756 that define the services provided and the abstract data elements that | 757 must be passed when the services are invoked. This section lists the 4 758 primitives that have been defined for the User-based Security Model. 4 759 | 760 1.6.1. User-based Security Model Primitives for Authentication | 761 | 762 The User-based Security Model provides the following internal | 763 primitives to pass data back and forth between the Security Model | 764 itself and the authentication service: | 765 | 766 statusInformation = | 767 authenticateOutgoingMsg( | 768 IN authKey -- secret key for authentication | 769 IN wholeMsg -- unauthenticated complete message | 770 OUT authenticatedWholeMsg -- complete authenticated message | 771 ) | 772 | 773 statusInformation = | 774 authenticateIncomingMsg( | 775 IN authKey -- secret key for authentication | 776 IN authParameters -- as received on the wire | 777 IN wholeMsg -- as received on the wire | 778 OUT authenticatedWholeMsg -- complete authenticated message | 779 ) | 780 | 781 1.6.2. User-based Security Model Primitives for Privacy | 782 | 783 The User-based Security Model provides the following internal | 784 primitives to pass data back and forth between the Security Model | 785 itself and the privacy service: | 786 | 787 statusInformation = | 788 encryptData( | 789 IN encryptKey -- secret key for encryption | 790 IN dataToEncrypt -- data to encrypt (scopedPDU) | 791 OUT encryptedData -- encrypted data (encryptedPDU) | 792 OUT privParameters -- filled in by service provider | 793 ) | 794 | 795 statusInformation = | 796 decryptData( | 797 IN decryptKey -- secret key for decrypting | 798 IN privParameters -- as received on the wire | 799 IN encryptedData -- encrypted data (encryptedPDU) | 800 OUT decryptedData -- decrypted data (scopedPDU) | 801 ) | 803 2. Elements of the Model 805 This section contains definitions required to realize the security 806 model defined by this memo. 808 2.1. User-based Security Model Users 810 Management operations using this Security Model make use of a 811 defined set of user identities. For any user on whose behalf 812 management operations are authorized at a particular SNMP engine, 813 that SNMP engine must have knowledge of that user. An SNMP engine 814 that wishes to communicate with another SNMP engine must also have 815 knowledge of a user known to that engine, including knowledge of 816 the applicable attributes of that user. 818 A user and its attributes are defined as follows: 820 userName 821 A string representing the name of the user. 823 securityName 824 A human-readable string representing the user in a format that 825 is Security Model independent. 827 authProtocol 828 An indication of whether messages sent on behalf of this user can 829 be authenticated, and if so, the type of authentication protocol 830 which is used. Two such protocols are defined in this memo: | 831 - the HMAC-MD5-96 authentication protocol. | 832 - the HMAC-SHA-96 authentication protocol. | 834 authKey 835 If messages sent on behalf of this user can be authenticated, 836 the (private) authentication key for use with the authentication 837 protocol. Note that a user's authentication key will normally 838 be different at different authoritative SNMP engines. The authKey | 839 is not accessible via SNMP. The length requirements of the authKey | 840 are defined by the authProtocol in use. | 842 authKeyChange and authOwnKeyChange 843 The only way to remotely update the authentication key. Does 844 that in a secure manner, so that the update can be completed 845 without the need to employ privacy protection. 847 privProtocol 848 An indication of whether messages sent on behalf of this user 849 can be protected from disclosure, and if so, the type of privacy 850 protocol which is used. One such protocol is defined in this 851 memo: the CBC-DES Symmetric Encryption Protocol. | 853 privKey 854 If messages sent on behalf of this user can be en/decrypted, 855 the (private) privacy key for use with the privacy protocol. 856 Note that a user's privacy key will normally be different at 857 different authoritative SNMP engines. The privKey is not 858 accessible via SNMP. The length requirements of the privKey are | 859 defined by the privProtocol in use. | 861 privKeyChange and privOwnKeyChange 862 The only way to remotely update the encryption key. Does that 863 in a secure manner, so that the update can be completed without 864 the need to employ privacy protection. 866 2.2. Replay Protection 868 Each SNMP engine maintains three objects: 870 - snmpEngineID, which (at least within an administrative domain) 871 uniquely and unambiguously identifies an SNMP engine. 873 - snmpEngineBoots, which is a count of the number of times the 874 SNMP engine has re-booted/re-initialized since snmpEngineID 875 was last configured; and, 877 - snmpEngineTime, which is the number of seconds since the 878 snmpEngineBoots counter was last incremented. 880 Each SNMP engine is always authoritative with respect to these 881 objects in its own SNMP entity. It is the responsibility of a 882 non-authoritative SNMP engine to synchronize with the 883 authoritative SNMP engine, as appropriate. 885 An authoritative SNMP engine is required to maintain the values of 886 its snmpEngineID and snmpEngineBoots in non-volatile storage. 888 2.2.1. msgAuthoritativeEngineID 890 The msgAuthoritativeEngineID value contained in an authenticated 891 message is used to defeat attacks in which messages from one SNMP 892 engine to another SNMP engine are replayed to a different SNMP 893 engine. It represents the snmpEngineID at the authoritative SNMP 894 engine involved in the exchange of the message. 896 When an authoritative SNMP engine is first installed, it sets its 897 local value of snmpEngineID according to a enterprise-specific 898 algorithm (see the definition of the Textual Convention for 899 SnmpEngineID in the SNMP Architecture document [SNMP-ARCH]). 901 2.2.2. msgAuthoritativeEngineBoots and msgAuthoritativeEngineTime 903 The msgAuthoritativeEngineBoots and msgAuthoritativeEngineTime 904 values contained in an authenticated message are used to defeat 905 attacks in which messages are replayed when they are no longer 906 valid. They represent the snmpEngineBoots and snmpEngineTime 907 values at the authoritative SNMP engine involved in the exchange 908 of the message. 910 Through use of snmpEngineBoots and snmpEngineTime, there is no 911 requirement for an SNMP engine to have a non-volatile clock which 912 ticks (i.e., increases with the passage of time) even when the 913 SNMP engine is powered off. Rather, each time an SNMP engine 914 re-boots, it retrieves, increments, and then stores snmpEngineBoots 915 in non-volatile storage, and resets snmpEngineTime to zero. 917 When an SNMP engine is first installed, it sets its local values 918 of snmpEngineBoots and snmpEngineTime to zero. If snmpEngineTime 919 ever reaches its maximum value (2147483647), then snmpEngineBoots 920 is incremented as if the SNMP engine has re-booted and 921 snmpEngineTime is reset to zero and starts incrementing again. 923 Each time an authoritative SNMP engine re-boots, any SNMP engines 924 holding that authoritative SNMP engine's values of snmpEngineBoots 925 and snmpEngineTime need to re-synchronize prior to sending 926 correctly authenticated messages to that authoritative SNMP engine 927 (see Section 2.3 for (re-)synchronization procedures). Note, 928 however, that the procedures do provide for a notification to be 929 accepted as authentic by a receiving SNMP engine, when sent by an 930 authoritative SNMP engine which has re-booted since the receiving 931 SNMP engine last (re-)synchronized. 933 If an authoritative SNMP engine is ever unable to determine its 934 latest snmpEngineBoots value, then it must set its snmpEngineBoots 935 value to 2147483647. 3 936 3 937 Whenever the local value of snmpEngineBoots has the value 2147483647 3 938 it latches at that value and an authenticated message always causes 3 939 an notInTimeWindow authentication failure. 3 941 In order to reset an SNMP engine whose snmpEngineBoots value has 942 reached the value 2147483647, manual intervention is required. 3 943 The engine must be physically visited and re-configured, either 944 with a new snmpEngineID value, or with new secret values for the 945 authentication and privacy protocols of all users known to that 946 SNMP engine. Note that even if an SNMP engine re-boots once a second 3 947 that it would still take approximately 68 years before the max value 3 948 of 2147483647 would be reached. 3 950 2.2.3. Time Window 952 The Time Window is a value that specifies the window of time in 953 which a message generated on behalf of any user is valid. This 954 memo specifies that the same value of the Time Window, 150 seconds, 955 is used for all users. 957 2.3. Time Synchronization 959 Time synchronization, required by a non-authoritative SNMP engine 960 in order to proceed with authentic communications, has occurred 961 when the non-authoritative SNMP engine has obtained a local notion 962 of the authoritative SNMP engine's values of snmpEngineBoots and 963 snmpEngineTime from the authoritative SNMP engine. These values 964 must be (and remain) within the authoritative SNMP engine's Time 965 Window. So the local notion of the authoritative SNMP engine's 966 values must be kept loosely synchronized with the values stored 967 at the authoritative SNMP engine. In addition to keeping a local 968 copy of snmpEngineBoots and snmpEngineTime from the authoritative 969 SNMP engine, a non-authoritative SNMP engine must also keep one 970 local variable, latestReceivedEngineTime. This value records the 971 highest value of snmpEngineTime that was received by the 972 non-authoritative SNMP engine from the authoritative SNMP engine 973 and is used to eliminate the possibility of replaying messages 974 that would prevent the non-authoritative SNMP engine's notion of 975 the snmpEngineTime from advancing. 977 A non-authoritative SNMP engine must keep local notions of these 978 values for each authoritative SNMP engine with which it wishes to 979 communicate. Since each authoritative SNMP engine is uniquely 980 and unambiguously identified by its value of snmpEngineID, the 981 non-authoritative SNMP engine may use this value as a key in 982 order to cache its local notions of these values. 984 Time synchronization occurs as part of the procedures of receiving 985 an SNMP message (Section 3.2, step 7b). As such, no explicit time | 986 synchronization procedure is required by a non-authoritative SNMP | 987 engine. Note, that whenever the local value of snmpEngineID is | 988 changed (e.g., through discovery) or when secure communications | 989 are first established with an authoritative SNMP engine, the local | 990 values of snmpEngineBoots and latestReceivedEngineTime should be | 991 set to zero. This will cause the time synchronization to occur | 992 when the next authentic message is received. | 993 5 995 2.4. SNMP Messages Using this Security Model 997 The syntax of an SNMP message using this Security Model adheres 998 to the message format defined in the version-specific Message 999 Processing Model document (for example [SNMP-MP]). 1001 The field msgSecurityParameters in SNMPv3 messages has a data type 1002 of OCTET STRING. Its value is the BER serialization of the 1003 following ASN.1 sequence: 1005 USMSecurityParametersSyntax DEFINITIONS IMPLICIT TAGS ::= BEGIN | 1006 4 1007 UsmSecurityParameters ::= 1008 SEQUENCE { 1009 -- global User-based security parameters 1010 msgAuthoritativeEngineID OCTET STRING, | 1011 msgAuthoritativeEngineBoots INTEGER (0..2147483647), 3 1012 msgAuthoritativeEngineTime INTEGER (0..2147483647), 3 1013 msgUserName OCTET STRING (SIZE(1..32)), | 1014 -- authentication protocol specific parameters 1015 msgAuthenticationParameters OCTET STRING, 1016 -- privacy protocol specific parameters 1017 msgPrivacyParameters OCTET STRING | 1018 } 1019 END 1021 The fields of this sequence are: 1023 - The msgAuthoritativeEngineID specifies the snmpEngineID of the 1024 authoritative SNMP engine involved in the exchange of the message. 1026 - The msgAuthoritativeEngineBoots specifies the snmpEngineBoots 1027 value at the authoritative SNMP engine involved in the exchange 1028 of the message. 1030 - The msgAuthoritativeEngineTime specifies the snmpEngineTime value 1031 at the authoritative SNMP engine involved in the exchange of the 1032 message. 1034 - The msgUserName specifies the user (principal) on whose behalf 1035 the message is being exchanged. 1037 - The msgAuthenticationParameters are defined by the authentication 1038 protocol in use for the message, as defined by the 1039 usmUserAuthProtocol column in the user's entry in the usmUserTable. 1041 - The msgPrivacyParameters are defined by the privacy protocol in 1042 use for the message, as defined by the usmUserPrivProtocol column 1043 in the user's entry in the usmUserTable). 1045 See appendix A.4 for an example of the BER encoding of field 1046 msgSecurityParameters. 1048 2.5. Services provided by the User-based Security Model 1050 This section describes the services provided by the User-based 1051 Security Model with their inputs and outputs. 1053 The services are described as primitives of an abstract service 1054 interface and the inputs and outputs are described as abstract data 1055 elements as they are passed in these abstract service primitives. 1057 2.5.1. Services for Generating an Outgoing SNMP Message 1059 When the Message Processing (MP) Subsystem invokes the User-based 1060 Security module to secure an outgoing SNMP message, it must use 1061 the appropriate service as provided by the Security module. These 1062 two services are provided: 1064 1) A service to generate a Request message. The abstract service 1065 primitive is: 1067 statusInformation = -- success or errorIndication 1068 generateRequestMsg( 1069 IN messageProcessingModel -- typically, SNMP version 1070 IN globalData -- message header, admin data 1071 IN maxMessageSize -- of the sending SNMP entity 1072 IN securityModel -- for the outgoing message 1073 IN securityEngineID -- authoritative SNMP entity 1074 IN securityName -- on behalf of this principal 1075 IN securityLevel -- Level of Security requested 1076 IN scopedPDU -- message (plaintext) payload 1077 OUT securityParameters -- filled in by Security Module 1078 OUT wholeMsg -- complete generated message 1079 OUT wholeMsgLength -- length of generated message 1080 ) 1082 2) A service to generate a Response message. The abstract service 1083 primitive is: 1085 statusInformation = -- success or errorIndication 1086 generateResponseMsg( 1087 IN messageProcessingModel -- typically, SNMP version 1088 IN globalData -- message header, admin data 1089 IN maxMessageSize -- of the sending SNMP entity 1090 IN securityModel -- for the outgoing message 1091 IN securityEngineID -- authoritative SNMP entity 1092 IN securityName -- on behalf of this principal 1093 IN securityLevel -- Level of Security requested 1094 IN scopedPDU -- message (plaintext) payload 1095 IN securityStateReference -- reference to security state 1096 -- information from original 1097 -- request 1098 OUT securityParameters -- filled in by Security Module 1099 OUT wholeMsg -- complete generated message 1100 OUT wholeMsgLength -- length of generated message 1101 ) 1103 The abstract data elements passed as parameters in the abstract 1104 service primitives are as follows: 1106 statusInformation 1107 An indication of whether the encoding and securing of the message 1108 was successful. If not it is an indication of the problem. 1109 messageProcessingModel 1110 The SNMP version number for the message to be generated. 1111 This data is not used by the User-based Security module. 1112 globalData 1113 The message header (i.e., its administrative information). This | 1114 data is not used by the User-based Security module. 1115 maxMessageSize 1116 The maximum message size as included in the message. 1117 This data is not used by the User-based Security module. 1118 securityParameters 1119 These are the security parameters. They will be filled in 1120 by the User-based Security module. 1121 securityModel 1122 The securityModel in use. Should be User-based Security Model. 1123 This data is not used by the User-based Security module. 1124 securityName 1125 Together with the snmpEngineID it identifies a row in the 1126 usmUserTable that is to be used for securing the message. 1127 The securityName has a format that is independent of the 1128 Security Model. In case of a response this parameter is 1129 ignored and the value from the cache is used. 5 1130 securityLevel 1131 The Level of Security from which the User-based Security 1132 module determines if the message needs to be protected from 1133 disclosure and if the message needs to be authenticated. 1134 In case of a response this parameter is ignored and the value 1135 from the cache is used. 5 1136 securityEngineID 1137 The snmpEngineID of the authoritative SNMP engine to which a 1138 Request message is to be sent. In case of a response it is 1139 implied to be the processing SNMP engine's snmpEngineID and 1140 so if it is specified, then it is ignored. 1141 scopedPDU 1142 The message payload. The data is opaque as far as the 1143 User-based Security Model is concerned. 1144 securityStateReference 1145 A handle/reference to cachedSecurityData to be used when 1146 securing an outgoing Response message. This is the exact same 1147 handle/reference as it was generated by the User-based Security 1148 module when processing the incoming Request message to which 1149 this is the Response message. 1150 wholeMsg 1151 The fully encoded and secured message ready for sending on 1152 the wire. 1153 wholeMsgLength 1154 The length of the encoded and secured message (wholeMsg). 1156 Upon completion of the process, the User-based Security module 1157 returns statusInformation. If the process was successful, the 1158 completed message with privacy and authentication applied if such 1159 was requested by the specified securityLevel is returned. If the 5 1160 process was not successful, then an errorIndication is returned. 5 1162 2.5.2. Services for Processing an Incoming SNMP Message 1164 When the Message Processing (MP) Subsystem invokes the User-based 1165 Security module to verify proper security of an incoming message, 1166 it must use the service provided for an incoming message. The 1167 abstract service primitive is: 1169 statusInformation = -- errorIndication or success 1170 -- error counter OID/value if error 1171 processIncomingMsg( 1172 IN messageProcessingModel -- typically, SNMP version 1173 IN maxMessageSize -- of the sending SNMP entity 1174 IN securityParameters -- for the received message 1175 IN securityModel -- for the received message 1176 IN securityLevel -- Level of Security 1177 IN wholeMsg -- as received on the wire 1178 IN wholeMsgLength -- length as received on the wire 1179 OUT securityEngineID -- authoritative SNMP entity 1180 OUT securityName -- identification of the principal 1181 OUT scopedPDU, -- message (plaintext) payload 1182 OUT maxSizeResponseScopedPDU -- maximum size of the Response PDU 1183 OUT securityStateReference -- reference to security state 1184 ) -- information, needed for response 1186 The abstract data elements passed as parameters in the abstract 1187 service primitives are as follows: 1189 statusInformation 1190 An indication of whether the process was successful or not. 1191 If not, then the statusInformation includes the OID and the 1192 value of the error counter that was incremented. 1193 messageProcessingModel 1194 The SNMP version number as received in the message. 1195 This data is not used by the User-based Security module. 1196 maxMessageSize 1197 The maximum message size as included in the message. 1199 The User-based Security module uses this value to calculate the 1200 maxSizeResponseScopedPDU. 1201 securityParameters 1202 These are the security parameters as received in the message. 1203 securityModel 1204 The securityModel in use. 1205 Should be the User-based Security Model. 1206 This data is not used by the User-based Security module. 1207 securityLevel 1208 The Level of Security from which the User-based Security 1209 module determines if the message needs to be protected from 1210 disclosure and if the message needs to be authenticated. 1211 wholeMsg 1212 The whole message as it was received. 1213 wholeMsgLength 1214 The length of the message as it was received (wholeMsg). 1215 securityEngineID 1216 The snmpEngineID that was extracted from the field 1217 msgAuthoritativeEngineID and that was used to lookup the secrets 1218 in the usmUserTable. 1219 securityName 1220 The security name representing the user on whose behalf the 1221 message was received. The securityName has a format that is 1222 independent of the Security Model. 1223 scopedPDU 1224 The message payload. The data is opaque as far as the 1225 User-based Security Model is concerned. 1226 maxSizeResponseScopedPDU 1227 The maximum size of a scopedPDU to be included in a possible 1228 Response message. The User-base Security module calculates 1229 this size based on the mms (as received in the message) and 1230 the space required for the message header (including the 1231 securityParameters) for such a Response message. 1232 securityStateReference 1233 A handle/reference to cachedSecurityData to be used when 1234 securing an outgoing Response message. When the Message 1235 Processing Subsystem calls the User-based Security module to 1236 generate a response to this incoming message it must pass this 1237 handle/reference. 1239 Upon completion of the process, the User-based Security module 1240 returns statusInformation and, if the process was successful, 1241 the additional data elements for further processing of the message. 1242 If the process was not successful, then an errorIndication, 1243 possibly with a OID and value pair of an error counter that was 1244 incremented. 1246 2.6. Key Localization Algorithm. 3 1247 3 1248 A localized key is a secret key shared between a user U and one 3 1249 authoritative SNMP engine E. Even though a user may have only one 3 1250 password and therefore one key for the whole network, the actual 3 1251 secrets shared between the user and each authoritative SNMP engine 3 1252 will be different. This is achieved by key localization 3 1253 [Localized-key]. 3 1254 3 1255 First, if a user uses a password, then the user's password is 3 1256 converted into a key Ku using one of the two algorithms described 4 1257 in Appendices A.2.1 and A.2.2. 3 1258 3 1259 To convert key Ku into a localized key Kul of user U at the 4 1260 authoritative SNMP engine E, one appends the snmpEngineID of the 3 1261 authoritative SNMP engine to the key Ku and then appends the key Ku 4 1262 to the result, thus enveloping the snmpEngineID within the two 3 1263 copies of user's key Ku. Then one runs a secure hash function 4 1264 (which one depends on the authentication protocol defined for this 3 1265 user U at authoritative SNMP engine E; this document defines two 3 1266 authentication protocols with their associated algorithms based on 3 1267 MD5 and SHA). The output of the hash-function is the localized key 3 1268 Kul for user U at the authoritative SNMP engine E. 4 1269 3 1271 3. Elements of Procedure 1273 This section describes the security related procedures followed by 1274 an SNMP engine when processing SNMP messages according to the 1275 User-based Security Model. 1277 3.1. Generating an Outgoing SNMP Message 1279 This section describes the procedure followed by an SNMP engine 1280 whenever it generates a message containing a management operation 1281 (like a request, a response, a notification, or a report) on 1282 behalf of a user, with a particular securityLevel. 1284 1) a) If any securityStateReference is passed (Response message), 1285 then information concerning the user is extracted from the 1286 cachedSecurityData. The securityEngineID and the 1287 securityLevel are extracted from the cachedSecurityData. 1288 The cachedSecurityData can now be discarded. 1290 Otherwise, 1292 b) based on the securityName, information concerning the 1293 user at the destination snmpEngineID, specified by the 1294 securityEngineID, is extracted from the Local Configuration 1295 Datastore (LCD, usmUserTable). If information about the user 1296 is absent from the LCD, then an error indication 1297 (unknownSecurityName) is returned to the calling module. 1299 2) If the securityLevel specifies that the message is to be 1300 protected from disclosure, but the user does not support both 1301 an authentication and a privacy protocol then the message 1302 cannot be sent. An error indication (unsupportedSecurityLevel) 1303 is returned to the calling module. 1305 3) If the securityLevel specifies that the message is to be 1306 authenticated, but the user does not support an authentication 1307 protocol, then the message cannot be sent. An error indication 1308 (unsupportedSecurityLevel) is returned to the calling module. 1310 4) a) If the securityLevel specifies that the message is to be 1311 protected from disclosure, then the octet sequence 1312 representing the serialized scopedPDU is encrypted according 1313 to the user's privacy protocol. To do so a call is made to 1314 the privacy module that implements the user's privacy 1315 protocol according to the abstract primitive: 1317 statusInformation = -- success or failure 1318 encryptData( 1319 IN encryptKey -- user's localized privKey 3 1320 IN dataToEncrypt -- serialized scopedPDU 1321 OUT encryptedData -- serialized encryptedPDU 1322 OUT privParameters -- serialized privacy parameters 1323 ) 1325 statusInformation 1326 indicates if the encryption process was successful or not. 1327 encryptKey 1328 the user's localized private privKey is the secret key that 3 1329 can be used by the encryption algorithm. 3 1330 dataToEncrypt 1331 the serialized scopedPDU is the data that to be encrypted. 1332 encryptedData 1333 the encryptedPDU represents the encrypted scopedPDU, 1334 encoded as an OCTET STRING. 1335 privParameters 1336 the privacy parameters, encoded as an OCTET STRING. 1338 If the privacy module returns failure, then the message 1339 cannot be sent and an error indication (encryptionError) 4 1340 is returned to the calling module. 1342 If the privacy module returns success, then the returned 1343 privParameters are put into the msgPrivacyParameters field of 1344 the securityParameters and the encryptedPDU serves as the 1345 payload of the message being prepared. 1347 Otherwise, 1349 b) If the securityLevel specifies that the message is not to be 1350 protected from disclosure, then the NULL string is encoded 1351 as an OCTET STRING and put into the msgPrivacyParameters 1352 field of the securityParameters and the plaintext scopedPDU 1353 serves as the payload of the message being prepared. 1355 5) The snmpEngineID is encoded as an OCTET STRING into the 1356 msgAuthoritativeEngineID field of the securityParameters. 1357 Note that an empty (zero length) snmpEngineID is OK for a 1358 Request message, because that will cause the remote 1359 (authoritative) SNMP engine to return a Report PDU with the 1360 proper snmpEngineID included in the msgAuthoritativeEngineID in 5 1361 the securityParameters of that returned Report PDU. 5 1363 6) a) If the securityLevel specifies that the message is to be 1364 authenticated, then the current values of snmpEngineBoots 1365 and snmpEngineTime corresponding to the snmpEngineID from 1366 the LCD are used. 1368 Otherwise, 1370 b) If this is a Response message, then the current value of 1371 snmpEngineBoots and snmpEngineTime corresponding to the 1372 local snmpEngineID from the LCD are used. 1374 Otherwise, 1376 c) If this is a Request message, then a zero value is used 1377 for both snmpEngineBoots and snmpEngineTime. This zero 1378 value gets used if snmpEngineID is empty. 1380 The values are encoded as Unsigned32 and Integer32 respectively | 1381 into the msgAuthoritativeEngineBoots and | 1382 msgAuthoritativeEngineTime fields of the securityParameters. | 1384 7) The userName is encoded as an OCTET STRING into the msgUserName 1385 field of the securityParameters. 1387 8) a) If the securityLevel specifies that the message is to be 1388 authenticated, the message is authenticated according to the 1389 user's authentication protocol. To do so a call is made to 1390 the authentication module that implements the user's 1391 authentication protocol according to the abstract service 1392 primitive: 1394 statusInformation = 1395 authenticateOutgoingMsg( 1396 IN authKey -- the user's localized authKey 3 1397 IN wholeMsg -- unauthenticated message 1398 OUT authenticatedWholeMsg -- authenticated complete message 1399 ) 1401 statusInformation 1402 indicates if authentication was successful or not. 1403 authKey 1404 the user's localized private authKey is the secret key that 3 1405 can be used by the authentication algorithm. 3 1406 wholeMsg 1407 the complete serialized message to be authenticated. 1408 authenticatedWholeMsg 1409 the same as the input given to the authenticateOutgoingMsg 1410 service, but with msgAuthenticationParameters properly 1411 filled in. 1413 If the authentication module returns failure, then the 1414 message cannot be sent and an error indication 1415 (authenticationFailure) is returned to the calling module. 1417 If the authentication module returns success, then the 1418 msgAuthenticationParameters field is put into the 1419 securityParameters and the authenticatedWholeMsg represents 1420 the serialization of the authenticated message being 1421 prepared. 1423 Otherwise, 1425 b) If the securityLevel specifies that the message is not to 1426 be authenticated then the NULL string is encoded as an 1427 OCTET STRING into the msgAuthenticationParameters field of 1428 the securityParameters. The wholeMsg is now serialized and 1429 then represents the unauthenticated message being prepared. 1431 9) The completed message with its length is returned to the 1432 calling module with the statusInformation set to success. 1434 3.2. Processing an Incoming SNMP Message 1436 This section describes the procedure followed by an SNMP engine 1437 whenever it receives a message containing a management operation 1438 on behalf of a user, with a particular securityLevel. 1440 To simplify the elements of procedure, the release of state 1441 information is not always explicitly specified. As a general rule, 1442 if state information is available when a message gets discarded, 1443 the state information should also be released. 1444 Also, when an error indication with an OID and value for an 1445 incremented counter is returned, then the available information 1446 (like securityStateReference) must be passed back to the caller 1447 so it can generate a Report PDU. 1449 1) If the received securityParameters is not the serialization 1450 (according to the conventions of [RFC1906]) of an OCTET STRING 1451 formatted according to the UsmSecurityParameters defined in 1452 section 2.4, then the snmpInASNParseErrs counter [RFC1907] is 1453 incremented, and an error indication (parseError) is returned 1454 to the calling module. 1455 Note that we return without the OID and value of the incremented 1456 counter, because in this case there is not enough information 1457 to generate a Report PDU. 1459 2) The values of the security parameter fields are extracted from 1460 the securityParameters. The securityEngineID to be returned to 1461 the caller is the value of the msgAuthoritativeEngineID field. 1462 The cachedSecurityData is prepared and a securityStateReference 1463 is prepared to reference this data. Values to be cached are: 1465 msgUserName 1466 securityEngineID 1467 securityLevel 1469 3) If the value of the msgAuthoritativeEngineID field in the 1470 securityParameters is unknown then: 1472 a) a non-authoritative SNMP engine that performs discovery may 1473 optionally create a new entry in its Local Configuration 1474 Datastore (LCD) and continue processing; 1475 or 1477 b) the usmStatsUnknownEngineIDs counter is incremented, and 1478 an error indication (unknownEngineID) together with the 1479 OID and value of the incremented counter is returned to 1480 the calling module. 1482 4) Information about the value of the msgUserName and 1483 msgAuthoritativeEngineID fields is extracted from the Local 1484 Configuration Datastore (LCD, usmUserTable). If no information 1485 is available for the user, then the usmStatsUnknownUserNames 1486 counter is incremented and an error indication 1487 (unknownSecurityName) together with the OID and value of the 1488 incremented counter is returned to the calling module. 1490 5) If the information about the user indicates that it does not 1491 support the securityLevel requested by the caller, then the 1492 usmStatsUnsupportedSecLevels counter is incremented and an 1493 error indication (unsupportedSecurityLevel) together with the 1494 OID and value of the incremented counter is returned to the 1495 calling module. 1497 6) If the securityLevel specifies that the message is to be 1498 authenticated, then the message is authenticated according to 1499 the user's authentication protocol. To do so a call is made 1500 to the authentication module that implements the user's 1501 authentication protocol according to the abstract service 1502 primitive: 1504 statusInformation = -- success or failure 1505 authenticateIncomingMsg( 1506 IN authKey -- the user's localized authKey 3 1507 IN authParameters -- as received on the wire 1508 IN wholeMsg -- as received on the wire 1509 OUT authenticatedWholeMsg -- checked for authentication 1510 ) 1512 statusInformation 1513 indicates if authentication was successful or not. 1514 authKey 1515 the user's localized private authKey is the secret key that 3 1516 can be used by the authentication algorithm. 3 1517 wholeMsg 1518 the complete serialized message to be authenticated. 1519 authenticatedWholeMsg 1520 the same as the input given to the authenticateIncomingMsg 1521 service, but after authentication has been checked. 1523 If the authentication module returns failure, then the message 1524 cannot be trusted, so the usmStatsWrongDigests counter is 1525 incremented and an error indication (authenticationFailure) 1526 together with the OID and value of the incremented counter is 1527 returned to the calling module. 1529 If the authentication module returns success, then the message 1530 is authentic and can be trusted so processing continues. 1532 7) If the securityLevel indicates an authenticated message, then 1533 the local values of snmpEngineBoots and snmpEngineTime 1534 corresponding to the value of the msgAuthoritativeEngineID 1535 field are extracted from the Local Configuration Datastore. 1537 a) If the extracted value of msgAuthoritativeEngineID is the 1538 same as the value of snmpEngineID of the processing SNMP 1539 engine (meaning this is the authoritative SNMP engine), 1540 then if any of the following conditions is true, then the 1541 message is considered to be outside of the Time Window: 1543 - the local value of snmpEngineBoots is 2147483647; 3 1545 - the value of the msgAuthoritativeEngineBoots field differs 1546 from the local value of snmpEngineBoots; or, 1548 - the value of the msgAuthoritativeEngineTime field differs 1549 from the local notion of snmpEngineTime by more than 1550 +/- 150 seconds. 1552 If the message is considered to be outside of the Time Window 1553 then the usmStatsNotInTimeWindows counter is incremented and 1554 an error indication (notInTimeWindow) together with the OID 1555 and value of the incremented counter is returned to the 1556 calling module. 1558 b) If the extracted value of msgAuthoritativeEngineID is not the 1559 same as the value snmpEngineID of the processing SNMP engine 1560 (meaning this is not the authoritative SNMP engine), then: 1562 1) if at least one of the following conditions is true: 1564 - the extracted value of the msgAuthoritativeEngineBoots 1565 field is greater than the local notion of the value of 1566 snmpEngineBoots; or, 1568 - the extracted value of the msgAuthoritativeEngineBoots 1569 field is equal to the local notion of the value of 1570 snmpEngineBoots, the extracted value of 1571 msgAuthoritativeEngineTime field is greater than the 1572 value of latestReceivedEngineTime, | 1573 | 1574 then the LCD entry corresponding to the extracted value 1575 of the msgAuthoritativeEngineID field is updated, by 1576 setting: 1578 - the local notion of the value of snmpEngineBoots to 1579 the value of the msgAuthoritativeEngineBoots field, 1580 - the local notion of the value of snmpEngineTime to 1581 the value of the msgAuthoritativeEngineTime field, 1582 and 1583 - the latestReceivedEngineTime to the value of the 1584 value of the msgAuthoritativeEngineTime field. 1586 2) if any of the following conditions is true, then the 1587 message is considered to be outside of the Time Window: 1589 - the local notion of the value of snmpEngineBoots is 1590 2147483647; 3 1592 - the value of the msgAuthoritativeEngineBoots field is 1593 less than the local notion of the value of 1594 snmpEngineBoots; or, 1596 - the value of the msgAuthoritativeEngineBoots field is 1597 equal to the local notion of the value of 1598 snmpEngineBoots and the value of the 1599 msgAuthoritativeEngineTime field is more than 150 1600 seconds less than the local notion of of the value of 1601 snmpEngineTime. 1603 If the message is considered to be outside of the Time 1604 Window then an error indication (notInTimeWindow) is 1605 returned to the calling module; 1607 Note that this means that a too old (possibly replayed) 1608 message has been detected and is deemed unauthentic. 1610 Note that this procedure allows for the value of 1611 msgAuthoritativeEngineBoots in the message to be greater 1612 than the local notion of the value of snmpEngineBoots to 1613 allow for received messages to be accepted as authentic 1614 when received from an authoritative SNMP engine that has 1615 re-booted since the receiving SNMP engine last 1616 (re-)synchronized. 1618 Note that this procedure does not allow for automatic 1619 time synchronization if the non-authoritative SNMP engine 1620 has a real out-of-sync situation whereby the authoritative 1621 SNMP engine is more than 150 seconds behind the 1622 non-authoritative SNMP engine. 1624 8) a) If the securityLevel indicates that the message was protected 1625 from disclosure, then the OCTET STRING representing the 1626 encryptedPDU is decrypted according to the user's privacy 1627 protocol to obtain an unencrypted serialized scopedPDU value. 1628 To do so a call is made to the privacy module that implements 1629 the user's privacy protocol according to the abstract 1630 primitive: 1632 statusInformation = -- success or failure 1633 decryptData( 1634 IN decryptKey -- the user's localized privKey 3 1635 IN privParameters -- as received on the wire 1636 IN encryptedData -- encryptedPDU as received 1637 OUT decryptedData -- serialized decrypted scopedPDU 1638 ) 1640 statusInformation 1641 indicates if the decryption process was successful or not. 1642 decryptKey 1643 the user's localized private privKey is the secret key that 3 1644 can be used by the decryption algorithm. 3 1645 privParameters 1646 the msgPrivacyParameters, encoded as an OCTET STRING. 1647 encryptedData 1648 the encryptedPDU represents the encrypted scopedPDU, 1649 encoded as an OCTET STRING. 1650 decryptedData 1651 the serialized scopedPDU if decryption is successful. 1653 If the privacy module returns failure, then the message can 1654 not be processed, so the usmStatsDecryptionErrors counter 1655 is incremented and an error indication (decryptionError) 4 1656 together with the OID and value of the incremented counter 1657 is returned to the calling module. 1659 If the privacy module returns success, then the decrypted 1660 scopedPDU is the message payload to be returned to the 1661 calling module. 1663 Otherwise, 1665 b) The scopedPDU component is assumed to be in plain text 1666 and is the message payload to be returned to the calling 1667 module. 1669 9) The maxSizeResponseScopedPDU is calculated. This is the 1670 maximum size allowed for a scopedPDU for a possible Response 1671 message. Provision is made for a message header that allows 1672 the same securityLevel as the received Request. 1674 10) The securityName for the user is retrieved from the 1675 usmUserTable. 1677 11) The security data is cached as cachedSecurityData, so that a 1678 possible response to this message can and will use the same 1679 authentication and privacy secrets, the same securityLevel and 1680 the same value for msgAuthoritativeEngineID. Information to be 1681 saved/cached is as follows: 1683 msgUserName, 1684 usmUserAuthProtocol, usmUserAuthKey 1685 usmUserPrivProtocol, usmUserPrivKey 1686 securityEngineID, securityLevel 1688 12) The statusInformation is set to success and a return is made to 1689 the calling module passing back the OUT parameters as specified 1690 in the processIncomingMsg primitive. 1692 4. Discovery 1694 The User-based Security Model requires that a discovery process 1695 obtains sufficient information about other SNMP engines in order 1696 to communicate with them. Discovery requires an non-authoritative 1697 SNMP engine to learn the authoritative SNMP engine's snmpEngineID 1698 value before communication may proceed. This may be accomplished by 1699 generating a Request message with a securityLevel of noAuthNoPriv, 1700 a msgUserName of "initial", a msgAuthoritativeEngineID value of zero 1701 length, and the varBindList left empty. 1702 The response to this message will be a Report message containing 1703 the snmpEngineID of the authoritative SNMP engine as the value of 1704 the msgAuthoritativeEngineID field within the msgSecurityParameters 1705 field. It contains a Report PDU with the usmStatsUnknownEngineIDs 1706 counter in the varBindList. 1708 If authenticated communication is required, then the discovery 1709 process should also establish time synchronization with the 1710 authoritative SNMP engine. This may be accomplished by sending an 1711 authenticated Request message with the value of 1712 msgAuthoritativeEngineID set to the newly learned snmpEngineID and 1713 with the values of msgAuthoritativeEngineBoots and 1714 msgAuthoritativeEngineTime set to zero. 1715 The response to this authenticated message will be a Report message 1716 containing the up to date values of the authoritative SNMP engine's 1717 snmpEngineBoots and snmpEngineTime as the value of the 1718 msgAuthoritativeEngineBoots and msgAuthoritativeEngineTime fields 1719 respectively. It also contains the usmStatsNotInTimeWindows counter 1720 in the varBindList of the Report PDU. The time synchronization then 1721 happens automatically as part of the procedures in section 3.2 1722 step 7b. See also section 2.3. 1724 5. Definitions 1726 SNMP-USER-BASED-SM-MIB DEFINITIONS ::= BEGIN 1728 IMPORTS 1729 MODULE-IDENTITY, OBJECT-TYPE, 1730 OBJECT-IDENTITY, 1731 snmpModules, Counter32 FROM SNMPv2-SMI 1732 TEXTUAL-CONVENTION, TestAndIncr, 1733 RowStatus, RowPointer, 1734 StorageType, AutonomousType FROM SNMPv2-TC 1735 MODULE-COMPLIANCE, OBJECT-GROUP FROM SNMPv2-CONF 1736 SnmpAdminString, SnmpEngineID, 1737 snmpAuthProtocols, snmpPrivProtocols FROM SNMP-FRAMEWORK-MIB; 1739 snmpUsmMIB MODULE-IDENTITY 1740 LAST-UPDATED "9710280000Z" -- 28 Oct 1997, midnight 5 1741 ORGANIZATION "SNMPv3 Working Group" 1742 CONTACT-INFO "WG-email: snmpv3@tis.com 1743 Subscribe: majordomo@tis.com 1744 In msg body: subscribe snmpv3 1746 Chair: Russ Mundy 1747 Trusted Information Systems 1748 postal: 3060 Washington Rd 1749 Glenwood MD 21738 1750 USA 1751 email: mundy@tis.com 1752 phone: +1-301-854-6889 1754 Co-editor Uri Blumenthal 1755 IBM T. J. Watson Research 1756 postal: 30 Saw Mill River Pkwy, 1757 Hawthorne, NY 10532 1758 USA 1759 email: uri@watson.ibm.com 1760 phone: +1-914-784-7964 1762 Co-editor: Bert Wijnen 1763 IBM T. J. Watson Research 1764 postal: Schagen 33 1765 3461 GL Linschoten 1766 Netherlands 1767 email: wijnen@vnet.ibm.com 1768 phone: +31-348-432-794 1769 " 1771 DESCRIPTION "The management information definitions for the 1772 SNMP User-based Security Model. 1773 " 1774 ::= { snmpModules 9 } -- to be verified with IANA 1776 -- Administrative assignments **************************************** 1778 usmMIBObjects OBJECT IDENTIFIER ::= { snmpUsmMIB 1 } 5 1779 usmMIBConformance OBJECT IDENTIFIER ::= { snmpUsmMIB 2 } 5 1781 -- Identification of Authentication and Privacy Protocols ************ 1783 usmNoAuthProtocol OBJECT-IDENTITY 1784 STATUS current 1785 DESCRIPTION "No Authentication Protocol." 1786 ::= { snmpAuthProtocols 1 } 1788 usmHMACMD5AuthProtocol OBJECT-IDENTITY | 1789 STATUS current | 1790 DESCRIPTION "The HMAC-MD5-96 Digest Authentication Protocol." | 1791 REFERENCE "- H. Krawczyk, M. Bellare, R. Canetti HMAC: | 1792 Keyed-Hashing for Message Authentication, | 1793 RFC2104, Feb 1997. | 1794 - Rivest, R., Message Digest Algorithm MD5, RFC1321. | 1795 " | 1796 ::= { snmpAuthProtocols 2 } | 1797 | 1798 usmHMACSHAAuthProtocol OBJECT-IDENTITY | 1799 STATUS current | 1800 DESCRIPTION "The HMAC-SHA-96 Digest Authentication Protocol." | 1801 REFERENCE "- H. Krawczyk, M. Bellare, R. Canetti, HMAC: | 1802 Keyed-Hashing for Message Authentication, | 1803 RFC2104, Feb 1997. | 1804 - Secure Hash Algorithm. NIST FIPS 180-1. | | 1805 " | 1806 ::= { snmpAuthProtocols 3 } | 1807 | 1808 usmNoPrivProtocol OBJECT-IDENTITY 1809 STATUS current 1810 DESCRIPTION "No Privacy Protocol." 1811 ::= { snmpPrivProtocols 1 } 1813 usmDESPrivProtocol OBJECT-IDENTITY 1814 STATUS current 1815 DESCRIPTION "The CBC-DES Symmetric Encryption Protocol." 1816 REFERENCE "- Data Encryption Standard, National Institute of 1817 Standards and Technology. Federal Information 1818 Processing Standard (FIPS) Publication 46-1. 1819 Supersedes FIPS Publication 46, 1820 (January, 1977; reaffirmed January, 1988). 1822 - Data Encryption Algorithm, American National 1823 Standards Institute. ANSI X3.92-1981, 1824 (December, 1980). 1826 - DES Modes of Operation, National Institute of 1827 Standards and Technology. Federal Information 1828 Processing Standard (FIPS) Publication 81, 1829 (December, 1980). 1831 - Data Encryption Algorithm - Modes of Operation, 1832 American National Standards Institute. 1833 ANSI X3.106-1983, (May 1983). 1834 " 1835 ::= { snmpPrivProtocols 2 } 1837 -- Textual Conventions *********************************************** 1839 -- Editor's note: 1840 -- If in the future the MD5 gets replaced by another Authentication 1841 -- algorithm, then it seems we also need to use that new algorithm to 1842 -- calculate the digest during KeyChange. So this TC has been defined 1843 -- to cater for that. 1844 -- End Editor's note 1846 KeyChange ::= TEXTUAL-CONVENTION 1847 STATUS current 1848 DESCRIPTION 1849 "Every definition of an object with this syntax must identify 1850 a protocol, P, a secret key, K, and a hash algorithm, H | 1851 that produces output of L octets. | 1852 | 1853 The object's value is a manager-generated, partially-random 1854 value which, when modified, causes the value of the secret 1855 key, K, to be modified via a one-way function. 1857 The value of an instance of this object is the concatenation 1858 of two components: a 'random' component and a 'delta' 1859 component. The lengths of the random and delta components 1860 are given by the corresponding value of the protocol, P; 1861 if P requires K to be a fixed length, the length of both the 1862 random and delta components is that fixed length; if P 1863 allows the length of K to be variable up to a particular 1864 maximum length, the length of the random component is that 1865 maximum length and the length of the delta component is any 1866 length less than or equal to that maximum length. 1867 For example, usmHMACMD5AuthProtocol requires K to be a fixed | 1868 length of 16 octets and L - of 16 octets. | 1869 usmHMACSHAAuthProtocol requires K to be a fixed length of | 1870 20 octets and L - of 20 octets. Other protocols may define | 1871 other sizes, as deemed appropriate. | 1873 When an instance of this object is modified to have a new 1874 value by the management protocol, the agent generates a new 1875 value of K as follows: 1877 - a temporary variable is initialized to the existing value 1878 of K; 1879 - if the length of the delta component is greater than 16 1880 octets, then: | 1881 - the random component is appended to the value of the 1882 temporary variable, and the result is input to the 1883 the hash algorithm H to produce a digest value, and 1884 the temporary variable is set to this digest value; 1885 - the value of the temporary variable is XOR-ed with 1886 the first (next) L-octets (16 octets in case of MD5) | 1887 of the delta component to produce the first (next) | 1888 L-octets (16 octets in case of MD5) of the new value | 1889 of K. | 1890 - the above two steps are repeated until the unused 1891 portion of the delta component is 16 octets or less, 1892 - the random component is appended to the value of the 1893 temporary variable, and the result is input to the 1894 hash algorithm H to produce a digest value; 1895 - this digest value, truncated if necessary to be the same 1896 length as the unused portion of the delta component, is 1897 XOR-ed with the unused portion of the delta component to 1898 produce the (final portion of the) new value of K. 1900 for example, using MD5 as the hash algorithm H: 1902 iterations = (lenOfDelta - 1)/16; /* integer division */ 1903 temp = keyOld; 1904 for (i = 0; i < iterations; i++) { 1905 temp = MD5 (temp || random); 1906 keyNew[i*16 .. (i*16)+15] = 1907 temp XOR delta[i*16 .. (i*16)+15]; 1908 } 1909 temp = MD5 (temp || random); 1910 keyNew[i*16 .. lenOfDelta-1] = 1911 temp XOR delta[i*16 .. lenOfDelta-1]; 1913 The value of an object with this syntax, whenever it is 1914 retrieved by the management protocol, is always the zero 1915 length string. 1916 " 1917 SYNTAX OCTET STRING 1919 -- Statistics for the User-based Security Model ********************** 1921 usmStats OBJECT IDENTIFIER ::= { usmMIBObjects 1 } 1923 usmStatsUnsupportedSecLevels OBJECT-TYPE 1924 SYNTAX Counter32 1925 MAX-ACCESS read-only 1926 STATUS current 1927 DESCRIPTION "The total number of packets received by the SNMP 1928 engine which were dropped because they requested a 1929 securityLevel that was unknown to the SNMP engine 1930 or otherwise unavailable. 1931 " 1932 ::= { usmStats 1 } 1934 usmStatsNotInTimeWindows OBJECT-TYPE 1935 SYNTAX Counter32 1936 MAX-ACCESS read-only 1937 STATUS current 1938 DESCRIPTION "The total number of packets received by the SNMP 1939 engine which were dropped because they appeared 1940 outside of the authoritative SNMP engine's window. 1941 " 1942 ::= { usmStats 2 } 1944 usmStatsUnknownUserNames OBJECT-TYPE 1945 SYNTAX Counter32 1946 MAX-ACCESS read-only 1947 STATUS current 1948 DESCRIPTION "The total number of packets received by the SNMP 1949 engine which were dropped because they referenced a 1950 user that was not known to the SNMP engine. 1951 " 1952 ::= { usmStats 3 } 1954 usmStatsUnknownEngineIDs OBJECT-TYPE 1955 SYNTAX Counter32 1956 MAX-ACCESS read-only 1957 STATUS current 1958 DESCRIPTION "The total number of packets received by the SNMP 1959 engine which were dropped because they referenced an 1960 snmpEngineID that was not known to the SNMP engine. 1961 " 1962 ::= { usmStats 4 } 1964 usmStatsWrongDigests OBJECT-TYPE 1965 SYNTAX Counter32 1966 MAX-ACCESS read-only 1967 STATUS current 1968 DESCRIPTION "The total number of packets received by the SNMP 1969 engine which were dropped because they didn't 1970 contain the expected digest value. 1971 " 1972 ::= { usmStats 5 } 1974 usmStatsDecryptionErrors OBJECT-TYPE 1975 SYNTAX Counter32 1976 MAX-ACCESS read-only 1977 STATUS current 1978 DESCRIPTION "The total number of packets received by the SNMP 1979 engine which were dropped because they could not be 1980 decrypted. 1981 " 1982 ::= { usmStats 6 } 1984 -- The usmUser Group ************************************************ 1986 usmUser OBJECT IDENTIFIER ::= { usmMIBObjects 2 } 1988 usmUserSpinLock OBJECT-TYPE 1989 SYNTAX TestAndIncr 1990 MAX-ACCESS read-write 1991 STATUS current 1992 DESCRIPTION "An advisory lock used to allow several cooperating 1993 Command Generator Applications to coordinate their 1994 use of facilities to alter secrets in the 1995 usmUserTable. 1996 " 1997 ::= { usmUser 1 } 1999 -- The table of valid users for the User-based Security Model ******** 2001 usmUserTable OBJECT-TYPE 2002 SYNTAX SEQUENCE OF UsmUserEntry 2003 MAX-ACCESS not-accessible 2004 STATUS current 2005 DESCRIPTION "The table of users configured in the SNMP engine's 2006 Local Configuration Datastore (LCD)." 2007 ::= { usmUser 2 } 2009 usmUserEntry OBJECT-TYPE 2010 SYNTAX UsmUserEntry 2011 MAX-ACCESS not-accessible 2012 STATUS current 2013 DESCRIPTION "A user configured in the SNMP engine's Local 2014 Configuration Datastore (LCD) for the User-based 2015 Security Model. 2016 " 2017 INDEX { usmUserEngineID, 2018 usmUserName 2019 } 2020 ::= { usmUserTable 1 } 2022 UsmUserEntry ::= SEQUENCE 2023 { 2024 usmUserEngineID SnmpEngineID, 2025 usmUserName SnmpAdminString, 2026 usmUserSecurityName SnmpAdminString, 2027 usmUserCloneFrom RowPointer, 2028 usmUserAuthProtocol AutonomousType, 2029 usmUserAuthKeyChange KeyChange, 2030 usmUserOwnAuthKeyChange KeyChange, 2031 usmUserPrivProtocol AutonomousType, 2032 usmUserPrivKeyChange KeyChange, 2033 usmUserOwnPrivKeyChange KeyChange, 2034 usmUserPublic OCTET STRING, 2035 usmUserStorageType StorageType, 2036 usmUserStatus RowStatus 2037 } 2039 usmUserEngineID OBJECT-TYPE 2040 SYNTAX SnmpEngineID 2041 MAX-ACCESS not-accessible 2042 STATUS current 2043 DESCRIPTION "An SNMP engine's administratively-unique identifier. 2045 In a simple agent, this value is always that agent's 2046 own snmpEngineID value. 2048 The value can also take the value of the snmpEngineID 2049 of a remote SNMP engine with which this user can 2050 communicate. 2051 " 2052 ::= { usmUserEntry 1 } 2054 usmUserName OBJECT-TYPE 2055 SYNTAX SnmpAdminString (SIZE(1..32)) 2056 MAX-ACCESS not-accessible 2057 STATUS current 2058 DESCRIPTION "A human readable string representing the name of 2059 the user. 2061 This is the (User-based Security) Model dependent 2062 security ID. 2063 " 2064 ::= { usmUserEntry 2 } 2066 usmUserSecurityName OBJECT-TYPE 2067 SYNTAX SnmpAdminString 2068 MAX-ACCESS read-only 2069 STATUS current 2070 DESCRIPTION "A human readable string representing the user in 2071 Security Model independent format. 2073 The default transformation of the User-based Security 2074 Model dependent security ID to the securityName and 2075 vice versa is the identity function so that the 2076 securityName is the same as the userName. 2077 " 2078 ::= { usmUserEntry 3 } 2080 usmUserCloneFrom OBJECT-TYPE 2081 SYNTAX RowPointer 2082 MAX-ACCESS read-create 2083 STATUS current 2084 DESCRIPTION "A pointer to another conceptual row in this 2085 usmUserTable. The user in this other conceptual 2086 row is called the clone-from user. 2088 When a new user is created (i.e., a new conceptual 2089 row is instantiated in this table), the privacy and 2090 authentication parameters of the new user are cloned 2091 from its clone-from user. 2093 The first time an instance of this object is set by 2094 a management operation (either at or after its 2095 instantiation), the cloning process is invoked. 2096 Subsequent writes are successful but invoke no 2097 action to be taken by the receiver. 2098 The cloning process fails with an 'inconsistentName' 2099 error if the conceptual row representing the 2100 clone-from user is not in an active state when the 2101 cloning process is invoked. 2103 Cloning also causes the initial values of the secret 2104 authentication key and the secret encryption key of 2105 the new user to be set to the same value as the 2106 corresponding secret of the clone-from user. 2108 When this object is read, the ZeroDotZero OID 2109 is returned. 2110 " 2111 ::= { usmUserEntry 4 } 2113 usmUserAuthProtocol OBJECT-TYPE 2114 SYNTAX AutonomousType 2115 MAX-ACCESS read-create 2116 STATUS current 2117 DESCRIPTION "An indication of whether messages sent on behalf of 2118 this user to/from the SNMP engine identified by 2119 usmUserEngineID, can be authenticated, and if so, 2120 the type of authentication protocol which is used. 2122 An instance of this object is created concurrently 2123 with the creation of any other object instance for 2124 the same user (i.e., as part of the processing of 2125 the set operation which creates the first object 2126 instance in the same conceptual row). Once created, 2127 the value of an instance of this object can not be 2128 changed. 2129 | 2130 If a set operation tries to set a value for an unknown | 2131 or unsupported protocol, then a wrongValue error must | 2132 be returned. | 2133 " 2134 DEFVAL { usmHMACMD5AuthProtocol } | 2135 ::= { usmUserEntry 5 } 2137 usmUserAuthKeyChange OBJECT-TYPE 2138 SYNTAX KeyChange -- typically (SIZE (0..32)) 2139 MAX-ACCESS read-create 2140 STATUS current 2141 DESCRIPTION "An object, which when modified, causes the secret 2142 authentication key used for messages sent on behalf 2143 of this user to/from the SNMP engine identified by 2144 usmUserEngineID, to be modified via a one-way 2145 function. 2147 The associated protocol is the usmUserAuthProtocol. 2148 The associated secret key is the user's secret 2149 authentication key (authKey). The associated hash 2150 algorithm is the algorithm used by the user's 2151 usmUserAuthProtocol. 2153 When creating a new user, it is an 'inconsistentName' 2154 error for a Set operation to refer to this object 2155 unless it is previously or concurrently initialized 2156 through a set operation on the corresponding value 2157 of usmUserCloneFrom. 2158 " 2159 DEFVAL { ''H } -- the empty string 2160 ::= { usmUserEntry 6 } 2162 usmUserOwnAuthKeyChange OBJECT-TYPE 2163 SYNTAX KeyChange -- typically (SIZE (0..32)) 2164 MAX-ACCESS read-create 2165 STATUS current 2166 DESCRIPTION "Behaves exactly as usmUserAuthKeyChange, with one 2167 notable difference: in order for the Set operation 2168 to succeed, the usmUserName of the operation 2169 requester must match the usmUserName that 2170 indexes the row which is targeted by this 2171 operation. 2173 The idea here is that access to this column can be 2174 public, since it will only allow a user to change 2175 his own secret authentication key (authKey). 2176 " 2177 DEFVAL { ''H } -- the empty string 2178 ::= { usmUserEntry 7 } 2180 usmUserPrivProtocol OBJECT-TYPE 2181 SYNTAX AutonomousType 2182 MAX-ACCESS read-create 2183 STATUS current 2184 DESCRIPTION "An indication of whether messages sent on behalf of 2185 this user to/from the SNMP engine identified by 2186 usmUserEngineID, can be protected from disclosure, 2187 and if so, the type of privacy protocol which is used. 2189 An instance of this object is created concurrently 2190 with the creation of any other object instance for 2191 the same user (i.e., as part of the processing of 2192 the set operation which creates the first object 2193 instance in the same conceptual row). Once created, 2194 the value of an instance of this object can not be 2195 changed. 2196 | 2197 If a set operation tries to set a value for an unknown | 2198 or unsupported protocol, then a wrongValue error must | 2199 be returned. | 2200 " 2201 DEFVAL { usmNoPrivProtocol } 2202 ::= { usmUserEntry 8 } 2204 usmUserPrivKeyChange OBJECT-TYPE 2205 SYNTAX KeyChange -- typically (SIZE (0..32)) 2206 MAX-ACCESS read-create 2207 STATUS current 2208 DESCRIPTION "An object, which when modified, causes the secret 2209 encryption key used for messages sent on behalf 2210 of this user to/from the SNMP engine identified by 2211 usmUserEngineID, to be modified via a one-way 2212 function. 2214 The associated protocol is the usmUserPrivProtocol. 2215 The associated secret key is the user's secret 2216 privacy key (privKey). The associated hash 2217 algorithm is the algorithm used by the user's 2218 usmUserAuthProtocol. 2220 When creating a new user, it is an 'inconsistentName' 2221 error for a set operation to refer to this object 2222 unless it is previously or concurrently initialized 2223 through a set operation on the corresponding value 2224 of usmUserCloneFrom. 2225 " 2226 DEFVAL { ''H } -- the empty string 2227 ::= { usmUserEntry 9 } 2229 usmUserOwnPrivKeyChange OBJECT-TYPE 2230 SYNTAX KeyChange -- typically (SIZE (0..32)) 2231 MAX-ACCESS read-create 2232 STATUS current 2233 DESCRIPTION "Behaves exactly as usmUserPrivKeyChange, with one 2234 notable difference: in order for the Set operation 2235 to succeed, the usmUserName of the operation 2236 requester must match the usmUserName that indexes 2237 the row which is targeted by this operation. 2239 The idea here is that access to this column can be 2240 public, since it will only allow a user to change 2241 his own secret privacy key (privKey). 2242 " 2243 DEFVAL { ''H } -- the empty string 2244 ::= { usmUserEntry 10 } 2246 usmUserPublic OBJECT-TYPE 2247 SYNTAX OCTET STRING (SIZE(0..32)) 2248 MAX-ACCESS read-create 2249 STATUS current 2250 DESCRIPTION "A publicly-readable value which is written as part 2251 of the procedure for changing a user's secret 2252 authentication and/or privacy key, and later read to 2253 determine whether the change of the secret was 2254 effected. 2255 " 2256 DEFVAL { ''H } -- the empty string 2257 ::= { usmUserEntry 11 } 2259 usmUserStorageType OBJECT-TYPE 2260 SYNTAX StorageType 2261 MAX-ACCESS read-create 2262 STATUS current 2263 DESCRIPTION "The storage type for this conceptual row. 2265 Conceptual rows having the value 'permanent' 2266 must allow write-access at a minimum to: 2268 - usmUserAuthKeyChange, usmUserOwnAuthKeyChange 2269 and usmUserPublic for a user who employs 2270 authentication, and 2271 - usmUserPrivKeyChange, usmUserOwnPrivKeyChange 2272 and usmUserPublic for a user who employs 2273 privacy. 2275 Note that any user who employs authentication or 2276 privacy must allow its secret(s) to be updated and 2277 thus cannot be 'readOnly'. 2278 " 2279 DEFVAL { nonVolatile } 2280 ::= { usmUserEntry 12 } 2282 usmUserStatus OBJECT-TYPE 2283 SYNTAX RowStatus 2284 MAX-ACCESS read-create 2285 STATUS current 2286 DESCRIPTION "The status of this conceptual row. 2288 Until instances of all corresponding columns are 2289 appropriately configured, the value of the 2290 corresponding instance of the usmUserStatus column 2291 is 'notReady'. 2293 In particular, a newly created row cannot be made 2294 active until the corresponding usmUserCloneFrom, 2295 usmUserAuthKeyChange, usmUserOwnAuthKeyChange, 2296 usmUserPrivKeyChange and usmUserOwnPrivKeyChange 2297 have all been set. 2299 The RowStatus TC [RFC1903] requires that this 2300 DESCRIPTION clause states under which circumstances 2301 other objects in this row can be modified: 2303 The value of this object has no effect on whether 2304 other objects in this conceptual row can be modified. 2305 " 2306 ::= { usmUserEntry 13 } 2308 -- Conformance Information ******************************************* 2310 usmMIBCompliances OBJECT IDENTIFIER ::= { usmMIBConformance 1 } 2311 usmMIBGroups OBJECT IDENTIFIER ::= { usmMIBConformance 2 } 2313 -- Compliance statements 2315 usmMIBCompliance MODULE-COMPLIANCE 2316 STATUS current 2317 DESCRIPTION "The compliance statement for SNMP engines which 2318 implement the SNMP-USER-BASED-SM-MIB. 2319 " 2321 MODULE -- this module 2322 MANDATORY-GROUPS { usmMIBBasicGroup } 2324 OBJECT usmUserAuthProtocol 2325 MIN-ACCESS read-only 2326 DESCRIPTION "Write access is not required." 2328 OBJECT usmUserPrivProtocol 2329 MIN-ACCESS read-only 2330 DESCRIPTION "Write access is not required." 2332 ::= { usmMIBCompliances 1 } 2334 -- Units of compliance 2335 usmMIBBasicGroup OBJECT-GROUP 2336 OBJECTS { 2337 usmStatsUnsupportedSecLevels, 2338 usmStatsNotInTimeWindows, 2339 usmStatsUnknownUserNames, 2340 usmStatsUnknownEngineIDs, 2341 usmStatsWrongDigests, 2342 usmStatsDecryptionErrors, 2343 usmUserSpinLock, 2344 usmUserSecurityName, 2345 usmUserCloneFrom, 2346 usmUserAuthProtocol, 2347 usmUserAuthKeyChange, 2348 usmUserOwnAuthKeyChange, 2349 usmUserPrivProtocol, 2350 usmUserPrivKeyChange, 2351 usmUserOwnPrivKeyChange, 2352 usmUserPublic, 2353 usmUserStorageType, 2354 usmUserStatus 2355 } 2356 STATUS current 2357 DESCRIPTION "A collection of objects providing for configuration 2358 of an SNMP engine which implements the SNMP 2359 User-based Security Model. 2360 " 2361 ::= { usmMIBGroups 1 } 2363 END 2364 6. HMAC-MD5-96 Authentication Protocol | 2365 | 2366 This section describes the HMAC-MD5-96 authentication protocol. | 2367 This authentication protocol is the first defined for | 2368 the User-based Security Model. It uses MD5 hash-function which | 2369 is described in [MD5], in HMAC mode described in [RFC2104], | 2370 truncating the output to 96 bits. | 2371 | 2372 This protocol is identified by usmHMACMD5AuthProtocol. | 2374 Over time, other authentication protocols may be defined either 2375 as a replacement of this protocol or in addition to this protocol. 2377 6.1. Mechanisms 2379 - In support of data integrity, a message digest algorithm is 2380 required. A digest is calculated over an appropriate portion 2381 of an SNMP message and included as part of the message sent 2382 to the recipient. 2384 - In support of data origin authentication and data integrity, | 2385 a secret value is prepended to SNMP message prior to computing the | 2386 digest; the calculated digest is partially inserted into the SNMP | 2387 message prior to transmission, and the prepended value is not | 2388 transmitted. The secret value is shared by all SNMP engines | 2389 authorized to originate messages on behalf of the appropriate user. | 2390 3 2391 3 2392 6.1.1. Digest Authentication Mechanism | 2394 The Digest Authentication Mechanism defined in this memo provides | 2395 for: 2397 - verification of the integrity of a received message, i.e., the | 2398 message received is the message sent. | 2400 The integrity of the message is protected by computing a digest 2401 over an appropriate portion of the message. The digest is 2402 computed by the originator of the message, transmitted with the 2403 message, and verified by the recipient of the message. 2405 - verification of the user on whose behalf the message was generated. | 2406 | 2407 A secret value known only to SNMP engines authorized to | 2408 generate messages on behalf of a user is used in HMAC mode | 2409 (see [RFC2104]). It also recommends the hash-function output | 2410 used as Message Authentication Code, to be truncated. | 2412 This protocol uses the MD5 [MD5] message digest algorithm. 2413 A 128-bit MD5 digest is calculated in a special (HMAC) way over | 2414 the designated portion of an SNMP message and the first 96 bits | 2415 o this digest is included as part of the message sent to the | 2416 recipient. The size of the digest carried in a message is 12 | 2417 octets. The size of the private authentication key (the secret) | 2418 is 16 octets. For the details see section 6.3. | 2420 6.2. Elements of the Digest Authentication Protocol 2422 This section contains definitions required to realize the 2423 authentication module defined in this section of this memo. | 2425 6.2.1. Users 2427 Authentication using this authentication protocol makes 2428 use of a defined set of userNames. For any user on whose behalf a 2429 message must be authenticated at a particular SNMP engine, that 2430 SNMP engine must have knowledge of that user. An SNMP engine that 2431 wishes to communicate with another SNMP engine must also have 2432 knowledge of a user known to that engine, including knowledge of 2433 the applicable attributes of that user. 2435 A user and its attributes are defined as follows: 2437 2438 A string representing the name of the user. 2439 2440 A user's secret key to be used when calculating a digest. 2441 It MUST be 16 octets long for MD5. | 2443 6.2.2. msgAuthoritativeEngineID 2445 The msgAuthoritativeEngineID value contained in an authenticated 2446 message specifies the authoritative SNMP engine for that particular 2447 message (see the definition of SnmpEngineID in the SNMP 2448 Architecture document [SNMP-ARCH]). 2450 The user's (private) authentication key is normally different at 2451 each authoritative SNMP engine and so the snmpEngineID is used 2452 to select the proper key for the authentication process. 2454 6.2.3. SNMP Messages Using this Authentication Protocol 2456 Messages using this authentication protocol carry a 2457 msgAuthenticationParameters field as part of the 2458 msgSecurityParameters. For this protocol, the 2459 msgAuthenticationParameters field is the serialized OCTET STRING 2460 representing the first 12 octets of the HMAC-MD5-96 output done | 2461 over the wholeMsg. | 2463 The digest is calculated over the wholeMsg so if a message is 2464 authenticated, that also means that all the fields in the message 2465 are intact and have not been tampered with. 2467 6.2.4. Services provided by the HMAC-MD5-96 Authentication Module | 2468 | 2469 This section describes the inputs and outputs that the HMAC-MD5-96 | 2470 Authentication module expects and produces when the User-based | 2471 Security module calls the HMAC-MD5-96 Authentication module for | 2472 services. | 2474 6.2.4.1. Services for Generating an Outgoing SNMP Message 2476 The HMAC-MD5-96 authentication protocol assumes that the selection | 2477 of the authKey is done by the caller and that the caller passes 2478 the secret key to be used. 2480 Upon completion the authentication module returns statusInformation 2481 and, if the message digest was correctly calculated, the wholeMsg 2482 with the digest inserted at the proper place. The abstract service 2483 primitive is: 2485 statusInformation = -- success or failure 2486 authenticateOutgoingMsg( 2487 IN authKey -- secret key for authentication 2488 IN wholeMsg -- unauthenticated complete message 2489 OUT authenticatedWholeMsg -- complete authenticated message 2490 ) 2492 The abstract data elements are: 2494 statusInformation 2495 An indication of whether the authentication process was 2496 successful. If not it is an indication of the problem. 2497 authKey 2498 The secret key to be used by the authentication algorithm. 2499 The length of this key MUST be 16 octets. | 2500 wholeMsg 2501 The message to be authenticated. 2502 authenticatedWholeMsg 2503 The authenticated message (including inserted digest) on output. 2505 Note, that authParameters field is filled by the authentication 2506 module and this field should be already present in the wholeMsg 2507 before the Message Authentication Code (MAC) is generated. 2509 6.2.4.2. Services for Processing an Incoming SNMP Message 2511 The HMAC-MD5-96 authentication protocol assumes that the selection | 2512 of the authKey is done by the caller and that the caller passes | 2513 the secret key to be used. | 2515 Upon completion the authentication module returns statusInformation 2516 and, if the message digest was correctly calculated, the wholeMsg 2517 as it was processed. The abstract service primitive is: 2519 statusInformation = -- success or failure 2520 authenticateIncomingMsg( 2521 IN authKey -- secret key for authentication 2522 IN authParameters -- as received on the wire 2523 IN wholeMsg -- as received on the wire 2524 OUT authenticatedWholeMsg -- complete authenticated message 2525 ) 2527 The abstract data elements are: 2529 statusInformation 2530 An indication of whether the authentication process was 2531 successful. If not it is an indication of the problem. 2532 authKey 2533 The secret key to be used by the authentication algorithm. 2534 The length of this key MUST be 16 octets. | 2535 authParameters 2536 The authParameters from the incoming message. 2537 wholeMsg 2538 The message to be authenticated on input and the authenticated 2539 message on output. 2540 authenticatedWholeMsg 2541 The whole message after the authentication check is complete. 2543 6.3. Elements of Procedure 2545 This section describes the procedures for the HMAC-MD5-96 | 2546 authentication protocol. 2548 6.3.1. Processing an Outgoing Message 2550 This section describes the procedure followed by an SNMP engine 2551 whenever it must authenticate an outgoing message using the 2552 usmHMACMD5AuthProtocol. | 2554 1) The msgAuthenticationParameters field is set to the 2555 serialization, according to the rules in [RFC1906], of an 2556 OCTET STRING containing 12 zero octets. 5 2557 | 2558 2) From the secret authKey, two keys K1 and K2 are derived: 3 2559 3 2560 a) extend the authKey to 64 octets by appending 48 zero | 2561 octets; save it as extendedAuthKey | 2562 b) obtain IPAD by replicating the octet 0x36 64 times; | 2563 c) obtain K1 by XORing extendedAuthKey with IPAD; | 2564 d) obtain OPAD by replicating the octet 0x5C 64 times; | 2565 e) obtain K2 by XORing extendedAuthKey with OPAD. | 2566 | 2568 4) Prepend K1 to the wholeMsg and calculate MD5 digest over it | 2569 according to [MD5]. | 2570 | 2571 5) Prepend K2 to the result of the step 4 and calculate MD5 digest | 2572 over it according to [MD5]. Take the first 12 octets of the final | 2573 digest - this is Message Authentication Code (MAC). | 2574 | 2575 6) Replace the msgAuthenticationParameters field with MAC obtained | 2576 in the step 5. | 2577 | 2578 7) The authenticatedWholeMsg is then returned to the caller | 2579 together with statusInformation indicating success. | 2580 | 2581 6.3.2. Processing an Incoming Message 2583 This section describes the procedure followed by an SNMP engine 2584 whenever it must authenticate an incoming message using the 2585 usmHMACMD5AuthProtocol. | 2586 | 2587 1) If the digest received in the msgAuthenticationParameters field | 2588 is not 12 octets long, then an failure and an errorIndication | 2589 (authenticationError) is returned to the calling module. | 2590 | 2591 2) The MAC received in the msgAuthenticationParameters field | 2592 is saved. | 2593 | 2594 3) The digest in the msgAuthenticationParameters field is replaced | 2595 by the 12 zero octets. | 2596 | 2597 4) From the secret authKey, two keys K1 and K2 are derived: 3 2598 3 2599 a) extend the authKey to 64 octets by appending 48 zero | 2600 octets; save it as extendedAuthKey | 2601 b) obtain IPAD by replicating the octet 0x36 64 times; | 2602 c) obtain K1 by XORing extendedAuthKey with IPAD; | 2603 d) obtain OPAD by replicating the octet 0x5C 64 times; | 2604 e) obtain K2 by XORing extendedAuthKey with OPAD. | 2605 | 2606 5) The MAC is calculated over the wholeMsg: | 2607 | 2608 a) prepend K1 to the wholeMsg and calculate the MD5 digest | 2609 over it; | 2610 b) prepend K2 to the result of step 5.a and calculate the | 2611 MD5 digest over it; | 2612 c) first 12 octets of the result of step 5.b is the MAC. | 2613 | 2614 The msgAuthenticationParameters field is replaced with the | 2615 MAC value that was saved in step 2. | 2616 | 2617 6) Then the newly calculated MAC is compared with the MAC | 2618 saved in step 2. If they do not match, then an failure | 2619 and an errorIndication (authenticationFailure) is returned to | 2620 the calling module. | 2621 | 2622 7) The authenticatedWholeMsg and statusInformation indicating | 2623 success are then returned to the caller. | 2624 | 2625 | 2627 7. HMAC-SHA-96 Authentication Protocol | 2628 | 2629 This section describes the HMAC-SHA-96 authentication protocol. | 2630 This protocol uses the SHA hash-function which is described in | 2631 [SHA-NIST], in HMAC mode described in [RFC2104], truncating | 2632 the output to 96 bits. | 2633 | 2634 This protocol is identified by usmHMACSHAAuthProtocol. | 2635 | 2636 Over time, other authentication protocols may be defined either | 2637 as a replacement of this protocol or in addition to this protocol. | 2638 | 2639 7.1. Mechanisms | 2640 | 2641 - In support of data integrity, a message digest algorithm is | 2642 required. A digest is calculated over an appropriate portion | 2643 of an SNMP message and included as part of the message sent | 2644 to the recipient. | 2645 | 2646 - In support of data origin authentication and data integrity, | 2647 a secret value is prepended to the SNMP message prior to | 2648 computing the digest; the calculated digest is then partially | 2649 inserted into the message prior to transmission. The prepended | 2650 secret is not transmitted. The secret value is shared by all | 2651 SNMP engines authorized to originate messages on behalf of the | 2652 appropriate user. | 2653 3 2654 3 2655 7.1.1. Digest Authentication Mechanism | 2656 | 2657 The Digest Authentication Mechanism defined in this memo provides | 2658 for: | 2659 | 2660 - verification of the integrity of a received message, i.e., the | 2661 the message received is the message sent. | 2662 | 2663 The integrity of the message is protected by computing a digest | 2664 over an appropriate portion of the message. The digest is | 2665 computed by the originator of the message, transmitted with the | 2666 message, and verified by the recipient of the message. | 2667 | 2668 - verification of the user on whose behalf the message was generated. | 2669 | 2670 A secret value known only to SNMP engines authorized to | 2671 generate messages on behalf of a user is used in HMAC mode | 2672 (see [RFC2104]). It also recommends the hash-function output | 2673 used as Message Authentication Code, to be truncated. | 2674 | 2675 This mechanism uses the SHA [SHA-NIST] message digest algorithm. | 2676 A 160-bit SHA digest is calculated in a special (HMAC) way over | 2677 the designated portion of an SNMP message and the first 96 bits | 2678 of this digest is included as part of the message sent to the | 2679 recipient. The size of the digest carried in a message is 12 | 2680 octets. The size of the private authentication key (the secret) | 2681 is 20 octets. For the details see section 7.3. | 2682 | 2683 7.2. Elements of the HMAC-SHA-96 Authentication Protocol | 2684 | 2685 This section contains definitions required to realize the | 2686 authentication module defined in this section of this memo. | 2687 | 2688 7.2.1. Users | 2689 | 2690 Authentication using this authentication protocol makes use | 2691 of a defined set of userNames. For any user on whose behalf a | 2692 message must be authenticated at a particular SNMP engine, that | 2693 SNMP engine must have knowledge of that user. An SNMP engine that | 2694 wishes to communicate with another SNMP engine must also have | 2695 knowledge of a user known to that engine, including knowledge of | 2696 the applicable attributes of that user. | 2697 | 2698 A user and its attributes are defined as follows: | 2699 | 2700 | 2701 A string representing the name of the user. | 2702 | 2703 A user's secret key to be used when calculating a digest. | 2704 It MUST be 20 octets long for SHA. | 2705 | 2706 7.2.2. msgAuthoritativeEngineID | 2707 | 2708 The msgAuthoritativeEngineID value contained in an authenticated | 2709 message specifies the authoritative SNMP engine for that particular | 2710 message (see the definition of SnmpEngineID in the SNMP | 2711 Architecture document [SNMP-ARCH]). | 2712 | 2713 The user's (private) authentication key is normally different at | 2714 each authoritative SNMP engine and so the snmpEngineID is used | 2715 to select the proper key for the authentication process. | 2716 | 2717 7.2.3. SNMP Messages Using this Authentication Protocol | 2718 | 2719 Messages using this authentication protocol carry a | 2720 msgAuthenticationParameters field as part of the | 2721 msgSecurityParameters. For this protocol, the | 2722 msgAuthenticationParameters field is the serialized | 2723 OCTET STRING representing the first 12 octets of HMAC-SHA-96 | 2724 output done over the wholeMsg. | 2725 | 2726 The digest is calculated over the wholeMsg so if a message is | 2727 authenticated, that also means that all the fields in the | 2728 message are intact and have not been tampered with. | 2729 | 2730 7.2.4. Services provided by the HMAC-SHA-96 Authentication Module | 2731 | 2732 This section describes the inputs and outputs that the HMAC-SHA-96 | 2733 Authentication module expects and produces when the User-based | 2734 Security module calls the HMAC-SHA-96 Authentication module | 2735 for services. | 2736 | 2737 | 2738 7.2.4.1. Services for Generating an Outgoing SNMP Message | 2739 | 2740 HMAC-SHA-96 authentication protocol assumes that the selection | 2741 of the authKey is done by the caller and that the caller passes | 2742 the secret key to be used. | 2743 | 2744 Upon completion the authentication module returns statusInformation | 2745 and, if the message digest was correctly calculated, the wholeMsg | 2746 with the digest inserted at the proper place. The abstract service | 2747 primitive is: | 2748 | 2749 statusInformation = -- success or failure | 2750 authenticateOutgoingMsg( | 2751 IN authKey -- secret key for authentication | 2752 IN wholeMsg -- unauthenticated complete message | 2753 OUT authenticatedWholeMsg -- complete authenticated message | 2754 ) | 2755 | 2756 The abstract data elements are: | 2757 | 2758 statusInformation | 2759 An indication of whether the authentication process was | 2760 successful. If not it is an indication of the problem. | 2761 authKey | 2762 The secret key to be used by the authentication algorithm. | 2763 The length of this key MUST be 20 octets. | 2764 wholeMsg | 2765 The message to be authenticated. | 2766 authenticatedWholeMsg | 2767 The authenticated message (including inserted digest) on output. | 2768 | 2769 Note, that authParameters field is filled by the authentication | 2770 module and this field should be already present in the wholeMsg | 2771 before the Message Authentication Code (MAC) is generated. | 2772 | 2773 7.2.4.2. Services for Processing an Incoming SNMP Message | 2774 | 2775 HMAC-SHA-96 authentication protocol assumes that the selection | 2776 of the authKey is done by the caller and that the caller passes | 2777 the secret key to be used. | 2778 | 2779 Upon completion the authentication module returns statusInformation | 2780 and, if the message digest was correctly calculated, the wholeMsg | 2781 as it was processed. The abstract service primitive is: | 2782 | 2783 statusInformation = -- success or failure | 2784 authenticateIncomingMsg( | 2785 IN authKey -- secret key for authentication | 2786 IN authParameters -- as received on the wire | 2787 IN wholeMsg -- as received on the wire | 2788 OUT authenticatedWholeMsg -- complete authenticated message | 2789 ) | 2790 | 2791 The abstract data elements are: | 2792 | 2793 statusInformation | 2794 An indication of whether the authentication process was | 2795 successful. If not it is an indication of the problem. | 2796 authKey | 2797 The secret key to be used by the authentication algorithm. | 2798 The length of this key MUST be 20 octets. | 2799 authParameters | 2800 The authParameters from the incoming message. | 2801 wholeMsg | 2802 The message to be authenticated on input and the authenticated | 2803 message on output. | 2804 authenticatedWholeMsg | 2805 The whole message after the authentication check is complete. | 2807 7.3. Elements of Procedure | 2808 | 2809 This section describes the procedures for the HMAC-SHA-96 | 2810 authentication protocol. | 2811 | 2812 7.3.1. Processing an Outgoing Message | 2813 | 2814 This section describes the procedure followed by an SNMP engine | 2815 whenever it must authenticate an outgoing message using the | 2816 usmHMACSHAAuthProtocol. | 2817 | 2818 1) The msgAuthenticationParameters field is set to the | 2819 serialization, according to the rules in [RFC1906], of an | 2820 OCTET STRING containing 12 zero octets. | 2821 | 2822 2) From the secret authKey, two keys K1 and K2 are derived: 3 2823 3 2824 a) extend the authKey to 64 octets by appending 44 zero | 2825 octets; save it as extendedAuthKey | 2826 b) obtain IPAD by replicating the octet 0x36 64 times; | 2827 c) obtain K1 by XORing extendedAuthKey with IPAD; | 2828 d) obtain OPAD by replicating the octet 0x5C 64 times; | 2829 e) obtain K2 by XORing extendedAuthKey with OPAD. | 2830 | 2832 4) Prepend K1 to the wholeMsg and calculate the SHA digest over it | 2833 according to [SHA-NIST]. | 2834 | 2835 5) Prepend K2 to the result of the step 4 and calculate SHA digest | 2836 over it according to [SHA-NIST]. Take the first 12 octets of the | 2837 final digest - this is Message Authentication Code (MAC). | 2838 | 2839 6) Replace the msgAuthenticationParameters field with MAC obtained | 2840 in the step 5. | 2841 | 2842 7) The authenticatedWholeMsg is then returned to the caller | 2843 together with statusInformation indicating success. | 2844 | 2845 7.3.2. Processing an Incoming Message | 2846 | 2847 This section describes the procedure followed by an SNMP engine | 2848 whenever it must authenticate an incoming message using the | 2849 usmHMACSHAAuthProtocol. | 2850 | 2851 1) If the digest received in the msgAuthenticationParameters field | 2852 is not 12 octets long, then an failure and an errorIndication | 2853 (authenticationError) is returned to the calling module. | 2854 | 2855 2) The MAC received in the msgAuthenticationParameters field | 2856 is saved. | 2857 | 2858 3) The digest in the msgAuthenticationParameters field is | 2859 replaced by the 12 zero octets. | 2860 | 2861 4) From the secret authKey, two keys K1 and K2 are derived: 3 2862 3 2863 a) extend the authKey to 64 octets by appending 44 zero | 2864 octets; save it as extendedAuthKey | 2865 b) obtain IPAD by replicating the octet 0x36 64 times; | 2866 c) obtain K1 by XORing extendedAuthKey with IPAD; | 2867 d) obtain OPAD by replicating the octet 0x5C 64 times; | 2868 e) obtain K2 by XORing extendedAuthKey with OPAD. | 2869 | 2870 5) The MAC is calculated over the wholeMsg: | 2871 | 2872 a) prepend K1 to the wholeMsg and calculate the SHA digest | 2873 over it; | 2874 b) prepend K2 to the result of step 5.a and calculate the | 2875 SHA digest over it; | 2876 c) first 12 octets of the result of step 5.b is the MAC. | 2877 | 2878 The msgAuthenticationParameters field is replaced with the | 2879 MAC value that was saved in step 2. | 2880 | 2881 6) The the newly calculated MAC is compared with the MAC saved in | 2882 step 2. If they do not match, then a failure and an | 2883 errorIndication (authenticationFailure) are returned to the | 2884 calling module. | 2885 | 2886 7) The authenticatedWholeMsg and statusInformation indicating | 2887 success are then returned to the caller. | 2888 | 2889 | 2891 8. CBC-DES Symmetric Encryption Protocol | 2892 | 2893 This section describes the CBC-DES Symmetric Encryption Protocol. | 2894 This protocol is the first privacy protocol defined for the 2895 User-based Security Model. 2897 This protocol is identified by usmDESPrivProtocol. 2899 Over time, other privacy protocols may be defined either 2900 as a replacement of this protocol or in addition to this protocol. 2902 8.1. Mechanisms | 2904 - In support of data confidentiality, an encryption algorithm is 2905 required. An appropriate portion of the message is encrypted 2906 prior to being transmitted. The User-based Security Model 2907 specifies that the scopedPDU is the portion of the message 2908 that needs to be encrypted. 2910 - A secret value in combination with a timeliness value is used 2911 to create the en/decryption key and the initialization vector. 2912 The secret value is shared by all SNMP engines authorized to 2913 originate messages on behalf of the appropriate user. 2914 3 2915 3 2916 8.1.1. Symmetric Encryption Protocol | 2918 The Symmetric Encryption Protocol defined in this memo provides 2919 support for data confidentiality. The designated portion of an 2920 SNMP message is encrypted and included as part of the message 2921 sent to the recipient. 2923 Two organizations have published specifications defining the DES: 2924 the National Institute of Standards and Technology (NIST) 2925 [DES-NIST] and the American National Standards Institute 2926 [DES-ANSI]. There is a companion Modes of Operation specification 2927 for each definition ([DESO-NIST] and [DESO-ANSI], respectively). 2929 The NIST has published three additional documents that implementors 2930 may find useful. 2932 - There is a document with guidelines for implementing and using 2933 the DES, including functional specifications for the DES and 2934 its modes of operation [DESG-NIST]. 2936 - There is a specification of a validation test suite for the DES 2937 [DEST-NIST]. The suite is designed to test all aspects of the 2938 DES and is useful for pinpointing specific problems. 2940 - There is a specification of a maintenance test for the DES 2942 [DESM-NIST]. The test utilizes a minimal amount of data and 2943 processing to test all components of the DES. It provides a 2944 simple yes-or-no indication of correct operation and is useful 2945 to run as part of an initialization step, e.g., when a computer 2946 re-boots. 2948 8.1.1.1. DES key and Initialization Vector. | 2950 The first 8 octets of the 16-octet secret (private privacy key) are | 2951 used as a DES key. Since DES uses only 56 bits, the Least 2952 Significant Bit in each octet is disregarded. | 2954 The Initialization Vector for encryption is obtained using the 2955 following procedure. 2957 The last 8 octets of the 16-octet secret (private privacy key) | 2958 are used as pre-IV. 2960 In order to ensure that the IV for two different packets encrypted 2961 by the same key, are not the same (i.e., the IV does not repeat) we | 2962 need to "salt" the pre-IV with something unique per packet. 2963 An 8-octet string is used as the "salt". The concatenation | 2964 of the generating SNMP engine's 32-bit snmpEngineBoots and a local 2965 32-bit integer, that the encryption engine maintains, is input to 2966 the "salt". The 32-bit integer is initialized to an arbitrary 2967 value at boot time. 2968 The 32-bit snmpEngineBoots is converted to the first 4 octets | 2969 (Most Significant Byte first) of our "salt". The 32-bit integer 2970 is then converted to the last 4 octet (Most Significant Byte first) | 2971 of our "salt". The resulting "salt" is then XOR-ed with the 2972 pre-IV. The 8-octet "salt" is then put into the privParameters 2973 field encoded as an OCTET STRING. The "salt" integer is then 2974 modified. We recommend that it be incremented by one and wrap 2975 when it reaches the maximum value. 2977 How exactly the value of the "salt" (and thus of the IV) varies, 2978 is an implementation issue, as long as the measures are taken to 2979 avoid producing a duplicate IV. 2981 The "salt" must be placed in the privParameters field to enable the 2982 receiving entity to compute the correct IV and to decrypt the 2983 message. 2985 8.1.1.2. Data Encryption. | 2987 The data to be encrypted is treated as sequence of octets. Its 2988 length should be an integral multiple of 8 - and if it is not, the 2989 data is padded at the end as necessary. The actual pad value 2990 is irrelevant. 2992 The data is encrypted in Cipher Block Chaining mode. 2994 The plaintext is divided into 64-bit blocks. 2996 The plaintext for each block is XOR-ed with the ciphertext 2997 of the previous block, the result is encrypted and the output 2998 of the encryption is the ciphertext for the block. 2999 This procedure is repeated until there are no more plaintext 3000 blocks. 3002 For the very first block, the Initialization Vector is used 3003 instead of the ciphertext of the previous block. 3005 8.1.1.3. Data Decryption | 3007 Before decryption, the encrypted data length is verified. 3008 If the length of the OCTET STRING to be decrypted is not an 3009 integral multiple of 8 octets, the decryption process is halted 3010 and an appropriate exception noted. When decrypting, the padding 3011 is ignored. 3013 The first ciphertext block is decrypted, the decryption output is 3014 XOR-ed with the Initialization Vector, and the result is the first 3015 plaintext block. 3017 For each subsequent block, the ciphertext block is decrypted, 3018 the decryption output is XOR-ed with the previous ciphertext 3019 block and the result is the plaintext block. 3021 8.2. Elements of the DES Privacy Protocol | 3023 This section contains definitions required to realize the privacy 3024 module defined by this memo. 3026 8.2.1. Users | 3028 Data en/decryption using this Symmetric Encryption Protocol makes 3029 use of a defined set of userNames. For any user on whose behalf 3030 a message must be en/decrypted at a particular SNMP engine, that 3031 SNMP engine must have knowledge of that user. An SNMP engine that 3032 wishes to communicate with another SNMP engine must also have 3033 knowledge of a user known to that SNMP engine, including knowledge 3034 of the applicable attributes of that user. 3036 A user and its attributes are defined as follows: 3038 3039 An octet string representing the name of the user. 3040 3041 A user's secret key to be used as input for the DES key and IV. 3042 The length of this key MUST be 16 octets. | 3044 8.2.2. msgAuthoritativeEngineID | 3045 The msgAuthoritativeEngineID value contained in an authenticated 3046 message specifies the authoritative SNMP engine for that particular 3047 message (see the definition of SnmpEngineID in the SNMP 3048 Architecture document [SNMP-ARCH]). 3050 The user's (private) privacy key is normally different at each 3051 authoritative SNMP engine and so the snmpEngineID is used to select 3052 the proper key for the en/decryption process. 3054 8.2.3. SNMP Messages Using this Privacy Protocol | 3056 Messages using this privacy protocol carry a msgPrivacyParameters 3057 field as part of the msgSecurityParameters. For this protocol, the 3058 msgPrivacyParameters field is the serialized OCTET STRING 3059 representing the "salt" that was used to create the IV. 3061 8.2.4. Services provided by the DES Privacy Module | 3063 This section describes the inputs and outputs that the DES Privacy 3064 module expects and produces when the User-based Security module 3065 invokes the DES Privacy module for services. 3067 8.2.4.1. Services for Encrypting Outgoing Data | 3069 This DES privacy protocol assumes that the selection of the 3070 privKey is done by the caller and that the caller passes 3071 the secret key to be used. 3073 Upon completion the privacy module returns statusInformation 3074 and, if the encryption process was successful, the encryptedPDU 3075 and the msgPrivacyParameters encoded as an OCTET STRING. 3076 The abstract service primitive is: 3078 statusInformation = -- success of failure 3079 encryptData( 3080 IN encryptKey -- secret key for encryption 3081 IN dataToEncrypt -- data to encrypt (scopedPDU) 3082 OUT encryptedData -- encrypted data (encryptedPDU) 3083 OUT privParameters -- filled in by service provider 3084 ) 3086 The abstract data elements are: 3088 statusInformation 3089 An indication of the success or failure of the encryption 3090 process. In case of failure, it is an indication of the error. 3091 encryptKey 3092 The secret key to be used by the encryption algorithm. 3093 The length of this key MUST be 16 octets. | 3094 dataToEncrypt 3095 The data that must be encrypted. 3096 encryptedData 3097 The encrypted data upon successful completion. 3098 privParameters 3099 The privParameters encoded as an OCTET STRING. 3101 8.2.4.2. Services for Decrypting Incoming Data | 3103 This DES privacy protocol assumes that the selection of the 3104 privKey is done by the caller and that the caller passes 3105 the secret key to be used. 3107 Upon completion the privacy module returns statusInformation 3108 and, if the decryption process was successful, the scopedPDU 3109 in plain text. The abstract service primitive is: 3111 statusInformation = 3112 decryptData( 3113 IN decryptKey -- secret key for decryption 3114 IN privParameters -- as received on the wire 3115 IN encryptedData -- encrypted data (encryptedPDU) 3116 OUT decryptedData -- decrypted data (scopedPDU) 3117 ) 3119 The abstract data elements are: 3121 statusInformation 3122 An indication whether the data was successfully decrypted 3123 and if not an indication of the error. 3124 decryptKey 3125 The secret key to be used by the decryption algorithm. 3126 The length of this key MUST be 16 octets. | 3127 privParameters 3128 The "salt" to be used to calculate the IV. 3129 encryptedData 3130 The data to be decrypted. 3131 decryptedData 3132 The decrypted data. 3134 8.3. Elements of Procedure. | 3136 This section describes the procedures for the DES privacy protocol. 3138 8.3.1. Processing an Outgoing Message | 3140 This section describes the procedure followed by an SNMP engine 3141 whenever it must encrypt part of an outgoing message using the 3142 usmDESPrivProtocol. 3144 1) The secret cryptKey is used to construct the DES encryption key, 3 3145 the "salt" and the DES pre-IV (as described in section 8.1.1.1). 3 3147 2) The privParameters field is set to the serialization according 3148 to the rules in [RFC1906] of an OCTET STRING representing the 3149 the "salt" string. 3151 3) The scopedPDU is encrypted (as described in section 8.1.1.2) | 3152 and the encrypted data is serialized according to the rules 3153 in [RFC1906] as an OCTET STRING. 3155 4) The serialized OCTET STRING representing the encrypted 3156 scopedPDU together with the privParameters and statusInformation 3157 indicating success is returned to the calling module. 3159 8.3.2. Processing an Incoming Message | 3161 This section describes the procedure followed by an SNMP engine 3162 whenever it must decrypt part of an incoming message using the 3163 usmDESPrivProtocol. 3165 1) If the privParameters field is not an 8-octet OCTET STRING, | 3166 then an error indication (decryptionError) is returned to 3167 the calling module. 3169 2) The "salt" is extracted from the privParameters field. 3171 3) The secret cryptKey and the "salt" are then used to construct the 3 3172 DES decryption key and pre-IV (as described in section 8.1.1.1). 3 3174 4) The encryptedPDU is then decrypted (as described in 3175 section 8.1.1.3). | 3177 5) If the encryptedPDU cannot be decrypted, then an error 3178 indication (decryptionError) is returned to the calling module. 3180 6) The decrypted scopedPDU and statusInformation indicating 3181 success are returned to the calling module. 3183 9. Intellectual Property 3185 The IETF takes no position regarding the validity or scope of any 5 3186 intellectual property or other rights that might be claimed to 5 3187 pertain to the implementation or use of the technology described in 5 3188 this document or the extent to which any license under such rights 5 3189 might or might not be available; neither does it represent that it 5 3190 has made any effort to identify any such rights. Information on the 5 3191 IETF's procedures with respect to rights in standards-track and 5 3192 standards-related documentation can be found in BCP-11. Copies of 5 3193 claims of rights made available for publication and any assurances of 5 3194 licenses to be made available, or the result of an attempt made to 5 3195 obtain a general license or permission for the use of such 5 3196 proprietary rights by implementors or users of this specification can 5 3197 be obtained from the IETF Secretariat. 5 3198 5 3199 The IETF invites any interested party to bring to its attention any 5 3200 copyrights, patents or patent applications, or other proprietary 5 3201 rights which may cover technology that may be required to practice 5 3202 this standard. Please address the information to the IETF Executive 5 3203 Director. 5 3205 10. Acknowledgements 3207 This document is the result of the efforts of the SNMPv3 Working Group. 3208 Some special thanks are in order to the following SNMPv3 WG members: 3210 Dave Battle (SNMP Research, Inc.) 3211 Uri Blumenthal (IBM T.J. Watson Research Center) 3212 Jeff Case (SNMP Research, Inc.) 3213 John Curran (BBN) 3214 T. Max Devlin (Hi-TECH Connections) 3215 John Flick (Hewlett Packard) 3216 David Harrington (Cabletron Systems Inc.) 3217 N.C. Hien (IBM T.J. Watson Research Center) 3218 Dave Levi (SNMP Research, Inc.) 3219 Louis A Mamakos (UUNET Technologies Inc.) 3220 Paul Meyer (Secure Computing Corporation) 3221 Keith McCloghrie (Cisco Systems) 3222 Russ Mundy (Trusted Information Systems, Inc.) 3223 Bob Natale (ACE*COMM Corporation) 3224 Mike O'Dell (UUNET Technologies Inc.) 3225 Dave Perkins (DeskTalk) 3226 Peter Polkinghorne (Brunel University) 3227 Randy Presuhn (BMC Software, Inc.) 3228 David Reid (SNMP Research, Inc.) 3229 Shawn Routhier (Epilogue) 3230 Juergen Schoenwaelder (TU Braunschweig) 3231 Bob Stewart (Cisco Systems) 3232 Bert Wijnen (IBM T.J. Watson Research Center) 3234 The document is based on recommendations of the IETF Security and 3235 Administrative Framework Evolution for SNMP Advisory Team. 3236 Members of that Advisory Team were: 3238 David Harrington (Cabletron Systems Inc.) 3239 Jeff Johnson (Cisco Systems) 3240 David Levi (SNMP Research Inc.) 3241 John Linn (Openvision) 3242 Russ Mundy (Trusted Information Systems) chair 3243 Shawn Routhier (Epilogue) 3244 Glenn Waters (Nortel) 3245 Bert Wijnen (IBM T. J. Watson Research Center) 3247 As recommended by the Advisory Team and the SNMPv3 Working Group 3248 Charter, the design incorporates as much as practical from previous 3249 RFCs and drafts. As a result, special thanks are due to the authors 3250 of previous designs known as SNMPv2u and SNMPv2*: 3252 Jeff Case (SNMP Research, Inc.) 3253 David Harrington (Cabletron Systems Inc.) 3254 David Levi (SNMP Research, Inc.) 3255 Keith McCloghrie (Cisco Systems) 3256 Brian O'Keefe (Hewlett Packard) 3257 Marshall T. Rose (Dover Beach Consulting) 3258 Jon Saperia (BGS Systems Inc.) 3259 Steve Waldbusser (International Network Services) 3260 Glenn W. Waters (Bell-Northern Research Ltd.) 3262 11. Security Considerations | 3264 11.1. Recommended Practices | 3266 This section describes practices that contribute to the secure, 3267 effective operation of the mechanisms defined in this memo. 3269 - An SNMP engine must discard SNMP Response messages that do not 3270 correspond to any currently outstanding Request message. It is 3271 the responsibility of the Message Processing module to take care 3272 of this. For example it can use a msgID for that. 3274 An SNMP Command Generator Application must discard any Response 3275 PDU for which there is no currently outstanding Request PDU; 3276 for example for SNMPv2 [RFC1905] PDUs, the request-id component 3277 in the PDU can be used to correlate Responses to outstanding 3278 Requests. 3280 Although it would be typical for an SNMP engine and an SNMP 3281 Command Generator Application to do this as a matter of course, 3282 when using these security protocols it is significant due to 3283 the possibility of message duplication (malicious or otherwise). 3285 - If an SNMP engine uses a msgID for correlating Response messages 3286 to outstanding Request messages, then it MUST use different 3287 msgIDs in all such Request messages that it sends out during a 3288 Time Window (150 seconds) period. 3290 A Command Generator or Notification Originator Application MUST 3291 use different request-ids in all Request PDUs that it sends out 3292 during a TimeWindow (150 seconds) period. 3294 This must be done to protect against the possibility of message 3295 duplication (malicious or otherwise). 3297 For example, starting operations with a msgID and/or request-id 3298 value of zero is not a good idea. Initializing them with an 3299 unpredictable number (so they do not start out the same after 3300 each reboot) and then incrementing by one would be acceptable. 3302 - An SNMP engine should perform time synchronization using 3303 authenticated messages in order to protect against the 3304 possibility of message duplication (malicious or otherwise). 3306 - When sending state altering messages to a managed authoritative 3307 SNMP engine, a Command Generator Application should delay sending 3308 successive messages to that managed SNMP engine until a positive 3309 acknowledgement is received for the previous message or until 3310 the previous message expires. 3312 No message ordering is imposed by the SNMP. Messages may be 3313 received in any order relative to their time of generation and 3314 each will be processed in the ordered received. Note that when 3315 an authenticated message is sent to a managed SNMP engine, it 3316 will be valid for a period of time of approximately 150 seconds 3317 under normal circumstances, and is subject to replay during this 3318 period. Indeed, an SNMP engine and SNMP Command Generator 3319 Applications must cope with the loss and re-ordering of messages 3320 resulting from anomalies in the network as a matter of course. 3322 However, a managed object, snmpSetSerialNo [RFC1907], is 3323 specifically defined for use with SNMP Set operations in order 3324 to provide a mechanism to ensure that the processing of SNMP 3325 messages occurs in a specific order. 3327 - The frequency with which the secrets of a User-based Security 3328 Model user should be changed is indirectly related to the 3329 frequency of their use. 3331 Protecting the secrets from disclosure is critical to the overall 3332 security of the protocols. Frequent use of a secret provides a 3333 continued source of data that may be useful to a cryptanalyst in 3334 exploiting known or perceived weaknesses in an algorithm. 3335 Frequent changes to the secret avoid this vulnerability. 3337 Changing a secret after each use is generally regarded as the 3338 most secure practice, but a significant amount of overhead may 3339 be associated with that approach. 3341 Note, too, in a local environment the threat of disclosure may be 3342 less significant, and as such the changing of secrets may be less 3343 frequent. However, when public data networks are used as the 3344 communication paths, more caution is prudent. 3346 11.2 Defining Users | 3348 The mechanisms defined in this document employ the notion of users 3349 on whose behalf messages are sent. How "users" are defined is 3350 subject to the security policy of the network administration. 3351 For example, users could be individuals (e.g., "joe" or "jane"), 3352 or a particular role (e.g., "operator" or "administrator"), or a 3353 combination (e.g., "joe-operator", "jane-operator" or "joe-admin"). 3354 Furthermore, a user may be a logical entity, such as an SNMP 3355 Application or a set of SNMP Applications, acting on behalf of an 3356 individual or role, or set of individuals, or set of roles, 3357 including combinations. 3359 Appendix A describes an algorithm for mapping a user "password" to 3360 a 16 octet value for use as either a user's authentication key or 3361 privacy key (or both). Note however, that using the same password 3362 (and therefore the same key) for both authentication and privacy 3363 is very poor security practice and should be strongly discouraged. 3364 Passwords are often generated, remembered, and input by a human. 3365 Human-generated passwords may be less than the 16 octets required 3366 by the authentication and privacy protocols, and brute force 3367 attacks can be quite easy on a relatively short ASCII character 3368 set. Therefore, the algorithm is Appendix A performs a 3369 transformation on the password. If the Appendix A algorithm is 3370 used, SNMP implementations (and SNMP configuration applications) 3371 must ensure that passwords are at least 8 characters in length. 3373 Because the Appendix A algorithm uses such passwords (nearly) 3374 directly, it is very important that they not be easily guessed. 3375 It is suggested that they be composed of mixed-case alphanumeric 3376 and punctuation characters that don't form words or phrases that 3377 might be found in a dictionary. Longer passwords improve the 3378 security of the system. Users may wish to input multiword 3379 phrases to make their password string longer while ensuring that 3380 it is memorable. 3382 Since it is infeasible for human users to maintain different 3383 passwords for every SNMP engine, but security requirements 3384 strongly discourage having the same key for more than one SNMP 3385 engine, the User-based Security Model employs a compromise 3386 proposed in [Localized-key]. It derives the user keys for the 3387 SNMP engines from user's password in such a way that it is 3388 practically impossible to either determine the user's password, 3389 or user's key for another SNMP engine from any combination of 3390 user's keys on SNMP engines. 3392 Note however, that if user's password is disclosed, then key 3393 localization will not help and network security may be compromised 3 3394 in this case. Therefore a user's password or non-localized key 3 3395 MUST NOT be stored on a managed device/node. Instead the 4 3396 localized key SHALL be stored (if at all) , so that, in case a 4 3397 device does get compromised, no other managed or managing devices 4 3398 get compromised. 3 3400 11.3. Conformance | 3402 To be termed a "Secure SNMP implementation" based on the 3403 User-based Security Model, an SNMP implementation MUST: 3405 - implement one or more Authentication Protocol(s). The HMAC-MD5-96 | 3406 and HMAC-SHA-96 Authentication Protocols defined in this memo are | 3407 examples of such protocols. | 3409 - to the maximum extent possible, prohibit access to the secret(s) | 3410 of each user about which it maintains information in a Local | 3411 Configuration Datastore (LCD) under all circumstances except as | 3412 required to generate and/or validate SNMP messages with respect | 3413 to that user. | 3415 - implement the key-localization mechanism. 3417 - implement the SNMP-USER-BASED-SM-MIB. | 3419 In addition, an authoritative SNMP engine SHOULD provide initial | 3420 configuration in accordance with Appendix A.1. | 3422 Implementation of a Privacy Protocol (the DES Symmetric Encryption 3423 Protocol defined in this memo is one such protocol) is optional. 3425 12. References | 3427 [RFC1903] The SNMPv2 Working Group, Case, J., McCloghrie, K., Rose, M., | 3428 and S. Waldbusser, "Textual Conventions for Version 2 of the Simple | 3429 Network Management Protocol (SNMPv2)", RFC 1903, January 1996. | 3430 | 3431 [RFC1905] The SNMPv2 Working Group, Case, J., McCloghrie, K., 3432 Rose, M., and S., Waldbusser, "Protocol Operations for 3433 Version 2 of the Simple Network Management Protocol (SNMPv2)", 3434 RFC 1905, January 1996. 3436 [RFC1906] The SNMPv2 Working Group, Case, J., McCloghrie, K., 3437 Rose, M., and S. Waldbusser, "Transport Mappings for 3438 Version 2 of the Simple Network Management Protocol (SNMPv2)", 3439 RFC 1906, January 1996. 3441 [RFC1907] The SNMPv2 Working Group, Case, J., McCloghrie, K., 3442 Rose, M., and S. Waldbusser, "Management Information Base for 3443 Version 2 of the Simple Network Management Protocol (SNMPv2)", 3444 RFC 1907 January 1996. 3446 [RFC2104] Network Working Group, H. Krawczyk, M. Bellare, R. Canetti, | 3447 "HMAC: Keyed-Hashing for Message Authentication", RFC 2104, | 3448 February 1997. | 3450 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 4 3451 Requirement Levels", BCP 14, RFC 2119, March 1997. 4 3453 [BCP-11] Hovey, R., and S. Bradner, "The Organizations Involved in 5 3454 the IETF Standards Process", BCP 11, RFC 2028, October 1996. 5 3456 [SNMP-ARCH] The SNMPv3 Working Group, Harrington, D., Wijnen, B., 3 3457 Presuhn, R., "An Architecture for describing SNMP Management 3 3458 Frameworks", draft-ietf-snmpv3-next-gen-arch-06.txt, 5 3459 October 1997. 5 3461 [SNMP-USM] The SNMPv3 Working Group, Blumenthal, U., Wijnen, B., 3462 "The User-Based Security Model for Version 3 of the Simple 3463 Network Management Protocol (SNMPv3)", 3464 draft-ietf-snmpv3-usm-03.txt, October 1997. 5 3466 [Localized-Key] U. Blumenthal, N. C. Hien, B. Wijnen 3467 "Key Derivation for Network Management Applications" 3468 IEEE Network Magazine, April/May issue, 1997. 3470 [MD5] Rivest, R., "Message Digest Algorithm MD5", 3471 RFC 1321, April 1992. 3473 [DES-NIST] Data Encryption Standard, National Institute of Standards 3474 and Technology. Federal Information Processing Standard (FIPS) 3475 Publication 46-1. Supersedes FIPS Publication 46, (January, 1977; 3476 reaffirmed January, 1988). 3478 [DES-ANSI] Data Encryption Algorithm, American National Standards 3479 Institute. ANSI X3.92-1981, (December, 1980). 3481 [DESO-NIST] DES Modes of Operation, National Institute of Standards and 3482 Technology. Federal Information Processing Standard (FIPS) 3483 Publication 81, (December, 1980). 3485 [DESO-ANSI] Data Encryption Algorithm - Modes of Operation, American 3486 National Standards Institute. ANSI X3.106-1983, (May 1983). 3488 [DESG-NIST] Guidelines for Implementing and Using the NBS Data 3489 Encryption Standard, National Institute of Standards and 3490 Technology. Federal Information Processing Standard (FIPS) 3491 Publication 74, (April, 1981). 3493 [DEST-NIST] Validating the Correctness of Hardware Implementations of 3494 the NBS Data Encryption Standard, National Institute of Standards 3495 and Technology. Special Publication 500-20. 3497 [DESM-NIST] Maintenance Testing for the Data Encryption Standard, 3498 National Institute of Standards and Technology. 3499 Special Publication 500-61, (August, 1980). 3501 [SHA-NIST] Secure Hash Algorithm. NIST FIPS 180-1, (April, 1995) 4 3502 http://csrc.nist.gov/fips/fip180-1.txt (ASCII) 4 3503 http://csrc.nist.gov/fips/fip180-1.ps (Postscript) 4 3505 13. Editors' Addresses 5 3507 Co-editor Uri Blumenthal 3508 IBM T. J. Watson Research 3509 postal: 30 Saw Mill River Pkwy, 3510 Hawthorne, NY 10532 3511 USA 3512 email: uri@watson.ibm.com 3513 phone: +1-914-784-7064 3515 Co-editor: Bert Wijnen 3516 IBM T. J. Watson Research 3517 postal: Schagen 33 3518 3461 GL Linschoten 3519 Netherlands 3520 email: wijnen@vnet.ibm.com 3521 phone: +31-348-432-794 3523 APPENDIX A - Installation 3525 A.1. SNMP engine Installation Parameters 3527 During installation, an authoritative SNMP engine SHOULD (in the 3528 meaning as defined in [RFC2119]) be configured with several initial 3529 parameters. These include: 3531 1) A security posture 3533 The choice of security posture determines if initial configuration 3534 is implemented and if so how. One of three possible choices 3535 is selected: 3537 minimum-secure, 3538 semi-secure, 3539 very-secure (i.e., no-initial-configuration) 3541 In the case of a very-secure posture, there is no initial 3542 configuration, and so the following steps are irrelevant. 3544 2) one or more secrets 3546 These are the authentication/privacy secrets for the first user 3547 to be configured. 3549 One way to accomplish this is to have the installer enter a 3550 "password" for each required secret. The password is then 3551 algorithmically converted into the required secret by: 3553 - forming a string of length 1,048,576 octets by repeating the 3554 value of the password as often as necessary, truncating 3555 accordingly, and using the resulting string as the input to 3556 the MD5 algorithm [MD5]. The resulting digest, termed 3557 "digest1", is used in the next step. 3559 - a second string is formed by concatenating digest1, the SNMP 3560 engine's snmpEngineID value, and digest1. 3561 This string is used as input to the MD5 algorithm [MD5]. 3563 The resulting digest is the required secret (see Appendix A.2). 3565 With these configured parameters, the SNMP engine instantiates 3566 the following usmUserEntry in the usmUserTable: 3568 no privacy support privacy support 3569 ------------------ --------------- 3570 usmUserEngineID localEngineID localEngineID 3571 usmUserName "initial" "initial" 3572 usmUserSecurityName "initial" "initial" 3573 usmUserCloneFrom ZeroDotZero ZeroDotZero 3574 usmUserAuthProtocol usmHMACMD5AuthProtocol usmHMACMD5AuthProtocol | 3575 usmUserAuthKeyChange "" "" 3576 usmUserOwnAuthKeyChange "" "" 3577 usmUserPrivProtocol none usmDESPrivProtocol 3578 usmUserPrivKeyChange "" "" 3579 usmUserOwnPrivKeyChange "" "" 3580 usmUserPublic "" "" 3581 usmUserStorageType anyValidStorageType anyValidStorageType 3582 usmUserStatus active active 3584 A.2. Password to Key Algorithm 3586 A sample code fragment (section A.2.1) demonstrates the password to 3 3587 key algorithm which can be used when mapping a password to an 3 3588 authentication or privacy key using MD5. The reference source code 4 3589 of MD5 is available in [RFC1321]. 4 3590 3 3591 Another sample code fragment (section A.2.2) demonstrates the 3 3592 password to key algorithm which can be used when mapping a password 3 3593 to an authentication or privacy key using SHA (documented in 4 3594 SHA-NIST). 4 3596 An example of the results of a correct implementation is provided 3597 (section A.3) which an implementor can use to check if his 3 3598 implementation produces the same result. 3600 A.2.1. Password to Key Sample Code for MD5 3 3602 void password_to_key_md5( 3 3603 u_char *password, /* IN */ 3604 u_int passwordlen, /* IN */ 3605 u_char *engineID, /* IN - pointer to snmpEngineID */ 3606 u_int engineLength /* IN - length of snmpEngineID */ 3607 u_char *key) /* OUT - pointer to caller 16-octet buffer */ 3608 { 3609 MD5_CTX MD; 3610 u_char *cp, password_buf[64]; 3611 u_long password_index = 0; 3612 u_long count = 0, i; 3614 MD5Init (&MD); /* initialize MD5 */ 3616 /**********************************************/ 3617 /* Use while loop until we've done 1 Megabyte */ 3618 /**********************************************/ 3619 while (count < 1048576) { 3620 cp = password_buf; 3621 for (i = 0; i < 64; i++) { 3622 /*************************************************/ 3623 /* Take the next octet of the password, wrapping */ 3624 /* to the beginning of the password as necessary.*/ 3625 /*************************************************/ 3626 *cp++ = password[password_index++ % passwordlen]; 3627 } 3628 MD5Update (&MD, password_buf, 64); 3629 count += 64; 3630 } 3631 MD5Final (key, &MD); /* tell MD5 we're done */ 3633 /*****************************************************/ 3634 /* Now localize the key with the engineID and pass */ 3635 /* through MD5 to produce final key */ 3636 /* May want to ensure that engineLength <= 32, */ 3637 /* otherwise need to use a buffer larger than 64 */ 3638 /*****************************************************/ 3639 memcpy(password_buf, key, 16); 3640 memcpy(password_buf+16, engineID, engineLength); 3641 memcpy(password_buf+engineLength, key, 16); 3643 MD5Init(&MD); 3644 MD5Update(&MD, password_buf, 32+engineLength); 3645 MD5Final(key, &MD); 3647 return; 3648 } 3649 A.2.2. Password to Key Sample Code for SHA 3 3650 3 3651 void password_to_key_sha( 3 3652 u_char *password, /* IN */ 3 3653 u_int passwordlen, /* IN */ 3 3654 u_char *engineID, /* IN - pointer to snmpEngineID */ 3 3655 u_int engineLength /* IN - length of snmpEngineID */ 3 3656 u_char *key) /* OUT - pointer to caller 20-octet buffer */ 3 3657 { 3 3658 SHA_CTX SH; 4 3659 u_char *cp, password_buf[72]; 3 3660 u_long password_index = 0; 3 3661 u_long count = 0, i; 3 3662 3 3663 SHAInit (&SH); /* initialize SHA */ 4 3664 3 3665 /**********************************************/ 3 3666 /* Use while loop until we've done 1 Megabyte */ 3 3667 /**********************************************/ 3 3668 while (count < 1048576) { 3 3669 cp = password_buf; 3 3670 for (i = 0; i < 64; i++) { 3 3671 /*************************************************/ 3 3672 /* Take the next octet of the password, wrapping */ 3 3673 /* to the beginning of the password as necessary.*/ 3 3674 /*************************************************/ 3 3675 *cp++ = password[password_index++ % passwordlen]; 3 3676 } 3 3677 SHAUpdate (&SH, password_buf, 64); 4 3678 count += 64; 3 3679 } 3 3680 SHAFinal (key, &SH); /* tell SHA we're done */ 4 3681 3 3682 /*****************************************************/ 3 3683 /* Now localize the key with the engineID and pass */ 3 3684 /* through SHA to produce final key */ 3 3685 /* May want to ensure that engineLength <= 32, */ 3 3686 /* otherwise need to use a buffer larger than 72 */ 3 3687 /*****************************************************/ 3 3688 memcpy(password_buf, key, 20); 3 3689 memcpy(password_buf+20, engineID, engineLength); 3 3690 memcpy(password_buf+engineLength, key, 20); 3 3691 3 3692 SHAInit(&SH); 4 3693 SHAUpdate(&SH, password_buf, 40+engineLength); 4 3694 SHAFinal(key, &SH); 4 3695 3 3696 return; 3 3697 } 3 3698 A.3. Password to Key Sample Results 3700 A.3.1. Password to Key Sample Results using MD5 3 3702 The following shows a sample output of the password to key 3703 algorithm for a 16-octet key using MD5. 3 3705 With a password of "maplesyrup" the output of the password to key 3706 algorithm before the key is localized with the SNMP engine's 3707 snmpEngineID is: 3709 '9f af 32 83 88 4e 92 83 4e bc 98 47 d8 ed d9 63'H 3711 After the intermediate key (shown above) is localized with the 3712 snmpEngineID value of: 3714 '00 00 00 00 00 00 00 00 00 00 00 02'H 3716 the final output of the password to key algorithm is: 3718 '52 6f 5e ed 9f cc e2 6f 89 64 c2 93 07 87 d8 2b'H 3720 A.3.2. Password to Key Sample Results using SHA 3 3721 3 3722 The following shows a sample output of the password to key 3 3723 algorithm for a 20-octet key using SHA. 4 3724 3 3725 With a password of "maplesyrup" the output of the password to key 3 3726 algorithm before the key is localized with the SNMP engine's 3 3727 snmpEngineID is: 3 3728 3 3729 'f1 be a9 ae 66 7f 4f b6 34 1e 51 af 06 80 7e 91 e4 3b 01 ac'H 4 3730 3 3731 After the intermediate key (shown above) is localized with the 3 3732 snmpEngineID value of: 3 3733 3 3734 '00 00 00 00 00 00 00 00 00 00 00 02'H 3 3735 3 3736 the final output of the password to key algorithm is: 3 3737 3 3738 '8a a3 d9 9e 3e 30 56 f2 bf e3 a9 ee f3 45 d5 39 54 91 12 be'H 4 3739 3 3741 A.4. Sample encoding of msgSecurityParameters 3743 The msgSecurityParameters in an SNMP message are represented as 3744 an OCTET STRING. This OCTET STRING should be considered opaque 3745 outside a specific Security Model. 3747 The User-based Security Model defines the contents of the OCTET 3748 STRING as a SEQUENCE (see section 2.4). 3750 Given these two properties, the following is an example of the 3751 msgSecurityParameters for the User-based Security Model, encoded 3752 as an OCTET STRING: 3754 04 3755 30 3756 04 3757 02 3758 02 3759 04 3760 04 0c | 3761 04 08 3763 Here is the example once more, but now with real values (except 3764 for the digest in msgAuthenticationParameters and the salt in 3765 msgPrivacyParameters, which depend on variable data that we have 3766 not defined here): 3768 Hex Data Description 3769 -------------- ----------------------------------------------- 3770 04 39 OCTET STRING, length 57 3771 30 37 SEQUENCE, length 55 3772 04 0c 80000002 msgAuthoritativeEngineID: IBM | 3773 01 IPv4 address | 3774 09840301 9.132.3.1 3775 02 01 01 msgAuthoritativeEngineBoots: 1 3776 02 02 0101 msgAuthoritativeEngineTime: 257 3777 04 04 62657274 msgUserName: bert 3778 04 0c 01234567 msgAuthenticationParameters: sample value | 3779 89abcdef 3780 fedcba98 3781 04 08 01234567 msgPrivacyParameters: sample value 3782 89abcdef 3784 B. Full Copyright Statement 5 3785 5 3786 Copyright (C) The Internet Society (1997). All Rights Reserved. 5 3787 5 3788 This document and translations of it may be copied and furnished to 5 3789 others, and derivative works that comment on or otherwise explain it 5 3790 or assist in its implementation may be prepared, copied, published 5 3791 and distributed, in whole or in part, without restriction of any 5 3792 kind, provided that the above copyright notice and this paragraph 5 3793 are included on all such copies and derivative works. However, this 5 3794 document itself may not be modified in any way, such as by removing 5 3795 the copyright notice or references to the Internet Society or other 5 3796 Internet organizations, except as needed for the purpose of 5 3797 developing Internet standards in which case the procedures for 5 3798 copyrights defined in the Internet Standards process must be 5 3799 followed, or as required to translate it into languages other than 5 3800 English. 5 3801 5 3802 The limited permissions granted above are perpetual and will not be 5 3803 revoked by the Internet Society or its successors or assigns. 5 3804 5 3805 This document and the information contained herein is provided on an 5 3806 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING 5 3807 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 5 3808 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION 5 3809 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF 5 3810 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 5