userapps/opensource/net-snmp/mibs/SNMP-USER-BASED-SM-MIB.txt

   1 SNMP-USER-BASED-SM-MIB DEFINITIONS ::= BEGIN
   2
   3 IMPORTS
   4     MODULE-IDENTITY, OBJECT-TYPE,
   5     OBJECT-IDENTITY,
   6     snmpModules, Counter32                FROM SNMPv2-SMI
   7     TEXTUAL-CONVENTION, TestAndIncr,
   8     RowStatus, RowPointer,
   9     StorageType, AutonomousType           FROM SNMPv2-TC
  10     MODULE-COMPLIANCE, OBJECT-GROUP       FROM SNMPv2-CONF
  11     SnmpAdminString, SnmpEngineID,
  12     snmpAuthProtocols, snmpPrivProtocols  FROM SNMP-FRAMEWORK-MIB;
  13
  14 snmpUsmMIB MODULE-IDENTITY
  15     LAST-UPDATED "200210160000Z"            -- 16 Oct 2002, midnight
  16     ORGANIZATION "SNMPv3 Working Group"
  17     CONTACT-INFO "WG-email:   snmpv3@lists.tislabs.com
  18                   Subscribe:  majordomo@lists.tislabs.com
  19                               In msg body:  subscribe snmpv3
  20
  21                   Chair:      Russ Mundy
  22                               Network Associates Laboratories
  23                   postal:     15204 Omega Drive, Suite 300
  24                               Rockville, MD 20850-4601
  25                               USA
  26                   email:      mundy@tislabs.com
  27
  28                   phone:      +1 301-947-7107
  29
  30                   Co-Chair:   David Harrington
  31                               Enterasys Networks
  32                   Postal:     35 Industrial Way
  33                               P. O. Box 5004
  34                               Rochester, New Hampshire 03866-5005
  35                               USA
  36                   EMail:      dbh@enterasys.com
  37                   Phone:      +1 603-337-2614
  38
  39                   Co-editor   Uri Blumenthal
  40                               Lucent Technologies
  41                   postal:     67 Whippany Rd.
  42                               Whippany, NJ 07981
  43                               USA
  44                   email:      uri@lucent.com
  45                   phone:      +1-973-386-2163
  46
  47                   Co-editor:  Bert Wijnen
  48                               Lucent Technologies
  49                   postal:     Schagen 33
  50                               3461 GL Linschoten
  51                               Netherlands
  52                   email:      bwijnen@lucent.com
  53                   phone:      +31-348-480-685
  54                  "
  55     DESCRIPTION  "The management information definitions for the
  56                   SNMP User-based Security Model.
  57
  58                   Copyright (C) The Internet Society (2002). This
  59                   version of this MIB module is part of RFC 3414;
  60                   see the RFC itself for full legal notices.
  61                  "
  62 --  Revision history
  63
  64     REVISION     "200210160000Z"          -- 16 Oct 2002, midnight
  65     DESCRIPTION  "Changes in this revision:
  66                   - Updated references and contact info.
  67                   - Clarification to usmUserCloneFrom DESCRIPTION
  68                     clause
  69                   - Fixed 'command responder' into 'command generator'
  70                     in last para of DESCRIPTION clause of
  71                     usmUserTable.
  72                   This revision published as RFC3414.
  73                  "
  74     REVISION     "199901200000Z"          -- 20 Jan 1999, midnight
  75     DESCRIPTION  "Clarifications, published as RFC2574"
  76
  77     REVISION     "199711200000Z"          -- 20 Nov 1997, midnight
  78     DESCRIPTION  "Initial version, published as RFC2274"
  79     ::= { snmpModules 15 }
  80
  81 -- Administrative assignments ****************************************
  82
  83 usmMIBObjects     OBJECT IDENTIFIER ::= { snmpUsmMIB 1 }
  84 usmMIBConformance OBJECT IDENTIFIER ::= { snmpUsmMIB 2 }
  85
  86 -- Identification of Authentication and Privacy Protocols ************
  87
  88 usmNoAuthProtocol OBJECT-IDENTITY
  89     STATUS        current
  90     DESCRIPTION  "No Authentication Protocol."
  91     ::= { snmpAuthProtocols 1 }
  92
  93 usmHMACMD5AuthProtocol OBJECT-IDENTITY
  94     STATUS        current
  95     DESCRIPTION  "The HMAC-MD5-96 Digest Authentication Protocol."
  96     REFERENCE    "- H. Krawczyk, M. Bellare, R. Canetti HMAC:
  97                     Keyed-Hashing for Message Authentication,
  98                     RFC2104, Feb 1997.
  99                   - Rivest, R., Message Digest Algorithm MD5, RFC1321.
 100                  "
 101     ::= { snmpAuthProtocols 2 }
 102
 103 usmHMACSHAAuthProtocol OBJECT-IDENTITY
 104     STATUS        current
 105     DESCRIPTION  "The HMAC-SHA-96 Digest Authentication Protocol."
 106     REFERENCE    "- H. Krawczyk, M. Bellare, R. Canetti, HMAC:
 107                     Keyed-Hashing for Message Authentication,
 108                     RFC2104, Feb 1997.
 109                   - Secure Hash Algorithm. NIST FIPS 180-1.
 110                  "
 111     ::= { snmpAuthProtocols 3 }
 112
 113 usmNoPrivProtocol OBJECT-IDENTITY
 114     STATUS        current
 115     DESCRIPTION  "No Privacy Protocol."
 116     ::= { snmpPrivProtocols 1 }
 117
 118 usmDESPrivProtocol OBJECT-IDENTITY
 119     STATUS        current
 120     DESCRIPTION  "The CBC-DES Symmetric Encryption Protocol."
 121     REFERENCE    "- Data Encryption Standard, National Institute of
 122                     Standards and Technology.  Federal Information
 123                     Processing Standard (FIPS) Publication 46-1.
 124
 125                     Supersedes FIPS Publication 46,
 126                     (January, 1977; reaffirmed January, 1988).
 127
 128                   - Data Encryption Algorithm, American National
 129                     Standards Institute.  ANSI X3.92-1981,
 130                     (December, 1980).
 131
 132                   - DES Modes of Operation, National Institute of
 133                     Standards and Technology.  Federal Information
 134                     Processing Standard (FIPS) Publication 81,
 135                     (December, 1980).
 136
 137                   - Data Encryption Algorithm - Modes of Operation,
 138                     American National Standards Institute.
 139                     ANSI X3.106-1983, (May 1983).
 140                  "
 141     ::= { snmpPrivProtocols 2 }
 142
 143 -- Textual Conventions ***********************************************
 144
 145 KeyChange ::=     TEXTUAL-CONVENTION
 146    STATUS         current
 147    DESCRIPTION
 148          "Every definition of an object with this syntax must identify
 149           a protocol P, a secret key K, and a hash algorithm H
 150           that produces output of L octets.
 151
 152           The object's value is a manager-generated, partially-random
 153           value which, when modified, causes the value of the secret
 154           key K, to be modified via a one-way function.
 155
 156           The value of an instance of this object is the concatenation
 157           of two components: first a 'random' component and then a
 158           'delta' component.
 159
 160           The lengths of the random and delta components
 161           are given by the corresponding value of the protocol P;
 162           if P requires K to be a fixed length, the length of both the
 163           random and delta components is that fixed length; if P
 164           allows the length of K to be variable up to a particular
 165           maximum length, the length of the random component is that
 166           maximum length and the length of the delta component is any
 167           length less than or equal to that maximum length.
 168           For example, usmHMACMD5AuthProtocol requires K to be a fixed
 169           length of 16 octets and L - of 16 octets.
 170           usmHMACSHAAuthProtocol requires K to be a fixed length of
 171           20 octets and L - of 20 octets. Other protocols may define
 172           other sizes, as deemed appropriate.
 173
 174           When a requester wants to change the old key K to a new
 175           key keyNew on a remote entity, the 'random' component is
 176           obtained from either a true random generator, or from a
 177           pseudorandom generator, and the 'delta' component is
 178           computed as follows:
 179
 180            - a temporary variable is initialized to the existing value
 181              of K;
 182            - if the length of the keyNew is greater than L octets,
 183              then:
 184               - the random component is appended to the value of the
 185                 temporary variable, and the result is input to the
 186                 the hash algorithm H to produce a digest value, and
 187                 the temporary variable is set to this digest value;
 188               - the value of the temporary variable is XOR-ed with
 189                 the first (next) L-octets (16 octets in case of MD5)
 190                 of the keyNew to produce the first (next) L-octets
 191                 (16 octets in case of MD5) of the 'delta' component.
 192               - the above two steps are repeated until the unused
 193                 portion of the keyNew component is L octets or less,
 194            - the random component is appended to the value of the
 195              temporary variable, and the result is input to the
 196              hash algorithm H to produce a digest value;
 197            - this digest value, truncated if necessary to be the same
 198              length as the unused portion of the keyNew, is XOR-ed
 199              with the unused portion of the keyNew to produce the
 200              (final portion of the) 'delta' component.
 201
 202            For example, using MD5 as the hash algorithm H:
 203
 204               iterations = (lenOfDelta - 1)/16; /* integer division */
 205               temp = keyOld;
 206               for (i = 0; i < iterations; i++) {
 207                   temp = MD5 (temp || random);
 208                   delta[i*16 .. (i*16)+15] =
 209                          temp XOR keyNew[i*16 .. (i*16)+15];
 210               }
 211               temp = MD5 (temp || random);
 212               delta[i*16 .. lenOfDelta-1] =
 213                      temp XOR keyNew[i*16 .. lenOfDelta-1];
 214
 215           The 'random' and 'delta' components are then concatenated as
 216           described above, and the resulting octet string is sent to
 217           the recipient as the new value of an instance of this object.
 218
 219           At the receiver side, when an instance of this object is set
 220           to a new value, then a new value of K is computed as follows:
 221
 222            - a temporary variable is initialized to the existing value
 223              of K;
 224            - if the length of the delta component is greater than L
 225              octets, then:
 226               - the random component is appended to the value of the
 227                 temporary variable, and the result is input to the
 228                 hash algorithm H to produce a digest value, and the
 229                 temporary variable is set to this digest value;
 230               - the value of the temporary variable is XOR-ed with
 231                 the first (next) L-octets (16 octets in case of MD5)
 232                 of the delta component to produce the first (next)
 233                 L-octets (16 octets in case of MD5) of the new value
 234                 of K.
 235               - the above two steps are repeated until the unused
 236                 portion of the delta component is L octets or less,
 237            - the random component is appended to the value of the
 238              temporary variable, and the result is input to the
 239              hash algorithm H to produce a digest value;
 240            - this digest value, truncated if necessary to be the same
 241              length as the unused portion of the delta component, is
 242              XOR-ed with the unused portion of the delta component to
 243              produce the (final portion of the) new value of K.
 244
 245            For example, using MD5 as the hash algorithm H:
 246
 247               iterations = (lenOfDelta - 1)/16; /* integer division */
 248               temp = keyOld;
 249               for (i = 0; i < iterations; i++) {
 250                   temp = MD5 (temp || random);
 251                   keyNew[i*16 .. (i*16)+15] =
 252                          temp XOR delta[i*16 .. (i*16)+15];
 253               }
 254               temp = MD5 (temp || random);
 255               keyNew[i*16 .. lenOfDelta-1] =
 256                      temp XOR delta[i*16 .. lenOfDelta-1];
 257
 258           The value of an object with this syntax, whenever it is
 259           retrieved by the management protocol, is always the zero
 260           length string.
 261
 262           Note that the keyOld and keyNew are the localized keys.
 263
 264           Note that it is probably wise that when an SNMP entity sends
 265           a SetRequest to change a key, that it keeps a copy of the old
 266           key until it has confirmed that the key change actually
 267           succeeded.
 268          "
 269     SYNTAX       OCTET STRING
 270
 271 -- Statistics for the User-based Security Model **********************
 272
 273 usmStats         OBJECT IDENTIFIER ::= { usmMIBObjects 1 }
 274
 275 usmStatsUnsupportedSecLevels OBJECT-TYPE
 276     SYNTAX       Counter32
 277     MAX-ACCESS   read-only
 278     STATUS       current
 279     DESCRIPTION "The total number of packets received by the SNMP
 280                  engine which were dropped because they requested a
 281                  securityLevel that was unknown to the SNMP engine
 282                  or otherwise unavailable.
 283                 "
 284     ::= { usmStats 1 }
 285
 286 usmStatsNotInTimeWindows OBJECT-TYPE
 287     SYNTAX       Counter32
 288     MAX-ACCESS   read-only
 289     STATUS       current
 290     DESCRIPTION "The total number of packets received by the SNMP
 291                  engine which were dropped because they appeared
 292                  outside of the authoritative SNMP engine's window.
 293                 "
 294     ::= { usmStats 2 }
 295
 296 usmStatsUnknownUserNames OBJECT-TYPE
 297     SYNTAX       Counter32
 298     MAX-ACCESS   read-only
 299     STATUS       current
 300     DESCRIPTION "The total number of packets received by the SNMP
 301                  engine which were dropped because they referenced a
 302                  user that was not known to the SNMP engine.
 303                 "
 304     ::= { usmStats 3 }
 305
 306 usmStatsUnknownEngineIDs OBJECT-TYPE
 307     SYNTAX       Counter32
 308     MAX-ACCESS   read-only
 309     STATUS       current
 310     DESCRIPTION "The total number of packets received by the SNMP
 311                  engine which were dropped because they referenced an
 312                  snmpEngineID that was not known to the SNMP engine.
 313                 "
 314     ::= { usmStats 4 }
 315
 316 usmStatsWrongDigests OBJECT-TYPE
 317     SYNTAX       Counter32
 318     MAX-ACCESS   read-only
 319     STATUS       current
 320     DESCRIPTION "The total number of packets received by the SNMP
 321                  engine which were dropped because they didn't
 322                  contain the expected digest value.
 323                 "
 324     ::= { usmStats 5 }
 325
 326 usmStatsDecryptionErrors OBJECT-TYPE
 327     SYNTAX       Counter32
 328     MAX-ACCESS   read-only
 329     STATUS       current
 330     DESCRIPTION "The total number of packets received by the SNMP
 331                  engine which were dropped because they could not be
 332                  decrypted.
 333                 "
 334     ::= { usmStats 6 }
 335
 336 -- The usmUser Group ************************************************
 337
 338 usmUser          OBJECT IDENTIFIER ::= { usmMIBObjects 2 }
 339
 340 usmUserSpinLock  OBJECT-TYPE
 341     SYNTAX       TestAndIncr
 342     MAX-ACCESS   read-write
 343     STATUS       current
 344     DESCRIPTION "An advisory lock used to allow several cooperating
 345                  Command Generator Applications to coordinate their
 346                  use of facilities to alter secrets in the
 347                  usmUserTable.
 348                 "
 349     ::= { usmUser 1 }
 350
 351 -- The table of valid users for the User-based Security Model ********
 352
 353 usmUserTable     OBJECT-TYPE
 354     SYNTAX       SEQUENCE OF UsmUserEntry
 355     MAX-ACCESS   not-accessible
 356     STATUS       current
 357     DESCRIPTION "The table of users configured in the SNMP engine's
 358                  Local Configuration Datastore (LCD).
 359
 360                  To create a new user (i.e., to instantiate a new
 361                  conceptual row in this table), it is recommended to
 362                  follow this procedure:
 363
 364                    1)  GET(usmUserSpinLock.0) and save in sValue.
 365
 366                    2)  SET(usmUserSpinLock.0=sValue,
 367                            usmUserCloneFrom=templateUser,
 368                            usmUserStatus=createAndWait)
 369                        You should use a template user to clone from
 370                        which has the proper auth/priv protocol defined.
 371
 372                  If the new user is to use privacy:
 373
 374                    3)  generate the keyChange value based on the secret
 375                        privKey of the clone-from user and the secret key
 376                        to be used for the new user. Let us call this
 377                        pkcValue.
 378                    4)  GET(usmUserSpinLock.0) and save in sValue.
 379                    5)  SET(usmUserSpinLock.0=sValue,
 380                            usmUserPrivKeyChange=pkcValue
 381                            usmUserPublic=randomValue1)
 382                    6)  GET(usmUserPulic) and check it has randomValue1.
 383                        If not, repeat steps 4-6.
 384
 385                  If the new user will never use privacy:
 386
 387                    7)  SET(usmUserPrivProtocol=usmNoPrivProtocol)
 388
 389                  If the new user is to use authentication:
 390
 391                    8)  generate the keyChange value based on the secret
 392                        authKey of the clone-from user and the secret key
 393                        to be used for the new user. Let us call this
 394                        akcValue.
 395                    9)  GET(usmUserSpinLock.0) and save in sValue.
 396                    10) SET(usmUserSpinLock.0=sValue,
 397                            usmUserAuthKeyChange=akcValue
 398                            usmUserPublic=randomValue2)
 399                    11) GET(usmUserPulic) and check it has randomValue2.
 400                        If not, repeat steps 9-11.
 401
 402                  If the new user will never use authentication:
 403
 404                    12) SET(usmUserAuthProtocol=usmNoAuthProtocol)
 405
 406                  Finally, activate the new user:
 407
 408                    13) SET(usmUserStatus=active)
 409
 410                  The new user should now be available and ready to be
 411                  used for SNMPv3 communication. Note however that access
 412                  to MIB data must be provided via configuration of the
 413                  SNMP-VIEW-BASED-ACM-MIB.
 414
 415                  The use of usmUserSpinlock is to avoid conflicts with
 416                  another SNMP command generator application which may
 417                  also be acting on the usmUserTable.
 418                 "
 419     ::= { usmUser 2 }
 420
 421 usmUserEntry     OBJECT-TYPE
 422     SYNTAX       UsmUserEntry
 423     MAX-ACCESS   not-accessible
 424     STATUS       current
 425     DESCRIPTION "A user configured in the SNMP engine's Local
 426                  Configuration Datastore (LCD) for the User-based
 427                  Security Model.
 428                 "
 429     INDEX       { usmUserEngineID,
 430                   usmUserName
 431                 }
 432     ::= { usmUserTable 1 }
 433
 434 UsmUserEntry ::= SEQUENCE
 435     {
 436         usmUserEngineID         SnmpEngineID,
 437         usmUserName             SnmpAdminString,
 438         usmUserSecurityName     SnmpAdminString,
 439         usmUserCloneFrom        RowPointer,
 440         usmUserAuthProtocol     AutonomousType,
 441         usmUserAuthKeyChange    KeyChange,
 442         usmUserOwnAuthKeyChange KeyChange,
 443         usmUserPrivProtocol     AutonomousType,
 444         usmUserPrivKeyChange    KeyChange,
 445         usmUserOwnPrivKeyChange KeyChange,
 446         usmUserPublic           OCTET STRING,
 447         usmUserStorageType      StorageType,
 448         usmUserStatus           RowStatus
 449     }
 450
 451 usmUserEngineID  OBJECT-TYPE
 452     SYNTAX       SnmpEngineID
 453     MAX-ACCESS   not-accessible
 454     STATUS       current
 455     DESCRIPTION "An SNMP engine's administratively-unique identifier.
 456
 457                  In a simple agent, this value is always that agent's
 458                  own snmpEngineID value.
 459
 460                  The value can also take the value of the snmpEngineID
 461                  of a remote SNMP engine with which this user can
 462                  communicate.
 463                 "
 464     ::= { usmUserEntry 1 }
 465
 466 usmUserName      OBJECT-TYPE
 467     SYNTAX       SnmpAdminString (SIZE(1..32))
 468     MAX-ACCESS   not-accessible
 469     STATUS       current
 470     DESCRIPTION "A human readable string representing the name of
 471                  the user.
 472
 473                  This is the (User-based Security) Model dependent
 474                  security ID.
 475                 "
 476     ::= { usmUserEntry 2 }
 477
 478 usmUserSecurityName OBJECT-TYPE
 479     SYNTAX       SnmpAdminString
 480     MAX-ACCESS   read-only
 481     STATUS       current
 482     DESCRIPTION "A human readable string representing the user in
 483                  Security Model independent format.
 484
 485                  The default transformation of the User-based Security
 486                  Model dependent security ID to the securityName and
 487                  vice versa is the identity function so that the
 488                  securityName is the same as the userName.
 489                 "
 490     ::= { usmUserEntry 3 }
 491
 492 usmUserCloneFrom OBJECT-TYPE
 493     SYNTAX       RowPointer
 494     MAX-ACCESS   read-create
 495     STATUS       current
 496     DESCRIPTION "A pointer to another conceptual row in this
 497                  usmUserTable.  The user in this other conceptual
 498                  row is called the clone-from user.
 499
 500                  When a new user is created (i.e., a new conceptual
 501                  row is instantiated in this table), the privacy and
 502                  authentication parameters of the new user must be
 503                  cloned from its clone-from user. These parameters are:
 504                    - authentication protocol (usmUserAuthProtocol)
 505                    - privacy protocol (usmUserPrivProtocol)
 506                  They will be copied regardless of what the current
 507                  value is.
 508
 509                  Cloning also causes the initial values of the secret
 510                  authentication key (authKey) and the secret encryption
 511
 512                  key (privKey) of the new user to be set to the same
 513                  values as the corresponding secrets of the clone-from
 514                  user to allow the KeyChange process to occur as
 515                  required during user creation.
 516
 517                  The first time an instance of this object is set by
 518                  a management operation (either at or after its
 519                  instantiation), the cloning process is invoked.
 520                  Subsequent writes are successful but invoke no
 521                  action to be taken by the receiver.
 522                  The cloning process fails with an 'inconsistentName'
 523                  error if the conceptual row representing the
 524                  clone-from user does not exist or is not in an active
 525                  state when the cloning process is invoked.
 526
 527                  When this object is read, the ZeroDotZero OID
 528                  is returned.
 529                 "
 530     ::= { usmUserEntry 4 }
 531
 532 usmUserAuthProtocol OBJECT-TYPE
 533     SYNTAX       AutonomousType
 534     MAX-ACCESS   read-create
 535     STATUS       current
 536     DESCRIPTION "An indication of whether messages sent on behalf of
 537                  this user to/from the SNMP engine identified by
 538                  usmUserEngineID, can be authenticated, and if so,
 539                  the type of authentication protocol which is used.
 540
 541                  An instance of this object is created concurrently
 542                  with the creation of any other object instance for
 543                  the same user (i.e., as part of the processing of
 544                  the set operation which creates the first object
 545                  instance in the same conceptual row).
 546
 547                  If an initial set operation (i.e. at row creation time)
 548                  tries to set a value for an unknown or unsupported
 549                  protocol, then a 'wrongValue' error must be returned.
 550
 551                  The value will be overwritten/set when a set operation
 552                  is performed on the corresponding instance of
 553                  usmUserCloneFrom.
 554
 555                  Once instantiated, the value of such an instance of
 556                  this object can only be changed via a set operation to
 557                  the value of the usmNoAuthProtocol.
 558
 559                  If a set operation tries to change the value of an
 560
 561                  existing instance of this object to any value other
 562                  than usmNoAuthProtocol, then an 'inconsistentValue'
 563                  error must be returned.
 564
 565                  If a set operation tries to set the value to the
 566                  usmNoAuthProtocol while the usmUserPrivProtocol value
 567                  in the same row is not equal to usmNoPrivProtocol,
 568                  then an 'inconsistentValue' error must be returned.
 569                  That means that an SNMP command generator application
 570                  must first ensure that the usmUserPrivProtocol is set
 571                  to the usmNoPrivProtocol value before it can set
 572                  the usmUserAuthProtocol value to usmNoAuthProtocol.
 573                 "
 574     DEFVAL      { usmNoAuthProtocol }
 575     ::= { usmUserEntry 5 }
 576
 577 usmUserAuthKeyChange OBJECT-TYPE
 578     SYNTAX       KeyChange   -- typically (SIZE (0 | 32)) for HMACMD5
 579                              -- typically (SIZE (0 | 40)) for HMACSHA
 580     MAX-ACCESS   read-create
 581     STATUS       current
 582     DESCRIPTION "An object, which when modified, causes the secret
 583                  authentication key used for messages sent on behalf
 584                  of this user to/from the SNMP engine identified by
 585                  usmUserEngineID, to be modified via a one-way
 586                  function.
 587
 588                  The associated protocol is the usmUserAuthProtocol.
 589                  The associated secret key is the user's secret
 590                  authentication key (authKey). The associated hash
 591                  algorithm is the algorithm used by the user's
 592                  usmUserAuthProtocol.
 593
 594                  When creating a new user, it is an 'inconsistentName'
 595                  error for a set operation to refer to this object
 596                  unless it is previously or concurrently initialized
 597                  through a set operation on the corresponding instance
 598                  of usmUserCloneFrom.
 599
 600                  When the value of the corresponding usmUserAuthProtocol
 601                  is usmNoAuthProtocol, then a set is successful, but
 602                  effectively is a no-op.
 603
 604                  When this object is read, the zero-length (empty)
 605                  string is returned.
 606
 607                  The recommended way to do a key change is as follows:
 608
 609                    1) GET(usmUserSpinLock.0) and save in sValue.
 610                    2) generate the keyChange value based on the old
 611                       (existing) secret key and the new secret key,
 612                       let us call this kcValue.
 613
 614                  If you do the key change on behalf of another user:
 615
 616                    3) SET(usmUserSpinLock.0=sValue,
 617                           usmUserAuthKeyChange=kcValue
 618                           usmUserPublic=randomValue)
 619
 620                  If you do the key change for yourself:
 621
 622                    4) SET(usmUserSpinLock.0=sValue,
 623                           usmUserOwnAuthKeyChange=kcValue
 624                           usmUserPublic=randomValue)
 625
 626                  If you get a response with error-status of noError,
 627                  then the SET succeeded and the new key is active.
 628                  If you do not get a response, then you can issue a
 629                  GET(usmUserPublic) and check if the value is equal
 630                  to the randomValue you did send in the SET. If so, then
 631                  the key change succeeded and the new key is active
 632                  (probably the response got lost). If not, then the SET
 633                  request probably never reached the target and so you
 634                  can start over with the procedure above.
 635                 "
 636     DEFVAL      { ''H }    -- the empty string
 637     ::= { usmUserEntry 6 }
 638
 639 usmUserOwnAuthKeyChange OBJECT-TYPE
 640     SYNTAX       KeyChange   -- typically (SIZE (0 | 32)) for HMACMD5
 641                              -- typically (SIZE (0 | 40)) for HMACSHA
 642     MAX-ACCESS   read-create
 643     STATUS       current
 644     DESCRIPTION "Behaves exactly as usmUserAuthKeyChange, with one
 645                  notable difference: in order for the set operation
 646                  to succeed, the usmUserName of the operation
 647                  requester must match the usmUserName that
 648                  indexes the row which is targeted by this
 649                  operation.
 650                  In addition, the USM security model must be
 651                  used for this operation.
 652
 653                  The idea here is that access to this column can be
 654                  public, since it will only allow a user to change
 655                  his own secret authentication key (authKey).
 656                  Note that this can only be done once the row is active.
 657
 658                  When a set is received and the usmUserName of the
 659                  requester is not the same as the umsUserName that
 660                  indexes the row which is targeted by this operation,
 661                  then a 'noAccess' error must be returned.
 662
 663                  When a set is received and the security model in use
 664                  is not USM, then a 'noAccess' error must be returned.
 665                 "
 666     DEFVAL      { ''H }    -- the empty string
 667     ::= { usmUserEntry 7 }
 668
 669 usmUserPrivProtocol OBJECT-TYPE
 670     SYNTAX       AutonomousType
 671     MAX-ACCESS   read-create
 672     STATUS       current
 673     DESCRIPTION "An indication of whether messages sent on behalf of
 674                  this user to/from the SNMP engine identified by
 675                  usmUserEngineID, can be protected from disclosure,
 676                  and if so, the type of privacy protocol which is used.
 677
 678                  An instance of this object is created concurrently
 679                  with the creation of any other object instance for
 680                  the same user (i.e., as part of the processing of
 681                  the set operation which creates the first object
 682                  instance in the same conceptual row).
 683
 684                  If an initial set operation (i.e. at row creation time)
 685                  tries to set a value for an unknown or unsupported
 686                  protocol, then a 'wrongValue' error must be returned.
 687
 688                  The value will be overwritten/set when a set operation
 689                  is performed on the corresponding instance of
 690                  usmUserCloneFrom.
 691
 692                  Once instantiated, the value of such an instance of
 693                  this object can only be changed via a set operation to
 694                  the value of the usmNoPrivProtocol.
 695
 696                  If a set operation tries to change the value of an
 697                  existing instance of this object to any value other
 698                  than usmNoPrivProtocol, then an 'inconsistentValue'
 699                  error must be returned.
 700
 701                  Note that if any privacy protocol is used, then you
 702                  must also use an authentication protocol. In other
 703                  words, if usmUserPrivProtocol is set to anything else
 704                  than usmNoPrivProtocol, then the corresponding instance
 705                  of usmUserAuthProtocol cannot have a value of
 706
 707                  usmNoAuthProtocol. If it does, then an
 708                  'inconsistentValue' error must be returned.
 709                 "
 710     DEFVAL      { usmNoPrivProtocol }
 711     ::= { usmUserEntry 8 }
 712
 713 usmUserPrivKeyChange OBJECT-TYPE
 714     SYNTAX       KeyChange  -- typically (SIZE (0 | 32)) for DES
 715     MAX-ACCESS   read-create
 716     STATUS       current
 717     DESCRIPTION "An object, which when modified, causes the secret
 718                  encryption key used for messages sent on behalf
 719                  of this user to/from the SNMP engine identified by
 720                  usmUserEngineID, to be modified via a one-way
 721                  function.
 722
 723                  The associated protocol is the usmUserPrivProtocol.
 724                  The associated secret key is the user's secret
 725                  privacy key (privKey). The associated hash
 726                  algorithm is the algorithm used by the user's
 727                  usmUserAuthProtocol.
 728
 729                  When creating a new user, it is an 'inconsistentName'
 730                  error for a set operation to refer to this object
 731                  unless it is previously or concurrently initialized
 732                  through a set operation on the corresponding instance
 733                  of usmUserCloneFrom.
 734
 735                  When the value of the corresponding usmUserPrivProtocol
 736                  is usmNoPrivProtocol, then a set is successful, but
 737                  effectively is a no-op.
 738
 739                  When this object is read, the zero-length (empty)
 740                  string is returned.
 741                  See the description clause of usmUserAuthKeyChange for
 742                  a recommended procedure to do a key change.
 743                 "
 744     DEFVAL      { ''H }    -- the empty string
 745     ::= { usmUserEntry 9 }
 746
 747 usmUserOwnPrivKeyChange OBJECT-TYPE
 748     SYNTAX       KeyChange  -- typically (SIZE (0 | 32)) for DES
 749     MAX-ACCESS   read-create
 750     STATUS       current
 751     DESCRIPTION "Behaves exactly as usmUserPrivKeyChange, with one
 752                  notable difference: in order for the Set operation
 753                  to succeed, the usmUserName of the operation
 754                  requester must match the usmUserName that indexes
 755
 756                  the row which is targeted by this operation.
 757                  In addition, the USM security model must be
 758                  used for this operation.
 759
 760                  The idea here is that access to this column can be
 761                  public, since it will only allow a user to change
 762                  his own secret privacy key (privKey).
 763                  Note that this can only be done once the row is active.
 764
 765                  When a set is received and the usmUserName of the
 766                  requester is not the same as the umsUserName that
 767                  indexes the row which is targeted by this operation,
 768                  then a 'noAccess' error must be returned.
 769
 770                  When a set is received and the security model in use
 771                  is not USM, then a 'noAccess' error must be returned.
 772                 "
 773     DEFVAL      { ''H }    -- the empty string
 774     ::= { usmUserEntry 10 }
 775
 776 usmUserPublic    OBJECT-TYPE
 777     SYNTAX       OCTET STRING (SIZE(0..32))
 778     MAX-ACCESS   read-create
 779     STATUS       current
 780     DESCRIPTION "A publicly-readable value which can be written as part
 781                  of the procedure for changing a user's secret
 782                  authentication and/or privacy key, and later read to
 783                  determine whether the change of the secret was
 784                  effected.
 785                 "
 786     DEFVAL      { ''H }  -- the empty string
 787     ::= { usmUserEntry 11 }
 788
 789 usmUserStorageType OBJECT-TYPE
 790     SYNTAX       StorageType
 791     MAX-ACCESS   read-create
 792     STATUS       current
 793     DESCRIPTION "The storage type for this conceptual row.
 794
 795                  Conceptual rows having the value 'permanent' must
 796                  allow write-access at a minimum to:
 797
 798                  - usmUserAuthKeyChange, usmUserOwnAuthKeyChange
 799                    and usmUserPublic for a user who employs
 800                    authentication, and
 801                  - usmUserPrivKeyChange, usmUserOwnPrivKeyChange
 802                    and usmUserPublic for a user who employs
 803                    privacy.
 804
 805                  Note that any user who employs authentication or
 806                  privacy must allow its secret(s) to be updated and
 807                  thus cannot be 'readOnly'.
 808
 809                  If an initial set operation tries to set the value to
 810                  'readOnly' for a user who employs authentication or
 811                  privacy, then an 'inconsistentValue' error must be
 812                  returned.  Note that if the value has been previously
 813                  set (implicit or explicit) to any value, then the rules
 814                  as defined in the StorageType Textual Convention apply.
 815
 816                  It is an implementation issue to decide if a SET for
 817                  a readOnly or permanent row is accepted at all. In some
 818                  contexts this may make sense, in others it may not. If
 819                  a SET for a readOnly or permanent row is not accepted
 820                  at all, then a 'wrongValue' error must be returned.
 821                 "
 822     DEFVAL      { nonVolatile }
 823     ::= { usmUserEntry 12 }
 824
 825 usmUserStatus    OBJECT-TYPE
 826     SYNTAX       RowStatus
 827     MAX-ACCESS   read-create
 828     STATUS       current
 829     DESCRIPTION "The status of this conceptual row.
 830
 831                  Until instances of all corresponding columns are
 832                  appropriately configured, the value of the
 833                  corresponding instance of the usmUserStatus column
 834                  is 'notReady'.
 835
 836                  In particular, a newly created row for a user who
 837                  employs authentication, cannot be made active until the
 838                  corresponding usmUserCloneFrom and usmUserAuthKeyChange
 839                  have been set.
 840
 841                  Further, a newly created row for a user who also
 842                  employs privacy, cannot be made active until the
 843                  usmUserPrivKeyChange has been set.
 844
 845                  The RowStatus TC [RFC2579] requires that this
 846                  DESCRIPTION clause states under which circumstances
 847                  other objects in this row can be modified:
 848
 849                  The value of this object has no effect on whether
 850                  other objects in this conceptual row can be modified,
 851                  except for usmUserOwnAuthKeyChange and
 852                  usmUserOwnPrivKeyChange. For these 2 objects, the
 853
 854                  value of usmUserStatus MUST be active.
 855                 "
 856     ::= { usmUserEntry 13 }
 857
 858 -- Conformance Information *******************************************
 859
 860 usmMIBCompliances OBJECT IDENTIFIER ::= { usmMIBConformance 1 }
 861 usmMIBGroups      OBJECT IDENTIFIER ::= { usmMIBConformance 2 }
 862
 863 -- Compliance statements
 864
 865 usmMIBCompliance MODULE-COMPLIANCE
 866     STATUS       current
 867     DESCRIPTION "The compliance statement for SNMP engines which
 868                  implement the SNMP-USER-BASED-SM-MIB.
 869                 "
 870
 871     MODULE       -- this module
 872         MANDATORY-GROUPS { usmMIBBasicGroup }
 873
 874         OBJECT           usmUserAuthProtocol
 875         MIN-ACCESS       read-only
 876         DESCRIPTION     "Write access is not required."
 877
 878         OBJECT           usmUserPrivProtocol
 879         MIN-ACCESS       read-only
 880         DESCRIPTION     "Write access is not required."
 881     ::= { usmMIBCompliances 1 }
 882
 883 -- Units of compliance
 884 usmMIBBasicGroup OBJECT-GROUP
 885     OBJECTS     {
 886                   usmStatsUnsupportedSecLevels,
 887                   usmStatsNotInTimeWindows,
 888                   usmStatsUnknownUserNames,
 889                   usmStatsUnknownEngineIDs,
 890                   usmStatsWrongDigests,
 891                   usmStatsDecryptionErrors,
 892                   usmUserSpinLock,
 893                   usmUserSecurityName,
 894                   usmUserCloneFrom,
 895                   usmUserAuthProtocol,
 896                   usmUserAuthKeyChange,
 897                   usmUserOwnAuthKeyChange,
 898                   usmUserPrivProtocol,
 899                   usmUserPrivKeyChange,
 900                   usmUserOwnPrivKeyChange,
 901                   usmUserPublic,
 902                   usmUserStorageType,
 903                   usmUserStatus
 904                 }
 905     STATUS       current
 906     DESCRIPTION "A collection of objects providing for configuration
 907                  of an SNMP engine which implements the SNMP
 908                  User-based Security Model.
 909                 "
 910     ::= { usmMIBGroups 1 }
 911
 912 END