mibs/ietf/SNMP-USM-DH-OBJECTS-MIB

   1 SNMP-USM-DH-OBJECTS-MIB DEFINITIONS ::= BEGIN
   2
   3 IMPORTS
   4     MODULE-IDENTITY, OBJECT-TYPE,
   5     -- OBJECT-IDENTITY,
   6     experimental, Integer32
   7         FROM SNMPv2-SMI
   8     TEXTUAL-CONVENTION
   9         FROM SNMPv2-TC
  10     MODULE-COMPLIANCE, OBJECT-GROUP
  11         FROM SNMPv2-CONF
  12     usmUserEntry
  13         FROM SNMP-USER-BASED-SM-MIB
  14     SnmpAdminString
  15         FROM SNMP-FRAMEWORK-MIB;
  16
  17 snmpUsmDHObjectsMIB MODULE-IDENTITY
  18     LAST-UPDATED "200003060000Z"  -- 6 March 2000, Midnight
  19     ORGANIZATION "Excite@Home"
  20     CONTACT-INFO "Author: Mike StJohns
  21                   Postal: Excite@Home
  22                           450 Broadway
  23                           Redwood City, CA 94063
  24                   Email:  stjohns@corp.home.net
  25                   Phone:  +1-650-556-5368"
  26
  27     DESCRIPTION
  28         "The management information definitions for providing forward
  29     secrecy for key changes for the usmUserTable, and for providing a
  30     method for 'kickstarting' access to the agent via a Diffie-Helman
  31     key agreement."
  32
  33     REVISION     "200003060000Z"
  34     DESCRIPTION
  35        "Initial version published as RFC 2786."
  36
  37
  38     ::= { experimental 101 }  -- IANA DHKEY-CHANGE 101
  39
  40 -- Administrative assignments
  41
  42 usmDHKeyObjects OBJECT IDENTIFIER ::= { snmpUsmDHObjectsMIB 1 }
  43 usmDHKeyConformance OBJECT IDENTIFIER ::= { snmpUsmDHObjectsMIB 2 }
  44
  45 -- Textual conventions
  46
  47 DHKeyChange ::=         TEXTUAL-CONVENTION
  48     STATUS              current
  49     DESCRIPTION
  50         "Upon initialization, or upon creation of a row containing an
  51     object of this type, and after any successful SET of this value, a
  52     GET of this value returns 'y' where y = g^xa MOD p, and where g is
  53     the base from usmDHParameters, p is the prime from
  54     usmDHParameters, and xa is a new random integer selected by the
  55     agent in the interval 2^(l-1) <= xa < 2^l < p-1.  'l' is the
  56     optional privateValueLength from usmDHParameters in bits.  If 'l'
  57     is omitted, then xa (and xr below) is selected in the interval 0
  58     <= xa < p-1.  y is expressed as an OCTET STRING 'PV' of length 'k'
  59     which satisfies
  60
  61               k
  62         y =  SUM   2^(8(k-i)) PV'i
  63              i=1
  64
  65         where PV1,...,PVk are the octets of PV from first to last, and
  66         where PV1 <> 0.
  67
  68     A successful SET consists of the value 'y' expressed as an OCTET
  69     STRING as above concatenated with the value 'z'(expressed as an
  70     OCTET STRING in the same manner as y) where z = g^xr MOD p, where
  71     g, p and l are as above, and where xr is a new random integer
  72     selected by the manager in the interval 2^(l-1) <= xr < 2^l <
  73     p-1. A SET to an object of this type will fail with the error
  74     wrongValue if the current 'y' does not match the 'y' portion of
  75     the value of the varbind for the object. (E.g. GET yout, SET
  76     concat(yin, z), yout <> yin).
  77
  78     Note that the private values xa and xr are never transmitted from
  79     manager to device or vice versa, only the values y and z.
  80     Obviously, these values must be retained until a successful SET on
  81     the associated object.
  82
  83     The shared secret 'sk' is calculated at the agent as sk = z^xa MOD
  84     p, and at the manager as sk = y^xr MOD p.
  85
  86     Each object definition of this type MUST describe how to map from
  87     the shared secret 'sk' to the operational key value used by the
  88     protocols and operations related to the object.  In general, if n
  89     bits of key are required, the author suggests using the n
  90     right-most bits of the shared secret as the operational key value."
  91     REFERENCE
  92         "-- Diffie-Hellman Key-Agreement Standard, PKCS #3;
  93             RSA Laboratories, November 1993"
  94     SYNTAX              OCTET STRING
  95
  96 -- Diffie Hellman public values
  97
  98 usmDHPublicObjects      OBJECT IDENTIFIER ::= { usmDHKeyObjects 1 }
  99
 100 usmDHParameters OBJECT-TYPE
 101     SYNTAX  OCTET STRING
 102     MAX-ACCESS read-write
 103     STATUS  current
 104     DESCRIPTION
 105         "The public Diffie-Hellman parameters for doing a Diffie-Hellman
 106     key agreement for this device.  This is encoded as an ASN.1
 107     DHParameter per PKCS #3, section 9.  E.g.
 108
 109         DHParameter ::= SEQUENCE {
 110            prime   INTEGER,   -- p
 111            base    INTEGER,   -- g
 112            privateValueLength  INTEGER OPTIONAL }
 113
 114
 115     Implementors are encouraged to use either the values from
 116     Oakley Group 1  or the values of from Oakley Group 2 as specified
 117     in RFC-2409, The Internet Key Exchange, Section 6.1, 6.2 as the
 118     default for this object.  Other values may be used, but the
 119     security properties of those values MUST be well understood and
 120     MUST meet the requirements of PKCS #3 for the selection of
 121     Diffie-Hellman primes.
 122
 123         In addition, any time usmDHParameters changes, all values of
 124     type DHKeyChange will change and new random numbers MUST be
 125     generated by the agent for each DHKeyChange object."
 126     REFERENCE
 127         "-- Diffie-Hellman Key-Agreement Standard, PKCS #3,
 128             RSA Laboratories, November 1993
 129          -- The Internet Key Exchange, RFC 2409, November 1998,
 130             Sec 6.1, 6.2"
 131     ::= { usmDHPublicObjects 1 }
 132
 133 usmDHUserKeyTable OBJECT-TYPE
 134     SYNTAX  SEQUENCE OF UsmDHUserKeyEntry
 135     MAX-ACCESS not-accessible
 136     STATUS  current
 137     DESCRIPTION
 138         "This table augments and extends the usmUserTable and provides
 139     4 objects which exactly mirror the objects in that table with the
 140     textual convention of 'KeyChange'.  This extension allows key
 141     changes to be done in a manner where the knowledge of the current
 142     secret plus knowledge of the key change data exchanges (e.g. via
 143     wiretapping)  will not reveal the new key."
 144     ::= { usmDHPublicObjects 2 }
 145
 146 usmDHUserKeyEntry OBJECT-TYPE
 147     SYNTAX  UsmDHUserKeyEntry
 148     MAX-ACCESS not-accessible
 149     STATUS  current
 150     DESCRIPTION
 151         "A row of DHKeyChange objects which augment or replace the
 152     functionality of the KeyChange objects in the base table row."
 153     AUGMENTS { usmUserEntry }
 154     ::= {usmDHUserKeyTable 1 }
 155
 156 UsmDHUserKeyEntry ::= SEQUENCE {
 157         usmDHUserAuthKeyChange          DHKeyChange,
 158     usmDHUserOwnAuthKeyChange   DHKeyChange,
 159         usmDHUserPrivKeyChange          DHKeyChange,
 160         usmDHUserOwnPrivKeyChange       DHKeyChange
 161         }
 162
 163 usmDHUserAuthKeyChange OBJECT-TYPE
 164     SYNTAX  DHKeyChange
 165     MAX-ACCESS read-create
 166     STATUS  current
 167     DESCRIPTION
 168         "The object used to change any given user's Authentication Key
 169     using a Diffie-Hellman key exchange.
 170
 171     The right-most n bits of the shared secret 'sk', where 'n' is the
 172     number of bits required for the protocol defined by
 173     usmUserAuthProtocol, are installed as the operational
 174     authentication key for this row after a successful SET."
 175     ::= { usmDHUserKeyEntry 1 }
 176
 177 usmDHUserOwnAuthKeyChange OBJECT-TYPE
 178     SYNTAX  DHKeyChange
 179     MAX-ACCESS read-create
 180     STATUS  current
 181     DESCRIPTION
 182         "The object used to change the agents own Authentication Key
 183     using a Diffie-Hellman key exchange.
 184
 185     The right-most n bits of the shared secret 'sk', where 'n' is the
 186     number of bits required for the protocol defined by
 187     usmUserAuthProtocol, are installed as the operational
 188     authentication key for this row after a successful SET."
 189     ::= { usmDHUserKeyEntry 2 }
 190
 191 usmDHUserPrivKeyChange OBJECT-TYPE
 192     SYNTAX  DHKeyChange
 193     MAX-ACCESS read-create
 194     STATUS  current
 195     DESCRIPTION
 196         "The object used to change any given user's Privacy Key using
 197     a Diffie-Hellman key exchange.
 198
 199     The right-most n bits of the shared secret 'sk', where 'n' is the
 200     number of bits required for the protocol defined by
 201     usmUserPrivProtocol, are installed as the operational privacy key
 202     for this row after a successful SET."
 203     ::= { usmDHUserKeyEntry 3 }
 204
 205 usmDHUserOwnPrivKeyChange OBJECT-TYPE
 206     SYNTAX  DHKeyChange
 207     MAX-ACCESS read-create
 208     STATUS  current
 209     DESCRIPTION
 210         "The object used to change the agent's own Privacy Key using a
 211     Diffie-Hellman key exchange.
 212
 213     The right-most n bits of the shared secret 'sk', where 'n' is the
 214     number of bits required for the protocol defined by
 215     usmUserPrivProtocol, are installed as the operational privacy key
 216     for this row after a successful SET."
 217     ::= { usmDHUserKeyEntry 4 }
 218
 219 usmDHKickstartGroup OBJECT IDENTIFIER ::= { usmDHKeyObjects 2 }
 220
 221 usmDHKickstartTable OBJECT-TYPE
 222     SYNTAX      SEQUENCE OF UsmDHKickstartEntry
 223     MAX-ACCESS  not-accessible
 224     STATUS      current
 225     DESCRIPTION
 226         "A table of mappings between zero or more Diffie-Helman key
 227     agreement values and entries in the usmUserTable.  Entries in this
 228     table are created by providing the associated device with a
 229     Diffie-Helman public value and a usmUserName/usmUserSecurityName
 230     pair during initialization. How these values are provided is
 231     outside the scope of this MIB, but could be provided manually, or
 232     through a configuration file.  Valid public value/name pairs
 233     result in the creation of a row in this table as well as the
 234     creation of an associated row (with keys derived as indicated) in
 235     the usmUserTable.  The actual access the related usmSecurityName
 236     has is dependent on the entries in the VACM tables.  In general,
 237     an implementor will specify one or more standard security names
 238     and will provide entries in the VACM tables granting various
 239     levels of access to those names.  The actual content of the VACM
 240     table is beyond the scope of this MIB.
 241
 242     Note: This table is expected to be readable without authentication
 243     using the usmUserSecurityName 'dhKickstart'.  See the conformance
 244     statements for details."
 245     ::= { usmDHKickstartGroup 1 }
 246
 247 usmDHKickstartEntry OBJECT-TYPE
 248     SYNTAX      UsmDHKickstartEntry
 249     MAX-ACCESS  not-accessible
 250     STATUS      current
 251     DESCRIPTION
 252
 253         "An entry in the usmDHKickstartTable.  The agent SHOULD either
 254     delete this entry or mark it as inactive upon a successful SET of
 255     any of the KeyChange-typed objects in the usmUserEntry or upon a
 256     successful SET of any of the DHKeyChange-typed objects in the
 257     usmDhKeyChangeEntry where the related usmSecurityName (e.g. row of
 258     usmUserTable or row of ushDhKeyChangeTable) equals this entry's
 259     usmDhKickstartSecurityName.  In otherwords, once you've changed
 260     one or more of the keys for a row in usmUserTable with a
 261     particular security name, the row in this table with that same
 262     security name is no longer useful or meaningful."
 263
 264     INDEX   { usmDHKickstartIndex }
 265     ::= {usmDHKickstartTable 1 }
 266
 267 UsmDHKickstartEntry ::= SEQUENCE  {
 268         usmDHKickstartIndex     Integer32,
 269         usmDHKickstartMyPublic  OCTET STRING,
 270         usmDHKickstartMgrPublic OCTET STRING,
 271         usmDHKickstartSecurityName      SnmpAdminString
 272         }
 273
 274 usmDHKickstartIndex OBJECT-TYPE
 275     SYNTAX      Integer32  (1..2147483647)
 276     MAX-ACCESS  not-accessible
 277     STATUS      current
 278     DESCRIPTION
 279         "Index value for this row."
 280     ::= { usmDHKickstartEntry 1 }
 281
 282 usmDHKickstartMyPublic OBJECT-TYPE
 283     SYNTAX      OCTET STRING
 284     MAX-ACCESS  read-only
 285     STATUS      current
 286     DESCRIPTION
 287         "The agent's Diffie-Hellman public value for this row.  At
 288     initialization, the agent generates a random number and derives
 289     its public value from that number.  This public value is published
 290     here.  This public value 'y' equals g^r MOD p where g is the from
 291     the set of Diffie-Hellman parameters, p is the prime from those
 292     parameters, and r is a random integer selected by the agent in the
 293     interval 2^(l-1) <= r < p-1 < 2^l.  If l is unspecified, then r is
 294     a random integer selected in the interval 0 <= r < p-1
 295
 296     The public value is expressed as an OCTET STRING 'PV' of length
 297     'k' which satisfies
 298
 299               k
 300         y =  SUM   2^(8(k-i)) PV'i
 301              i = 1
 302
 303         where PV1,...,PVk are the octets of PV from first to last, and
 304         where PV1 != 0.
 305
 306
 307     The following DH parameters (Oakley group #2, RFC 2409, sec 6.1,
 308     6.2) are used for this object:
 309
 310     g = 2
 311     p = FFFFFFFF FFFFFFFF C90FDAA2 2168C234 C4C6628B 80DC1CD1
 312         29024E08 8A67CC74 020BBEA6 3B139B22 514A0879 8E3404DD
 313         EF9519B3 CD3A431B 302B0A6D F25F1437 4FE1356D 6D51C245
 314         E485B576 625E7EC6 F44C42E9 A637ED6B 0BFF5CB6 F406B7ED
 315         EE386BFB 5A899FA5 AE9F2411 7C4B1FE6 49286651 ECE65381
 316         FFFFFFFF FFFFFFFF
 317     l=1024
 318     "
 319     REFERENCE
 320         "-- Diffie-Hellman Key-Agreement Standard, PKCS#3v1.4;
 321             RSA Laboratories, November 1993
 322          -- The Internet Key Exchange, RFC2409;
 323             Harkins, D., Carrel, D.; November 1998"
 324     ::= { usmDHKickstartEntry 2 }
 325
 326 usmDHKickstartMgrPublic OBJECT-TYPE
 327     SYNTAX      OCTET STRING
 328     MAX-ACCESS  read-only
 329     STATUS      current
 330     DESCRIPTION
 331
 332         "The manager's Diffie-Hellman public value for this row.  Note
 333     that this value is not set via the SNMP agent, but may be set via
 334     some out of band method, such as the device's configuration file.
 335     The manager calculates this value in the same manner and using the
 336     same parameter set as the agent does.  E.g. it selects a random
 337     number 'r', calculates y = g^r mod p and provides 'y' as the
 338     public number expressed as an OCTET STRING.  See
 339     usmDHKickstartMyPublic for details.
 340
 341     When this object is set with a valid value during initialization,
 342     a row is created in the usmUserTable with the following values:
 343
 344     usmUserEngineID             localEngineID
 345     usmUserName                 [value of usmDHKickstartSecurityName]
 346     usmUserSecurityName         [value of usmDHKickstartSecurityName]
 347     usmUserCloneFrom            ZeroDotZero
 348     usmUserAuthProtocol         usmHMACMD5AuthProtocol
 349     usmUserAuthKeyChange        -- derived from set value
 350     usmUserOwnAuthKeyChange     -- derived from set value
 351     usmUserPrivProtocol         usmDESPrivProtocol
 352     usmUserPrivKeyChange        -- derived from set value
 353     usmUserOwnPrivKeyChange     -- derived from set value
 354     usmUserPublic               ''
 355     usmUserStorageType          permanent
 356     usmUserStatus               active
 357
 358     A shared secret 'sk' is calculated at the agent as sk =
 359     mgrPublic^r mod p where r is the agents random number and p is the
 360     DH prime from the common parameters.  The underlying privacy key
 361     for this row is derived from sk by applying the key derivation
 362     function PBKDF2 defined in PKCS#5v2.0 with a salt of 0xd1310ba6,
 363     and iterationCount of 500, a keyLength of 16 (for
 364     usmDESPrivProtocol), and a prf (pseudo random function) of
 365     'id-hmacWithSHA1'.  The underlying authentication key for this row
 366     is derived from sk by applying the key derivation function PBKDF2
 367     with a salt of 0x98dfb5ac , an interation count of 500, a
 368     keyLength of 16 (for usmHMAC5AuthProtocol), and a prf of
 369     'id-hmacWithSHA1'.  Note: The salts are the first two words in the
 370     ks0 [key schedule 0] of the BLOWFISH cipher from 'Applied
 371     Cryptography' by Bruce Schnier - they could be any relatively
 372     random string of bits.
 373
 374     The manager can use its knowledge of its own random number and the
 375     agent's public value to kickstart its access to the agent in a
 376     secure manner.  Note that the security of this approach is
 377     directly related to the strength of the authorization security of
 378     the out of band provisioning of the managers public value
 379     (e.g. the configuration file), but is not dependent at all on the
 380     strength of the confidentiality of the out of band provisioning
 381     data."
 382     REFERENCE
 383         "-- Password-Based Cryptography Standard, PKCS#5v2.0;
 384             RSA Laboratories, March 1999
 385          -- Applied Cryptography, 2nd Ed.; B. Schneier,
 386             Counterpane Systems; John Wiley & Sons, 1996"
 387     ::= { usmDHKickstartEntry 3 }
 388
 389 usmDHKickstartSecurityName OBJECT-TYPE
 390     SYNTAX      SnmpAdminString
 391     MAX-ACCESS  read-only
 392     STATUS      current
 393     DESCRIPTION
 394         "The usmUserName and usmUserSecurityName in the usmUserTable
 395     associated with this row.  This is provided in the same manner and
 396     at the same time as the usmDHKickstartMgrPublic value -
 397     e.g. possibly manually, or via the device's configuration file."
 398     ::= { usmDHKickstartEntry 4 }
 399
 400 -- Conformance Information
 401
 402 usmDHKeyMIBCompliances  OBJECT IDENTIFIER ::= { usmDHKeyConformance 1 }
 403 usmDHKeyMIBGroups       OBJECT IDENTIFIER ::= { usmDHKeyConformance 2 }
 404
 405 -- Compliance statements
 406
 407 usmDHKeyMIBCompliance   MODULE-COMPLIANCE
 408     STATUS      current
 409     DESCRIPTION
 410         "The compliance statement for this module."
 411     MODULE
 412         GROUP usmDHKeyMIBBasicGroup
 413         DESCRIPTION
 414         "This group MAY be implemented by any agent which
 415         implements the usmUserTable and which wishes to provide the
 416         ability to change user and agent authentication and privacy
 417         keys via Diffie-Hellman key exchanges."
 418
 419         GROUP usmDHKeyParamGroup
 420         DESCRIPTION
 421             "This group MUST be implemented by any agent which
 422         implements a MIB containing the DHKeyChange Textual
 423         Convention defined in this module."
 424
 425         GROUP usmDHKeyKickstartGroup
 426         DESCRIPTION
 427             "This group MAY be implemented by any agent which
 428         implements the usmUserTable and which wishes the ability to
 429         populate the USM table based on out-of-band provided DH
 430         ignition values.
 431              Any agent implementing this group is expected to provide
 432         preinstalled entries in the vacm tables as follows:
 433
 434              In the usmUserTable: This entry allows access to the
 435         system and dhKickstart groups
 436
 437         usmUserEngineID         localEngineID
 438         usmUserName             'dhKickstart'
 439         usmUserSecurityName     'dhKickstart'
 440         usmUserCloneFrom        ZeroDotZero
 441         usmUserAuthProtocol     none
 442         usmUserAuthKeyChange    ''
 443         usmUserOwnAuthKeyChange ''
 444         usmUserPrivProtocol     none
 445         usmUserPrivKeyChange    ''
 446         usmUserOwnPrivKeyChange ''
 447         usmUserPublic           ''
 448         usmUserStorageType      permanent
 449         usmUserStatus           active
 450
 451             In the vacmSecurityToGroupTable: This maps the initial
 452         user into the accessible objects.
 453
 454         vacmSecurityModel               3 (USM)
 455         vacmSecurityName                'dhKickstart'
 456         vacmGroupName                   'dhKickstart'
 457         vacmSecurityToGroupStorageType  permanent
 458         vacmSecurityToGroupStatus       active
 459
 460             In the vacmAccessTable: Group name to view name translation.
 461
 462         vacmGroupName                   'dhKickstart'
 463     vacmAccessContextPrefix             ''
 464         vacmAccessSecurityModel         3 (USM)
 465         vacmAccessSecurityLevel         noAuthNoPriv
 466         vacmAccessContextMatch          exact
 467         vacmAccessReadViewName          'dhKickRestricted'
 468         vacmAccessWriteViewName         ''
 469         vacmAccessNotifyViewName        'dhKickRestricted'
 470         vacmAccessStorageType           permanent
 471         vacmAccessStatus                active
 472
 473             In the vacmViewTreeFamilyTable: Two entries to allow the
 474         initial entry to access the system and kickstart groups.
 475
 476         vacmViewTreeFamilyViewName      'dhKickRestricted'
 477         vacmViewTreeFamilySubtree       1.3.6.1.2.1.1  (system)
 478         vacmViewTreeFamilyMask          ''
 479         vacmViewTreeFamilyType          1
 480         vacmViewTreeFamilyStorageType   permanent
 481         vacmViewTreeFamilyStatus        active
 482
 483         vacmViewTreeFamilyViewName      'dhKickRestricted'
 484         vacmViewTreeFamilySubtree         (usmDHKickstartTable OID)
 485         vacmViewTreeFamilyMask          ''
 486         vacmViewTreeFamilyType          1
 487         vacmViewTreeFamilyStorageType   permanent
 488         vacmViewTreeFamilyStatus        active
 489         "
 490
 491         OBJECT usmDHParameters
 492         MIN-ACCESS      read-only
 493         DESCRIPTION
 494             "It is compliant to implement this object as read-only for
 495         any device."
 496
 497     ::= { usmDHKeyMIBCompliances 1 }
 498
 499 -- Units of Compliance
 500
 501 usmDHKeyMIBBasicGroup OBJECT-GROUP
 502     OBJECTS     {
 503                   usmDHUserAuthKeyChange,
 504                   usmDHUserOwnAuthKeyChange,
 505                   usmDHUserPrivKeyChange,
 506                   usmDHUserOwnPrivKeyChange
 507                 }
 508     STATUS      current
 509     DESCRIPTION
 510         ""
 511     ::= { usmDHKeyMIBGroups 1 }
 512
 513 usmDHKeyParamGroup OBJECT-GROUP
 514     OBJECTS     {
 515                   usmDHParameters
 516                 }
 517     STATUS      current
 518     DESCRIPTION
 519         "The mandatory object for all MIBs which use the DHKeyChange
 520     textual convention."
 521     ::= { usmDHKeyMIBGroups 2 }
 522
 523 usmDHKeyKickstartGroup OBJECT-GROUP
 524     OBJECTS     {
 525                   usmDHKickstartMyPublic,
 526                   usmDHKickstartMgrPublic,
 527                   usmDHKickstartSecurityName
 528                 }
 529     STATUS      current
 530     DESCRIPTION
 531         "The objects used for kickstarting one or more SNMPv3 USM
 532     associations via a configuration file or other out of band,
 533     non-confidential access."
 534     ::= { usmDHKeyMIBGroups 3 }
 535
 536
 537 END