home *** CD-ROM | disk | FTP | other *** search
/ Internet Info 1997 December / Internet_Info_CD-ROM_Walnut_Creek_December_1997.iso / drafts / draft_ietf_q_t / draft-ietf-snmpv3-usm-03.txt < prev    next >
Text File  |  1997-10-29  |  207KB  |  4,839 lines
  1.  
  2.  
  3.  
  4. INTERNET-DRAFT                                             U. Blumenthal  5
  5.                                                IBM T. J. Watson Research  5
  6.                                                                B. Wijnen  5
  7.                                                IBM T. J. Watson Research  5
  8.                                                          28 October 1997  5
  9.  
  10.            User-based Security Model (USM) for version 3 of the
  11.                Simple Network Management Protocol (SNMPv3)
  12.                      <draft-ietf-snmpv3-usm-03.txt>                       5
  13.  
  14.  
  15.                           Status of this Memo
  16.  
  17. This document is an Internet-Draft.  Internet-Drafts are working
  18. documents of the Internet Engineering Task Force (IETF), its areas,
  19. and its working groups.  Note that other groups may also distribute
  20. working documents as Internet-Drafts.
  21.  
  22. Internet-Drafts are draft documents valid for a maximum of six months
  23. and may be updated, replaced, or obsoleted by other documents at any
  24. time.  It is inappropriate to use Internet- Drafts as reference
  25. material or to cite them other than as ``work in progress.''
  26.  
  27. To learn the current status of any Internet-Draft, please check the
  28. ``1id-abstracts.txt'' listing contained in the Internet- Drafts Shadow
  29. Directories on ds.internic.net (US East Coast), nic.nordu.net (Europe),
  30. ftp.isi.edu (US West Coast), or munnari.oz.au (Pacific Rim).
  31.  
  32. Copyright Notice                                                          5
  33.                                                                           5
  34.    Copyright (C) The Internet Society (1997).  All Rights Reserved.       5
  35.                                                                           5
  36.                           Abstract
  37.  
  38. This document describes the User-based Security Model (USM) for SNMP
  39. version 3 for use in the SNMP architecture [SNMP-ARCH].  It defines
  40. the Elements of Procedure for providing SNMP message level security.
  41. This document also includes a MIB for remotely monitoring/managing
  42. the configuration parameters for this Security Model.
  43.  
  44.  
  45.  
  46.  
  47.  
  48.  
  49.  
  50.  
  51.  
  52.  
  53.  
  54.  
  55.  
  56.  
  57.  
  58. SNMPv3 Working Group        Expires April 1998                 [Page  1]
  59.  
  60. Internet Draft     User-based Security Model for SNMPv3      28 Oct 1997
  61.  
  62.  
  63. Table of Contents
  64.  
  65. 0.  Issues and Change Log                                              4
  66. 0.1.  Resolved Issues                                                  4
  67. 0.2.  Change Log                                                       5
  68. 1.  Introduction                                                       9
  69. 1.1.  Threats                                                          9
  70. 1.2.  Goals and Constraints                                           11
  71. 1.3.  Security Services                                               11
  72. 1.4.  Module Organization                                             12
  73. 1.4.1.  Timeliness Module                                             13
  74. 1.4.2.  Authentication Protocol                                       13
  75. 1.4.3.  Privacy Protocol                                              13
  76. 1.5.  Protection against Message Replay, Delay and Redirection        13
  77. 1.5.1.  Authoritative SNMP engine                                     13
  78. 1.5.2.  Mechanisms                                                    14
  79. 1.6.  Abstract Service Interfaces.                                    15
  80. 1.6.1.  User-based Security Model Primitives for Authentication       16
  81. 1.6.2.  User-based Security Model Primitives for Privacy              16
  82. 2.  Elements of the Model                                             18
  83. 2.1.  User-based Security Model Users                                 18
  84. 2.2.  Replay Protection                                               19
  85. 2.2.1.  msgAuthoritativeEngineID                                      19
  86. 2.2.2.  msgAuthoritativeEngineBoots and msgAuthoritativeEngineTime    19
  87. 2.2.3.  Time Window                                                   20
  88. 2.3.  Time Synchronization                                            21
  89. 2.4.  SNMP Messages Using this Security Model                         22
  90. 2.5.  Services provided by the User-based Security Model              23
  91. 2.5.1.  Services for Generating an Outgoing SNMP Message              23
  92. 2.5.2.  Services for Processing an Incoming SNMP Message              25
  93. 2.6.  Key Localization Algorithm.                                     26
  94. 3.  Elements of Procedure                                             28
  95. 3.1.  Generating an Outgoing SNMP Message                             28
  96. 3.2.  Processing an Incoming SNMP Message                             31
  97. 4.  Discovery                                                         37
  98. 5.  Definitions                                                       38
  99. 6.  HMAC-MD5-96 Authentication Protocol                               51
  100. 6.1.  Mechanisms                                                      51
  101. 6.1.1.  Digest Authentication Mechanism                               51
  102. 6.2.  Elements of the Digest Authentication Protocol                  52
  103. 6.2.1.  Users                                                         52
  104. 6.2.2.  msgAuthoritativeEngineID                                      52
  105. 6.2.3.  SNMP Messages Using this Authentication Protocol              52
  106. 6.2.4.  Services provided by the HMAC-MD5-96 Authentication Module    53
  107. 6.2.4.1.  Services for Generating an Outgoing SNMP Message            53
  108. 6.2.4.2.  Services for Processing an Incoming SNMP Message            53
  109. 6.3.  Elements of Procedure                                           54
  110. 6.3.1.  Processing an Outgoing Message                                54
  111. 6.3.2.  Processing an Incoming Message                                55
  112. 7.  HMAC-SHA-96 Authentication Protocol                               57
  113. 7.1.  Mechanisms                                                      57
  114.  
  115.  
  116.  
  117. SNMPv3 Working Group        Expires April 1998                 [Page  2]
  118.  
  119. Internet Draft     User-based Security Model for SNMPv3      28 Oct 1997
  120.  
  121.  
  122. 7.1.1.  Digest Authentication Mechanism                               57
  123. 7.2.  Elements of the HMAC-SHA-96 Authentication Protocol             58
  124. 7.2.1.  Users                                                         58
  125. 7.2.2.  msgAuthoritativeEngineID                                      58
  126. 7.2.3.  SNMP Messages Using this Authentication Protocol              58
  127. 7.2.4.  Services provided by the HMAC-SHA-96 Authentication Module    59
  128. 7.2.4.1.  Services for Generating an Outgoing SNMP Message            59
  129. 7.2.4.2.  Services for Processing an Incoming SNMP Message            59
  130. 7.3.  Elements of Procedure                                           60
  131. 7.3.1.  Processing an Outgoing Message                                60
  132. 7.3.2.  Processing an Incoming Message                                61
  133. 8.  CBC-DES Symmetric Encryption Protocol                             63
  134. 8.1.  Mechanisms                                                      63
  135. 8.1.1.  Symmetric Encryption Protocol                                 63
  136. 8.1.1.1.  DES key and Initialization Vector.                          64
  137. 8.1.1.2.  Data Encryption.                                            64
  138. 8.1.1.3.  Data Decryption                                             65
  139. 8.2.  Elements of the DES Privacy Protocol                            65
  140. 8.2.1.  Users                                                         65
  141. 8.2.2.  msgAuthoritativeEngineID                                      65
  142. 8.2.3.  SNMP Messages Using this Privacy Protocol                     66
  143. 8.2.4.  Services provided by the DES Privacy Module                   66
  144. 8.2.4.1.  Services for Encrypting Outgoing Data                       66
  145. 8.2.4.2.  Services for Decrypting Incoming Data                       67
  146. 8.3.  Elements of Procedure.                                          67
  147. 8.3.1.  Processing an Outgoing Message                                67
  148. 8.3.2.  Processing an Incoming Message                                68
  149. 9.  Intellectual Property                                             69
  150. A.1.  SNMP engine Installation Parameters                             76
  151. A.2.  Password to Key Algorithm                                       77
  152. A.2.1.  Password to Key Sample Code for MD5                           78
  153. A.2.2.  Password to Key Sample Code for SHA                           79
  154. A.3.  Password to Key Sample Results                                  80
  155. A.3.1.  Password to Key Sample Results using MD5                      80
  156. A.3.2.  Password to Key Sample Results using SHA                      80
  157. A.4.  Sample encoding of msgSecurityParameters                        81
  158. B.  Full Copyright Statement                                          81
  159.  
  160.  
  161.  
  162.  
  163.  
  164.  
  165.  
  166.  
  167.  
  168.  
  169.  
  170.  
  171.  
  172.  
  173.  
  174.  
  175.  
  176. SNMPv3 Working Group        Expires April 1998                 [Page  3]
  177.  
  178. Internet Draft     User-based Security Model for SNMPv3      28 Oct 1997
  179.  
  180.  
  181. 0.  Issues and Change Log
  182.  
  183.     When we go to RFC status, we will remove all the text of section 0.   4
  184.  
  185. 0.1.  Resolved Issues
  186.       - Is it OK to use MD5 for KeyChange Algorithm ??
  187.         We changed the TC so that we use the hash-function that           |
  188.         the user's authentication protocol (usmUserAuthProtocol)          |
  189.         is based on instead of fixing it to MD5                           |
  190.       - Improve acknowledgements and sync it up with other documents
  191.         Resolved by Russ.
  192.       - Should the USM define checking such that a received Response
  193.         messages used the same or better securityLevel than the Request
  194.         message that this is a response to.
  195.         In section 3.1 step 9, we return a completed outgoing message
  196.         to the calling module (Message Processing). We believe it is
  197.         the Message Processing Subsystem that should cache information
  198.         about outgoing messages regarding msgID and such so that a
  199.         possible Response Message can be mapped to an outstanding
  200.         request. At the same time that piece of code can then ensure
  201.         that the same securityModel and the same (or better??)
  202.         securityLevel has been used for the Response Message. So in
  203.         step 9 we do not save any cachedSecurityData for outgoing
  204.         messages.
  205.         Resolution. Statements have been added to state that this is
  206.         the responsibility of the calling Message Processing Model.
  207.         The v3MP has been changed to indeed do the check.
  208.       - At an authoritative SNMP engine we must be able to determine
  209.         if the msgAuthoritativeEngineID value used for Requests is the
  210.         local snmpEngineID. However, to do so we'd have to peek into
  211.         either the message or into the PDU. That is not clean.
  212.         Resolution. The USM must pass the securityEngineID that was
  213.         used for security purposes (i.e., the value extracted from        |
  214.         the msgAuthoritativeEngineID) so that the MP can check it
  215.         when it determines that it is a Request. The MP document has
  216.         been updated to make the check.
  217.       - An authenticated incoming message at a non-authoritative SNMP
  218.         engine always allowed the notion snmpEngineTime to be updated
  219.         (as long as it was not older than what we had). This allowed
  220.         intruders to slow down our notion of time dramatically.
  221.         Resolution. Check the value not only to be greater than
  222.         latestReceivedEngineTime but also against out notion of
  223.         time to ensure it is not older than 150 seconds. This will
  224.         have a side-effect in that if an authoritative engine ever
  225.         gets more than 150 seconds behind, then the authoritative end
  226.         MUST do explicit time synchronization.
  227.       - Should we use Integers or OIDs for identifying protocols
  228.         Resolution. Consensus is to use OID.
  229.  
  230.  
  231.  
  232.  
  233.  
  234.  
  235. SNMPv3 Working Group        Expires April 1998                 [Page  4]
  236.  
  237. Internet Draft     User-based Security Model for SNMPv3      28 Oct 1997
  238.  
  239.  
  240. 0.2.  Change Log
  241.  
  242.    [version 3.5] October 28 version:                                      5
  243.      - fix typo's as reported by John Flick.                              5
  244.      - remove usmAdmin                                                    5
  245.      - Adjusted layout per RFC 2223.                                      5
  246.      - Added copyright statements required by RFC 2026.                   5
  247.      - post as I-D:    <draft-ietf-snmpv3-usm-03.txt>                     5
  248.  
  249.    [version 3.4] September 30 version:                                    4
  250.      - these changes are marked with a revision-code "4" in right margin  4
  251.      - editorial changes based on mail exchanges between Bert/Uri         4
  252.      - Quick spell check.                                                 4
  253.      - SMICng compile the USM MIB to verify correct syntax.               4
  254.      - paginate                                                           4
  255.      - post as I-D:    <draft-ietf-snmpv3-usm-02.txt>                     4
  256.                                                                           4
  257.    [version 3.3] Internal version exchanged between editors:              3
  258.      - these changes are marked with a revision-code "3" in right margin  3
  259.      - Added section 2.6 to explain algorithm for generating localized    3
  260.        key and added the word 'localized' at various places.              3
  261.      - Added appendix A.1.2 to show example code for SHA localized key    3
  262.      - Changed text at the end of section 11.2 to state that passwords    3
  263.        and non-localized keys SHOULD NOT be stored on managed devices.    3
  264.      - changed usmSecurityParameters so that Boots/Time values are now    3
  265.        represented as INTEGERS.                                           3
  266.                                                                           3
  267.    [version 3.2] September 29 version:                                    |
  268.      - these changes are marked with a revision-code "|" in right margin  |
  269.      - fix ASN.1 definition of securityParameters                         |
  270.      - specify that wrongValue must be returned if a SET tries to set     |
  271.        an unknown or unsupported Authentication or Privacy protocol       |
  272.      - add summary of USM internal ASIs now that they were removed from   |
  273.        the architecture document. This is section 1.6.                    |
  274.      - add text to section 1 to explain usage of SHOULD, MUST and such.   |
  275.      - tried to be more consistent in use of the terms Protocol,          |
  276.        Mechanism and Algorithm.                                           |
  277.      - defined that keys for MD5 and DES MUST be 16 octets long and for   |
  278.        SHA they MUST be 20 octets long                                    |
  279.      - described that key must be extended to 64 octets before applying   |
  280.        HMAC-MD5 or HMAC-SHA algorithms.                                   |
  281.      - Fixed writeup on key use. We no longer insert/append key but       |
  282.        instead prepend it to the message before calculating the digest.   |
  283.      - tried to be more consistent and always use the term octet(s)       |
  284.        instead of byte(s).                                                |
  285.      - placed a comma after each i.e.                                     |
  286.      - Adapt Appendix samples to match rest of document(s).               |
  287.      - SMICng compile the USM MIB to verify correct syntax.               |
  288.      - Quick spell check.                                                 |
  289.                                                                           |
  290.    [version 3.1] September 25 version:                                    |
  291.  
  292.  
  293.  
  294. SNMPv3 Working Group        Expires April 1998                 [Page  5]
  295.  
  296. Internet Draft     User-based Security Model for SNMPv3      28 Oct 1997
  297.  
  298.  
  299.      - these changes are marked with a revision-code "|" in right margin  |
  300.      - msgAuthoritativeEngineTime is an Integer32, not an Unsigned32      |
  301.      - msgUserName can be up to 32 octets long                            |
  302.      - changing authentication algorithm from MD5 to HMAC-MD5-96 and      |
  303.        HMAC-SHA-96 [RFC2104]                                              |
  304.      - Delete un-referenced references                                    |
  305.      - roll back time synchronization procedure                           |
  306.      - address comments from mailing list                                 |
  307.      - added section 7 to describe HMAC-SHA-96 and renumbered sections    |
  308.        8-11 as a result.                                                  |
  309.  
  310.    [version 2.2]
  311.      - formatting
  312.      - pagination
  313.  
  314.    [version 2.1] - August 1 version
  315.      - Changed max size for usmUserName from 16 to 32.
  316.        For SnmpAdminString 16 is rather short.
  317.      - incorporate comments by Uri.
  318.      - Update References
  319.      - Update acknowledgement section
  320.      - remove expectResponse parameter. It was a bad idea
  321.      - renamed snmpEngineID parameter to securityEngineID to
  322.        reduce confusion with other uses of term snmpEngineID
  323.      - added an OUT parameter securityEngineID to processIncomingMsg
  324.        primitive, so that MP can check if correct snmpEngineID was
  325.        used for Request messages.
  326.      - added some more considerations about redirected Traps.
  327.      - state that MP is responsible for matching a Response or Report
  328.        to an outstanding Request and discard it if none found.
  329.      - Discussion about msgID and request-id changed into an example,
  330.        because it is SNMPv3 MP specific and the MP MUST handle it.
  331.      - Spell check
  332.      - SMICng MIB check
  333.      - Paginate
  334.      - Post to I-D repository and SNMPv3 mailing list as:
  335.        <draft-ietf-snmpv3-usm-01.txt>
  336.  
  337.    [version 2.0] - July 28 version
  338.      - Address comments by Juergen
  339.        - fix typos and editorial changes
  340.      - Other changes
  341.        - adapt to new (synchronous) abstract service primitives
  342.        - adapt to new field names in the messages
  343.        - adapt to new parameter names for abstract data type
  344.      - Address Dave Perkins comments
  345.        - modify definition of usmSecurityParameters
  346.      - Address Dave Levi's issue on checking msgAuthoritativeEngineID
  347.        properly to local snmpEngineID for incoming Request Messages
  348.      - Address Uri issue about slow-down of non-authoritative
  349.        engine's notion of time at remote SNMP engine.
  350.  
  351.  
  352.  
  353. SNMPv3 Working Group        Expires April 1998                 [Page  6]
  354.  
  355. Internet Draft     User-based Security Model for SNMPv3      28 Oct 1997
  356.  
  357.  
  358.      - Address Uri issue about redirection of (authenticated) Traps.
  359.        Describe it is not a problem because they come from the
  360.        authoritative SNMP engine.
  361.      - Address comments by Arnoud Zwemmer about the fact that only
  362.        Report PDUs can slow down timeliness notion
  363.  
  364.    [version 1.8]
  365.      - Add reference to RFC2119 about use of SHOULD and MUST
  366.      - paginate and generate table of contents
  367.      - posted as I-D <draft-ietf-snmpv3-usm-00.txt> on 15 July 1997
  368.  
  369.    [version 1.7]
  370.      - Changed the KeyChange description so it allows for other
  371.        hash algorithms instead of MD5. If in the future the MD5 gets
  372.        replaced by another Authentication -- algorithm, then it seems
  373.        we also need to use that new algorithm to -- calculate the
  374.        digest during KeyChange.
  375.      - Updated the password to key code fragment to cater for the
  376.        variable length of the snmpEngineID.
  377.      - Added issue on cacheing of data on outgoing messages and one
  378.        on required review of timeliness handling.
  379.  
  380.    [version 1.4 - version 1.6]
  381.      - Editorial changes because of internal review by authors
  382.      - Adapt to latest list of Primitive names and parameters
  383.      - Change USEC to USM
  384.      - Changes based on comments from Jeff Case.
  385.      - Checked MIB with SMICng
  386.  
  387.    [version 1.3]
  388.      - Too many changes have taken place, so marking it was skipped
  389.        The most important changes are listed here.
  390.        However, changes that just split text on different lines
  391.        and changes like different capitalization of words/terms
  392.        has not been listed. Also changes to fit new terms and such
  393.        have not been listed.
  394.      - Split/Join some lines to ensure we stay within 72 columns
  395.        as required by RFC guidelines.
  396.      - Addressed Dave Perkins comments:
  397.        1) Section 1.3, last paragraph's, timeliness was left off. -done
  398.        2) Section 1.5.1, the operations need to be made general, since
  399.           additional one may be added later.  - done
  400.        3) Section 1.5.2, the field "request-id" is used throughout
  401.           this section when it should be field "msgID"  - done
  402.        4) The document must allow the value of engineID in the
  403.           security to be a zero length string. There are several
  404.           places that are affected by this change. An actual value is
  405.           never needed, since secrets are never the same on different
  406.           agents (see your paper).  - done
  407.        5) Last sentence of description for object usmUserCloneFrom is
  408.           not correct, since the object has a OID data type - done
  409.  
  410.  
  411.  
  412. SNMPv3 Working Group        Expires April 1998                 [Page  7]
  413.  
  414. Internet Draft     User-based Security Model for SNMPv3      28 Oct 1997
  415.  
  416.  
  417.      - Removed groupName from usmUserTable.
  418.        Now done in Access Control as agreed at 2nd interim
  419.      - Stats counters back in this document as agreed at 2nd interim
  420.      - Use AutonomousType for usmUserPrivProtocol and
  421.        usmUserAuthProtocol. Also use OBJECT-IDENTITY for the
  422.        protocol OIDs (John Flick).
  423.      - Changed "SNMPv3 engine" to "SNMP engine" at various places
  424.      - added appendix with sample encoding of securityParameters
  425.      - cleanup elements of procedure to use consistent terms
  426.      - fix up some problems in elements of procedure
  427.      - Do not use IMPLIED on usmUserTable as agreed at 2nd interim.
  428.        For one thing, SNMPv1 cannot handle it.
  429.      - cleanup section 2.3 and 3.3 step 7b based on comments by
  430.        Dave Levi.
  431.  
  432.    [version 1.2]
  433.      - changed (simplified) time sync in section 3 item 7.
  434.      - added usmUserMiId
  435.      - cleaned up text
  436.      - defined IV "salt" generation
  437.      - removed Statistics counters (now in MPC) and Report PDU
  438.        generation (now in MPC)
  439.      - Removed auth and DES MIBs which are now merged into
  440.        User-based Security MIB
  441.      - specified where cachedSecurityData needs to be discarded
  442.      - added abstract service interface definitions
  443.      - removed section on error reporting (is MPC responsibility)
  444.      - removed auth/priv protocol definitions, they are in ARCH now
  445.      - removed MIB definitions for snmpEngineID, Time, Boots. They
  446.        are in ARCH now.
  447.  
  448.    [version 1.1]
  449.      - removed <securityCookie>.
  450.      - added <securityIdentity>, <securityCachedData>.
  451.      - added abstract function interface description of
  452.        inter-module communications.
  453.      - modified IV generation process to accommodate messages produced
  454.        faster than one-per-second (still open).
  455.      - always update the clock regardless of whether incoming message
  456.        was Report or not (if the message was properly authenticated
  457.        and its time-stamp is ahead of our notion of their clock).
  458.  
  459.    [version 1.0]
  460.      - first version posted to the SNMPv3 editor's mailing list.
  461.      - based on v2adv slides, v2adv items and issues list and on
  462.        RFC1910 and SNMPv2u and SNMPv2* documents.
  463.      - various iterations were done by the authors via private email.
  464.  
  465.  
  466.  
  467.  
  468.  
  469.  
  470.  
  471. SNMPv3 Working Group        Expires April 1998                 [Page  8]
  472.  
  473. Internet Draft     User-based Security Model for SNMPv3      28 Oct 1997
  474.  
  475.  
  476. 1.  Introduction
  477.  
  478.    The Architecture for describing Internet Management Frameworks
  479.    [SNMP-ARCH] describes that an SNMP engine is composed of:
  480.  
  481.      1) a Dispatcher
  482.      2) a Message Processing Subsystem,
  483.      3) a Security Subsystem, and
  484.      4) an Access Control Subsystem.
  485.  
  486.    Applications make use of the services of these subsystems.
  487.  
  488.    It is important to understand the SNMP architecture and the
  489.    terminology of the architecture to understand where the Security
  490.    Model described in this document fits into the architecture and
  491.    interacts with other subsystems within the architecture.  The
  492.    reader is expected to have read and understood the description of
  493.    the SNMP architecture, as defined in [SNMP-ARCH].
  494.  
  495.    This memo [SNMP-USM] describes the User-based Security Model as it
  496.    is used within the SNMP Architecture.  The main idea is that we use
  497.    the traditional concept of a user (identified by a userName) with
  498.    which to associate security information.
  499.  
  500.    This memo describes the use of HMAC-MD5-96 and HMAC-SHA-96 as the      |
  501.    authentication protocols and the use of CBC-DES as the privacy         |
  502.    protocol. The User-based Security Model however allows for other       |
  503.    such protocols to be used instead of or concurrent with these          |
  504.    protocols. Therefore, the description of HMAC-MD5-96, HMAC-SHA-96      |
  505.    and CBC-DES are in separate sections to reflect their self-contained   |
  506.    nature and to indicate that they can be replaced or supplemented in    |
  507.    the future.                                                            |
  508.  
  509.    The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",    |
  510.    "SHOULD", "SHOULD NOT", "RECOMMENDED",  "MAY", and "OPTIONAL" in this  |
  511.    document are to be interpreted as described in [RFC2119].              |
  512.  
  513. 1.1.  Threats
  514.  
  515.    Several of the classical threats to network protocols are
  516.    applicable to the network management problem and therefore would
  517.    be applicable to any SNMP Security Model.  Other threats are not
  518.    applicable to the network management problem.  This section
  519.    discusses principal threats, secondary threats, and threats which
  520.    are of lesser importance.
  521.  
  522.    The principal threats against which this SNMP Security Model
  523.    should provide protection are:
  524.  
  525.    - Modification of Information
  526.      The modification threat is the danger that some unauthorized
  527.  
  528.  
  529.  
  530. SNMPv3 Working Group        Expires April 1998                 [Page  9]
  531.  
  532. Internet Draft     User-based Security Model for SNMPv3      28 Oct 1997
  533.  
  534.  
  535.      entity may alter in-transit SNMP messages generated on behalf
  536.      of an authorized user in such a way as to effect unauthorized
  537.      management operations, including falsifying the value of an
  538.      object.
  539.  
  540.    - Masquerade
  541.      The masquerade threat is the danger that management operations
  542.      not authorized for some user may be attempted by assuming the
  543.      identity of another user that has the appropriate authorizations.
  544.  
  545.    Two secondary threats are also identified.  The Security Model
  546.    defined in this memo provides limited protection against:
  547.  
  548.    - Disclosure
  549.      The disclosure threat is the danger of eavesdropping on the
  550.      exchanges between managed agents and a management station.
  551.      Protecting against this threat may be required as a matter of
  552.      local policy.
  553.  
  554.    - Message Stream Modification
  555.      The SNMP protocol is typically based upon a connection-less
  556.      transport service which may operate over any sub-network service.
  557.      The re-ordering, delay or replay of messages can and does occur
  558.      through the natural operation of many such sub-network services.
  559.      The message stream modification threat is the danger that
  560.      messages may be maliciously re-ordered, delayed or replayed to
  561.      an extent which is greater than can occur through the natural
  562.      operation of a sub-network service, in order to effect
  563.      unauthorized management operations.
  564.  
  565.    There are at least two threats that an SNMP Security Model need
  566.    not protect against.  The security protocols defined in this memo
  567.    do not provide protection against:
  568.  
  569.    - Denial of Service
  570.      This SNMP Security Model does not attempt to address the broad
  571.      range of attacks by which service on behalf of authorized users
  572.      is denied.  Indeed, such denial-of-service attacks are in many
  573.      cases indistinguishable from the type of network failures with
  574.      which any viable network management protocol must cope as a
  575.      matter of course.
  576.    - Traffic Analysis
  577.      This SNMP Security Model does not attempt to address traffic
  578.      analysis attacks.  Indeed, many traffic patterns are predictable
  579.      - devices may be managed on a regular basis by a relatively small
  580.      number of management applications - and therefore there is no
  581.      significant advantage afforded by protecting against traffic
  582.      analysis.
  583.  
  584.  
  585.  
  586.  
  587.  
  588.  
  589. SNMPv3 Working Group        Expires April 1998                 [Page 10]
  590.  
  591. Internet Draft     User-based Security Model for SNMPv3      28 Oct 1997
  592.  
  593.  
  594. 1.2.  Goals and Constraints
  595.  
  596.    Based on the foregoing account of threats in the SNMP network
  597.    management environment, the goals of this SNMP Security Model
  598.    are as follows.
  599.  
  600.    1) Provide for verification that each received SNMP message has
  601.       not been modified during its transmission through the network.
  602.  
  603.    2) Provide for verification of the identity of the user on whose
  604.       behalf a received SNMP message claims to have been generated.
  605.  
  606.    3) Provide for detection of received SNMP messages, which request
  607.       or contain management information, whose time of generation was
  608.       not recent.
  609.  
  610.    4) Provide, when necessary, that the contents of each received
  611.       SNMP message are protected from disclosure.
  612.  
  613.    In addition to the principal goal of supporting secure network
  614.    management, the design of this SNMP Security Model is also
  615.    influenced by the following constraints:
  616.  
  617.    1) When the requirements of effective management in times of
  618.       network stress are inconsistent with those of security, the
  619.       design should prefer the former.
  620.  
  621.    2) Neither the security protocol nor its underlying security
  622.       mechanisms should depend upon the ready availability of other
  623.       network services (e.g., Network Time Protocol (NTP) or key
  624.       management protocols).
  625.  
  626.    3) A security mechanism should entail no changes to the basic
  627.       SNMP network management philosophy.
  628.  
  629. 1.3.  Security Services
  630.  
  631.    The security services necessary to support the goals of this SNMP
  632.    Security Model are as follows:
  633.  
  634.    - Data Integrity
  635.      is the provision of the property that data has not been altered
  636.      or destroyed in an unauthorized manner, nor have data sequences
  637.      been altered to an extent greater than can occur non-maliciously.
  638.  
  639.    - Data Origin Authentication
  640.      is the provision of the property that the claimed identity of
  641.      the user on whose behalf received data was originated is
  642.      corroborated.
  643.  
  644.    - Data Confidentiality
  645.  
  646.  
  647.  
  648. SNMPv3 Working Group        Expires April 1998                 [Page 11]
  649.  
  650. Internet Draft     User-based Security Model for SNMPv3      28 Oct 1997
  651.  
  652.  
  653.      is the provision of the property that information is not made
  654.      available or disclosed to unauthorized individuals, entities,
  655.      or processes.
  656.  
  657.    - Message timeliness and limited replay protection
  658.      is the provision of the property that a message whose generation
  659.      time is outside of a specified time window is not accepted.
  660.      Note that message reordering is not dealt with and can occur in
  661.      normal conditions too.
  662.  
  663.    For the protocols specified in this memo, it is not possible to
  664.    assure the specific originator of a received SNMP message; rather,
  665.    it is the user on whose behalf the message was originated that is
  666.    authenticated.
  667.  
  668.    For these protocols, it not possible to obtain data integrity
  669.    without data origin authentication, nor is it possible to obtain
  670.    data origin authentication without data integrity.  Further,
  671.    there is no provision for data confidentiality without both data
  672.    integrity and data origin authentication.
  673.  
  674.    The security protocols used in this memo are considered acceptably
  675.    secure at the time of writing.  However, the procedures allow for
  676.    new authentication and privacy methods to be specified at a future
  677.    time if the need arises.
  678.  
  679. 1.4.  Module Organization
  680.  
  681.    The security protocols defined in this memo are split in three
  682.    different modules and each has its specific responsibilities such
  683.    that together they realize the goals and security services
  684.    described above:
  685.  
  686.    - The authentication module MUST provide for:
  687.  
  688.      - Data Integrity,
  689.  
  690.      - Data Origin Authentication
  691.  
  692.    - The timeliness module MUST provide for:
  693.  
  694.      - Protection against message delay or replay (to an extent
  695.        greater than can occur through normal operation)
  696.  
  697.    - The privacy module MUST provide for
  698.  
  699.      - Protection against disclosure of the message payload.
  700.  
  701.    The timeliness module is fixed for the User-based Security Model
  702.    while there is provision for multiple authentication and/or
  703.    privacy modules, each of which implements a specific authentication
  704.  
  705.  
  706.  
  707. SNMPv3 Working Group        Expires April 1998                 [Page 12]
  708.  
  709. Internet Draft     User-based Security Model for SNMPv3      28 Oct 1997
  710.  
  711.  
  712.    or privacy protocol respectively.
  713.  
  714. 1.4.1.  Timeliness Module
  715.  
  716.    Section 3 (Elements of Procedure) uses the timeliness values in an
  717.    SNMP message to do timeliness checking.  The timeliness check is
  718.    only performed if authentication is applied to the message.  Since
  719.    the complete message is checked for integrity, we can assume that
  720.    the timeliness values in a message that passes the authentication
  721.    module are trustworthy.
  722.  
  723. 1.4.2.  Authentication Protocol
  724.  
  725.    Section 6 describes the HMAC-MD5-96 authentication protocol which      |
  726.    is the first authentication protocol that MUST be supported with       |
  727.    the User-based Security Model.                                         |
  728.    Section 7 describes the HMAC-SHA-96 authentication protocol which      |
  729.    is another authentication protocol that SHOULD be supported with       |
  730.    the User-based Security Model.                                         |
  731.    In the future additional or replacement authentication protocols may   |
  732.    be defined as new needs arise.                                         |
  733.  
  734.    The User-based Security Model prescribes that, if authentication
  735.    is used, then the complete message is checked for integrity in
  736.    the authentication module.
  737.  
  738.    For a message to be authenticated, it needs to pass authentication
  739.    check by the authentication module and the timeliness check which
  740.    is a fixed part of this User-based Security model.
  741.  
  742. 1.4.3.  Privacy Protocol
  743.  
  744.    Section 8 describes the CBC-DES Symmetric Encryption Protocol          |
  745.    which is the first privacy protocol to be used with the
  746.    User-based Security Model.  In the future additional or
  747.    replacement privacy protocols may be defined as new needs arise.
  748.  
  749.    The User-based Security Model prescribes that the scopedPDU
  750.    is protected from disclosure when a message is sent with privacy.
  751.  
  752.    The User-based Security Model also prescribes that a message
  753.    needs to be authenticated if privacy is in use.
  754.  
  755. 1.5.  Protection against Message Replay, Delay and Redirection
  756.  
  757. 1.5.1.  Authoritative SNMP engine
  758.  
  759.    In order to protect against message replay, delay and redirection,
  760.    one of the SNMP engines involved in each communication is
  761.    designated to be the authoritative SNMP engine.  When an SNMP
  762.    message contains a payload which expects a response (for example
  763.  
  764.  
  765.  
  766. SNMPv3 Working Group        Expires April 1998                 [Page 13]
  767.  
  768. Internet Draft     User-based Security Model for SNMPv3      28 Oct 1997
  769.  
  770.  
  771.    a Get, GetNext, GetBulk, Set or Inform PDU), then the receiver of
  772.    such messages is authoritative.  When an SNMP message contains a
  773.    payload which does not expect a response (for example an
  774.    SNMPv2-Trap, Response or Report PDU), then the sender of such a
  775.    message is authoritative.
  776.  
  777. 1.5.2.  Mechanisms
  778.  
  779.    The following mechanisms are used:
  780.  
  781.    1) To protect against the threat of message delay or replay (to an
  782.       extent greater than can occur through normal operation), a set
  783.       of timeliness indicators (for the authoritative SNMP engine) are
  784.       included in each message generated.  An SNMP engine evaluates
  785.       the timeliness indicators to determine if a received message is
  786.       recent.  An SNMP engine may evaluate the timeliness indicators
  787.       to ensure that a received message is at least as recent as the
  788.       last message it received from the same source.
  789.       A non-authoritative SNMP engine uses received authentic messages
  790.       to advance its notion of the timeliness indicators at the remote
  791.       authoritative source.
  792.  
  793.       An SNMP engine MUST also use a mechanism to match incoming
  794.       Responses to outstanding Requests and it MUST drop any Responses
  795.       that do not match an outstanding request. For example, a msgID
  796.       can be inserted in every message to cater for this functionality.
  797.  
  798.       These mechanisms provide for the detection of authenticated
  799.       messages whose time of generation was not recent.
  800.  
  801.       This protection against the threat of message delay or replay
  802.       does not imply nor provide any protection against unauthorized
  803.       deletion or suppression of messages.  Also, an SNMP engine may
  804.       not be able to detect message reordering if all the messages
  805.       involved are sent within the Time Window interval.  Other
  806.       mechanisms defined independently of the security protocol can
  807.       also be used to detect the re-ordering replay, deletion, or
  808.       suppression of messages containing Set operations (e.g., the
  809.       MIB variable snmpSetSerialNo [RFC1907]).
  810.  
  811.    2) Verification that a message sent to/from one authoritative SNMP
  812.       engine cannot be replayed to/as-if-from another authoritative
  813.       SNMP engine.
  814.  
  815.       Included in each message is an identifier unique to the
  816.       authoritative SNMP engine associated with the sender or intended
  817.       recipient of the message.
  818.  
  819.       A Report, Response or Trap message sent by an authoritative SNMP
  820.       engine to one non-authoritative SNMP engine can potentially be
  821.       replayed to another non-authoritative SNMP engine. The latter
  822.  
  823.  
  824.  
  825. SNMPv3 Working Group        Expires April 1998                 [Page 14]
  826.  
  827. Internet Draft     User-based Security Model for SNMPv3      28 Oct 1997
  828.  
  829.  
  830.       non-authoritative SNMP engine might (if it knows about the same
  831.       userName with the same secrets at the authoritative SNMP engine)
  832.       as a result update its notion of timeliness indicators of the
  833.       authoritative SNMP engine, but that is not considered a threat.
  834.       In this case, A Report or Response message will be discarded by
  835.       the Message Processing Model, because there should not be an
  836.       outstanding Request message. A Trap will possibly be accepted.
  837.       Again, that is not considered a threat, because the communication
  838.       was authenticated and timely. It is as if the authoritative SNMP
  839.       engine was configured to start sending Traps to the second SNMP
  840.       engine, which theoretically can happen without the knowledge of
  841.       the second SNMP engine anyway. Anyway, the second SNMP engine may
  842.       not expect to receive this Trap, but is allowed to see the
  843.       management information contained in it.
  844.  
  845.    3) Detection of messages which were not recently generated.
  846.  
  847.       A set of time indicators are included in the message, indicating
  848.       the time of generation.  Messages without recent time indicators
  849.       are not considered authentic.  In addition, an SNMP engine MUST
  850.       drop any Responses that do not match an outstanding request. This
  851.       however is the responsibility of the Message Processing Model.
  852.  
  853.    This memo allows the same user to be defined on multiple SNMP
  854.    engines.  Each SNMP engine maintains a value, snmpEngineID,
  855.    which uniquely identifies the SNMP engine.  This value is included
  856.    in each message sent to/from the SNMP engine that is authoritative
  857.    (see section 1.5.1).  On receipt of a message, an authoritative
  858.    SNMP engine checks the value to ensure that it is the intended
  859.    recipient, and a non-authoritative SNMP engine uses the value to
  860.    ensure that the message is processed using the correct state
  861.    information.
  862.  
  863.    Each SNMP engine maintains two values, snmpEngineBoots and
  864.    snmpEngineTime, which taken together provide an indication of
  865.    time at that SNMP engine.  Both of these values are included in
  866.    an authenticated message sent to/received from that SNMP engine.
  867.    On receipt, the values are checked to ensure that the indicated
  868.    timeliness value is within a Time Window of the current time.
  869.    The Time Window represents an administrative upper bound on
  870.    acceptable delivery delay for protocol messages.
  871.  
  872.    For an SNMP engine to generate a message which an authoritative
  873.    SNMP engine will accept as authentic, and to verify that a message
  874.    received from that authoritative SNMP engine is authentic, such an
  875.    SNMP engine must first achieve timeliness synchronization with the
  876.    authoritative SNMP engine. See section 2.3.
  877.  
  878. 1.6.  Abstract Service Interfaces.                                        |
  879.                                                                           |
  880.    Abstract service interfaces have been defined to describe the          |
  881.  
  882.  
  883.  
  884. SNMPv3 Working Group        Expires April 1998                 [Page 15]
  885.  
  886. Internet Draft     User-based Security Model for SNMPv3      28 Oct 1997
  887.  
  888.  
  889.    conceptual interfaces between the various subsystems within an SNMP    |
  890.    entity. Similarly a set of abstract service interfaces have been       |
  891.    defined within the User-based Security Model (USM) to describe the     |
  892.    conceptual interfaces between the generic USM services and the         |
  893.    self-contained authentication and privacy services.                    |
  894.                                                                           |
  895.    These abstract service interfaces are defined by a set of primitives   |
  896.    that define the services provided and the abstract data elements that  |
  897.    must be passed when the services are invoked. This section lists the   4
  898.    primitives that have been defined for the User-based Security Model.   4
  899.                                                                           |
  900. 1.6.1.  User-based Security Model Primitives for Authentication           |
  901.                                                                           |
  902.    The User-based Security Model provides the following internal          |
  903.    primitives to pass data back and forth between the Security Model      |
  904.    itself and the authentication service:                                 |
  905.                                                                           |
  906.    statusInformation =                                                    |
  907.      authenticateOutgoingMsg(                                             |
  908.      IN   authKey                   -- secret key for authentication      |
  909.      IN   wholeMsg                  -- unauthenticated complete message   |
  910.      OUT  authenticatedWholeMsg     -- complete authenticated message     |
  911.           )                                                               |
  912.                                                                           |
  913.    statusInformation =                                                    |
  914.      authenticateIncomingMsg(                                             |
  915.      IN   authKey                   -- secret key for authentication      |
  916.      IN   authParameters            -- as received on the wire            |
  917.      IN   wholeMsg                  -- as received on the wire            |
  918.      OUT  authenticatedWholeMsg     -- complete authenticated message     |
  919.           )                                                               |
  920.                                                                           |
  921. 1.6.2.  User-based Security Model Primitives for Privacy                  |
  922.                                                                           |
  923.    The User-based Security Model provides the following internal          |
  924.    primitives to pass data back and forth between the Security Model      |
  925.    itself and the privacy service:                                        |
  926.                                                                           |
  927.    statusInformation =                                                    |
  928.      encryptData(                                                         |
  929.      IN    encryptKey               -- secret key for encryption          |
  930.      IN    dataToEncrypt            -- data to encrypt (scopedPDU)        |
  931.      OUT   encryptedData            -- encrypted data (encryptedPDU)      |
  932.      OUT   privParameters           -- filled in by service provider      |
  933.            )                                                              |
  934.                                                                           |
  935.    statusInformation =                                                    |
  936.      decryptData(                                                         |
  937.      IN    decryptKey               -- secret key for decrypting          |
  938.      IN    privParameters           -- as received on the wire            |
  939.      IN    encryptedData            -- encrypted data (encryptedPDU)      |
  940.  
  941.  
  942.  
  943. SNMPv3 Working Group        Expires April 1998                 [Page 16]
  944.  
  945. Internet Draft     User-based Security Model for SNMPv3      28 Oct 1997
  946.  
  947.  
  948.      OUT   decryptedData            -- decrypted data (scopedPDU)         |
  949.            )                                                              |
  950.  
  951.  
  952.  
  953.  
  954.  
  955.  
  956.  
  957.  
  958.  
  959.  
  960.  
  961.  
  962.  
  963.  
  964.  
  965.  
  966.  
  967.  
  968.  
  969.  
  970.  
  971.  
  972.  
  973.  
  974.  
  975.  
  976.  
  977.  
  978.  
  979.  
  980.  
  981.  
  982.  
  983.  
  984.  
  985.  
  986.  
  987.  
  988.  
  989.  
  990.  
  991.  
  992.  
  993.  
  994.  
  995.  
  996.  
  997.  
  998.  
  999.  
  1000.  
  1001.  
  1002. SNMPv3 Working Group        Expires April 1998                 [Page 17]
  1003.  
  1004. Internet Draft     User-based Security Model for SNMPv3      28 Oct 1997
  1005.  
  1006.  
  1007. 2.  Elements of the Model
  1008.  
  1009.    This section contains definitions required to realize the security
  1010.    model defined by this memo.
  1011.  
  1012. 2.1.  User-based Security Model Users
  1013.  
  1014.    Management operations using this Security Model make use of a
  1015.    defined set of user identities.  For any user on whose behalf
  1016.    management operations are authorized at a particular SNMP engine,
  1017.    that SNMP engine must have knowledge of that user.  An SNMP engine
  1018.    that wishes to communicate with another SNMP engine must also have
  1019.    knowledge of a user known to that engine, including knowledge of
  1020.    the applicable attributes of that user.
  1021.  
  1022.    A user and its attributes are defined as follows:
  1023.  
  1024.    userName
  1025.      A string representing the name of the user.
  1026.  
  1027.    securityName
  1028.      A human-readable string representing the user in a format that
  1029.      is Security Model independent.
  1030.  
  1031.    authProtocol
  1032.      An indication of whether messages sent on behalf of this user can
  1033.      be authenticated, and if so, the type of authentication protocol
  1034.      which is used.  Two such protocols are defined in this memo:         |
  1035.        - the HMAC-MD5-96 authentication protocol.                         |
  1036.        - the HMAC-SHA-96 authentication protocol.                         |
  1037.  
  1038.    authKey
  1039.      If messages sent on behalf of this user can be authenticated,
  1040.      the (private) authentication key for use with the authentication
  1041.      protocol.  Note that a user's authentication key will normally
  1042.      be different at different authoritative SNMP engines. The authKey    |
  1043.      is not accessible via SNMP. The length requirements of the authKey   |
  1044.      are defined by the authProtocol in use.                              |
  1045.  
  1046.    authKeyChange and authOwnKeyChange
  1047.      The only way to remotely update the authentication key.  Does
  1048.      that in a secure manner, so that the update can be completed
  1049.      without the need to employ privacy protection.
  1050.  
  1051.    privProtocol
  1052.      An indication of whether messages sent on behalf of this user
  1053.      can be protected from disclosure, and if so, the type of privacy
  1054.      protocol which is used.  One such protocol is defined in this
  1055.      memo: the CBC-DES Symmetric Encryption Protocol.                     |
  1056.  
  1057.    privKey
  1058.  
  1059.  
  1060.  
  1061. SNMPv3 Working Group        Expires April 1998                 [Page 18]
  1062.  
  1063. Internet Draft     User-based Security Model for SNMPv3      28 Oct 1997
  1064.  
  1065.  
  1066.      If messages sent on behalf of this user can be en/decrypted,
  1067.      the (private) privacy key for use with the privacy protocol.
  1068.      Note that a user's privacy key will normally be different at
  1069.      different authoritative SNMP engines. The privKey is not
  1070.      accessible via SNMP. The length requirements of the privKey are      |
  1071.      defined by the privProtocol in use.                                  |
  1072.  
  1073.    privKeyChange and privOwnKeyChange
  1074.      The only way to remotely update the encryption key. Does that
  1075.      in a secure manner, so that the update can be completed without
  1076.      the need to employ privacy protection.
  1077.  
  1078.  
  1079. 2.2.  Replay Protection
  1080.  
  1081.    Each SNMP engine maintains three objects:
  1082.  
  1083.    - snmpEngineID, which (at least within an administrative domain)
  1084.      uniquely and unambiguously identifies an SNMP engine.
  1085.  
  1086.    - snmpEngineBoots, which is a count of the number of times the
  1087.      SNMP engine has re-booted/re-initialized since snmpEngineID
  1088.      was last configured; and,
  1089.  
  1090.    - snmpEngineTime, which is the number of seconds since the
  1091.      snmpEngineBoots counter was last incremented.
  1092.  
  1093.    Each SNMP engine is always authoritative with respect to these
  1094.    objects in its own SNMP entity.  It is the responsibility of a
  1095.    non-authoritative SNMP engine to synchronize with the
  1096.    authoritative SNMP engine, as appropriate.
  1097.  
  1098.    An authoritative SNMP engine is required to maintain the values of
  1099.    its snmpEngineID and snmpEngineBoots in non-volatile storage.
  1100.  
  1101. 2.2.1.  msgAuthoritativeEngineID
  1102.  
  1103.    The msgAuthoritativeEngineID value contained in an authenticated
  1104.    message is used to defeat attacks in which messages from one SNMP
  1105.    engine to another SNMP engine are replayed to a different SNMP
  1106.    engine. It represents the snmpEngineID at the authoritative SNMP
  1107.    engine involved in the exchange of the message.
  1108.  
  1109.    When an authoritative SNMP engine is first installed, it sets its
  1110.    local value of snmpEngineID according to a enterprise-specific
  1111.    algorithm (see the definition of the Textual Convention for
  1112.    SnmpEngineID in the SNMP Architecture document [SNMP-ARCH]).
  1113.  
  1114. 2.2.2.  msgAuthoritativeEngineBoots and msgAuthoritativeEngineTime
  1115.  
  1116.    The msgAuthoritativeEngineBoots and msgAuthoritativeEngineTime
  1117.  
  1118.  
  1119.  
  1120. SNMPv3 Working Group        Expires April 1998                 [Page 19]
  1121.  
  1122. Internet Draft     User-based Security Model for SNMPv3      28 Oct 1997
  1123.  
  1124.  
  1125.    values contained in an authenticated message are used to defeat
  1126.    attacks in which messages are replayed when they are no longer
  1127.    valid.  They represent the snmpEngineBoots and snmpEngineTime
  1128.    values at the authoritative SNMP engine involved in the exchange
  1129.    of the message.
  1130.  
  1131.    Through use of snmpEngineBoots and snmpEngineTime, there is no
  1132.    requirement for an SNMP engine to have a non-volatile clock which
  1133.    ticks (i.e., increases with the passage of time) even when the
  1134.    SNMP engine is powered off.  Rather, each time an SNMP engine
  1135.    re-boots, it retrieves, increments, and then stores snmpEngineBoots
  1136.    in non-volatile storage, and resets snmpEngineTime to zero.
  1137.  
  1138.    When an SNMP engine is first installed, it sets its local values
  1139.    of snmpEngineBoots and snmpEngineTime to zero.  If snmpEngineTime
  1140.    ever reaches its maximum value (2147483647), then snmpEngineBoots
  1141.    is incremented as if the SNMP engine has re-booted and
  1142.    snmpEngineTime is reset to zero and starts incrementing again.
  1143.  
  1144.    Each time an authoritative SNMP engine re-boots, any SNMP engines
  1145.    holding that authoritative SNMP engine's values of snmpEngineBoots
  1146.    and snmpEngineTime need to re-synchronize prior to sending
  1147.    correctly authenticated messages to that authoritative SNMP engine
  1148.    (see Section 2.3 for (re-)synchronization procedures).  Note,
  1149.    however, that the procedures do provide for a notification to be
  1150.    accepted as authentic by a receiving SNMP engine, when sent by an
  1151.    authoritative SNMP engine which has re-booted since the receiving
  1152.    SNMP engine last (re-)synchronized.
  1153.  
  1154.    If an authoritative SNMP engine is ever unable to determine its
  1155.    latest snmpEngineBoots value, then it must set its snmpEngineBoots
  1156.    value to 2147483647.                                                   3
  1157.                                                                           3
  1158.    Whenever the local value of snmpEngineBoots has the value 2147483647   3
  1159.    it latches at that value and an authenticated message always causes    3
  1160.    an notInTimeWindow authentication failure.                             3
  1161.  
  1162.    In order to reset an SNMP engine whose snmpEngineBoots value has
  1163.    reached the value 2147483647, manual intervention is required.         3
  1164.    The engine must be physically visited and re-configured, either
  1165.    with a new snmpEngineID value, or with new secret values for the
  1166.    authentication and privacy protocols of all users known to that
  1167.    SNMP engine. Note that even if an SNMP engine re-boots once a second   3
  1168.    that it would still take approximately 68 years before the max value   3
  1169.    of 2147483647 would be reached.                                        3
  1170.  
  1171. 2.2.3.  Time Window
  1172.  
  1173.    The Time Window is a value that specifies the window of time in
  1174.    which a message generated on behalf of any user is valid.  This
  1175.    memo specifies that the same value of the Time Window, 150 seconds,
  1176.  
  1177.  
  1178.  
  1179. SNMPv3 Working Group        Expires April 1998                 [Page 20]
  1180.  
  1181. Internet Draft     User-based Security Model for SNMPv3      28 Oct 1997
  1182.  
  1183.  
  1184.    is used for all users.
  1185.  
  1186. 2.3.  Time Synchronization
  1187.  
  1188.    Time synchronization, required by a non-authoritative SNMP engine
  1189.    in order to proceed with authentic communications, has occurred
  1190.    when the non-authoritative SNMP engine has obtained a local notion
  1191.    of the authoritative SNMP engine's values of snmpEngineBoots and
  1192.    snmpEngineTime from the authoritative SNMP engine.  These values
  1193.    must be (and remain) within the authoritative SNMP engine's Time
  1194.    Window.  So the local notion of the authoritative SNMP engine's
  1195.    values must be kept loosely synchronized with the values stored
  1196.    at the authoritative SNMP engine.  In addition to keeping a local
  1197.    copy of snmpEngineBoots and snmpEngineTime from the authoritative
  1198.    SNMP engine, a non-authoritative SNMP engine must also keep one
  1199.    local variable, latestReceivedEngineTime.  This value records the
  1200.    highest value of snmpEngineTime that was received by the
  1201.    non-authoritative SNMP engine from the authoritative SNMP engine
  1202.    and is used to eliminate the possibility of replaying messages
  1203.    that would prevent the non-authoritative SNMP engine's notion of
  1204.    the snmpEngineTime from advancing.
  1205.  
  1206.    A non-authoritative SNMP engine must keep local notions of these
  1207.    values for each authoritative SNMP engine with which it wishes to
  1208.    communicate.  Since each authoritative SNMP engine is uniquely
  1209.    and unambiguously identified by its value of snmpEngineID, the
  1210.    non-authoritative SNMP engine may use this value as a key in
  1211.    order to cache its local notions of these values.
  1212.  
  1213.    Time synchronization occurs as part of the procedures of receiving
  1214.    an SNMP message (Section 3.2, step 7b). As such, no explicit time      |
  1215.    synchronization procedure is required by a non-authoritative SNMP      |
  1216.    engine.  Note, that whenever the local value of snmpEngineID is        |
  1217.    changed (e.g., through discovery) or when secure communications        |
  1218.    are first established with an authoritative SNMP engine, the local     |
  1219.    values of snmpEngineBoots and latestReceivedEngineTime should be       |
  1220.    set to zero.  This will cause the time synchronization to occur        |
  1221.    when the next authentic message is received.                           |
  1222.                                                                           5
  1223.  
  1224.  
  1225.  
  1226.  
  1227.  
  1228.  
  1229.  
  1230.  
  1231.  
  1232.  
  1233.  
  1234.  
  1235.  
  1236.  
  1237.  
  1238. SNMPv3 Working Group        Expires April 1998                 [Page 21]
  1239.  
  1240. Internet Draft     User-based Security Model for SNMPv3      28 Oct 1997
  1241.  
  1242.  
  1243. 2.4.  SNMP Messages Using this Security Model
  1244.  
  1245.    The syntax of an SNMP message using this Security Model adheres
  1246.    to the message format defined in the version-specific Message
  1247.    Processing Model document (for example [SNMP-MP]).
  1248.  
  1249.    The field msgSecurityParameters in SNMPv3 messages has a data type
  1250.    of OCTET STRING.  Its value is the BER serialization of the
  1251.    following ASN.1 sequence:
  1252.  
  1253.    USMSecurityParametersSyntax DEFINITIONS IMPLICIT TAGS ::= BEGIN        |
  1254.                                                                           4
  1255.       UsmSecurityParameters ::=
  1256.           SEQUENCE {
  1257.            -- global User-based security parameters
  1258.               msgAuthoritativeEngineID     OCTET STRING,                  |
  1259.               msgAuthoritativeEngineBoots  INTEGER (0..2147483647),       3
  1260.               msgAuthoritativeEngineTime   INTEGER (0..2147483647),       3
  1261.               msgUserName                  OCTET STRING (SIZE(1..32)),    |
  1262.            -- authentication protocol specific parameters
  1263.               msgAuthenticationParameters  OCTET STRING,
  1264.            -- privacy protocol specific parameters
  1265.               msgPrivacyParameters         OCTET STRING                   |
  1266.           }
  1267.    END
  1268.  
  1269.    The fields of this sequence are:
  1270.  
  1271.    - The msgAuthoritativeEngineID specifies the snmpEngineID of the
  1272.      authoritative SNMP engine involved in the exchange of the message.
  1273.  
  1274.    - The msgAuthoritativeEngineBoots specifies the snmpEngineBoots
  1275.      value at the authoritative SNMP engine involved in the exchange
  1276.      of the message.
  1277.  
  1278.    - The msgAuthoritativeEngineTime specifies the snmpEngineTime value
  1279.      at the authoritative SNMP engine involved in the exchange of the
  1280.      message.
  1281.  
  1282.    - The msgUserName specifies the user (principal) on whose behalf
  1283.      the message is being exchanged.
  1284.  
  1285.    - The msgAuthenticationParameters are defined by the authentication
  1286.      protocol in use for the message, as defined by the
  1287.      usmUserAuthProtocol column in the user's entry in the usmUserTable.
  1288.  
  1289.    - The msgPrivacyParameters are defined by the privacy protocol in
  1290.      use for the message, as defined by the usmUserPrivProtocol column
  1291.      in the user's entry in the usmUserTable).
  1292.  
  1293.    See appendix A.4 for an example of the BER encoding of field
  1294.  
  1295.  
  1296.  
  1297. SNMPv3 Working Group        Expires April 1998                 [Page 22]
  1298.  
  1299. Internet Draft     User-based Security Model for SNMPv3      28 Oct 1997
  1300.  
  1301.  
  1302.    msgSecurityParameters.
  1303.  
  1304. 2.5.  Services provided by the User-based Security Model
  1305.  
  1306.    This section describes the services provided by the User-based
  1307.    Security Model with their inputs and outputs.
  1308.  
  1309.    The services are described as primitives of an abstract service
  1310.    interface and the inputs and outputs are described as abstract data
  1311.    elements as they are passed in these abstract service primitives.
  1312.  
  1313.  
  1314. 2.5.1.  Services for Generating an Outgoing SNMP Message
  1315.  
  1316.    When the Message Processing (MP) Subsystem invokes the User-based
  1317.    Security module to secure an outgoing SNMP message, it must use
  1318.    the appropriate service as provided by the Security module.  These
  1319.    two services are provided:
  1320.  
  1321.    1) A service to generate a Request message. The abstract service
  1322.       primitive is:
  1323.  
  1324.       statusInformation =            -- success or errorIndication
  1325.         generateRequestMsg(
  1326.         IN   messageProcessingModel  -- typically, SNMP version
  1327.         IN   globalData              -- message header, admin data
  1328.         IN   maxMessageSize          -- of the sending SNMP entity
  1329.         IN   securityModel           -- for the outgoing message
  1330.         IN   securityEngineID        -- authoritative SNMP entity
  1331.         IN   securityName            -- on behalf of this principal
  1332.         IN   securityLevel           -- Level of Security requested
  1333.         IN   scopedPDU               -- message (plaintext) payload
  1334.         OUT  securityParameters      -- filled in by Security Module
  1335.         OUT  wholeMsg                -- complete generated message
  1336.         OUT  wholeMsgLength          -- length of generated message
  1337.              )
  1338.  
  1339.    2) A service to generate a Response message. The abstract service
  1340.       primitive is:
  1341.  
  1342.       statusInformation =            -- success or errorIndication
  1343.         generateResponseMsg(
  1344.         IN   messageProcessingModel  -- typically, SNMP version
  1345.         IN   globalData              -- message header, admin data
  1346.         IN   maxMessageSize          -- of the sending SNMP entity
  1347.         IN   securityModel           -- for the outgoing message
  1348.         IN   securityEngineID        -- authoritative SNMP entity
  1349.         IN   securityName            -- on behalf of this principal
  1350.         IN   securityLevel           -- Level of Security requested
  1351.         IN   scopedPDU               -- message (plaintext) payload
  1352.         IN   securityStateReference  -- reference to security state
  1353.  
  1354.  
  1355.  
  1356. SNMPv3 Working Group        Expires April 1998                 [Page 23]
  1357.  
  1358. Internet Draft     User-based Security Model for SNMPv3      28 Oct 1997
  1359.  
  1360.  
  1361.                                      -- information from original
  1362.                                      -- request
  1363.         OUT  securityParameters      -- filled in by Security Module
  1364.         OUT  wholeMsg                -- complete generated message
  1365.         OUT  wholeMsgLength          -- length of generated message
  1366.              )
  1367.  
  1368.    The abstract data elements passed as parameters in the abstract
  1369.    service primitives are as follows:
  1370.  
  1371.     statusInformation
  1372.       An indication of whether the encoding and securing of the message
  1373.       was successful.  If not it is an indication of the problem.
  1374.     messageProcessingModel
  1375.       The SNMP version number for the message to be generated.
  1376.       This data is not used by the User-based Security module.
  1377.     globalData
  1378.       The message header (i.e., its administrative information). This     |
  1379.       data is not used by the User-based Security module.
  1380.     maxMessageSize
  1381.       The maximum message size as included in the message.
  1382.       This data is not used by the User-based Security module.
  1383.     securityParameters
  1384.       These are the security parameters. They will be filled in
  1385.       by the User-based Security module.
  1386.     securityModel
  1387.       The securityModel in use. Should be User-based Security Model.
  1388.       This data is not used by the User-based Security module.
  1389.     securityName
  1390.       Together with the snmpEngineID it identifies a row in the
  1391.       usmUserTable that is to be used for securing the message.
  1392.       The securityName has a format that is independent of the
  1393.       Security Model. In case of a response this parameter is
  1394.       ignored and the value from the cache is used.                       5
  1395.     securityLevel
  1396.       The Level of Security from which the User-based Security
  1397.       module determines if the message needs to be protected from
  1398.       disclosure and if the message needs to be authenticated.
  1399.       In case of a response this parameter is ignored and the value
  1400.       from the cache is used.                                             5
  1401.     securityEngineID
  1402.       The snmpEngineID of the authoritative SNMP engine to which a
  1403.       Request message is to be sent. In case of a response it is
  1404.       implied to be the processing SNMP engine's snmpEngineID and
  1405.       so if it is specified, then it is ignored.
  1406.     scopedPDU
  1407.       The message payload.  The data is opaque as far as the
  1408.       User-based Security Model is concerned.
  1409.     securityStateReference
  1410.       A handle/reference to cachedSecurityData to be used when
  1411.       securing an outgoing Response message.  This is the exact same
  1412.  
  1413.  
  1414.  
  1415. SNMPv3 Working Group        Expires April 1998                 [Page 24]
  1416.  
  1417. Internet Draft     User-based Security Model for SNMPv3      28 Oct 1997
  1418.  
  1419.  
  1420.       handle/reference as it was generated by the User-based Security
  1421.       module when processing the incoming Request message to which
  1422.       this is the Response message.
  1423.     wholeMsg
  1424.       The fully encoded and secured message ready for sending on
  1425.       the wire.
  1426.     wholeMsgLength
  1427.       The length of the encoded and secured message (wholeMsg).
  1428.  
  1429.    Upon completion of the process, the User-based Security module
  1430.    returns statusInformation. If the process was successful, the
  1431.    completed message with privacy and authentication applied if such
  1432.    was requested by the specified securityLevel is returned. If the       5
  1433.    process was not successful, then an errorIndication is returned.       5
  1434.  
  1435. 2.5.2.  Services for Processing an Incoming SNMP Message
  1436.  
  1437.    When the Message Processing (MP) Subsystem invokes the User-based
  1438.    Security module to verify proper security of an incoming message,
  1439.    it must use the service provided for an incoming message. The
  1440.    abstract service primitive is:
  1441.  
  1442.    statusInformation =             -- errorIndication or success
  1443.                                    -- error counter OID/value if error
  1444.      processIncomingMsg(
  1445.      IN   messageProcessingModel   -- typically, SNMP version
  1446.      IN   maxMessageSize           -- of the sending SNMP entity
  1447.      IN   securityParameters       -- for the received message
  1448.      IN   securityModel            -- for the received message
  1449.      IN   securityLevel            -- Level of Security
  1450.      IN   wholeMsg                 -- as received on the wire
  1451.      IN   wholeMsgLength           -- length as received on the wire
  1452.      OUT  securityEngineID         -- authoritative SNMP entity
  1453.      OUT  securityName             -- identification of the principal
  1454.      OUT  scopedPDU,               -- message (plaintext) payload
  1455.      OUT  maxSizeResponseScopedPDU -- maximum size of the Response PDU
  1456.      OUT  securityStateReference   -- reference to security state
  1457.           )                        -- information, needed for response
  1458.  
  1459.    The abstract data elements passed as parameters in the abstract
  1460.    service primitives are as follows:
  1461.  
  1462.     statusInformation
  1463.       An indication of whether the process was successful or not.
  1464.       If not, then the statusInformation includes the OID and the
  1465.       value of the error counter that was incremented.
  1466.     messageProcessingModel
  1467.       The SNMP version number as received in the message.
  1468.       This data is not used by the User-based Security module.
  1469.     maxMessageSize
  1470.       The maximum message size as included in the message.
  1471.  
  1472.  
  1473.  
  1474. SNMPv3 Working Group        Expires April 1998                 [Page 25]
  1475.  
  1476. Internet Draft     User-based Security Model for SNMPv3      28 Oct 1997
  1477.  
  1478.  
  1479.       The User-based Security module uses this value to calculate the
  1480.       maxSizeResponseScopedPDU.
  1481.     securityParameters
  1482.       These are the security parameters as received in the message.
  1483.     securityModel
  1484.       The securityModel in use.
  1485.       Should be the User-based Security Model.
  1486.       This data is not used by the User-based Security module.
  1487.     securityLevel
  1488.       The Level of Security from which the User-based Security
  1489.       module determines if the message needs to be protected from
  1490.       disclosure and if the message needs to be authenticated.
  1491.     wholeMsg
  1492.       The whole message as it was received.
  1493.     wholeMsgLength
  1494.       The length of the message as it was received (wholeMsg).
  1495.     securityEngineID
  1496.       The snmpEngineID that was extracted from the field
  1497.       msgAuthoritativeEngineID and that was used to lookup the secrets
  1498.       in the usmUserTable.
  1499.     securityName
  1500.       The security name representing the user on whose behalf the
  1501.       message was received.  The securityName has a format that is
  1502.       independent of the Security Model.
  1503.     scopedPDU
  1504.       The message payload.  The data is opaque as far as the
  1505.       User-based Security Model is concerned.
  1506.     maxSizeResponseScopedPDU
  1507.       The maximum size of a scopedPDU to be included in a possible
  1508.       Response message.  The User-base Security module calculates
  1509.       this size based on the mms (as received in the message) and
  1510.       the space required for the message header (including the
  1511.       securityParameters) for such a Response message.
  1512.     securityStateReference
  1513.       A handle/reference to cachedSecurityData to be used when
  1514.       securing an outgoing Response message.  When the Message
  1515.       Processing Subsystem calls the User-based Security module to
  1516.       generate a response to this incoming message it must pass this
  1517.       handle/reference.
  1518.  
  1519.    Upon completion of the process, the User-based Security module
  1520.    returns statusInformation and, if the process was successful,
  1521.    the additional data elements for further processing of the message.
  1522.    If the process was not successful, then an errorIndication,
  1523.    possibly with a OID and value pair of an error counter that was
  1524.    incremented.
  1525.  
  1526. 2.6.  Key Localization Algorithm.                                         3
  1527.                                                                           3
  1528.    A localized key is a secret key shared between a user U and one        3
  1529.    authoritative SNMP engine E.  Even though a user may have only one     3
  1530.  
  1531.  
  1532.  
  1533. SNMPv3 Working Group        Expires April 1998                 [Page 26]
  1534.  
  1535. Internet Draft     User-based Security Model for SNMPv3      28 Oct 1997
  1536.  
  1537.  
  1538.    password and therefore one key for the whole network, the actual       3
  1539.    secrets shared between the user and each authoritative SNMP engine     3
  1540.    will be different. This is achieved by key localization                3
  1541.    [Localized-key].                                                       3
  1542.                                                                           3
  1543.    First, if a user uses a password, then the user's password is          3
  1544.    converted into a key Ku using one of the two algorithms described      4
  1545.    in Appendices A.2.1 and A.2.2.                                         3
  1546.                                                                           3
  1547.    To convert key Ku into a localized key Kul of user U at the            4
  1548.    authoritative SNMP engine E, one appends the snmpEngineID of the       3
  1549.    authoritative SNMP engine to the key Ku and then appends the key Ku    4
  1550.    to the result, thus enveloping the snmpEngineID within the two         3
  1551.    copies of user's key Ku. Then one runs a secure hash function          4
  1552.    (which one depends on the authentication protocol defined for this     3
  1553.    user U at authoritative SNMP engine E; this document defines two       3
  1554.    authentication protocols with their associated algorithms based on     3
  1555.    MD5 and SHA). The output of the hash-function is the localized key     3
  1556.    Kul for user U at the authoritative SNMP engine E.                     4
  1557.                                                                           3
  1558.  
  1559.  
  1560.  
  1561.  
  1562.  
  1563.  
  1564.  
  1565.  
  1566.  
  1567.  
  1568.  
  1569.  
  1570.  
  1571.  
  1572.  
  1573.  
  1574.  
  1575.  
  1576.  
  1577.  
  1578.  
  1579.  
  1580.  
  1581.  
  1582.  
  1583.  
  1584.  
  1585.  
  1586.  
  1587.  
  1588.  
  1589.  
  1590.  
  1591.  
  1592. SNMPv3 Working Group        Expires April 1998                 [Page 27]
  1593.  
  1594. Internet Draft     User-based Security Model for SNMPv3      28 Oct 1997
  1595.  
  1596.  
  1597. 3.  Elements of Procedure
  1598.  
  1599.    This section describes the security related procedures followed by
  1600.    an SNMP engine when processing SNMP messages according to the
  1601.    User-based Security Model.
  1602.  
  1603. 3.1.  Generating an Outgoing SNMP Message
  1604.  
  1605.    This section describes the procedure followed by an SNMP engine
  1606.    whenever it generates a message containing a management operation
  1607.    (like a request, a response, a notification, or a report) on
  1608.    behalf of a user, with a particular securityLevel.
  1609.  
  1610.    1)  a) If any securityStateReference is passed (Response message),
  1611.           then information concerning the user is extracted from the
  1612.           cachedSecurityData.  The securityEngineID and the
  1613.           securityLevel are extracted from the cachedSecurityData.
  1614.           The cachedSecurityData can now be discarded.
  1615.  
  1616.           Otherwise,
  1617.  
  1618.        b) based on the securityName, information concerning the
  1619.           user at the destination snmpEngineID, specified by the
  1620.           securityEngineID, is extracted from the Local Configuration
  1621.           Datastore (LCD, usmUserTable). If information about the user
  1622.           is absent from the LCD, then an error indication
  1623.           (unknownSecurityName) is returned to the calling module.
  1624.  
  1625.    2)  If the securityLevel specifies that the message is to be
  1626.        protected from disclosure, but the user does not support both
  1627.        an authentication and a privacy protocol then the message
  1628.        cannot be sent.  An error indication (unsupportedSecurityLevel)
  1629.        is returned to the calling module.
  1630.  
  1631.    3)  If the securityLevel specifies that the message is to be
  1632.        authenticated, but the user does not support an authentication
  1633.        protocol, then the message cannot be sent. An error indication
  1634.        (unsupportedSecurityLevel) is returned to the calling module.
  1635.  
  1636.    4)  a) If the securityLevel specifies that the message is to be
  1637.           protected from disclosure, then the octet sequence
  1638.           representing the serialized scopedPDU is encrypted according
  1639.           to the user's privacy protocol. To do so a call is made to
  1640.           the privacy module that implements the user's privacy
  1641.           protocol according to the abstract primitive:
  1642.  
  1643.           statusInformation =       -- success or failure
  1644.             encryptData(
  1645.             IN    encryptKey        -- user's localized privKey           3
  1646.             IN    dataToEncrypt     -- serialized scopedPDU
  1647.             OUT   encryptedData     -- serialized encryptedPDU
  1648.  
  1649.  
  1650.  
  1651. SNMPv3 Working Group        Expires April 1998                 [Page 28]
  1652.  
  1653. Internet Draft     User-based Security Model for SNMPv3      28 Oct 1997
  1654.  
  1655.  
  1656.             OUT   privParameters    -- serialized privacy parameters
  1657.                   )
  1658.  
  1659.           statusInformation
  1660.             indicates if the encryption process was successful or not.
  1661.           encryptKey
  1662.             the user's localized private privKey is the secret key that   3
  1663.             can be used by the encryption algorithm.                      3
  1664.           dataToEncrypt
  1665.             the serialized scopedPDU is the data that to be encrypted.
  1666.           encryptedData
  1667.             the encryptedPDU represents the encrypted scopedPDU,
  1668.             encoded as an OCTET STRING.
  1669.           privParameters
  1670.             the privacy parameters, encoded as an OCTET STRING.
  1671.  
  1672.           If the privacy module returns failure, then the message
  1673.           cannot be sent and an error indication (encryptionError)        4
  1674.           is returned to the calling module.
  1675.  
  1676.           If the privacy module returns success, then the returned
  1677.           privParameters are put into the msgPrivacyParameters field of
  1678.           the securityParameters and the encryptedPDU serves as the
  1679.           payload of the message being prepared.
  1680.  
  1681.           Otherwise,
  1682.  
  1683.        b) If the securityLevel specifies that the message is not to be
  1684.           protected from disclosure, then the NULL string is encoded
  1685.           as an OCTET STRING and put into the msgPrivacyParameters
  1686.           field of the securityParameters and the plaintext scopedPDU
  1687.           serves as the payload of the message being prepared.
  1688.  
  1689.    5)  The snmpEngineID is encoded as an OCTET STRING into the
  1690.        msgAuthoritativeEngineID field of the securityParameters.
  1691.        Note that an empty (zero length) snmpEngineID is OK for a
  1692.        Request message, because that will cause the remote
  1693.        (authoritative) SNMP engine to return a Report PDU with the
  1694.        proper snmpEngineID included in the msgAuthoritativeEngineID in    5
  1695.        the securityParameters of that returned Report PDU.                5
  1696.  
  1697.    6)  a) If the securityLevel specifies that the message is to be
  1698.           authenticated, then the current values of snmpEngineBoots
  1699.           and snmpEngineTime corresponding to the snmpEngineID from
  1700.           the LCD are used.
  1701.  
  1702.           Otherwise,
  1703.  
  1704.        b) If this is a Response message, then the current value of
  1705.           snmpEngineBoots and snmpEngineTime corresponding to the
  1706.           local snmpEngineID from the LCD are used.
  1707.  
  1708.  
  1709.  
  1710. SNMPv3 Working Group        Expires April 1998                 [Page 29]
  1711.  
  1712. Internet Draft     User-based Security Model for SNMPv3      28 Oct 1997
  1713.  
  1714.  
  1715.  
  1716.           Otherwise,
  1717.  
  1718.        c) If this is a Request message, then a zero value is used
  1719.           for both snmpEngineBoots and snmpEngineTime. This zero
  1720.           value gets used if snmpEngineID is empty.
  1721.  
  1722.        The values are encoded as Unsigned32 and Integer32 respectively    |
  1723.        into the msgAuthoritativeEngineBoots and                           |
  1724.        msgAuthoritativeEngineTime fields of the securityParameters.       |
  1725.  
  1726.    7)  The userName is encoded as an OCTET STRING into the msgUserName
  1727.        field of the securityParameters.
  1728.  
  1729.    8)  a) If the securityLevel specifies that the message is to be
  1730.           authenticated, the message is authenticated according to the
  1731.           user's authentication protocol. To do so a call is made to
  1732.           the authentication module that implements the user's
  1733.           authentication protocol according to the abstract service
  1734.           primitive:
  1735.  
  1736.           statusInformation =
  1737.             authenticateOutgoingMsg(
  1738.             IN  authKey               -- the user's localized authKey     3
  1739.             IN  wholeMsg              -- unauthenticated message
  1740.             OUT authenticatedWholeMsg -- authenticated complete message
  1741.                 )
  1742.  
  1743.           statusInformation
  1744.             indicates if authentication was successful or not.
  1745.           authKey
  1746.             the user's localized private authKey is the secret key that   3
  1747.             can be used by the authentication algorithm.                  3
  1748.           wholeMsg
  1749.             the complete serialized message to be authenticated.
  1750.           authenticatedWholeMsg
  1751.             the same as the input given to the authenticateOutgoingMsg
  1752.             service, but with msgAuthenticationParameters properly
  1753.             filled in.
  1754.  
  1755.           If the authentication module returns failure, then the
  1756.           message cannot be sent and an error indication
  1757.           (authenticationFailure) is returned to the calling module.
  1758.  
  1759.           If the authentication module returns success, then the
  1760.           msgAuthenticationParameters field is put into the
  1761.           securityParameters and the authenticatedWholeMsg represents
  1762.           the serialization of the authenticated message being
  1763.           prepared.
  1764.  
  1765.           Otherwise,
  1766.  
  1767.  
  1768.  
  1769. SNMPv3 Working Group        Expires April 1998                 [Page 30]
  1770.  
  1771. Internet Draft     User-based Security Model for SNMPv3      28 Oct 1997
  1772.  
  1773.  
  1774.  
  1775.        b) If the securityLevel specifies that the message is not to
  1776.           be authenticated then the NULL string is encoded as an
  1777.           OCTET STRING into the msgAuthenticationParameters field of
  1778.           the securityParameters.  The wholeMsg is now serialized and
  1779.           then represents the unauthenticated message being prepared.
  1780.  
  1781.    9)  The completed message with its length is returned to the
  1782.        calling module with the statusInformation set to success.
  1783.  
  1784. 3.2.  Processing an Incoming SNMP Message
  1785.  
  1786.    This section describes the procedure followed by an SNMP engine
  1787.    whenever it receives a message containing a management operation
  1788.    on behalf of a user, with a particular securityLevel.
  1789.  
  1790.    To simplify the elements of procedure, the release of state
  1791.    information is not always explicitly specified. As a general rule,
  1792.    if state information is available when a message gets discarded,
  1793.    the state information should also be released.
  1794.    Also, when an error indication with an OID and value for an
  1795.    incremented counter is returned, then the available information
  1796.    (like securityStateReference) must be passed back to the caller
  1797.    so it can generate a Report PDU.
  1798.  
  1799.    1)  If the received securityParameters is not the serialization
  1800.        (according to the conventions of [RFC1906]) of an OCTET STRING
  1801.        formatted according to the UsmSecurityParameters defined in
  1802.        section 2.4, then the snmpInASNParseErrs counter [RFC1907] is
  1803.        incremented, and an error indication (parseError) is returned
  1804.        to the calling module.
  1805.        Note that we return without the OID and value of the incremented
  1806.        counter, because in this case there is not enough information
  1807.        to generate a Report PDU.
  1808.  
  1809.    2)  The values of the security parameter fields are extracted from
  1810.        the securityParameters. The securityEngineID to be returned to
  1811.        the caller is the value of the msgAuthoritativeEngineID field.
  1812.        The cachedSecurityData is prepared and a securityStateReference
  1813.        is prepared to reference this data. Values to be cached are:
  1814.  
  1815.            msgUserName
  1816.            securityEngineID
  1817.            securityLevel
  1818.  
  1819.    3)  If the value of the msgAuthoritativeEngineID field in the
  1820.        securityParameters is unknown then:
  1821.  
  1822.        a) a non-authoritative SNMP engine that performs discovery may
  1823.           optionally create a new entry in its Local Configuration
  1824.           Datastore (LCD) and continue processing;
  1825.  
  1826.  
  1827.  
  1828. SNMPv3 Working Group        Expires April 1998                 [Page 31]
  1829.  
  1830. Internet Draft     User-based Security Model for SNMPv3      28 Oct 1997
  1831.  
  1832.  
  1833.  
  1834.           or
  1835.  
  1836.        b) the usmStatsUnknownEngineIDs counter is incremented, and
  1837.           an error indication (unknownEngineID) together with the
  1838.           OID and value of the incremented counter is returned to
  1839.           the calling module.
  1840.  
  1841.    4)  Information about the value of the msgUserName and
  1842.        msgAuthoritativeEngineID fields is extracted from the Local
  1843.        Configuration Datastore (LCD, usmUserTable).  If no information
  1844.        is available for the user, then the usmStatsUnknownUserNames
  1845.        counter is incremented and an error indication
  1846.        (unknownSecurityName) together with the OID and value of the
  1847.        incremented counter is returned to the calling module.
  1848.  
  1849.    5)  If the information about the user indicates that it does not
  1850.        support the securityLevel requested by the caller, then the
  1851.        usmStatsUnsupportedSecLevels counter is incremented and an
  1852.        error indication (unsupportedSecurityLevel) together with the
  1853.        OID and value of the incremented counter is returned to the
  1854.        calling module.
  1855.  
  1856.    6)  If the securityLevel specifies that the message is to be
  1857.        authenticated, then the message is authenticated according to
  1858.        the user's authentication protocol. To do so a call is made
  1859.        to the authentication module that implements the user's
  1860.        authentication protocol according to the abstract service
  1861.        primitive:
  1862.  
  1863.        statusInformation =          -- success or failure
  1864.          authenticateIncomingMsg(
  1865.          IN   authKey               -- the user's localized authKey       3
  1866.          IN   authParameters        -- as received on the wire
  1867.          IN   wholeMsg              -- as received on the wire
  1868.          OUT  authenticatedWholeMsg -- checked for authentication
  1869.                  )
  1870.  
  1871.        statusInformation
  1872.          indicates if authentication was successful or not.
  1873.        authKey
  1874.          the user's localized private authKey is the secret key that      3
  1875.          can be used by the authentication algorithm.                     3
  1876.        wholeMsg
  1877.          the complete serialized message to be authenticated.
  1878.        authenticatedWholeMsg
  1879.          the same as the input given to the authenticateIncomingMsg
  1880.          service, but after authentication has been checked.
  1881.  
  1882.        If the authentication module returns failure, then the message
  1883.        cannot be trusted, so the usmStatsWrongDigests counter is
  1884.  
  1885.  
  1886.  
  1887. SNMPv3 Working Group        Expires April 1998                 [Page 32]
  1888.  
  1889. Internet Draft     User-based Security Model for SNMPv3      28 Oct 1997
  1890.  
  1891.  
  1892.        incremented and an error indication (authenticationFailure)
  1893.        together with the OID and value of the incremented counter is
  1894.        returned to the calling module.
  1895.  
  1896.        If the authentication module returns success, then the message
  1897.        is authentic and can be trusted so processing continues.
  1898.  
  1899.    7)  If the securityLevel indicates an authenticated message, then
  1900.        the local values of snmpEngineBoots and snmpEngineTime
  1901.        corresponding to the value of the msgAuthoritativeEngineID
  1902.        field are extracted from the Local Configuration Datastore.
  1903.  
  1904.        a) If the extracted value of msgAuthoritativeEngineID is the
  1905.           same as the value of snmpEngineID of the processing SNMP
  1906.           engine (meaning this is the authoritative SNMP engine),
  1907.           then if any of the following conditions is true, then the
  1908.           message is considered to be outside of the Time Window:
  1909.  
  1910.            - the local value of snmpEngineBoots is 2147483647;            3
  1911.  
  1912.            - the value of the msgAuthoritativeEngineBoots field differs
  1913.              from the local value of snmpEngineBoots; or,
  1914.  
  1915.            - the value of the msgAuthoritativeEngineTime field differs
  1916.              from the local notion of snmpEngineTime by more than
  1917.              +/- 150 seconds.
  1918.  
  1919.           If the message is considered to be outside of the Time Window
  1920.           then the usmStatsNotInTimeWindows counter is incremented and
  1921.           an error indication (notInTimeWindow) together with the OID
  1922.           and value of the incremented counter is returned to the
  1923.           calling module.
  1924.  
  1925.        b) If the extracted value of msgAuthoritativeEngineID is not the
  1926.           same as the value snmpEngineID of the processing SNMP engine
  1927.           (meaning this is not the authoritative SNMP engine), then:
  1928.  
  1929.           1) if at least one of the following conditions is true:
  1930.  
  1931.              - the extracted value of the msgAuthoritativeEngineBoots
  1932.                field is greater than the local notion of the value of
  1933.                snmpEngineBoots; or,
  1934.  
  1935.              - the extracted value of the msgAuthoritativeEngineBoots
  1936.                field is equal to the local notion of the value of
  1937.                snmpEngineBoots, the extracted value of
  1938.                msgAuthoritativeEngineTime field is greater than the
  1939.                value of latestReceivedEngineTime,                         |
  1940.                                                                           |
  1941.              then the LCD entry corresponding to the extracted value
  1942.              of the msgAuthoritativeEngineID field is updated, by
  1943.  
  1944.  
  1945.  
  1946. SNMPv3 Working Group        Expires April 1998                 [Page 33]
  1947.  
  1948. Internet Draft     User-based Security Model for SNMPv3      28 Oct 1997
  1949.  
  1950.  
  1951.              setting:
  1952.  
  1953.                 - the local notion of the value of snmpEngineBoots to
  1954.                   the value of the msgAuthoritativeEngineBoots field,
  1955.                 - the local notion of the value of snmpEngineTime to
  1956.                   the value of the msgAuthoritativeEngineTime field,
  1957.                   and
  1958.                 - the latestReceivedEngineTime to the value of the
  1959.                   value of the msgAuthoritativeEngineTime field.
  1960.  
  1961.           2) if any of the following conditions is true, then the
  1962.              message is considered to be outside of the Time Window:
  1963.  
  1964.              - the local notion of the value of snmpEngineBoots is
  1965.                2147483647;                                                3
  1966.  
  1967.              - the value of the msgAuthoritativeEngineBoots field is
  1968.                less than the local notion of the value of
  1969.                snmpEngineBoots; or,
  1970.  
  1971.              - the value of the msgAuthoritativeEngineBoots field is
  1972.                equal to the local notion of the value of
  1973.                snmpEngineBoots and the value of the
  1974.                msgAuthoritativeEngineTime field is more than 150
  1975.                seconds less than the local notion of of the value of
  1976.                snmpEngineTime.
  1977.  
  1978.              If the message is considered to be outside of the Time
  1979.              Window then an error indication (notInTimeWindow) is
  1980.              returned to the calling module;
  1981.  
  1982.              Note that this means that a too old (possibly replayed)
  1983.              message has been detected and is deemed unauthentic.
  1984.  
  1985.              Note that this procedure allows for the value of
  1986.              msgAuthoritativeEngineBoots in the message to be greater
  1987.              than the local notion of the value of snmpEngineBoots to
  1988.              allow for received messages to be accepted as authentic
  1989.              when received from an authoritative SNMP engine that has
  1990.              re-booted since the receiving SNMP engine last
  1991.              (re-)synchronized.
  1992.  
  1993.              Note that this procedure does not allow for automatic
  1994.              time synchronization if the non-authoritative SNMP engine
  1995.              has a real out-of-sync situation whereby the authoritative
  1996.              SNMP engine is more than 150 seconds behind the
  1997.              non-authoritative SNMP engine.
  1998.  
  1999.    8)  a) If the securityLevel indicates that the message was protected
  2000.           from disclosure, then the OCTET STRING representing the
  2001.           encryptedPDU is decrypted according to the user's privacy
  2002.  
  2003.  
  2004.  
  2005. SNMPv3 Working Group        Expires April 1998                 [Page 34]
  2006.  
  2007. Internet Draft     User-based Security Model for SNMPv3      28 Oct 1997
  2008.  
  2009.  
  2010.           protocol to obtain an unencrypted serialized scopedPDU value.
  2011.           To do so a call is made to the privacy module that implements
  2012.           the user's privacy protocol according to the abstract
  2013.           primitive:
  2014.  
  2015.           statusInformation =       -- success or failure
  2016.             decryptData(
  2017.             IN    decryptKey        -- the user's localized privKey       3
  2018.             IN    privParameters    -- as received on the wire
  2019.             IN    encryptedData     -- encryptedPDU as received
  2020.             OUT   decryptedData     -- serialized decrypted scopedPDU
  2021.                   )
  2022.  
  2023.           statusInformation
  2024.             indicates if the decryption process was successful or not.
  2025.           decryptKey
  2026.             the user's localized private privKey is the secret key that   3
  2027.             can be used by the decryption algorithm.                      3
  2028.           privParameters
  2029.             the msgPrivacyParameters, encoded as an OCTET STRING.
  2030.           encryptedData
  2031.             the encryptedPDU represents the encrypted scopedPDU,
  2032.             encoded as an OCTET STRING.
  2033.           decryptedData
  2034.             the serialized scopedPDU if decryption is successful.
  2035.  
  2036.           If the privacy module returns failure, then the message can
  2037.           not be processed, so the usmStatsDecryptionErrors counter
  2038.           is incremented and an error indication (decryptionError)        4
  2039.           together with the OID and value of the incremented counter
  2040.           is returned to the calling module.
  2041.  
  2042.           If the privacy module returns success, then the decrypted
  2043.           scopedPDU is the message payload to be returned to the
  2044.           calling module.
  2045.  
  2046.           Otherwise,
  2047.  
  2048.        b) The scopedPDU component is assumed to be in plain text
  2049.           and is the message payload to be returned to the calling
  2050.           module.
  2051.  
  2052.    9)  The maxSizeResponseScopedPDU is calculated.  This is the
  2053.        maximum size allowed for a scopedPDU for a possible Response
  2054.        message.  Provision is made for a message header that allows
  2055.        the same securityLevel as the received Request.
  2056.  
  2057.    10) The securityName for the user is retrieved from the
  2058.        usmUserTable.
  2059.  
  2060.    11) The security data is cached as cachedSecurityData, so that a
  2061.  
  2062.  
  2063.  
  2064. SNMPv3 Working Group        Expires April 1998                 [Page 35]
  2065.  
  2066. Internet Draft     User-based Security Model for SNMPv3      28 Oct 1997
  2067.  
  2068.  
  2069.        possible response to this message can and will use the same
  2070.        authentication and privacy secrets, the same securityLevel and
  2071.        the same value for msgAuthoritativeEngineID.  Information to be
  2072.        saved/cached is as follows:
  2073.  
  2074.           msgUserName,
  2075.           usmUserAuthProtocol, usmUserAuthKey
  2076.           usmUserPrivProtocol, usmUserPrivKey
  2077.           securityEngineID, securityLevel
  2078.  
  2079.    12) The statusInformation is set to success and a return is made to
  2080.        the calling module passing back the OUT parameters as specified
  2081.        in the processIncomingMsg primitive.
  2082.  
  2083.  
  2084.  
  2085.  
  2086.  
  2087.  
  2088.  
  2089.  
  2090.  
  2091.  
  2092.  
  2093.  
  2094.  
  2095.  
  2096.  
  2097.  
  2098.  
  2099.  
  2100.  
  2101.  
  2102.  
  2103.  
  2104.  
  2105.  
  2106.  
  2107.  
  2108.  
  2109.  
  2110.  
  2111.  
  2112.  
  2113.  
  2114.  
  2115.  
  2116.  
  2117.  
  2118.  
  2119.  
  2120.  
  2121.  
  2122.  
  2123. SNMPv3 Working Group        Expires April 1998                 [Page 36]
  2124.  
  2125. Internet Draft     User-based Security Model for SNMPv3      28 Oct 1997
  2126.  
  2127.  
  2128. 4.  Discovery
  2129.  
  2130.    The User-based Security Model requires that a discovery process
  2131.    obtains sufficient information about other SNMP engines in order
  2132.    to communicate with them.  Discovery requires an non-authoritative
  2133.    SNMP engine to learn the authoritative SNMP engine's snmpEngineID
  2134.    value before communication may proceed.  This may be accomplished by
  2135.    generating a Request message with a securityLevel of noAuthNoPriv,
  2136.    a msgUserName of "initial", a msgAuthoritativeEngineID value of zero
  2137.    length, and the varBindList left empty.
  2138.    The response to this message will be a Report message containing
  2139.    the snmpEngineID of the authoritative SNMP engine as the value of
  2140.    the msgAuthoritativeEngineID field within the msgSecurityParameters
  2141.    field.  It contains a Report PDU with the usmStatsUnknownEngineIDs
  2142.    counter in the varBindList.
  2143.  
  2144.    If authenticated communication is required, then the discovery
  2145.    process should also establish time synchronization with the
  2146.    authoritative SNMP engine.  This may be accomplished by sending an
  2147.    authenticated Request message with the value of
  2148.    msgAuthoritativeEngineID set to the newly learned snmpEngineID and
  2149.    with the values of msgAuthoritativeEngineBoots and
  2150.    msgAuthoritativeEngineTime set to zero.
  2151.    The response to this authenticated message will be a Report message
  2152.    containing the up to date values of the authoritative SNMP engine's
  2153.    snmpEngineBoots and snmpEngineTime as the value of the
  2154.    msgAuthoritativeEngineBoots and msgAuthoritativeEngineTime fields
  2155.    respectively.  It also contains the usmStatsNotInTimeWindows counter
  2156.    in the varBindList of the Report PDU.  The time synchronization then
  2157.    happens automatically as part of the procedures in section 3.2
  2158.    step 7b. See also section 2.3.
  2159.  
  2160.  
  2161.  
  2162.  
  2163.  
  2164.  
  2165.  
  2166.  
  2167.  
  2168.  
  2169.  
  2170.  
  2171.  
  2172.  
  2173.  
  2174.  
  2175.  
  2176.  
  2177.  
  2178.  
  2179.  
  2180.  
  2181.  
  2182. SNMPv3 Working Group        Expires April 1998                 [Page 37]
  2183.  
  2184. Internet Draft     User-based Security Model for SNMPv3      28 Oct 1997
  2185.  
  2186.  
  2187. 5.  Definitions
  2188.  
  2189. SNMP-USER-BASED-SM-MIB DEFINITIONS ::= BEGIN
  2190.  
  2191. IMPORTS
  2192.     MODULE-IDENTITY, OBJECT-TYPE,
  2193.     OBJECT-IDENTITY,
  2194.     snmpModules, Counter32                FROM SNMPv2-SMI
  2195.     TEXTUAL-CONVENTION, TestAndIncr,
  2196.     RowStatus, RowPointer,
  2197.     StorageType, AutonomousType           FROM SNMPv2-TC
  2198.     MODULE-COMPLIANCE, OBJECT-GROUP       FROM SNMPv2-CONF
  2199.     SnmpAdminString, SnmpEngineID,
  2200.     snmpAuthProtocols, snmpPrivProtocols  FROM SNMP-FRAMEWORK-MIB;
  2201.  
  2202. snmpUsmMIB MODULE-IDENTITY
  2203.     LAST-UPDATED "9710280000Z"            -- 28 Oct 1997, midnight        5
  2204.     ORGANIZATION "SNMPv3 Working Group"
  2205.     CONTACT-INFO "WG-email:   snmpv3@tis.com
  2206.                   Subscribe:  majordomo@tis.com
  2207.                               In msg body:  subscribe snmpv3
  2208.  
  2209.                   Chair:      Russ Mundy
  2210.                               Trusted Information Systems
  2211.                   postal:     3060 Washington Rd
  2212.                               Glenwood MD 21738
  2213.                               USA
  2214.                   email:      mundy@tis.com
  2215.                   phone:      +1-301-854-6889
  2216.  
  2217.                   Co-editor   Uri Blumenthal
  2218.                               IBM T. J. Watson Research
  2219.                   postal:     30 Saw Mill River Pkwy,
  2220.                               Hawthorne, NY 10532
  2221.                               USA
  2222.                   email:      uri@watson.ibm.com
  2223.                   phone:      +1-914-784-7964
  2224.  
  2225.                   Co-editor:  Bert Wijnen
  2226.                               IBM T. J. Watson Research
  2227.                   postal:     Schagen 33
  2228.                               3461 GL Linschoten
  2229.                               Netherlands
  2230.                   email:      wijnen@vnet.ibm.com
  2231.                   phone:      +31-348-432-794
  2232.                  "
  2233.  
  2234.     DESCRIPTION  "The management information definitions for the
  2235.                   SNMP User-based Security Model.
  2236.                  "
  2237.     ::= { snmpModules 9 }     -- to be verified with IANA
  2238.  
  2239.  
  2240.  
  2241. SNMPv3 Working Group        Expires April 1998                 [Page 38]
  2242.  
  2243. Internet Draft     User-based Security Model for SNMPv3      28 Oct 1997
  2244.  
  2245.  
  2246.  
  2247. -- Administrative assignments ****************************************
  2248.  
  2249. usmMIBObjects     OBJECT IDENTIFIER ::= { snmpUsmMIB 1 }                  5
  2250. usmMIBConformance OBJECT IDENTIFIER ::= { snmpUsmMIB 2 }                  5
  2251.  
  2252. -- Identification of Authentication and Privacy Protocols ************
  2253.  
  2254. usmNoAuthProtocol OBJECT-IDENTITY
  2255.     STATUS        current
  2256.     DESCRIPTION  "No Authentication Protocol."
  2257.     ::= { snmpAuthProtocols 1 }
  2258.  
  2259. usmHMACMD5AuthProtocol OBJECT-IDENTITY                                    |
  2260.     STATUS        current                                                 |
  2261.     DESCRIPTION  "The HMAC-MD5-96 Digest Authentication Protocol."        |
  2262.     REFERENCE    "- H. Krawczyk, M. Bellare, R. Canetti HMAC:             |
  2263.                     Keyed-Hashing for Message Authentication,             |
  2264.                     RFC2104, Feb 1997.                                    |
  2265.                   - Rivest, R., Message Digest Algorithm MD5, RFC1321.    |
  2266.                  "                                                        |
  2267.     ::= { snmpAuthProtocols 2 }                                           |
  2268.                                                                           |
  2269. usmHMACSHAAuthProtocol OBJECT-IDENTITY                                    |
  2270.     STATUS        current                                                 |
  2271.     DESCRIPTION  "The HMAC-SHA-96 Digest Authentication Protocol."        |
  2272.     REFERENCE    "- H. Krawczyk, M. Bellare, R. Canetti, HMAC:            |
  2273.                     Keyed-Hashing for Message Authentication,             |
  2274.                     RFC2104, Feb 1997.                                    |
  2275.                   - Secure Hash Algorithm. NIST FIPS 180-1.               |        |
  2276.                  "                                                        |
  2277.     ::= { snmpAuthProtocols 3 }                                           |
  2278.                                                                           |
  2279. usmNoPrivProtocol OBJECT-IDENTITY
  2280.     STATUS        current
  2281.     DESCRIPTION  "No Privacy Protocol."
  2282.     ::= { snmpPrivProtocols 1 }
  2283.  
  2284. usmDESPrivProtocol OBJECT-IDENTITY
  2285.     STATUS        current
  2286.     DESCRIPTION  "The CBC-DES Symmetric Encryption Protocol."
  2287.     REFERENCE    "- Data Encryption Standard, National Institute of
  2288.                     Standards and Technology.  Federal Information
  2289.                     Processing Standard (FIPS) Publication 46-1.
  2290.                     Supersedes FIPS Publication 46,
  2291.                     (January, 1977; reaffirmed January, 1988).
  2292.  
  2293.                   - Data Encryption Algorithm, American National
  2294.                     Standards Institute.  ANSI X3.92-1981,
  2295.                     (December, 1980).
  2296.  
  2297.  
  2298.  
  2299.  
  2300. SNMPv3 Working Group        Expires April 1998                 [Page 39]
  2301.  
  2302. Internet Draft     User-based Security Model for SNMPv3      28 Oct 1997
  2303.  
  2304.  
  2305.                   - DES Modes of Operation, National Institute of
  2306.                     Standards and Technology.  Federal Information
  2307.                     Processing Standard (FIPS) Publication 81,
  2308.                     (December, 1980).
  2309.  
  2310.                   - Data Encryption Algorithm - Modes of Operation,
  2311.                     American National Standards Institute.
  2312.                     ANSI X3.106-1983, (May 1983).
  2313.                  "
  2314.     ::= { snmpPrivProtocols 2 }
  2315.  
  2316. -- Textual Conventions ***********************************************
  2317.  
  2318. -- Editor's note:
  2319. -- If in the future the MD5 gets replaced by another Authentication
  2320. -- algorithm, then it seems we also need to use that new algorithm to
  2321. -- calculate the digest during KeyChange. So this TC has been defined
  2322. -- to cater for that.
  2323. -- End Editor's note
  2324.  
  2325. KeyChange ::=     TEXTUAL-CONVENTION
  2326.    STATUS         current
  2327.    DESCRIPTION
  2328.          "Every definition of an object with this syntax must identify
  2329.           a protocol, P, a secret key, K, and a hash algorithm, H         |
  2330.           that produces output of L octets.                               |
  2331.                                                                           |
  2332.           The object's value is a manager-generated, partially-random
  2333.           value which, when modified, causes the value of the secret
  2334.           key, K, to be modified via a one-way function.
  2335.  
  2336.           The value of an instance of this object is the concatenation
  2337.           of two components: a 'random' component and a 'delta'
  2338.           component.  The lengths of the random and delta components
  2339.           are given by the corresponding value of the protocol, P;
  2340.           if P requires K to be a fixed length, the length of both the
  2341.           random and delta components is that fixed length; if P
  2342.           allows the length of K to be variable up to a particular
  2343.           maximum length, the length of the random component is that
  2344.           maximum length and the length of the delta component is any
  2345.           length less than or equal to that maximum length.
  2346.           For example, usmHMACMD5AuthProtocol requires K to be a fixed    |
  2347.           length of 16 octets and L - of 16 octets.                       |
  2348.           usmHMACSHAAuthProtocol requires K to be a fixed length of       |
  2349.           20 octets and L - of 20 octets. Other protocols may define      |
  2350.           other sizes, as deemed appropriate.                             |
  2351.  
  2352.           When an instance of this object is modified to have a new
  2353.           value by the management protocol, the agent generates a new
  2354.           value of K as follows:
  2355.  
  2356.  
  2357.  
  2358.  
  2359. SNMPv3 Working Group        Expires April 1998                 [Page 40]
  2360.  
  2361. Internet Draft     User-based Security Model for SNMPv3      28 Oct 1997
  2362.  
  2363.  
  2364.            - a temporary variable is initialized to the existing value
  2365.              of K;
  2366.            - if the length of the delta component is greater than 16
  2367.              octets, then:                                                |
  2368.               - the random component is appended to the value of the
  2369.                 temporary variable, and the result is input to the
  2370.                 the hash algorithm H to produce a digest value, and
  2371.                 the temporary variable is set to this digest value;
  2372.               - the value of the temporary variable is XOR-ed with
  2373.                 the first (next) L-octets (16 octets in case of MD5)      |
  2374.                 of the delta component to produce the first (next)        |
  2375.                 L-octets (16 octets in case of MD5) of the new value      |
  2376.                 of K.                                                     |
  2377.               - the above two steps are repeated until the unused
  2378.                 portion of the delta component is 16 octets or less,
  2379.            - the random component is appended to the value of the
  2380.              temporary variable, and the result is input to the
  2381.              hash algorithm H to produce a digest value;
  2382.            - this digest value, truncated if necessary to be the same
  2383.              length as the unused portion of the delta component, is
  2384.              XOR-ed with the unused portion of the delta component to
  2385.              produce the (final portion of the) new value of K.
  2386.  
  2387.              for example, using MD5 as the hash algorithm H:
  2388.  
  2389.               iterations = (lenOfDelta - 1)/16; /* integer division */
  2390.               temp = keyOld;
  2391.               for (i = 0; i < iterations; i++) {
  2392.                   temp = MD5 (temp || random);
  2393.                   keyNew[i*16 .. (i*16)+15] =
  2394.                          temp XOR delta[i*16 .. (i*16)+15];
  2395.               }
  2396.               temp = MD5 (temp || random);
  2397.               keyNew[i*16 .. lenOfDelta-1] =
  2398.                      temp XOR delta[i*16 .. lenOfDelta-1];
  2399.  
  2400.           The value of an object with this syntax, whenever it is
  2401.           retrieved by the management protocol, is always the zero
  2402.           length string.
  2403.          "
  2404.     SYNTAX       OCTET STRING
  2405.  
  2406. -- Statistics for the User-based Security Model **********************
  2407.  
  2408. usmStats         OBJECT IDENTIFIER ::= { usmMIBObjects 1 }
  2409.  
  2410. usmStatsUnsupportedSecLevels OBJECT-TYPE
  2411.     SYNTAX       Counter32
  2412.     MAX-ACCESS   read-only
  2413.     STATUS       current
  2414.     DESCRIPTION "The total number of packets received by the SNMP
  2415.  
  2416.  
  2417.  
  2418. SNMPv3 Working Group        Expires April 1998                 [Page 41]
  2419.  
  2420. Internet Draft     User-based Security Model for SNMPv3      28 Oct 1997
  2421.  
  2422.  
  2423.                  engine which were dropped because they requested a
  2424.                  securityLevel that was unknown to the SNMP engine
  2425.                  or otherwise unavailable.
  2426.                 "
  2427.     ::= { usmStats 1 }
  2428.  
  2429. usmStatsNotInTimeWindows OBJECT-TYPE
  2430.     SYNTAX       Counter32
  2431.     MAX-ACCESS   read-only
  2432.     STATUS       current
  2433.     DESCRIPTION "The total number of packets received by the SNMP
  2434.                  engine which were dropped because they appeared
  2435.                  outside of the authoritative SNMP engine's window.
  2436.                 "
  2437.     ::= { usmStats 2 }
  2438.  
  2439. usmStatsUnknownUserNames OBJECT-TYPE
  2440.     SYNTAX       Counter32
  2441.     MAX-ACCESS   read-only
  2442.     STATUS       current
  2443.     DESCRIPTION "The total number of packets received by the SNMP
  2444.                  engine which were dropped because they referenced a
  2445.                  user that was not known to the SNMP engine.
  2446.                 "
  2447.     ::= { usmStats 3 }
  2448.  
  2449. usmStatsUnknownEngineIDs OBJECT-TYPE
  2450.     SYNTAX       Counter32
  2451.     MAX-ACCESS   read-only
  2452.     STATUS       current
  2453.     DESCRIPTION "The total number of packets received by the SNMP
  2454.                  engine which were dropped because they referenced an
  2455.                  snmpEngineID that was not known to the SNMP engine.
  2456.                 "
  2457.     ::= { usmStats 4 }
  2458.  
  2459. usmStatsWrongDigests OBJECT-TYPE
  2460.     SYNTAX       Counter32
  2461.     MAX-ACCESS   read-only
  2462.     STATUS       current
  2463.     DESCRIPTION "The total number of packets received by the SNMP
  2464.                  engine which were dropped because they didn't
  2465.                  contain the expected digest value.
  2466.                 "
  2467.     ::= { usmStats 5 }
  2468.  
  2469. usmStatsDecryptionErrors OBJECT-TYPE
  2470.     SYNTAX       Counter32
  2471.     MAX-ACCESS   read-only
  2472.     STATUS       current
  2473.     DESCRIPTION "The total number of packets received by the SNMP
  2474.  
  2475.  
  2476.  
  2477. SNMPv3 Working Group        Expires April 1998                 [Page 42]
  2478.  
  2479. Internet Draft     User-based Security Model for SNMPv3      28 Oct 1997
  2480.  
  2481.  
  2482.                  engine which were dropped because they could not be
  2483.                  decrypted.
  2484.                 "
  2485.     ::= { usmStats 6 }
  2486.  
  2487. -- The usmUser Group ************************************************
  2488.  
  2489. usmUser          OBJECT IDENTIFIER ::= { usmMIBObjects 2 }
  2490.  
  2491. usmUserSpinLock  OBJECT-TYPE
  2492.     SYNTAX       TestAndIncr
  2493.     MAX-ACCESS   read-write
  2494.     STATUS       current
  2495.     DESCRIPTION "An advisory lock used to allow several cooperating
  2496.                  Command Generator Applications to coordinate their
  2497.                  use of facilities to alter secrets in the
  2498.                  usmUserTable.
  2499.                 "
  2500.     ::= { usmUser 1 }
  2501.  
  2502. -- The table of valid users for the User-based Security Model ********
  2503.  
  2504. usmUserTable     OBJECT-TYPE
  2505.     SYNTAX       SEQUENCE OF UsmUserEntry
  2506.     MAX-ACCESS   not-accessible
  2507.     STATUS       current
  2508.     DESCRIPTION "The table of users configured in the SNMP engine's
  2509.                  Local Configuration Datastore (LCD)."
  2510.     ::= { usmUser 2 }
  2511.  
  2512. usmUserEntry     OBJECT-TYPE
  2513.     SYNTAX       UsmUserEntry
  2514.     MAX-ACCESS   not-accessible
  2515.     STATUS       current
  2516.     DESCRIPTION "A user configured in the SNMP engine's Local
  2517.                  Configuration Datastore (LCD) for the User-based
  2518.                  Security Model.
  2519.                 "
  2520.     INDEX       { usmUserEngineID,
  2521.                   usmUserName
  2522.                 }
  2523.     ::= { usmUserTable 1 }
  2524.  
  2525. UsmUserEntry ::= SEQUENCE
  2526.     {
  2527.         usmUserEngineID         SnmpEngineID,
  2528.         usmUserName             SnmpAdminString,
  2529.         usmUserSecurityName     SnmpAdminString,
  2530.         usmUserCloneFrom        RowPointer,
  2531.         usmUserAuthProtocol     AutonomousType,
  2532.         usmUserAuthKeyChange    KeyChange,
  2533.  
  2534.  
  2535.  
  2536. SNMPv3 Working Group        Expires April 1998                 [Page 43]
  2537.  
  2538. Internet Draft     User-based Security Model for SNMPv3      28 Oct 1997
  2539.  
  2540.  
  2541.         usmUserOwnAuthKeyChange KeyChange,
  2542.         usmUserPrivProtocol     AutonomousType,
  2543.         usmUserPrivKeyChange    KeyChange,
  2544.         usmUserOwnPrivKeyChange KeyChange,
  2545.         usmUserPublic           OCTET STRING,
  2546.         usmUserStorageType      StorageType,
  2547.         usmUserStatus           RowStatus
  2548.     }
  2549.  
  2550. usmUserEngineID  OBJECT-TYPE
  2551.     SYNTAX       SnmpEngineID
  2552.     MAX-ACCESS   not-accessible
  2553.     STATUS       current
  2554.     DESCRIPTION "An SNMP engine's administratively-unique identifier.
  2555.  
  2556.                  In a simple agent, this value is always that agent's
  2557.                  own snmpEngineID value.
  2558.  
  2559.                  The value can also take the value of the snmpEngineID
  2560.                  of a remote SNMP engine with which this user can
  2561.                  communicate.
  2562.                 "
  2563.     ::= { usmUserEntry 1 }
  2564.  
  2565. usmUserName      OBJECT-TYPE
  2566.     SYNTAX       SnmpAdminString (SIZE(1..32))
  2567.     MAX-ACCESS   not-accessible
  2568.     STATUS       current
  2569.     DESCRIPTION "A human readable string representing the name of
  2570.                  the user.
  2571.  
  2572.                  This is the (User-based Security) Model dependent
  2573.                  security ID.
  2574.                 "
  2575.     ::= { usmUserEntry 2 }
  2576.  
  2577. usmUserSecurityName OBJECT-TYPE
  2578.     SYNTAX       SnmpAdminString
  2579.     MAX-ACCESS   read-only
  2580.     STATUS       current
  2581.     DESCRIPTION "A human readable string representing the user in
  2582.                  Security Model independent format.
  2583.  
  2584.                  The default transformation of the User-based Security
  2585.                  Model dependent security ID to the securityName and
  2586.                  vice versa is the identity function so that the
  2587.                  securityName is the same as the userName.
  2588.                 "
  2589.     ::= { usmUserEntry 3 }
  2590.  
  2591. usmUserCloneFrom OBJECT-TYPE
  2592.  
  2593.  
  2594.  
  2595. SNMPv3 Working Group        Expires April 1998                 [Page 44]
  2596.  
  2597. Internet Draft     User-based Security Model for SNMPv3      28 Oct 1997
  2598.  
  2599.  
  2600.     SYNTAX       RowPointer
  2601.     MAX-ACCESS   read-create
  2602.     STATUS       current
  2603.     DESCRIPTION "A pointer to another conceptual row in this
  2604.                  usmUserTable.  The user in this other conceptual
  2605.                  row is called the clone-from user.
  2606.  
  2607.                  When a new user is created (i.e., a new conceptual
  2608.                  row is instantiated in this table), the privacy and
  2609.                  authentication parameters of the new user are cloned
  2610.                  from its clone-from user.
  2611.  
  2612.                  The first time an instance of this object is set by
  2613.                  a management operation (either at or after its
  2614.                  instantiation), the cloning process is invoked.
  2615.                  Subsequent writes are successful but invoke no
  2616.                  action to be taken by the receiver.
  2617.                  The cloning process fails with an 'inconsistentName'
  2618.                  error if the conceptual row representing the
  2619.                  clone-from user is not in an active state when the
  2620.                  cloning process is invoked.
  2621.  
  2622.                  Cloning also causes the initial values of the secret
  2623.                  authentication key and the secret encryption key of
  2624.                  the new user to be set to the same value as the
  2625.                  corresponding secret of the clone-from user.
  2626.  
  2627.                  When this object is read, the ZeroDotZero OID
  2628.                  is returned.
  2629.                 "
  2630.     ::= { usmUserEntry 4 }
  2631.  
  2632. usmUserAuthProtocol OBJECT-TYPE
  2633.     SYNTAX       AutonomousType
  2634.     MAX-ACCESS   read-create
  2635.     STATUS       current
  2636.     DESCRIPTION "An indication of whether messages sent on behalf of
  2637.                  this user to/from the SNMP engine identified by
  2638.                  usmUserEngineID, can be authenticated, and if so,
  2639.                  the type of authentication protocol which is used.
  2640.  
  2641.                  An instance of this object is created concurrently
  2642.                  with the creation of any other object instance for
  2643.                  the same user (i.e., as part of the processing of
  2644.                  the set operation which creates the first object
  2645.                  instance in the same conceptual row).  Once created,
  2646.                  the value of an instance of this object can not be
  2647.                  changed.
  2648.                                                                           |
  2649.                  If a set operation tries to set a value for an unknown   |
  2650.                  or unsupported protocol, then a wrongValue error must    |
  2651.  
  2652.  
  2653.  
  2654. SNMPv3 Working Group        Expires April 1998                 [Page 45]
  2655.  
  2656. Internet Draft     User-based Security Model for SNMPv3      28 Oct 1997
  2657.  
  2658.  
  2659.                  be returned.                                             |
  2660.                 "
  2661.     DEFVAL      { usmHMACMD5AuthProtocol }                                |
  2662.     ::= { usmUserEntry 5 }
  2663.  
  2664. usmUserAuthKeyChange OBJECT-TYPE
  2665.     SYNTAX       KeyChange   -- typically (SIZE (0..32))
  2666.     MAX-ACCESS   read-create
  2667.     STATUS       current
  2668.     DESCRIPTION "An object, which when modified, causes the secret
  2669.                  authentication key used for messages sent on behalf
  2670.                  of this user to/from the SNMP engine identified by
  2671.                  usmUserEngineID, to be modified via a one-way
  2672.                  function.
  2673.  
  2674.                  The associated protocol is the usmUserAuthProtocol.
  2675.                  The associated secret key is the user's secret
  2676.                  authentication key (authKey). The associated hash
  2677.                  algorithm is the algorithm used by the user's
  2678.                  usmUserAuthProtocol.
  2679.  
  2680.                  When creating a new user, it is an 'inconsistentName'
  2681.                  error for a Set operation to refer to this object
  2682.                  unless it is previously or concurrently initialized
  2683.                  through a set operation on the corresponding value
  2684.                  of usmUserCloneFrom.
  2685.                 "
  2686.     DEFVAL      { ''H }    -- the empty string
  2687.     ::= { usmUserEntry 6 }
  2688.  
  2689. usmUserOwnAuthKeyChange OBJECT-TYPE
  2690.     SYNTAX       KeyChange  -- typically (SIZE (0..32))
  2691.     MAX-ACCESS   read-create
  2692.     STATUS       current
  2693.     DESCRIPTION "Behaves exactly as usmUserAuthKeyChange, with one
  2694.                  notable difference: in order for the Set operation
  2695.                  to succeed, the usmUserName of the operation
  2696.                  requester must match the usmUserName that
  2697.                  indexes the row which is targeted by this
  2698.                  operation.
  2699.  
  2700.                  The idea here is that access to this column can be
  2701.                  public, since it will only allow a user to change
  2702.                  his own secret authentication key (authKey).
  2703.                 "
  2704.     DEFVAL      { ''H }    -- the empty string
  2705.     ::= { usmUserEntry 7 }
  2706.  
  2707. usmUserPrivProtocol OBJECT-TYPE
  2708.     SYNTAX       AutonomousType
  2709.     MAX-ACCESS   read-create
  2710.  
  2711.  
  2712.  
  2713. SNMPv3 Working Group        Expires April 1998                 [Page 46]
  2714.  
  2715. Internet Draft     User-based Security Model for SNMPv3      28 Oct 1997
  2716.  
  2717.  
  2718.     STATUS       current
  2719.     DESCRIPTION "An indication of whether messages sent on behalf of
  2720.                  this user to/from the SNMP engine identified by
  2721.                  usmUserEngineID, can be protected from disclosure,
  2722.                  and if so, the type of privacy protocol which is used.
  2723.  
  2724.                  An instance of this object is created concurrently
  2725.                  with the creation of any other object instance for
  2726.                  the same user (i.e., as part of the processing of
  2727.                  the set operation which creates the first object
  2728.                  instance in the same conceptual row).  Once created,
  2729.                  the value of an instance of this object can not be
  2730.                  changed.
  2731.                                                                           |
  2732.                  If a set operation tries to set a value for an unknown   |
  2733.                  or unsupported protocol, then a wrongValue error must    |
  2734.                  be returned.                                             |
  2735.                 "
  2736.     DEFVAL      { usmNoPrivProtocol }
  2737.     ::= { usmUserEntry 8 }
  2738.  
  2739. usmUserPrivKeyChange OBJECT-TYPE
  2740.     SYNTAX       KeyChange  -- typically (SIZE (0..32))
  2741.     MAX-ACCESS   read-create
  2742.     STATUS       current
  2743.     DESCRIPTION "An object, which when modified, causes the secret
  2744.                  encryption key used for messages sent on behalf
  2745.                  of this user to/from the SNMP engine identified by
  2746.                  usmUserEngineID, to be modified via a one-way
  2747.                  function.
  2748.  
  2749.                  The associated protocol is the usmUserPrivProtocol.
  2750.                  The associated secret key is the user's secret
  2751.                  privacy key (privKey). The associated hash
  2752.                  algorithm is the algorithm used by the user's
  2753.                  usmUserAuthProtocol.
  2754.  
  2755.                  When creating a new user, it is an 'inconsistentName'
  2756.                  error for a set operation to refer to this object
  2757.                  unless it is previously or concurrently initialized
  2758.                  through a set operation on the corresponding value
  2759.                  of usmUserCloneFrom.
  2760.                 "
  2761.     DEFVAL      { ''H }    -- the empty string
  2762.     ::= { usmUserEntry 9 }
  2763.  
  2764. usmUserOwnPrivKeyChange OBJECT-TYPE
  2765.     SYNTAX       KeyChange  -- typically (SIZE (0..32))
  2766.     MAX-ACCESS   read-create
  2767.     STATUS       current
  2768.     DESCRIPTION "Behaves exactly as usmUserPrivKeyChange, with one
  2769.  
  2770.  
  2771.  
  2772. SNMPv3 Working Group        Expires April 1998                 [Page 47]
  2773.  
  2774. Internet Draft     User-based Security Model for SNMPv3      28 Oct 1997
  2775.  
  2776.  
  2777.                  notable difference: in order for the Set operation
  2778.                  to succeed, the usmUserName of the operation
  2779.                  requester must match the usmUserName that indexes
  2780.                  the row which is targeted by this operation.
  2781.  
  2782.                  The idea here is that access to this column can be
  2783.                  public, since it will only allow a user to change
  2784.                  his own secret privacy key (privKey).
  2785.                 "
  2786.     DEFVAL      { ''H }    -- the empty string
  2787.     ::= { usmUserEntry 10 }
  2788.  
  2789. usmUserPublic    OBJECT-TYPE
  2790.     SYNTAX       OCTET STRING (SIZE(0..32))
  2791.     MAX-ACCESS   read-create
  2792.     STATUS       current
  2793.     DESCRIPTION "A publicly-readable value which is written as part
  2794.                  of the procedure for changing a user's secret
  2795.                  authentication and/or privacy key, and later read to
  2796.                  determine whether the change of the secret was
  2797.                  effected.
  2798.                 "
  2799.     DEFVAL      { ''H }  -- the empty string
  2800.     ::= { usmUserEntry 11 }
  2801.  
  2802. usmUserStorageType OBJECT-TYPE
  2803.     SYNTAX       StorageType
  2804.     MAX-ACCESS   read-create
  2805.     STATUS       current
  2806.     DESCRIPTION "The storage type for this conceptual row.
  2807.  
  2808.                  Conceptual rows having the value 'permanent'
  2809.                  must allow write-access at a minimum to:
  2810.  
  2811.                  - usmUserAuthKeyChange, usmUserOwnAuthKeyChange
  2812.                    and usmUserPublic for a user who employs
  2813.                    authentication, and
  2814.                  - usmUserPrivKeyChange, usmUserOwnPrivKeyChange
  2815.                    and usmUserPublic for a user who employs
  2816.                    privacy.
  2817.  
  2818.                  Note that any user who employs authentication or
  2819.                  privacy must allow its secret(s) to be updated and
  2820.                  thus cannot be 'readOnly'.
  2821.                 "
  2822.     DEFVAL      { nonVolatile }
  2823.     ::= { usmUserEntry 12 }
  2824.  
  2825. usmUserStatus    OBJECT-TYPE
  2826.     SYNTAX       RowStatus
  2827.     MAX-ACCESS   read-create
  2828.  
  2829.  
  2830.  
  2831. SNMPv3 Working Group        Expires April 1998                 [Page 48]
  2832.  
  2833. Internet Draft     User-based Security Model for SNMPv3      28 Oct 1997
  2834.  
  2835.  
  2836.     STATUS       current
  2837.     DESCRIPTION "The status of this conceptual row.
  2838.  
  2839.                  Until instances of all corresponding columns are
  2840.                  appropriately configured, the value of the
  2841.                  corresponding instance of the usmUserStatus column
  2842.                  is 'notReady'.
  2843.  
  2844.                  In particular, a newly created row cannot be made
  2845.                  active until the corresponding usmUserCloneFrom,
  2846.                  usmUserAuthKeyChange, usmUserOwnAuthKeyChange,
  2847.                  usmUserPrivKeyChange and usmUserOwnPrivKeyChange
  2848.                  have all been set.
  2849.  
  2850.                  The  RowStatus TC [RFC1903] requires that this
  2851.                  DESCRIPTION clause states under which circumstances
  2852.                  other objects in this row can be modified:
  2853.  
  2854.                  The value of this object has no effect on whether
  2855.                  other objects in this conceptual row can be modified.
  2856.                 "
  2857.     ::= { usmUserEntry 13 }
  2858.  
  2859. -- Conformance Information *******************************************
  2860.  
  2861. usmMIBCompliances OBJECT IDENTIFIER ::= { usmMIBConformance 1 }
  2862. usmMIBGroups      OBJECT IDENTIFIER ::= { usmMIBConformance 2 }
  2863.  
  2864. -- Compliance statements
  2865.  
  2866. usmMIBCompliance MODULE-COMPLIANCE
  2867.     STATUS       current
  2868.     DESCRIPTION "The compliance statement for SNMP engines which
  2869.                  implement the SNMP-USER-BASED-SM-MIB.
  2870.                 "
  2871.  
  2872.     MODULE       -- this module
  2873.         MANDATORY-GROUPS { usmMIBBasicGroup }
  2874.  
  2875.         OBJECT           usmUserAuthProtocol
  2876.         MIN-ACCESS       read-only
  2877.         DESCRIPTION     "Write access is not required."
  2878.  
  2879.         OBJECT           usmUserPrivProtocol
  2880.         MIN-ACCESS       read-only
  2881.         DESCRIPTION     "Write access is not required."
  2882.  
  2883.     ::= { usmMIBCompliances 1 }
  2884.  
  2885. -- Units of compliance
  2886.  
  2887.  
  2888.  
  2889.  
  2890. SNMPv3 Working Group        Expires April 1998                 [Page 49]
  2891.  
  2892. Internet Draft     User-based Security Model for SNMPv3      28 Oct 1997
  2893.  
  2894.  
  2895. usmMIBBasicGroup OBJECT-GROUP
  2896.     OBJECTS     {
  2897.                   usmStatsUnsupportedSecLevels,
  2898.                   usmStatsNotInTimeWindows,
  2899.                   usmStatsUnknownUserNames,
  2900.                   usmStatsUnknownEngineIDs,
  2901.                   usmStatsWrongDigests,
  2902.                   usmStatsDecryptionErrors,
  2903.                   usmUserSpinLock,
  2904.                   usmUserSecurityName,
  2905.                   usmUserCloneFrom,
  2906.                   usmUserAuthProtocol,
  2907.                   usmUserAuthKeyChange,
  2908.                   usmUserOwnAuthKeyChange,
  2909.                   usmUserPrivProtocol,
  2910.                   usmUserPrivKeyChange,
  2911.                   usmUserOwnPrivKeyChange,
  2912.                   usmUserPublic,
  2913.                   usmUserStorageType,
  2914.                   usmUserStatus
  2915.                 }
  2916.     STATUS       current
  2917.     DESCRIPTION "A collection of objects providing for configuration
  2918.                  of an SNMP engine which implements the SNMP
  2919.                  User-based Security Model.
  2920.                 "
  2921.     ::= { usmMIBGroups 1 }
  2922.  
  2923. END
  2924.  
  2925.  
  2926.  
  2927.  
  2928.  
  2929.  
  2930.  
  2931.  
  2932.  
  2933.  
  2934.  
  2935.  
  2936.  
  2937.  
  2938.  
  2939.  
  2940.  
  2941.  
  2942.  
  2943.  
  2944.  
  2945.  
  2946.  
  2947.  
  2948.  
  2949. SNMPv3 Working Group        Expires April 1998                 [Page 50]
  2950.  
  2951. Internet Draft     User-based Security Model for SNMPv3      28 Oct 1997
  2952.  
  2953.  
  2954. 6.  HMAC-MD5-96 Authentication Protocol                                   |
  2955.                                                                           |
  2956.    This section describes the HMAC-MD5-96 authentication protocol.        |
  2957.    This authentication protocol is the first defined for                  |
  2958.    the User-based Security Model. It uses MD5 hash-function which         |
  2959.    is described in [MD5], in HMAC mode described in [RFC2104],            |
  2960.    truncating the output to 96 bits.                                      |
  2961.                                                                           |
  2962.    This protocol is identified by usmHMACMD5AuthProtocol.                 |
  2963.  
  2964.    Over time, other authentication protocols may be defined either
  2965.    as a replacement of this protocol or in addition to this protocol.
  2966.  
  2967. 6.1.  Mechanisms
  2968.  
  2969.    - In support of data integrity, a message digest algorithm is
  2970.      required.  A digest is calculated over an appropriate portion
  2971.      of an SNMP message and included as part of the message sent
  2972.      to the recipient.
  2973.  
  2974.    - In support of data origin authentication and data integrity,         |
  2975.      a secret value is prepended to SNMP message prior to computing the   |
  2976.      digest; the calculated digest is partially inserted into the SNMP    |
  2977.      message prior to transmission, and the prepended value is not        |
  2978.      transmitted.  The secret value is shared by all SNMP engines         |
  2979.      authorized to originate messages on behalf of the appropriate user.  |
  2980.                                                                           3
  2981.                                                                           3
  2982. 6.1.1.  Digest Authentication Mechanism                                   |
  2983.  
  2984.    The Digest Authentication Mechanism defined in this memo provides      |
  2985.    for:
  2986.  
  2987.    - verification of the integrity of a received message, i.e., the       |
  2988.      message received is the message sent.                                |
  2989.  
  2990.      The integrity of the message is protected by computing a digest
  2991.      over an appropriate portion of the message.  The digest is
  2992.      computed by the originator of the message, transmitted with the
  2993.      message, and verified by the recipient of the message.
  2994.  
  2995.    - verification of the user on whose behalf the message was generated.  |
  2996.                                                                           |
  2997.      A secret value known only to SNMP engines authorized to              |
  2998.      generate messages on behalf of a user is used in HMAC mode           |
  2999.      (see [RFC2104]). It also recommends the hash-function output         |
  3000.      used as Message Authentication Code, to be truncated.                |
  3001.  
  3002.    This protocol uses the MD5 [MD5] message digest algorithm.
  3003.    A 128-bit MD5 digest is calculated in a special (HMAC) way over        |
  3004.    the designated portion of an SNMP message and the first 96 bits        |
  3005.  
  3006.  
  3007.  
  3008. SNMPv3 Working Group        Expires April 1998                 [Page 51]
  3009.  
  3010. Internet Draft     User-based Security Model for SNMPv3      28 Oct 1997
  3011.  
  3012.  
  3013.    o this digest is included as part of the message sent to the           |
  3014.    recipient. The size of the digest carried in a message is 12           |
  3015.    octets. The size of the private authentication key (the secret)        |
  3016.    is 16 octets. For the details see section 6.3.                         |
  3017.  
  3018. 6.2.  Elements of the Digest Authentication Protocol
  3019.  
  3020.    This section contains definitions required to realize the
  3021.    authentication module defined in this section of this memo.            |
  3022.  
  3023. 6.2.1.  Users
  3024.  
  3025.    Authentication using this authentication protocol makes
  3026.    use of a defined set of userNames. For any user on whose behalf a
  3027.    message must be authenticated at a particular SNMP engine, that
  3028.    SNMP engine must have knowledge of that user. An SNMP engine that
  3029.    wishes to communicate with another SNMP engine must also have
  3030.    knowledge of a user known to that engine, including knowledge of
  3031.    the applicable attributes of that user.
  3032.  
  3033.    A user and its attributes are defined as follows:
  3034.  
  3035.    <userName>
  3036.      A string representing the name of the user.
  3037.    <authKey>
  3038.      A user's secret key to be used when calculating a digest.
  3039.      It MUST be 16 octets long for MD5.                                   |
  3040.  
  3041. 6.2.2.  msgAuthoritativeEngineID
  3042.  
  3043.    The msgAuthoritativeEngineID value contained in an authenticated
  3044.    message specifies the authoritative SNMP engine for that particular
  3045.    message (see the definition of SnmpEngineID in the SNMP
  3046.    Architecture document [SNMP-ARCH]).
  3047.  
  3048.    The user's (private) authentication key is normally different at
  3049.    each authoritative SNMP engine and so the snmpEngineID is used
  3050.    to select the proper key for the authentication process.
  3051.  
  3052. 6.2.3.  SNMP Messages Using this Authentication Protocol
  3053.  
  3054.    Messages using this authentication protocol carry a
  3055.    msgAuthenticationParameters field as part of the
  3056.    msgSecurityParameters.  For this protocol, the
  3057.    msgAuthenticationParameters field is the serialized OCTET STRING
  3058.    representing the first 12 octets of the HMAC-MD5-96 output done        |
  3059.    over the wholeMsg.                                                     |
  3060.  
  3061.    The digest is calculated over the wholeMsg so if a message is
  3062.    authenticated, that also means that all the fields in the message
  3063.    are intact and have not been tampered with.
  3064.  
  3065.  
  3066.  
  3067. SNMPv3 Working Group        Expires April 1998                 [Page 52]
  3068.  
  3069. Internet Draft     User-based Security Model for SNMPv3      28 Oct 1997
  3070.  
  3071.  
  3072.  
  3073. 6.2.4.  Services provided by the HMAC-MD5-96 Authentication Module        |
  3074.                                                                           |
  3075.    This section describes the inputs and outputs that the HMAC-MD5-96     |
  3076.    Authentication module expects and produces when the User-based         |
  3077.    Security module calls the HMAC-MD5-96 Authentication module for        |
  3078.    services.                                                              |
  3079.  
  3080.  
  3081. 6.2.4.1.  Services for Generating an Outgoing SNMP Message
  3082.  
  3083.    The HMAC-MD5-96 authentication protocol assumes that the selection     |
  3084.    of the authKey is done by the caller and that the caller passes
  3085.    the secret key to be used.
  3086.  
  3087.    Upon completion the authentication module returns statusInformation
  3088.    and, if the message digest was correctly calculated, the wholeMsg
  3089.    with the digest inserted at the proper place. The abstract service
  3090.    primitive is:
  3091.  
  3092.    statusInformation =              -- success or failure
  3093.      authenticateOutgoingMsg(
  3094.      IN   authKey                   -- secret key for authentication
  3095.      IN   wholeMsg                  -- unauthenticated complete message
  3096.      OUT  authenticatedWholeMsg     -- complete authenticated message
  3097.           )
  3098.  
  3099.    The abstract data elements are:
  3100.  
  3101.      statusInformation
  3102.        An indication of whether the authentication process was
  3103.        successful.  If not it is an indication of the problem.
  3104.      authKey
  3105.        The secret key to be used by the authentication algorithm.
  3106.        The length of this key MUST be 16 octets.                          |
  3107.      wholeMsg
  3108.        The message to be authenticated.
  3109.      authenticatedWholeMsg
  3110.        The authenticated message (including inserted digest) on output.
  3111.  
  3112.    Note, that authParameters field is filled by the authentication
  3113.    module and this field should be already present in the wholeMsg
  3114.    before the Message Authentication Code (MAC) is generated.
  3115.  
  3116. 6.2.4.2.  Services for Processing an Incoming SNMP Message
  3117.  
  3118.    The HMAC-MD5-96 authentication protocol assumes that the selection     |
  3119.    of the authKey is done by the caller and that the caller passes        |
  3120.    the secret key to be used.                                             |
  3121.  
  3122.    Upon completion the authentication module returns statusInformation
  3123.  
  3124.  
  3125.  
  3126. SNMPv3 Working Group        Expires April 1998                 [Page 53]
  3127.  
  3128. Internet Draft     User-based Security Model for SNMPv3      28 Oct 1997
  3129.  
  3130.  
  3131.    and, if the message digest was correctly calculated, the wholeMsg
  3132.    as it was processed. The abstract service primitive is:
  3133.  
  3134.    statusInformation =              -- success or failure
  3135.      authenticateIncomingMsg(
  3136.      IN   authKey                   -- secret key for authentication
  3137.      IN   authParameters            -- as received on the wire
  3138.      IN   wholeMsg                  -- as received on the wire
  3139.      OUT  authenticatedWholeMsg     -- complete authenticated message
  3140.        )
  3141.  
  3142.    The abstract data elements are:
  3143.  
  3144.      statusInformation
  3145.        An indication of whether the authentication process was
  3146.        successful.  If not it is an indication of the problem.
  3147.      authKey
  3148.        The secret key to be used by the authentication algorithm.
  3149.        The length of this key MUST be 16 octets.                          |
  3150.      authParameters
  3151.        The authParameters from the incoming message.
  3152.      wholeMsg
  3153.        The message to be authenticated on input and the authenticated
  3154.        message on output.
  3155.      authenticatedWholeMsg
  3156.        The whole message after the authentication check is complete.
  3157.  
  3158. 6.3.  Elements of Procedure
  3159.  
  3160.    This section describes the procedures for the HMAC-MD5-96              |
  3161.    authentication protocol.
  3162.  
  3163. 6.3.1.  Processing an Outgoing Message
  3164.  
  3165.    This section describes the procedure followed by an SNMP engine
  3166.    whenever it must authenticate an outgoing message using the
  3167.    usmHMACMD5AuthProtocol.                                                |
  3168.  
  3169.    1)  The msgAuthenticationParameters field is set to the
  3170.        serialization, according to the rules in [RFC1906], of an
  3171.        OCTET STRING containing 12 zero octets.                            5
  3172.                                                                           |
  3173.    2)  From the secret authKey, two keys K1 and K2 are derived:           3
  3174.                                                                           3
  3175.          a) extend the authKey to 64 octets by appending 48 zero          |
  3176.             octets; save it as extendedAuthKey                            |
  3177.          b) obtain IPAD by replicating the octet 0x36 64 times;           |
  3178.          c) obtain K1 by XORing extendedAuthKey with IPAD;                |
  3179.          d) obtain OPAD by replicating the octet 0x5C 64 times;           |
  3180.          e) obtain K2 by XORing extendedAuthKey with OPAD.                |
  3181.                                                                           |
  3182.  
  3183.  
  3184.  
  3185. SNMPv3 Working Group        Expires April 1998                 [Page 54]
  3186.  
  3187. Internet Draft     User-based Security Model for SNMPv3      28 Oct 1997
  3188.  
  3189.  
  3190.    4) Prepend K1 to the wholeMsg and calculate MD5 digest over it         |
  3191.       according to [MD5].                                                 |
  3192.                                                                           |
  3193.    5) Prepend K2 to the result of the step 4 and calculate MD5 digest     |
  3194.       over it according to [MD5]. Take the first 12 octets of the final   |
  3195.       digest - this is Message Authentication Code (MAC).                 |
  3196.                                                                           |
  3197.    6) Replace the msgAuthenticationParameters field with MAC obtained     |
  3198.       in the step 5.                                                      |
  3199.                                                                           |
  3200.    7) The authenticatedWholeMsg is then returned to the caller            |
  3201.       together with statusInformation indicating success.                 |
  3202.                                                                           |
  3203. 6.3.2.  Processing an Incoming Message
  3204.  
  3205.    This section describes the procedure followed by an SNMP engine
  3206.    whenever it must authenticate an incoming message using the
  3207.    usmHMACMD5AuthProtocol.                                                |
  3208.                                                                           |
  3209.    1)  If the digest received in the msgAuthenticationParameters field    |
  3210.        is not 12 octets long, then an failure and an errorIndication      |
  3211.        (authenticationError) is returned to the calling module.           |
  3212.                                                                           |
  3213.    2)  The MAC received in the msgAuthenticationParameters field          |
  3214.        is saved.                                                          |
  3215.                                                                           |
  3216.    3)  The digest in the msgAuthenticationParameters field is replaced    |
  3217.        by the 12 zero octets.                                             |
  3218.                                                                           |
  3219.    4)  From the secret authKey, two keys K1 and K2 are derived:           3
  3220.                                                                           3
  3221.          a) extend the authKey to 64 octets by appending 48 zero          |
  3222.             octets; save it as extendedAuthKey                            |
  3223.          b) obtain IPAD by replicating the octet 0x36 64 times;           |
  3224.          c) obtain K1 by XORing extendedAuthKey with IPAD;                |
  3225.          d) obtain OPAD by replicating the octet 0x5C 64 times;           |
  3226.          e) obtain K2 by XORing extendedAuthKey with OPAD.                |
  3227.                                                                           |
  3228.    5)  The MAC is calculated over the wholeMsg:                           |
  3229.                                                                           |
  3230.          a) prepend K1 to the wholeMsg and calculate the MD5 digest       |
  3231.             over it;                                                      |
  3232.          b) prepend K2 to the result of step 5.a and calculate the        |
  3233.             MD5 digest over it;                                           |
  3234.          c) first 12 octets of the result of step 5.b is the MAC.         |
  3235.                                                                           |
  3236.        The msgAuthenticationParameters field is replaced with the         |
  3237.        MAC value that was saved in step 2.                                |
  3238.                                                                           |
  3239.    6)  Then the newly calculated MAC is compared with the MAC             |
  3240.        saved in step 2. If they do not match, then an failure             |
  3241.  
  3242.  
  3243.  
  3244. SNMPv3 Working Group        Expires April 1998                 [Page 55]
  3245.  
  3246. Internet Draft     User-based Security Model for SNMPv3      28 Oct 1997
  3247.  
  3248.  
  3249.        and an errorIndication (authenticationFailure) is returned to      |
  3250.        the calling module.                                                |
  3251.                                                                           |
  3252.    7)  The authenticatedWholeMsg and statusInformation indicating         |
  3253.        success are then returned to the caller.                           |
  3254.                                                                           |
  3255.                                                                           |
  3256.  
  3257.  
  3258.  
  3259.  
  3260.  
  3261.  
  3262.  
  3263.  
  3264.  
  3265.  
  3266.  
  3267.  
  3268.  
  3269.  
  3270.  
  3271.  
  3272.  
  3273.  
  3274.  
  3275.  
  3276.  
  3277.  
  3278.  
  3279.  
  3280.  
  3281.  
  3282.  
  3283.  
  3284.  
  3285.  
  3286.  
  3287.  
  3288.  
  3289.  
  3290.  
  3291.  
  3292.  
  3293.  
  3294.  
  3295.  
  3296.  
  3297.  
  3298.  
  3299.  
  3300.  
  3301.  
  3302.  
  3303. SNMPv3 Working Group        Expires April 1998                 [Page 56]
  3304.  
  3305. Internet Draft     User-based Security Model for SNMPv3      28 Oct 1997
  3306.  
  3307.  
  3308. 7.  HMAC-SHA-96 Authentication Protocol                                   |
  3309.                                                                           |
  3310.    This section describes the HMAC-SHA-96 authentication protocol.        |
  3311.    This protocol uses the SHA hash-function which is described in         |
  3312.    [SHA-NIST], in HMAC mode described in [RFC2104], truncating            |
  3313.    the output to 96 bits.                                                 |
  3314.                                                                           |
  3315.    This protocol is identified by usmHMACSHAAuthProtocol.                 |
  3316.                                                                           |
  3317.    Over time, other authentication protocols may be defined either        |
  3318.    as a replacement of this protocol or in addition to this protocol.     |
  3319.                                                                           |
  3320. 7.1.  Mechanisms                                                          |
  3321.                                                                           |
  3322.    - In support of data integrity, a message digest algorithm is          |
  3323.      required.  A digest is calculated over an appropriate portion        |
  3324.      of an SNMP message and included as part of the message sent          |
  3325.      to the recipient.                                                    |
  3326.                                                                           |
  3327.    - In support of data origin authentication and data integrity,         |
  3328.      a secret value is prepended to the SNMP message prior to             |
  3329.      computing the digest; the calculated digest is then partially        |
  3330.      inserted into the message prior to transmission. The prepended       |
  3331.      secret is not transmitted.  The secret value is shared by all        |
  3332.      SNMP engines authorized to originate messages on behalf of the       |
  3333.      appropriate user.                                                    |
  3334.                                                                           3
  3335.                                                                           3
  3336. 7.1.1.  Digest Authentication Mechanism                                   |
  3337.                                                                           |
  3338.    The Digest Authentication Mechanism defined in this memo provides      |
  3339.    for:                                                                   |
  3340.                                                                           |
  3341.    - verification of the integrity of a received message, i.e., the       |
  3342.      the message received is the message sent.                            |
  3343.                                                                           |
  3344.      The integrity of the message is protected by computing a digest      |
  3345.      over an appropriate portion of the message.  The digest is           |
  3346.      computed by the originator of the message, transmitted with the      |
  3347.      message, and verified by the recipient of the message.               |
  3348.                                                                           |
  3349.    - verification of the user on whose behalf the message was generated.  |
  3350.                                                                           |
  3351.      A secret value known only to SNMP engines authorized to              |
  3352.      generate messages on behalf of a user is used in HMAC mode           |
  3353.      (see [RFC2104]). It also recommends the hash-function output         |
  3354.      used as Message Authentication Code, to be truncated.                |
  3355.                                                                           |
  3356.    This mechanism uses the SHA [SHA-NIST] message digest algorithm.       |
  3357.    A 160-bit SHA digest is calculated in a special (HMAC) way over        |
  3358.    the designated portion of an SNMP message and the first 96 bits        |
  3359.  
  3360.  
  3361.  
  3362. SNMPv3 Working Group        Expires April 1998                 [Page 57]
  3363.  
  3364. Internet Draft     User-based Security Model for SNMPv3      28 Oct 1997
  3365.  
  3366.  
  3367.    of this digest is included as part of the message sent to the          |
  3368.    recipient. The size of the digest carried in a message is 12           |
  3369.    octets. The size of the private authentication key (the secret)        |
  3370.    is 20 octets. For the details see section 7.3.                         |
  3371.                                                                           |
  3372. 7.2.  Elements of the HMAC-SHA-96 Authentication Protocol                 |
  3373.                                                                           |
  3374.    This section contains definitions required to realize the              |
  3375.    authentication module defined in this section of this memo.            |
  3376.                                                                           |
  3377. 7.2.1.  Users                                                             |
  3378.                                                                           |
  3379.    Authentication using this authentication protocol makes use            |
  3380.    of a defined set of userNames.  For any user on whose behalf a         |
  3381.    message must be authenticated at a particular SNMP engine, that        |
  3382.    SNMP engine must have knowledge of that user.  An SNMP engine that     |
  3383.    wishes to communicate with another SNMP engine must also have          |
  3384.    knowledge of a user known to that engine, including knowledge of       |
  3385.    the applicable attributes of that user.                                |
  3386.                                                                           |
  3387.    A user and its attributes are defined as follows:                      |
  3388.                                                                           |
  3389.    <userName>                                                             |
  3390.      A string representing the name of the user.                          |
  3391.    <authKey>                                                              |
  3392.      A user's secret key to be used when calculating a digest.            |
  3393.      It MUST be 20 octets long for SHA.                                   |
  3394.                                                                           |
  3395. 7.2.2.  msgAuthoritativeEngineID                                          |
  3396.                                                                           |
  3397.    The msgAuthoritativeEngineID value contained in an authenticated       |
  3398.    message specifies the authoritative SNMP engine for that particular    |
  3399.    message (see the definition of SnmpEngineID in the SNMP                |
  3400.    Architecture document [SNMP-ARCH]).                                    |
  3401.                                                                           |
  3402.    The user's (private) authentication key is normally different at       |
  3403.    each authoritative SNMP engine and so the snmpEngineID is used         |
  3404.    to select the proper key for the authentication process.               |
  3405.                                                                           |
  3406. 7.2.3.  SNMP Messages Using this Authentication Protocol                  |
  3407.                                                                           |
  3408.    Messages using this authentication protocol carry a                    |
  3409.    msgAuthenticationParameters field as part of the                       |
  3410.    msgSecurityParameters. For this protocol, the                          |
  3411.    msgAuthenticationParameters field is the serialized                    |
  3412.    OCTET STRING representing the first 12 octets of HMAC-SHA-96           |
  3413.    output done over the wholeMsg.                                         |
  3414.                                                                           |
  3415.    The digest is calculated over the wholeMsg so if a message is          |
  3416.    authenticated, that also means that all the fields in the              |
  3417.    message are intact and have not been tampered with.                    |
  3418.  
  3419.  
  3420.  
  3421. SNMPv3 Working Group        Expires April 1998                 [Page 58]
  3422.  
  3423. Internet Draft     User-based Security Model for SNMPv3      28 Oct 1997
  3424.  
  3425.  
  3426.                                                                           |
  3427. 7.2.4.  Services provided by the HMAC-SHA-96 Authentication Module        |
  3428.                                                                           |
  3429.    This section describes the inputs and outputs that the HMAC-SHA-96     |
  3430.    Authentication module expects and produces when the User-based         |
  3431.    Security module calls the HMAC-SHA-96 Authentication module            |
  3432.    for services.                                                          |
  3433.                                                                           |
  3434.                                                                           |
  3435. 7.2.4.1.  Services for Generating an Outgoing SNMP Message                |
  3436.                                                                           |
  3437.    HMAC-SHA-96 authentication protocol assumes that the selection         |
  3438.    of the authKey is done by the caller and that the caller passes        |
  3439.    the secret key to be used.                                             |
  3440.                                                                           |
  3441.    Upon completion the authentication module returns statusInformation    |
  3442.    and, if the message digest was correctly calculated, the wholeMsg      |
  3443.    with the digest inserted at the proper place. The abstract service     |
  3444.    primitive is:                                                          |
  3445.                                                                           |
  3446.    statusInformation =              -- success or failure                 |
  3447.      authenticateOutgoingMsg(                                             |
  3448.      IN   authKey                   -- secret key for authentication      |
  3449.      IN   wholeMsg                  -- unauthenticated complete message   |
  3450.      OUT  authenticatedWholeMsg     -- complete authenticated message     |
  3451.           )                                                               |
  3452.                                                                           |
  3453.    The abstract data elements are:                                        |
  3454.                                                                           |
  3455.      statusInformation                                                    |
  3456.        An indication of whether the authentication process was            |
  3457.        successful.  If not it is an indication of the problem.            |
  3458.      authKey                                                              |
  3459.        The secret key to be used by the authentication algorithm.         |
  3460.        The length of this key MUST be 20 octets.                          |
  3461.      wholeMsg                                                             |
  3462.        The message to be authenticated.                                   |
  3463.      authenticatedWholeMsg                                                |
  3464.        The authenticated message (including inserted digest) on output.   |
  3465.                                                                           |
  3466.    Note, that authParameters field is filled by the authentication        |
  3467.    module and this field should be already present in the wholeMsg        |
  3468.    before the Message Authentication Code (MAC) is generated.             |
  3469.                                                                           |
  3470. 7.2.4.2.  Services for Processing an Incoming SNMP Message                |
  3471.                                                                           |
  3472.    HMAC-SHA-96 authentication protocol assumes that the selection         |
  3473.    of the authKey is done by the caller and that the caller passes        |
  3474.    the secret key to be used.                                             |
  3475.                                                                           |
  3476.    Upon completion the authentication module returns statusInformation    |
  3477.  
  3478.  
  3479.  
  3480. SNMPv3 Working Group        Expires April 1998                 [Page 59]
  3481.  
  3482. Internet Draft     User-based Security Model for SNMPv3      28 Oct 1997
  3483.  
  3484.  
  3485.    and, if the message digest was correctly calculated, the wholeMsg      |
  3486.    as it was processed. The abstract service primitive is:                |
  3487.                                                                           |
  3488.    statusInformation =              -- success or failure                 |
  3489.      authenticateIncomingMsg(                                             |
  3490.      IN   authKey                   -- secret key for authentication      |
  3491.      IN   authParameters            -- as received on the wire            |
  3492.      IN   wholeMsg                  -- as received on the wire            |
  3493.      OUT  authenticatedWholeMsg     -- complete authenticated message     |
  3494.        )                                                                  |
  3495.                                                                           |
  3496.    The abstract data elements are:                                        |
  3497.                                                                           |
  3498.      statusInformation                                                    |
  3499.        An indication of whether the authentication process was            |
  3500.        successful.  If not it is an indication of the problem.            |
  3501.      authKey                                                              |
  3502.        The secret key to be used by the authentication algorithm.         |
  3503.        The length of this key MUST be 20 octets.                          |
  3504.      authParameters                                                       |
  3505.        The authParameters from the incoming message.                      |
  3506.      wholeMsg                                                             |
  3507.        The message to be authenticated on input and the authenticated     |
  3508.        message on output.                                                 |
  3509.      authenticatedWholeMsg                                                |
  3510.        The whole message after the authentication check is complete.      |
  3511.  
  3512. 7.3.  Elements of Procedure                                               |
  3513.                                                                           |
  3514.    This section describes the procedures for the HMAC-SHA-96              |
  3515.    authentication protocol.                                               |
  3516.                                                                           |
  3517. 7.3.1.  Processing an Outgoing Message                                    |
  3518.                                                                           |
  3519.    This section describes the procedure followed by an SNMP engine        |
  3520.    whenever it must authenticate an outgoing message using the            |
  3521.    usmHMACSHAAuthProtocol.                                                |
  3522.                                                                           |
  3523.    1)  The msgAuthenticationParameters field is set to the                |
  3524.        serialization, according to the rules in [RFC1906], of an          |
  3525.        OCTET STRING containing 12 zero octets.                            |
  3526.                                                                           |
  3527.    2)  From the secret authKey, two keys K1 and K2 are derived:           3
  3528.                                                                           3
  3529.          a) extend the authKey to 64 octets by appending 44 zero          |
  3530.             octets; save it as extendedAuthKey                            |
  3531.          b) obtain IPAD by replicating the octet 0x36 64 times;           |
  3532.          c) obtain K1 by XORing extendedAuthKey with IPAD;                |
  3533.          d) obtain OPAD by replicating the octet 0x5C 64 times;           |
  3534.          e) obtain K2 by XORing extendedAuthKey with OPAD.                |
  3535.                                                                           |
  3536.  
  3537.  
  3538.  
  3539. SNMPv3 Working Group        Expires April 1998                 [Page 60]
  3540.  
  3541. Internet Draft     User-based Security Model for SNMPv3      28 Oct 1997
  3542.  
  3543.  
  3544.    4) Prepend K1 to the wholeMsg and calculate the SHA digest over it     |
  3545.       according to [SHA-NIST].                                            |
  3546.                                                                           |
  3547.    5) Prepend K2 to the result of the step 4 and calculate SHA digest     |
  3548.       over it according to [SHA-NIST]. Take the first 12 octets of the    |
  3549.       final digest - this is Message Authentication Code (MAC).           |
  3550.                                                                           |
  3551.    6) Replace the msgAuthenticationParameters field with MAC obtained     |
  3552.       in the step 5.                                                      |
  3553.                                                                           |
  3554.    7) The authenticatedWholeMsg is then returned to the caller            |
  3555.       together with statusInformation indicating success.                 |
  3556.                                                                           |
  3557. 7.3.2.  Processing an Incoming Message                                    |
  3558.                                                                           |
  3559.    This section describes the procedure followed by an SNMP engine        |
  3560.    whenever it must authenticate an incoming message using the            |
  3561.    usmHMACSHAAuthProtocol.                                                |
  3562.                                                                           |
  3563.    1)  If the digest received in the msgAuthenticationParameters field    |
  3564.        is not 12 octets long, then an failure and an errorIndication      |
  3565.        (authenticationError) is returned to the calling module.           |
  3566.                                                                           |
  3567.    2)  The MAC received in the msgAuthenticationParameters field          |
  3568.        is saved.                                                          |
  3569.                                                                           |
  3570.    3)  The digest in the msgAuthenticationParameters field is             |
  3571.        replaced by the 12 zero octets.                                    |
  3572.                                                                           |
  3573.    4)  From the secret authKey, two keys K1 and K2 are derived:           3
  3574.                                                                           3
  3575.          a) extend the authKey to 64 octets by appending 44 zero          |
  3576.             octets; save it as extendedAuthKey                            |
  3577.          b) obtain IPAD by replicating the octet 0x36 64 times;           |
  3578.          c) obtain K1 by XORing extendedAuthKey with IPAD;                |
  3579.          d) obtain OPAD by replicating the octet 0x5C 64 times;           |
  3580.          e) obtain K2 by XORing extendedAuthKey with OPAD.                |
  3581.                                                                           |
  3582.    5)  The MAC is calculated over the wholeMsg:                           |
  3583.                                                                           |
  3584.          a) prepend K1 to the wholeMsg and calculate the SHA digest       |
  3585.             over it;                                                      |
  3586.          b) prepend K2 to the result of step 5.a and calculate the        |
  3587.             SHA digest over it;                                           |
  3588.          c) first 12 octets of the result of step 5.b is the MAC.         |
  3589.                                                                           |
  3590.        The msgAuthenticationParameters field is replaced with the         |
  3591.        MAC value that was saved in step 2.                                |
  3592.                                                                           |
  3593.    6)  The the newly calculated MAC is compared with the MAC saved in     |
  3594.        step 2. If they do not match, then a failure and an                |
  3595.  
  3596.  
  3597.  
  3598. SNMPv3 Working Group        Expires April 1998                 [Page 61]
  3599.  
  3600. Internet Draft     User-based Security Model for SNMPv3      28 Oct 1997
  3601.  
  3602.  
  3603.        errorIndication (authenticationFailure) are returned to the        |
  3604.        calling module.                                                    |
  3605.                                                                           |
  3606.    7)  The authenticatedWholeMsg and statusInformation indicating         |
  3607.        success are then returned to the caller.                           |
  3608.                                                                           |
  3609.                                                                           |
  3610.  
  3611.  
  3612.  
  3613.  
  3614.  
  3615.  
  3616.  
  3617.  
  3618.  
  3619.  
  3620.  
  3621.  
  3622.  
  3623.  
  3624.  
  3625.  
  3626.  
  3627.  
  3628.  
  3629.  
  3630.  
  3631.  
  3632.  
  3633.  
  3634.  
  3635.  
  3636.  
  3637.  
  3638.  
  3639.  
  3640.  
  3641.  
  3642.  
  3643.  
  3644.  
  3645.  
  3646.  
  3647.  
  3648.  
  3649.  
  3650.  
  3651.  
  3652.  
  3653.  
  3654.  
  3655.  
  3656.  
  3657. SNMPv3 Working Group        Expires April 1998                 [Page 62]
  3658.  
  3659. Internet Draft     User-based Security Model for SNMPv3      28 Oct 1997
  3660.  
  3661.  
  3662. 8.  CBC-DES Symmetric Encryption Protocol                                 |
  3663.                                                                           |
  3664.    This section describes the CBC-DES Symmetric Encryption Protocol.      |
  3665.    This protocol is the first privacy protocol defined for the
  3666.    User-based Security Model.
  3667.  
  3668.    This protocol is identified by usmDESPrivProtocol.
  3669.  
  3670.    Over time, other privacy protocols may be defined either
  3671.    as a replacement of this protocol or in addition to this protocol.
  3672.  
  3673.  
  3674. 8.1.  Mechanisms                                                          |
  3675.  
  3676.    - In support of data confidentiality, an encryption algorithm is
  3677.      required.  An appropriate portion of the message is encrypted
  3678.      prior to being transmitted. The User-based Security Model
  3679.      specifies that the scopedPDU is the portion of the message
  3680.      that needs to be encrypted.
  3681.  
  3682.    - A secret value in combination with a timeliness value is used
  3683.      to create the en/decryption key and the initialization vector.
  3684.      The secret value is shared by all SNMP engines authorized to
  3685.      originate messages on behalf of the appropriate user.
  3686.                                                                           3
  3687.                                                                           3
  3688. 8.1.1.  Symmetric Encryption Protocol                                     |
  3689.  
  3690.    The Symmetric Encryption Protocol defined in this memo provides
  3691.    support for data confidentiality.  The designated portion of an
  3692.    SNMP message is encrypted and included as part of the message
  3693.    sent to the recipient.
  3694.  
  3695.    Two organizations have published specifications defining the DES:
  3696.    the National Institute of Standards and Technology (NIST)
  3697.    [DES-NIST] and the American National Standards Institute
  3698.    [DES-ANSI].  There is a companion Modes of Operation specification
  3699.    for each definition ([DESO-NIST] and [DESO-ANSI], respectively).
  3700.  
  3701.    The NIST has published three additional documents that implementors
  3702.    may find useful.
  3703.  
  3704.    - There is a document with guidelines for implementing and using
  3705.      the DES, including functional specifications for the DES and
  3706.      its modes of operation [DESG-NIST].
  3707.  
  3708.    - There is a specification of a validation test suite for the DES
  3709.      [DEST-NIST].  The suite is designed to test all aspects of the
  3710.      DES and is useful for pinpointing specific problems.
  3711.  
  3712.    - There is a specification of a maintenance test for the DES
  3713.  
  3714.  
  3715.  
  3716. SNMPv3 Working Group        Expires April 1998                 [Page 63]
  3717.  
  3718. Internet Draft     User-based Security Model for SNMPv3      28 Oct 1997
  3719.  
  3720.  
  3721.      [DESM-NIST].  The test utilizes a minimal amount of data and
  3722.      processing to test all components of the DES.  It provides a
  3723.      simple yes-or-no indication of correct operation and is useful
  3724.      to run as part of an initialization step, e.g., when a computer
  3725.      re-boots.
  3726.  
  3727. 8.1.1.1.  DES key and Initialization Vector.                              |
  3728.  
  3729.    The first 8 octets of the 16-octet secret (private privacy key) are    |
  3730.    used as a DES key.  Since DES uses only 56 bits, the Least
  3731.    Significant Bit in each octet is disregarded.                          |
  3732.  
  3733.    The Initialization Vector for encryption is obtained using the
  3734.    following procedure.
  3735.  
  3736.    The last 8 octets of the 16-octet secret (private privacy key)         |
  3737.    are used as pre-IV.
  3738.  
  3739.    In order to ensure that the IV for two different packets encrypted
  3740.    by the same key, are not the same (i.e., the IV does not repeat) we    |
  3741.    need to "salt" the pre-IV with something unique per packet.
  3742.    An 8-octet string is used as the "salt".  The concatenation            |
  3743.    of the generating SNMP engine's 32-bit snmpEngineBoots and a local
  3744.    32-bit integer, that the encryption engine maintains, is input to
  3745.    the "salt".  The 32-bit integer is initialized to an arbitrary
  3746.    value at boot time.
  3747.    The 32-bit snmpEngineBoots is converted to the first 4 octets          |
  3748.    (Most Significant Byte first) of our "salt".  The 32-bit integer
  3749.    is then converted to the last 4 octet (Most Significant Byte first)    |
  3750.    of our "salt".  The resulting "salt" is then XOR-ed with the
  3751.    pre-IV. The 8-octet "salt" is then put into the privParameters
  3752.    field encoded as an OCTET STRING.  The "salt" integer is then
  3753.    modified.  We recommend that it be incremented by one and wrap
  3754.    when it reaches the maximum value.
  3755.  
  3756.    How exactly the value of the "salt" (and thus of the IV) varies,
  3757.    is an implementation issue, as long as the measures are taken to
  3758.    avoid producing a duplicate IV.
  3759.  
  3760.    The "salt" must be placed in the privParameters field to enable the
  3761.    receiving entity to compute the correct IV and to decrypt the
  3762.    message.
  3763.  
  3764. 8.1.1.2.  Data Encryption.                                                |
  3765.  
  3766.    The data to be encrypted is treated as sequence of octets. Its
  3767.    length should be an integral multiple of 8 - and if it is not, the
  3768.    data is padded at the end as necessary.  The actual pad value
  3769.    is irrelevant.
  3770.  
  3771.    The data is encrypted in Cipher Block Chaining mode.
  3772.  
  3773.  
  3774.  
  3775. SNMPv3 Working Group        Expires April 1998                 [Page 64]
  3776.  
  3777. Internet Draft     User-based Security Model for SNMPv3      28 Oct 1997
  3778.  
  3779.  
  3780.    The plaintext is divided into 64-bit blocks.
  3781.  
  3782.    The plaintext for each block is XOR-ed with the ciphertext
  3783.    of the previous block, the result is encrypted and the output
  3784.    of the encryption is the ciphertext for the block.
  3785.    This procedure is repeated until there are no more plaintext
  3786.    blocks.
  3787.  
  3788.    For the very first block, the Initialization Vector is used
  3789.    instead of the ciphertext of the previous block.
  3790.  
  3791. 8.1.1.3.  Data Decryption                                                 |
  3792.  
  3793.    Before decryption, the encrypted data length is verified.
  3794.    If the length of the OCTET STRING to be decrypted is not an
  3795.    integral multiple of 8 octets, the decryption process is halted
  3796.    and an appropriate exception noted.  When decrypting, the padding
  3797.    is ignored.
  3798.  
  3799.    The first ciphertext block is decrypted, the decryption output is
  3800.    XOR-ed with the Initialization Vector, and the result is the first
  3801.    plaintext block.
  3802.  
  3803.    For each subsequent block, the ciphertext block is decrypted,
  3804.    the decryption output is XOR-ed with the previous ciphertext
  3805.    block and the result is the plaintext block.
  3806.  
  3807. 8.2.  Elements of the DES Privacy Protocol                                |
  3808.  
  3809.    This section contains definitions required to realize the privacy
  3810.    module defined by this memo.
  3811.  
  3812. 8.2.1.  Users                                                             |
  3813.  
  3814.    Data en/decryption using this Symmetric Encryption Protocol makes
  3815.    use of a defined set of userNames.  For any user on whose behalf
  3816.    a message must be en/decrypted at a particular SNMP engine, that
  3817.    SNMP engine must have knowledge of that user.  An SNMP engine that
  3818.    wishes to communicate with another SNMP engine must also have
  3819.    knowledge of a user known to that SNMP engine, including knowledge
  3820.    of the applicable attributes of that user.
  3821.  
  3822.    A user and its attributes are defined as follows:
  3823.  
  3824.    <userName>
  3825.      An octet string representing the name of the user.
  3826.    <privKey>
  3827.      A user's secret key to be used as input for the DES key and IV.
  3828.      The length of this key MUST be 16 octets.                            |
  3829.  
  3830. 8.2.2.  msgAuthoritativeEngineID                                          |
  3831.  
  3832.  
  3833.  
  3834. SNMPv3 Working Group        Expires April 1998                 [Page 65]
  3835.  
  3836. Internet Draft     User-based Security Model for SNMPv3      28 Oct 1997
  3837.  
  3838.  
  3839.  
  3840.    The msgAuthoritativeEngineID value contained in an authenticated
  3841.    message specifies the authoritative SNMP engine for that particular
  3842.    message (see the definition of SnmpEngineID in the SNMP
  3843.    Architecture document [SNMP-ARCH]).
  3844.  
  3845.    The user's (private) privacy key is normally different at each
  3846.    authoritative SNMP engine and so the snmpEngineID is used to select
  3847.    the proper key for the en/decryption process.
  3848.  
  3849. 8.2.3.  SNMP Messages Using this Privacy Protocol                         |
  3850.  
  3851.    Messages using this privacy protocol carry a msgPrivacyParameters
  3852.    field as part of the msgSecurityParameters. For this protocol, the
  3853.    msgPrivacyParameters field is the serialized OCTET STRING
  3854.    representing the "salt" that was used to create the IV.
  3855.  
  3856. 8.2.4.  Services provided by the DES Privacy Module                       |
  3857.  
  3858.    This section describes the inputs and outputs that the DES Privacy
  3859.    module expects and produces when the User-based Security module
  3860.    invokes the DES Privacy module for services.
  3861.  
  3862. 8.2.4.1.  Services for Encrypting Outgoing Data                           |
  3863.  
  3864.    This DES privacy protocol assumes that the selection of the
  3865.    privKey is done by the caller and that the caller passes
  3866.    the secret key to be used.
  3867.  
  3868.    Upon completion the privacy module returns statusInformation
  3869.    and, if the encryption process was successful, the encryptedPDU
  3870.    and the msgPrivacyParameters encoded as an OCTET STRING.
  3871.    The abstract service primitive is:
  3872.  
  3873.    statusInformation =              -- success of failure
  3874.      encryptData(
  3875.      IN    encryptKey               -- secret key for encryption
  3876.      IN    dataToEncrypt            -- data to encrypt (scopedPDU)
  3877.      OUT   encryptedData            -- encrypted data (encryptedPDU)
  3878.      OUT   privParameters           -- filled in by service provider
  3879.            )
  3880.  
  3881.    The abstract data elements are:
  3882.  
  3883.      statusInformation
  3884.        An indication of the success or failure of the encryption
  3885.        process.  In case of failure, it is an indication of the error.
  3886.      encryptKey
  3887.        The secret key to be used by the encryption algorithm.
  3888.        The length of this key MUST be 16 octets.                          |
  3889.      dataToEncrypt
  3890.  
  3891.  
  3892.  
  3893. SNMPv3 Working Group        Expires April 1998                 [Page 66]
  3894.  
  3895. Internet Draft     User-based Security Model for SNMPv3      28 Oct 1997
  3896.  
  3897.  
  3898.        The data that must be encrypted.
  3899.      encryptedData
  3900.        The encrypted data upon successful completion.
  3901.      privParameters
  3902.        The privParameters encoded as an OCTET STRING.
  3903.  
  3904. 8.2.4.2.  Services for Decrypting Incoming Data                           |
  3905.  
  3906.    This DES privacy protocol assumes that the selection of the
  3907.    privKey is done by the caller and that the caller passes
  3908.    the secret key to be used.
  3909.  
  3910.    Upon completion the privacy module returns statusInformation
  3911.    and, if the decryption process was successful, the scopedPDU
  3912.    in plain text. The abstract service primitive is:
  3913.  
  3914.    statusInformation =
  3915.      decryptData(
  3916.      IN    decryptKey               -- secret key for decryption
  3917.      IN    privParameters           -- as received on the wire
  3918.      IN    encryptedData            -- encrypted data (encryptedPDU)
  3919.      OUT   decryptedData            -- decrypted data (scopedPDU)
  3920.            )
  3921.  
  3922.    The abstract data elements are:
  3923.  
  3924.      statusInformation
  3925.        An indication whether the data was successfully decrypted
  3926.        and if not an indication of the error.
  3927.      decryptKey
  3928.        The secret key to be used by the decryption algorithm.
  3929.        The length of this key MUST be 16 octets.                          |
  3930.      privParameters
  3931.        The "salt" to be used to calculate the IV.
  3932.      encryptedData
  3933.        The data to be decrypted.
  3934.      decryptedData
  3935.        The decrypted data.
  3936.  
  3937. 8.3.  Elements of Procedure.                                              |
  3938.  
  3939.    This section describes the procedures for the DES privacy protocol.
  3940.  
  3941. 8.3.1.  Processing an Outgoing Message                                    |
  3942.  
  3943.    This section describes the procedure followed by an SNMP engine
  3944.    whenever it must encrypt part of an outgoing message using the
  3945.    usmDESPrivProtocol.
  3946.  
  3947.    1)  The secret cryptKey is used to construct the DES encryption key,   3
  3948.        the "salt" and the DES pre-IV (as described in section 8.1.1.1).   3
  3949.  
  3950.  
  3951.  
  3952. SNMPv3 Working Group        Expires April 1998                 [Page 67]
  3953.  
  3954. Internet Draft     User-based Security Model for SNMPv3      28 Oct 1997
  3955.  
  3956.  
  3957.  
  3958.    2)  The privParameters field is set to the serialization according
  3959.        to the rules in [RFC1906] of an OCTET STRING representing the
  3960.        the "salt" string.
  3961.  
  3962.    3)  The scopedPDU is encrypted (as described in section 8.1.1.2)       |
  3963.        and the encrypted data is serialized according to the rules
  3964.        in [RFC1906] as an OCTET STRING.
  3965.  
  3966.    4)  The serialized OCTET STRING representing the encrypted
  3967.        scopedPDU together with the privParameters and statusInformation
  3968.        indicating success is returned to the calling module.
  3969.  
  3970. 8.3.2.  Processing an Incoming Message                                    |
  3971.  
  3972.    This section describes the procedure followed by an SNMP engine
  3973.    whenever it must decrypt part of an incoming message using the
  3974.    usmDESPrivProtocol.
  3975.  
  3976.    1)  If the privParameters field is not an 8-octet OCTET STRING,        |
  3977.        then an error indication (decryptionError) is returned to
  3978.        the calling module.
  3979.  
  3980.    2)  The "salt" is extracted from the privParameters field.
  3981.  
  3982.    3)  The secret cryptKey and the "salt" are then used to construct the  3
  3983.        DES decryption key and pre-IV (as described in section 8.1.1.1).   3
  3984.  
  3985.    4)  The encryptedPDU is then decrypted (as described in
  3986.        section 8.1.1.3).                                                  |
  3987.  
  3988.    5)  If the encryptedPDU cannot be decrypted, then an error
  3989.        indication (decryptionError) is returned to the calling module.
  3990.  
  3991.    6)  The decrypted scopedPDU and statusInformation indicating
  3992.        success are returned to the calling module.
  3993.  
  3994.  
  3995.  
  3996.  
  3997.  
  3998.  
  3999.  
  4000.  
  4001.  
  4002.  
  4003.  
  4004.  
  4005.  
  4006.  
  4007.  
  4008.  
  4009.  
  4010.  
  4011. SNMPv3 Working Group        Expires April 1998                 [Page 68]
  4012.  
  4013. Internet Draft     User-based Security Model for SNMPv3      28 Oct 1997
  4014.  
  4015.  
  4016. 9.  Intellectual Property
  4017.  
  4018.    The IETF takes no position regarding the validity or scope of any      5
  4019.    intellectual property or other rights that might be claimed to         5
  4020.    pertain to the implementation or use of the technology described in    5
  4021.    this document or the extent to which any license under such rights     5
  4022.    might or might not be available; neither does it represent that it     5
  4023.    has made any effort to identify any such rights.  Information on the   5
  4024.    IETF's procedures with respect to rights in standards-track and        5
  4025.    standards-related documentation can be found in BCP-11.  Copies of     5
  4026.    claims of rights made available for publication and any assurances of  5
  4027.    licenses to be made available, or the result of an attempt made to     5
  4028.    obtain a general license or permission for the use of such             5
  4029.    proprietary rights by implementors or users of this specification can  5
  4030.    be obtained from the IETF Secretariat.                                 5
  4031.                                                                           5
  4032.    The IETF invites any interested party to bring to its attention any    5
  4033.    copyrights, patents or patent applications, or other proprietary       5
  4034.    rights which may cover technology that may be required to practice     5
  4035.    this standard.  Please address the information to the IETF Executive   5
  4036.    Director.                                                              5
  4037.  
  4038. 10.  Acknowledgements
  4039.  
  4040. This document is the result of the efforts of the SNMPv3 Working Group.
  4041. Some special thanks are in order to the following SNMPv3 WG members:
  4042.  
  4043.     Dave Battle (SNMP Research, Inc.)
  4044.     Uri Blumenthal (IBM T.J. Watson Research Center)
  4045.     Jeff Case (SNMP Research, Inc.)
  4046.     John Curran (BBN)
  4047.     T. Max Devlin (Hi-TECH Connections)
  4048.     John Flick (Hewlett Packard)
  4049.     David Harrington (Cabletron Systems Inc.)
  4050.     N.C. Hien (IBM T.J. Watson Research Center)
  4051.     Dave Levi (SNMP Research, Inc.)
  4052.     Louis A Mamakos (UUNET Technologies Inc.)
  4053.     Paul Meyer (Secure Computing Corporation)
  4054.     Keith McCloghrie (Cisco Systems)
  4055.     Russ Mundy (Trusted Information Systems, Inc.)
  4056.     Bob Natale (ACE*COMM Corporation)
  4057.     Mike O'Dell (UUNET Technologies Inc.)
  4058.     Dave Perkins (DeskTalk)
  4059.     Peter Polkinghorne (Brunel University)
  4060.     Randy Presuhn (BMC Software, Inc.)
  4061.     David Reid (SNMP Research, Inc.)
  4062.     Shawn Routhier (Epilogue)
  4063.     Juergen Schoenwaelder (TU Braunschweig)
  4064.     Bob Stewart (Cisco Systems)
  4065.     Bert Wijnen (IBM T.J. Watson Research Center)
  4066.  
  4067.  
  4068.  
  4069.  
  4070. SNMPv3 Working Group        Expires April 1998                 [Page 69]
  4071.  
  4072. Internet Draft     User-based Security Model for SNMPv3      28 Oct 1997
  4073.  
  4074.  
  4075. The document is based on recommendations of the IETF Security and
  4076. Administrative Framework Evolution for SNMP Advisory Team.
  4077. Members of that Advisory Team were:
  4078.  
  4079.     David Harrington (Cabletron Systems Inc.)
  4080.     Jeff Johnson (Cisco Systems)
  4081.     David Levi (SNMP Research Inc.)
  4082.     John Linn (Openvision)
  4083.     Russ Mundy (Trusted Information Systems) chair
  4084.     Shawn Routhier (Epilogue)
  4085.     Glenn Waters (Nortel)
  4086.     Bert Wijnen (IBM T. J. Watson Research Center)
  4087.  
  4088. As recommended by the Advisory Team and the SNMPv3 Working Group
  4089. Charter, the design incorporates as much as practical from previous
  4090. RFCs and drafts. As a result, special thanks are due to the authors
  4091. of previous designs known as SNMPv2u and SNMPv2*:
  4092.  
  4093.     Jeff Case (SNMP Research, Inc.)
  4094.     David Harrington (Cabletron Systems Inc.)
  4095.     David Levi (SNMP Research, Inc.)
  4096.     Keith McCloghrie (Cisco Systems)
  4097.     Brian O'Keefe (Hewlett Packard)
  4098.     Marshall T. Rose (Dover Beach Consulting)
  4099.     Jon Saperia (BGS Systems Inc.)
  4100.     Steve Waldbusser (International Network Services)
  4101.     Glenn W. Waters (Bell-Northern Research Ltd.)
  4102.  
  4103. 11.  Security Considerations                                              |
  4104.  
  4105. 11.1.  Recommended Practices                                              |
  4106.  
  4107.    This section describes practices that contribute to the secure,
  4108.    effective operation of the mechanisms defined in this memo.
  4109.  
  4110.    - An SNMP engine must discard SNMP Response messages that do not
  4111.      correspond to any currently outstanding Request message. It is
  4112.      the responsibility of the Message Processing module to take care
  4113.      of this. For example it can use a msgID for that.
  4114.  
  4115.      An SNMP Command Generator Application must discard any Response
  4116.      PDU for which there is no currently outstanding Request PDU;
  4117.      for example for SNMPv2 [RFC1905] PDUs, the request-id component
  4118.      in the PDU can be used to correlate Responses to outstanding
  4119.      Requests.
  4120.  
  4121.      Although it would be typical for an SNMP engine and an SNMP
  4122.      Command Generator Application to do this as a matter of course,
  4123.      when using these security protocols it is significant due to
  4124.      the possibility of message duplication (malicious or otherwise).
  4125.  
  4126.  
  4127.  
  4128.  
  4129. SNMPv3 Working Group        Expires April 1998                 [Page 70]
  4130.  
  4131. Internet Draft     User-based Security Model for SNMPv3      28 Oct 1997
  4132.  
  4133.  
  4134.    - If an SNMP engine uses a msgID for correlating Response messages
  4135.      to outstanding Request messages, then it MUST use different
  4136.      msgIDs in all such Request messages that it sends out during a
  4137.      Time Window (150 seconds) period.
  4138.  
  4139.      A Command Generator or Notification Originator Application MUST
  4140.      use different request-ids in all Request PDUs that it sends out
  4141.      during a TimeWindow (150 seconds) period.
  4142.  
  4143.      This must be done to protect against the possibility of message
  4144.      duplication (malicious or otherwise).
  4145.  
  4146.      For example, starting operations with a msgID and/or request-id
  4147.      value of zero is not a good idea.  Initializing them with an
  4148.      unpredictable number (so they do not start out the same after
  4149.      each reboot) and then incrementing by one would be acceptable.
  4150.  
  4151.    - An SNMP engine should perform time synchronization using
  4152.      authenticated messages in order to protect against the
  4153.      possibility of message duplication (malicious or otherwise).
  4154.  
  4155.    - When sending state altering messages to a managed authoritative
  4156.      SNMP engine, a Command Generator Application should delay sending
  4157.      successive messages to that managed SNMP engine until a positive
  4158.      acknowledgement is received for the previous message or until
  4159.      the previous message expires.
  4160.  
  4161.      No message ordering is imposed by the SNMP. Messages may be
  4162.      received in any order relative to their time of generation and
  4163.      each will be processed in the ordered received.  Note that when
  4164.      an authenticated message is sent to a managed SNMP engine, it
  4165.      will be valid for a period of time of approximately 150 seconds
  4166.      under normal circumstances, and is subject to replay during this
  4167.      period.  Indeed, an SNMP engine and SNMP Command Generator
  4168.      Applications must cope with the loss and re-ordering of messages
  4169.      resulting from anomalies in the network as a matter of course.
  4170.  
  4171.      However, a managed object, snmpSetSerialNo [RFC1907], is
  4172.      specifically defined for use with SNMP Set operations in order
  4173.      to provide a mechanism to ensure that the processing of SNMP
  4174.      messages occurs in a specific order.
  4175.  
  4176.    - The frequency with which the secrets of a User-based Security
  4177.      Model user should be changed is indirectly related to the
  4178.      frequency of their use.
  4179.  
  4180.      Protecting the secrets from disclosure is critical to the overall
  4181.      security of the protocols.  Frequent use of a secret provides a
  4182.      continued source of data that may be useful to a cryptanalyst in
  4183.      exploiting known or perceived weaknesses in an algorithm.
  4184.      Frequent changes to the secret avoid this vulnerability.
  4185.  
  4186.  
  4187.  
  4188. SNMPv3 Working Group        Expires April 1998                 [Page 71]
  4189.  
  4190. Internet Draft     User-based Security Model for SNMPv3      28 Oct 1997
  4191.  
  4192.  
  4193.  
  4194.      Changing a secret after each use is generally regarded as the
  4195.      most secure practice, but a significant amount of overhead may
  4196.      be associated with that approach.
  4197.  
  4198.      Note, too, in a local environment the threat of disclosure may be
  4199.      less significant, and as such the changing of secrets may be less
  4200.      frequent.  However, when public data networks are used as the
  4201.      communication paths, more caution is prudent.
  4202.  
  4203. 11.2  Defining Users                                                      |
  4204.  
  4205.    The mechanisms defined in this document employ the notion of users
  4206.    on whose behalf messages are sent.  How "users" are defined is
  4207.    subject to the security policy of the network administration.
  4208.    For example, users could be individuals (e.g., "joe" or "jane"),
  4209.    or a particular role (e.g., "operator" or "administrator"), or a
  4210.    combination (e.g., "joe-operator", "jane-operator" or "joe-admin").
  4211.    Furthermore, a user may be a logical entity, such as an SNMP
  4212.    Application or a set of SNMP Applications, acting on behalf of an
  4213.    individual or role, or set of individuals, or set of roles,
  4214.    including combinations.
  4215.  
  4216.    Appendix A describes an algorithm for mapping a user "password" to
  4217.    a 16 octet value for use as either a user's authentication key or
  4218.    privacy key (or both).  Note however, that using the same password
  4219.    (and therefore the same key) for both authentication and privacy
  4220.    is very poor security practice and should be strongly discouraged.
  4221.    Passwords are often generated, remembered, and input by a human.
  4222.    Human-generated passwords may be less than the 16 octets required
  4223.    by the authentication and privacy protocols, and brute force
  4224.    attacks can be quite easy on a relatively short ASCII character
  4225.    set.  Therefore, the algorithm is Appendix A performs a
  4226.    transformation on the password.  If the Appendix A algorithm is
  4227.    used, SNMP implementations (and SNMP configuration applications)
  4228.    must ensure that passwords are at least 8 characters in length.
  4229.  
  4230.    Because the Appendix A algorithm uses such passwords (nearly)
  4231.    directly, it is very important that they not be easily guessed.
  4232.    It is suggested that they be composed of mixed-case alphanumeric
  4233.    and punctuation characters that don't form words or phrases that
  4234.    might be found in a dictionary.  Longer passwords improve the
  4235.    security of the system.  Users may wish to input multiword
  4236.    phrases to make their password string longer while ensuring that
  4237.    it is memorable.
  4238.  
  4239.    Since it is infeasible for human users to maintain different
  4240.    passwords for every SNMP engine, but security requirements
  4241.    strongly discourage having the same key for more than one SNMP
  4242.    engine, the User-based Security Model employs a compromise
  4243.    proposed in [Localized-key].  It derives the user keys for the
  4244.  
  4245.  
  4246.  
  4247. SNMPv3 Working Group        Expires April 1998                 [Page 72]
  4248.  
  4249. Internet Draft     User-based Security Model for SNMPv3      28 Oct 1997
  4250.  
  4251.  
  4252.    SNMP engines from user's password in such a way that it is
  4253.    practically impossible to either determine the user's password,
  4254.    or user's key for another SNMP engine from any combination of
  4255.    user's keys on SNMP engines.
  4256.  
  4257.    Note however, that if user's password is disclosed, then key
  4258.    localization will not help and network security may be compromised     3
  4259.    in this case. Therefore a user's password or non-localized key         3
  4260.    MUST NOT be stored on a managed device/node. Instead the               4
  4261.    localized key SHALL be stored (if at all) , so that, in case a         4
  4262.    device does get compromised, no other managed or managing devices      4
  4263.    get compromised.                                                       3
  4264.  
  4265. 11.3.  Conformance                                                        |
  4266.  
  4267.    To be termed a "Secure SNMP implementation" based on the
  4268.    User-based Security Model, an SNMP implementation MUST:
  4269.  
  4270.    - implement one or more Authentication Protocol(s). The HMAC-MD5-96    |
  4271.      and HMAC-SHA-96 Authentication Protocols defined in this memo are    |
  4272.      examples of such protocols.                                          |
  4273.  
  4274.    - to the maximum extent possible, prohibit access to the secret(s)     |
  4275.      of each user about which it maintains information in a Local         |
  4276.      Configuration Datastore (LCD) under all circumstances except as      |
  4277.      required to generate and/or validate SNMP messages with respect      |
  4278.      to that user.                                                        |
  4279.  
  4280.    - implement the key-localization mechanism.
  4281.  
  4282.    - implement the SNMP-USER-BASED-SM-MIB.                                |
  4283.  
  4284.    In addition, an authoritative SNMP engine SHOULD provide initial       |
  4285.    configuration in accordance with Appendix A.1.                         |
  4286.  
  4287.    Implementation of a Privacy Protocol (the DES Symmetric Encryption
  4288.    Protocol defined in this memo is one such protocol) is optional.
  4289.  
  4290. 12.  References                                                           |
  4291.  
  4292. [RFC1903] The SNMPv2 Working Group, Case, J., McCloghrie, K., Rose, M.,   |
  4293.     and S. Waldbusser, "Textual Conventions for Version 2 of the Simple   |
  4294.     Network Management Protocol (SNMPv2)", RFC 1903, January 1996.        |
  4295.                                                                           |
  4296. [RFC1905] The SNMPv2 Working Group, Case, J., McCloghrie, K.,
  4297.      Rose, M., and S., Waldbusser, "Protocol Operations for
  4298.      Version 2 of the Simple Network Management Protocol (SNMPv2)",
  4299.      RFC 1905, January 1996.
  4300.  
  4301. [RFC1906] The SNMPv2 Working Group, Case, J., McCloghrie, K.,
  4302.      Rose, M., and S. Waldbusser, "Transport Mappings for
  4303.  
  4304.  
  4305.  
  4306. SNMPv3 Working Group        Expires April 1998                 [Page 73]
  4307.  
  4308. Internet Draft     User-based Security Model for SNMPv3      28 Oct 1997
  4309.  
  4310.  
  4311.      Version 2 of the Simple Network Management Protocol (SNMPv2)",
  4312.      RFC 1906, January 1996.
  4313.  
  4314. [RFC1907] The SNMPv2 Working Group, Case, J., McCloghrie, K.,
  4315.      Rose, M., and S. Waldbusser, "Management Information Base for
  4316.      Version 2 of the Simple Network Management Protocol (SNMPv2)",
  4317.      RFC 1907 January 1996.
  4318.  
  4319. [RFC2104] Network Working Group, H. Krawczyk, M. Bellare, R. Canetti,     |
  4320.      "HMAC: Keyed-Hashing for Message Authentication", RFC 2104,          |
  4321.      February 1997.                                                       |
  4322.  
  4323. [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate             4
  4324.      Requirement Levels", BCP 14, RFC 2119, March 1997.                   4
  4325.  
  4326. [BCP-11] Hovey, R., and S. Bradner, "The Organizations Involved in        5
  4327.      the IETF Standards Process", BCP 11, RFC 2028, October 1996.         5
  4328.  
  4329.  
  4330. [SNMP-ARCH] The SNMPv3 Working Group, Harrington, D., Wijnen, B.,         3
  4331.      Presuhn, R., "An Architecture for describing SNMP Management         3
  4332.      Frameworks", draft-ietf-snmpv3-next-gen-arch-06.txt,                 5
  4333.      October 1997.                                                        5
  4334.  
  4335. [SNMP-USM] The SNMPv3 Working Group, Blumenthal, U., Wijnen, B.,
  4336.      "The User-Based Security Model for Version 3 of the Simple
  4337.      Network Management Protocol (SNMPv3)",
  4338.      draft-ietf-snmpv3-usm-03.txt, October 1997.                          5
  4339.  
  4340. [Localized-Key] U. Blumenthal, N. C. Hien, B. Wijnen
  4341.      "Key Derivation for Network Management Applications"
  4342.      IEEE Network Magazine, April/May issue, 1997.
  4343.  
  4344. [MD5] Rivest, R.,  "Message Digest Algorithm MD5",
  4345.      RFC 1321, April 1992.
  4346.  
  4347. [DES-NIST] Data Encryption Standard, National Institute of Standards
  4348.      and Technology.  Federal Information Processing Standard (FIPS)
  4349.      Publication 46-1.  Supersedes FIPS Publication 46, (January, 1977;
  4350.      reaffirmed January, 1988).
  4351.  
  4352. [DES-ANSI] Data Encryption Algorithm, American National Standards
  4353.      Institute.  ANSI X3.92-1981, (December, 1980).
  4354.  
  4355. [DESO-NIST] DES Modes of Operation, National Institute of Standards and
  4356.      Technology.  Federal Information Processing Standard (FIPS)
  4357.      Publication 81, (December, 1980).
  4358.  
  4359. [DESO-ANSI] Data Encryption Algorithm - Modes of Operation, American
  4360.      National Standards Institute.  ANSI X3.106-1983, (May 1983).
  4361.  
  4362.  
  4363.  
  4364.  
  4365. SNMPv3 Working Group        Expires April 1998                 [Page 74]
  4366.  
  4367. Internet Draft     User-based Security Model for SNMPv3      28 Oct 1997
  4368.  
  4369.  
  4370. [DESG-NIST] Guidelines for Implementing and Using the NBS Data
  4371.      Encryption Standard, National Institute of Standards and
  4372.      Technology.  Federal Information Processing Standard (FIPS)
  4373.      Publication 74, (April, 1981).
  4374.  
  4375. [DEST-NIST] Validating the Correctness of Hardware Implementations of
  4376.      the NBS Data Encryption Standard, National Institute of Standards
  4377.      and Technology.  Special Publication 500-20.
  4378.  
  4379. [DESM-NIST] Maintenance Testing for the Data Encryption Standard,
  4380.      National Institute of Standards and Technology.
  4381.      Special Publication 500-61, (August, 1980).
  4382.  
  4383. [SHA-NIST] Secure Hash Algorithm. NIST FIPS 180-1, (April, 1995)          4
  4384.      http://csrc.nist.gov/fips/fip180-1.txt (ASCII)                       4
  4385.      http://csrc.nist.gov/fips/fip180-1.ps  (Postscript)                  4
  4386.  
  4387. 13.  Editors' Addresses                                                   5
  4388.  
  4389.    Co-editor   Uri Blumenthal
  4390.                IBM T. J. Watson Research
  4391.    postal:     30 Saw Mill River Pkwy,
  4392.                Hawthorne, NY 10532
  4393.                USA
  4394.    email:      uri@watson.ibm.com
  4395.    phone:      +1-914-784-7064
  4396.  
  4397.    Co-editor:  Bert Wijnen
  4398.                IBM T. J. Watson Research
  4399.    postal:     Schagen 33
  4400.                3461 GL Linschoten
  4401.                Netherlands
  4402.    email:      wijnen@vnet.ibm.com
  4403.    phone:      +31-348-432-794
  4404.  
  4405.  
  4406.  
  4407.  
  4408.  
  4409.  
  4410.  
  4411.  
  4412.  
  4413.  
  4414.  
  4415.  
  4416.  
  4417.  
  4418.  
  4419.  
  4420.  
  4421.  
  4422.  
  4423.  
  4424. SNMPv3 Working Group        Expires April 1998                 [Page 75]
  4425.  
  4426. Internet Draft     User-based Security Model for SNMPv3      28 Oct 1997
  4427.  
  4428.  
  4429. APPENDIX A - Installation
  4430.  
  4431. A.1.  SNMP engine Installation Parameters
  4432.  
  4433. During installation, an authoritative SNMP engine SHOULD (in the
  4434. meaning as defined in [RFC2119]) be configured with several initial
  4435. parameters.  These include:
  4436.  
  4437. 1) A security posture
  4438.  
  4439.    The choice of security posture determines if initial configuration
  4440.    is implemented and if so how.  One of three possible choices
  4441.    is selected:
  4442.  
  4443.          minimum-secure,
  4444.          semi-secure,
  4445.          very-secure (i.e., no-initial-configuration)
  4446.  
  4447.    In the case of a very-secure posture, there is no initial
  4448.    configuration, and so the following steps are irrelevant.
  4449.  
  4450. 2) one or more secrets
  4451.  
  4452.    These are the authentication/privacy secrets for the first user
  4453.    to be configured.
  4454.  
  4455.    One way to accomplish this is to have the installer enter a
  4456.    "password" for each required secret. The password is then
  4457.    algorithmically converted into the required secret by:
  4458.  
  4459.    - forming a string of length 1,048,576 octets by repeating the
  4460.      value of the password as often as necessary, truncating
  4461.      accordingly, and using the resulting string as the input to
  4462.      the MD5 algorithm [MD5].  The resulting digest, termed
  4463.      "digest1", is used in the next step.
  4464.  
  4465.    - a second string is formed by concatenating digest1, the SNMP
  4466.      engine's snmpEngineID value, and digest1.
  4467.      This string is used as input to the MD5 algorithm [MD5].
  4468.  
  4469.      The resulting digest is the required secret (see Appendix A.2).
  4470.  
  4471.  
  4472.  
  4473.  
  4474.  
  4475.  
  4476.  
  4477.  
  4478.  
  4479.  
  4480.  
  4481.  
  4482.  
  4483. SNMPv3 Working Group        Expires April 1998                 [Page 76]
  4484.  
  4485. Internet Draft     User-based Security Model for SNMPv3      28 Oct 1997
  4486.  
  4487.  
  4488.    With these configured parameters, the SNMP engine instantiates
  4489.    the following usmUserEntry in the usmUserTable:
  4490.  
  4491.                            no privacy support     privacy support
  4492.                            ------------------     ---------------
  4493.    usmUserEngineID         localEngineID          localEngineID
  4494.    usmUserName             "initial"              "initial"
  4495.    usmUserSecurityName     "initial"              "initial"
  4496.    usmUserCloneFrom        ZeroDotZero            ZeroDotZero
  4497.    usmUserAuthProtocol     usmHMACMD5AuthProtocol usmHMACMD5AuthProtocol  |
  4498.    usmUserAuthKeyChange    ""                     ""
  4499.    usmUserOwnAuthKeyChange ""                     ""
  4500.    usmUserPrivProtocol     none                   usmDESPrivProtocol
  4501.    usmUserPrivKeyChange    ""                     ""
  4502.    usmUserOwnPrivKeyChange ""                     ""
  4503.    usmUserPublic           ""                     ""
  4504.    usmUserStorageType      anyValidStorageType    anyValidStorageType
  4505.    usmUserStatus           active                 active
  4506.  
  4507.  
  4508. A.2.  Password to Key Algorithm
  4509.  
  4510.    A sample code fragment (section A.2.1) demonstrates the password to    3
  4511.    key algorithm which can be used when mapping a password to an          3
  4512.    authentication or privacy key using MD5. The reference source code     4
  4513.    of MD5 is available in [RFC1321].                                      4
  4514.                                                                           3
  4515.    Another sample code fragment (section A.2.2) demonstrates the          3
  4516.    password to key algorithm which can be used when mapping a password    3
  4517.    to an authentication or privacy key using SHA (documented in           4
  4518.    SHA-NIST).                                                             4
  4519.  
  4520.    An example of the results of a correct implementation is provided
  4521.    (section A.3) which an implementor can use to check if his             3
  4522.    implementation produces the same result.
  4523.  
  4524.  
  4525.  
  4526.  
  4527.  
  4528.  
  4529.  
  4530.  
  4531.  
  4532.  
  4533.  
  4534.  
  4535.  
  4536.  
  4537.  
  4538.  
  4539.  
  4540.  
  4541.  
  4542. SNMPv3 Working Group        Expires April 1998                 [Page 77]
  4543.  
  4544. Internet Draft     User-based Security Model for SNMPv3      28 Oct 1997
  4545.  
  4546.  
  4547. A.2.1.  Password to Key Sample Code for MD5                               3
  4548.  
  4549. void password_to_key_md5(                                                 3
  4550.    u_char *password,    /* IN */
  4551.    u_int   passwordlen, /* IN */
  4552.    u_char *engineID,    /* IN  - pointer to snmpEngineID  */
  4553.    u_int   engineLength /* IN  - length of snmpEngineID */
  4554.    u_char *key)         /* OUT - pointer to caller 16-octet buffer */
  4555. {
  4556.    MD5_CTX     MD;
  4557.    u_char     *cp, password_buf[64];
  4558.    u_long      password_index = 0;
  4559.    u_long      count = 0, i;
  4560.  
  4561.    MD5Init (&MD);   /* initialize MD5 */
  4562.  
  4563.    /**********************************************/
  4564.    /* Use while loop until we've done 1 Megabyte */
  4565.    /**********************************************/
  4566.    while (count < 1048576) {
  4567.       cp = password_buf;
  4568.       for (i = 0; i < 64; i++) {
  4569.           /*************************************************/
  4570.           /* Take the next octet of the password, wrapping */
  4571.           /* to the beginning of the password as necessary.*/
  4572.           /*************************************************/
  4573.           *cp++ = password[password_index++ % passwordlen];
  4574.       }
  4575.       MD5Update (&MD, password_buf, 64);
  4576.       count += 64;
  4577.    }
  4578.    MD5Final (key, &MD);          /* tell MD5 we're done */
  4579.  
  4580.    /*****************************************************/
  4581.    /* Now localize the key with the engineID and pass   */
  4582.    /* through MD5 to produce final key                  */
  4583.    /* May want to ensure that engineLength <= 32,       */
  4584.    /* otherwise need to use a buffer larger than 64     */
  4585.    /*****************************************************/
  4586.    memcpy(password_buf, key, 16);
  4587.    memcpy(password_buf+16, engineID, engineLength);
  4588.    memcpy(password_buf+engineLength, key, 16);
  4589.  
  4590.    MD5Init(&MD);
  4591.    MD5Update(&MD, password_buf, 32+engineLength);
  4592.    MD5Final(key, &MD);
  4593.  
  4594.    return;
  4595. }
  4596.  
  4597.  
  4598.  
  4599.  
  4600.  
  4601. SNMPv3 Working Group        Expires April 1998                 [Page 78]
  4602.  
  4603. Internet Draft     User-based Security Model for SNMPv3      28 Oct 1997
  4604.  
  4605.  
  4606. A.2.2.  Password to Key Sample Code for SHA                               3
  4607.                                                                           3
  4608. void password_to_key_sha(                                                 3
  4609.    u_char *password,    /* IN */                                          3
  4610.    u_int   passwordlen, /* IN */                                          3
  4611.    u_char *engineID,    /* IN  - pointer to snmpEngineID  */              3
  4612.    u_int   engineLength /* IN  - length of snmpEngineID */                3
  4613.    u_char *key)         /* OUT - pointer to caller 20-octet buffer */     3
  4614. {                                                                         3
  4615.    SHA_CTX     SH;                                                        4
  4616.    u_char     *cp, password_buf[72];                                      3
  4617.    u_long      password_index = 0;                                        3
  4618.    u_long      count = 0, i;                                              3
  4619.                                                                           3
  4620.    SHAInit (&SH);   /* initialize SHA */                                  4
  4621.                                                                           3
  4622.    /**********************************************/                       3
  4623.    /* Use while loop until we've done 1 Megabyte */                       3
  4624.    /**********************************************/                       3
  4625.    while (count < 1048576) {                                              3
  4626.       cp = password_buf;                                                  3
  4627.       for (i = 0; i < 64; i++) {                                          3
  4628.           /*************************************************/             3
  4629.           /* Take the next octet of the password, wrapping */             3
  4630.           /* to the beginning of the password as necessary.*/             3
  4631.           /*************************************************/             3
  4632.           *cp++ = password[password_index++ % passwordlen];               3
  4633.       }                                                                   3
  4634.       SHAUpdate (&SH, password_buf, 64);                                  4
  4635.       count += 64;                                                        3
  4636.    }                                                                      3
  4637.    SHAFinal (key, &SH);          /* tell SHA we're done */                4
  4638.                                                                           3
  4639.    /*****************************************************/                3
  4640.    /* Now localize the key with the engineID and pass   */                3
  4641.    /* through SHA to produce final key                  */                3
  4642.    /* May want to ensure that engineLength <= 32,       */                3
  4643.    /* otherwise need to use a buffer larger than 72     */                3
  4644.    /*****************************************************/                3
  4645.    memcpy(password_buf, key, 20);                                         3
  4646.    memcpy(password_buf+20, engineID, engineLength);                       3
  4647.    memcpy(password_buf+engineLength, key, 20);                            3
  4648.                                                                           3
  4649.    SHAInit(&SH);                                                          4
  4650.    SHAUpdate(&SH, password_buf, 40+engineLength);                         4
  4651.    SHAFinal(key, &SH);                                                    4
  4652.                                                                           3
  4653.    return;                                                                3
  4654. }                                                                         3
  4655.  
  4656.  
  4657.  
  4658.  
  4659.  
  4660. SNMPv3 Working Group        Expires April 1998                 [Page 79]
  4661.  
  4662. Internet Draft     User-based Security Model for SNMPv3      28 Oct 1997
  4663.  
  4664.  
  4665. A.3.  Password to Key Sample Results
  4666.  
  4667. A.3.1.  Password to Key Sample Results using MD5                          3
  4668.  
  4669.    The following shows a sample output of the password to key
  4670.    algorithm for a 16-octet key using MD5.                                3
  4671.  
  4672.    With a password of "maplesyrup" the output of the password to key
  4673.    algorithm before the key is localized with the SNMP engine's
  4674.    snmpEngineID is:
  4675.  
  4676.       '9f af 32 83 88 4e 92 83 4e bc 98 47 d8 ed d9 63'H
  4677.  
  4678.    After the intermediate key (shown above) is localized with the
  4679.    snmpEngineID value of:
  4680.  
  4681.       '00 00 00 00 00 00 00 00 00 00 00 02'H
  4682.  
  4683.    the final output of the password to key algorithm is:
  4684.  
  4685.       '52 6f 5e ed 9f cc e2 6f 89 64 c2 93 07 87 d8 2b'H
  4686.  
  4687.  
  4688. A.3.2.  Password to Key Sample Results using SHA                          3
  4689.                                                                           3
  4690.    The following shows a sample output of the password to key             3
  4691.    algorithm for a 20-octet key using SHA.                                4
  4692.                                                                           3
  4693.    With a password of "maplesyrup" the output of the password to key      3
  4694.    algorithm before the key is localized with the SNMP engine's           3
  4695.    snmpEngineID is:                                                       3
  4696.                                                                           3
  4697.       'f1 be a9 ae 66 7f 4f b6 34 1e 51 af 06 80 7e 91 e4 3b 01 ac'H      4
  4698.                                                                           3
  4699.    After the intermediate key (shown above) is localized with the         3
  4700.    snmpEngineID value of:                                                 3
  4701.                                                                           3
  4702.       '00 00 00 00 00 00 00 00 00 00 00 02'H                              3
  4703.                                                                           3
  4704.    the final output of the password to key algorithm is:                  3
  4705.                                                                           3
  4706.       '8a a3 d9 9e 3e 30 56 f2 bf e3 a9 ee f3 45 d5 39 54 91 12 be'H      4
  4707.                                                                           3
  4708.  
  4709.  
  4710.  
  4711.  
  4712.  
  4713.  
  4714.  
  4715.  
  4716.  
  4717.  
  4718.  
  4719. SNMPv3 Working Group        Expires April 1998                 [Page 80]
  4720.  
  4721. Internet Draft     User-based Security Model for SNMPv3      28 Oct 1997
  4722.  
  4723.  
  4724. A.4.  Sample encoding of msgSecurityParameters
  4725.  
  4726.    The msgSecurityParameters in an SNMP message are represented as
  4727.    an OCTET STRING. This OCTET STRING should be considered opaque
  4728.    outside a specific Security Model.
  4729.  
  4730.    The User-based Security Model defines the contents of the OCTET
  4731.    STRING as a SEQUENCE (see section 2.4).
  4732.  
  4733.    Given these two properties, the following is an example of the
  4734.    msgSecurityParameters for the User-based Security Model, encoded
  4735.    as an OCTET STRING:
  4736.  
  4737.      04 <length>
  4738.      30 <length>
  4739.      04 <length> <msgAuthoritativeEngineID>
  4740.      02 <length> <msgAuthoritativeEngineBoots>
  4741.      02 <length> <msgAuthoritativeEngineTime>
  4742.      04 <length> <msgUserName>
  4743.      04 0c       <HMAC-MD5-96-digest>                                     |
  4744.      04 08       <salt>
  4745.  
  4746.    Here is the example once more, but now with real values (except
  4747.    for the digest in msgAuthenticationParameters and the salt in
  4748.    msgPrivacyParameters, which depend on variable data that we have
  4749.    not defined here):
  4750.  
  4751.      Hex Data                         Description
  4752.      --------------  -----------------------------------------------
  4753.      04 39           OCTET STRING,                  length 57
  4754.      30 37           SEQUENCE,                      length 55
  4755.      04 0c 80000002  msgAuthoritativeEngineID:      IBM                   |
  4756.            01                                       IPv4 address          |
  4757.            09840301                                 9.132.3.1
  4758.      02 01 01        msgAuthoritativeEngineBoots:   1
  4759.      02 02 0101      msgAuthoritativeEngineTime:    257
  4760.      04 04 62657274  msgUserName:                   bert
  4761.      04 0c 01234567  msgAuthenticationParameters:   sample value          |
  4762.            89abcdef
  4763.            fedcba98
  4764.      04 08 01234567  msgPrivacyParameters:          sample value
  4765.            89abcdef
  4766.  
  4767. B.  Full Copyright Statement                                              5
  4768.                                                                           5
  4769.    Copyright (C) The Internet Society (1997).  All Rights Reserved.       5
  4770.                                                                           5
  4771.    This document and translations of it may be copied and furnished to    5
  4772.    others, and derivative works that comment on or otherwise explain it   5
  4773.    or assist in its implementation may be prepared, copied, published     5
  4774.    and distributed, in whole or in part, without restriction of any       5
  4775.  
  4776.  
  4777.  
  4778. SNMPv3 Working Group        Expires April 1998                 [Page 81]
  4779.  
  4780. Internet Draft     User-based Security Model for SNMPv3      28 Oct 1997
  4781.  
  4782.  
  4783.    kind, provided that the above copyright notice and this paragraph      5
  4784.    are included on all such copies and derivative works.  However, this   5
  4785.    document itself may not be modified in any way, such as by removing    5
  4786.    the copyright notice or references to the Internet Society or other    5
  4787.    Internet organizations, except as needed for the purpose of            5
  4788.    developing Internet standards in which case the procedures for         5
  4789.    copyrights defined in the Internet Standards process must be           5
  4790.    followed, or as required to translate it into languages other than     5
  4791.    English.                                                               5
  4792.                                                                           5
  4793.    The limited permissions granted above are perpetual and will not be    5
  4794.    revoked by the Internet Society or its successors or assigns.          5
  4795.                                                                           5
  4796.    This document and the information contained herein is provided on an   5
  4797.    "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING    5
  4798.    TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING     5
  4799.    BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION        5
  4800.    HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF       5
  4801.    MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.                   5
  4802.  
  4803.  
  4804.  
  4805.  
  4806.  
  4807.  
  4808.  
  4809.  
  4810.  
  4811.  
  4812.  
  4813.  
  4814.  
  4815.  
  4816.  
  4817.  
  4818.  
  4819.  
  4820.  
  4821.  
  4822.  
  4823.  
  4824.  
  4825.  
  4826.  
  4827.  
  4828.  
  4829.  
  4830.  
  4831.  
  4832.  
  4833.  
  4834.  
  4835.  
  4836.  
  4837. SNMPv3 Working Group        Expires April 1998                 [Page 82]
  4838.  
  4839.