-- extracted from rfc2264.txt -- at Mon Nov 15 17:11:43 1999 SNMP-USER-BASED-SM-MIB DEFINITIONS ::= BEGIN IMPORTS MODULE-IDENTITY, OBJECT-TYPE, OBJECT-IDENTITY, snmpModules, Counter32 FROM SNMPv2-SMI TEXTUAL-CONVENTION, TestAndIncr, RowStatus, RowPointer, StorageType, AutonomousType FROM SNMPv2-TC MODULE-COMPLIANCE, OBJECT-GROUP FROM SNMPv2-CONF SnmpAdminString, SnmpEngineID, snmpAuthProtocols, snmpPrivProtocols FROM SNMP-FRAMEWORK-MIB; snmpUsmMIB MODULE-IDENTITY LAST-UPDATED "9711200000Z" -- 20 Nov 1997, midnight ORGANIZATION "SNMPv3 Working Group" CONTACT-INFO "WG-email: snmpv3@tis.com Subscribe: majordomo@tis.com In msg body: subscribe snmpv3 Chair: Russ Mundy Trusted Information Systems postal: 3060 Washington Rd Glenwood MD 21738 USA email: mundy@tis.com phone: +1-301-854-6889 Co-editor Uri Blumenthal IBM T. J. Watson Research postal: 30 Saw Mill River Pkwy, Hawthorne, NY 10532 USA email: uri@watson.ibm.com phone: +1-914-784-7964 Co-editor: Bert Wijnen IBM T. J. Watson Research postal: Schagen 33 3461 GL Linschoten Netherlands email: wijnen@vnet.ibm.com phone: +31-348-432-794 " DESCRIPTION "The management information definitions for the SNMP User-based Security Model. " ::= { snmpModules 4 } -- Administrative assignments **************************************** usmMIBObjects OBJECT IDENTIFIER ::= { snmpUsmMIB 1 } usmMIBConformance OBJECT IDENTIFIER ::= { snmpUsmMIB 2 } -- Identification of Authentication and Privacy Protocols ************ usmNoAuthProtocol OBJECT-IDENTITY STATUS current DESCRIPTION "No Authentication Protocol." ::= { snmpAuthProtocols 1 } usmHMACMD5AuthProtocol OBJECT-IDENTITY STATUS current DESCRIPTION "The HMAC-MD5-96 Digest Authentication Protocol." REFERENCE "- H. Krawczyk, M. Bellare, R. Canetti HMAC: Keyed-Hashing for Message Authentication, RFC2104, Feb 1997. - Rivest, R., Message Digest Algorithm MD5, RFC1321. " ::= { snmpAuthProtocols 2 } usmHMACSHAAuthProtocol OBJECT-IDENTITY STATUS current DESCRIPTION "The HMAC-SHA-96 Digest Authentication Protocol." REFERENCE "- H. Krawczyk, M. Bellare, R. Canetti, HMAC: Keyed-Hashing for Message Authentication, RFC2104, Feb 1997. - Secure Hash Algorithm. NIST FIPS 180-1. " ::= { snmpAuthProtocols 3 } usmNoPrivProtocol OBJECT-IDENTITY STATUS current DESCRIPTION "No Privacy Protocol." ::= { snmpPrivProtocols 1 } usmDESPrivProtocol OBJECT-IDENTITY STATUS current DESCRIPTION "The CBC-DES Symmetric Encryption Protocol." REFERENCE "- Data Encryption Standard, National Institute of Standards and Technology. Federal Information Processing Standard (FIPS) Publication 46-1. Supersedes FIPS Publication 46, (January, 1977; reaffirmed January, 1988). - Data Encryption Algorithm, American National Standards Institute. ANSI X3.92-1981, (December, 1980). - DES Modes of Operation, National Institute of Standards and Technology. Federal Information Processing Standard (FIPS) Publication 81, (December, 1980). - Data Encryption Algorithm - Modes of Operation, American National Standards Institute. ANSI X3.106-1983, (May 1983). " ::= { snmpPrivProtocols 2 } -- Textual Conventions *********************************************** KeyChange ::= TEXTUAL-CONVENTION STATUS current DESCRIPTION "Every definition of an object with this syntax must identify a protocol P, a secret key K, and a hash algorithm H that produces output of L octets. The object's value is a manager-generated, partially-random value which, when modified, causes the value of the secret key K, to be modified via a one-way function. The value of an instance of this object is the concatenation of two components: first a 'random' component and then a 'delta' component. The lengths of the random and delta components are given by the corresponding value of the protocol P; if P requires K to be a fixed length, the length of both the random and delta components is that fixed length; if P allows the length of K to be variable up to a particular maximum length, the length of the random component is that maximum length and the length of the delta component is any length less than or equal to that maximum length. For example, usmHMACMD5AuthProtocol requires K to be a fixed length of 16 octets and L - of 16 octets. usmHMACSHAAuthProtocol requires K to be a fixed length of 20 octets and L - of 20 octets. Other protocols may define other sizes, as deemed appropriate. When a requestor wants to change the old key K to a new key keyNew on a remote entity, the 'random' component is obtained from either a true random generator, or from a pseudorandom generator, and the 'delta' component is computed as follows: - a temporary variable is initialized to the existing value of K; - if the length of the keyNew is greater than L octets, then: - the random component is appended to the value of the temporary variable, and the result is input to the the hash algorithm H to produce a digest value, and the temporary variable is set to this digest value; - the value of the temporary variable is XOR-ed with the first (next) L-octets (16 octets in case of MD5) of the keyNew to produce the first (next) L-octets (16 octets in case of MD5) of the 'delta' component. - the above two steps are repeated until the unused portion of the delta component is L octets or less, - the random component is appended to the value of the temporary variable, and the result is input to the hash algorithm H to produce a digest value; - this digest value, truncated if necessary to be the same length as the unused portion of the keyNew, is XOR-ed with the unused portion of the keyNew to produce the (final portion of the) 'delta' component. For example, using MD5 as the hash algorithm H: iterations = (lenOfDelta - 1)/16; /* integer division */ temp = keyOld; for (i = 0; i < iterations; i++) { temp = MD5 (temp || random); delta[i*16 .. (i*16)+15] = temp XOR keyNew[i*16 .. (i*16)+15]; } temp = MD5 (temp || random); delta[i*16 .. lenOfDelta-1] = temp XOR keyNew[i*16 .. lenOfDelta-1]; The 'random' and 'delta' components are then concatenated as described above, and the resulting octet string is sent to the receipient as the new value of an instance of this object. At the receiver side, when an instance of this object is set to a new value, then a new value of K is computed as follows: - a temporary variable is initialized to the existing value of K; - if the length of the delta component is greater than L octets, then: - the random component is appended to the value of the temporary variable, and the result is input to the the hash algorithm H to produce a digest value, and the temporary variable is set to this digest value; - the value of the temporary variable is XOR-ed with the first (next) L-octets (16 octets in case of MD5) of the delta component to produce the first (next) L-octets (16 octets in case of MD5) of the new value of K. - the above two steps are repeated until the unused portion of the delta component is L octets or less, - the random component is appended to the value of the temporary variable, and the result is input to the hash algorithm H to produce a digest value; - this digest value, truncated if necessary to be the same length as the unused portion of the delta component, is XOR-ed with the unused portion of the delta component to produce the (final portion of the) new value of K. For example, using MD5 as the hash algorithm H: iterations = (lenOfDelta - 1)/16; /* integer division */ temp = keyOld; for (i = 0; i < iterations; i++) { temp = MD5 (temp || random); keyNew[i*16 .. (i*16)+15] = temp XOR delta[i*16 .. (i*16)+15]; } temp = MD5 (temp || random); keyNew[i*16 .. lenOfDelta-1] = temp XOR delta[i*16 .. lenOfDelta-1]; The value of an object with this syntax, whenever it is retrieved by the management protocol, is always the zero length string. " SYNTAX OCTET STRING -- Statistics for the User-based Security Model ********************** usmStats OBJECT IDENTIFIER ::= { usmMIBObjects 1 } usmStatsUnsupportedSecLevels OBJECT-TYPE SYNTAX Counter32 MAX-ACCESS read-only STATUS current DESCRIPTION "The total number of packets received by the SNMP engine which were dropped because they requested a securityLevel that was unknown to the SNMP engine or otherwise unavailable. " ::= { usmStats 1 } usmStatsNotInTimeWindows OBJECT-TYPE SYNTAX Counter32 MAX-ACCESS read-only STATUS current DESCRIPTION "The total number of packets received by the SNMP engine which were dropped because they appeared outside of the authoritative SNMP engine's window. " ::= { usmStats 2 } usmStatsUnknownUserNames OBJECT-TYPE SYNTAX Counter32 MAX-ACCESS read-only STATUS current DESCRIPTION "The total number of packets received by the SNMP engine which were dropped because they referenced a user that was not known to the SNMP engine. " ::= { usmStats 3 } usmStatsUnknownEngineIDs OBJECT-TYPE SYNTAX Counter32 MAX-ACCESS read-only STATUS current DESCRIPTION "The total number of packets received by the SNMP engine which were dropped because they referenced an snmpEngineID that was not known to the SNMP engine. " ::= { usmStats 4 } usmStatsWrongDigests OBJECT-TYPE SYNTAX Counter32 MAX-ACCESS read-only STATUS current DESCRIPTION "The total number of packets received by the SNMP engine which were dropped because they didn't contain the expected digest value. " ::= { usmStats 5 } usmStatsDecryptionErrors OBJECT-TYPE SYNTAX Counter32 MAX-ACCESS read-only STATUS current DESCRIPTION "The total number of packets received by the SNMP engine which were dropped because they could not be decrypted. " ::= { usmStats 6 } -- The usmUser Group ************************************************ usmUser OBJECT IDENTIFIER ::= { usmMIBObjects 2 } usmUserSpinLock OBJECT-TYPE SYNTAX TestAndIncr MAX-ACCESS read-write STATUS current DESCRIPTION "An advisory lock used to allow several cooperating Command Generator Applications to coordinate their use of facilities to alter secrets in the usmUserTable. " ::= { usmUser 1 } -- The table of valid users for the User-based Security Model ******** usmUserTable OBJECT-TYPE SYNTAX SEQUENCE OF UsmUserEntry MAX-ACCESS not-accessible STATUS current DESCRIPTION "The table of users configured in the SNMP engine's Local Configuration Datastore (LCD)." ::= { usmUser 2 } usmUserEntry OBJECT-TYPE SYNTAX UsmUserEntry MAX-ACCESS not-accessible STATUS current DESCRIPTION "A user configured in the SNMP engine's Local Configuration Datastore (LCD) for the User-based Security Model. " INDEX { usmUserEngineID, usmUserName } ::= { usmUserTable 1 } UsmUserEntry ::= SEQUENCE { usmUserEngineID SnmpEngineID, usmUserName SnmpAdminString, usmUserSecurityName SnmpAdminString, usmUserCloneFrom RowPointer, usmUserAuthProtocol AutonomousType, usmUserAuthKeyChange KeyChange, usmUserOwnAuthKeyChange KeyChange, usmUserPrivProtocol AutonomousType, usmUserPrivKeyChange KeyChange, usmUserOwnPrivKeyChange KeyChange, usmUserPublic OCTET STRING, usmUserStorageType StorageType, usmUserStatus RowStatus } usmUserEngineID OBJECT-TYPE SYNTAX SnmpEngineID MAX-ACCESS not-accessible STATUS current DESCRIPTION "An SNMP engine's administratively-unique identifier. In a simple agent, this value is always that agent's own snmpEngineID value. The value can also take the value of the snmpEngineID of a remote SNMP engine with which this user can communicate. " ::= { usmUserEntry 1 } usmUserName OBJECT-TYPE SYNTAX SnmpAdminString (SIZE(1..32)) MAX-ACCESS not-accessible STATUS current DESCRIPTION "A human readable string representing the name of the user. This is the (User-based Security) Model dependent security ID. " ::= { usmUserEntry 2 } usmUserSecurityName OBJECT-TYPE SYNTAX SnmpAdminString MAX-ACCESS read-only STATUS current DESCRIPTION "A human readable string representing the user in Security Model independent format. The default transformation of the User-based Security Model dependent security ID to the securityName and vice versa is the identity function so that the securityName is the same as the userName. " ::= { usmUserEntry 3 } usmUserCloneFrom OBJECT-TYPE SYNTAX RowPointer MAX-ACCESS read-create STATUS current DESCRIPTION "A pointer to another conceptual row in this usmUserTable. The user in this other conceptual row is called the clone-from user. When a new user is created (i.e., a new conceptual row is instantiated in this table), the privacy and authentication parameters of the new user are cloned from its clone-from user. The first time an instance of this object is set by a management operation (either at or after its instantiation), the cloning process is invoked. Subsequent writes are successful but invoke no action to be taken by the receiver. The cloning process fails with an 'inconsistentName' error if the conceptual row representing the clone-from user is not in an active state when the cloning process is invoked. Cloning also causes the initial values of the secret authentication key and the secret encryption key of the new user to be set to the same value as the corresponding secret of the clone-from user. When this object is read, the ZeroDotZero OID is returned. " ::= { usmUserEntry 4 } usmUserAuthProtocol OBJECT-TYPE SYNTAX AutonomousType MAX-ACCESS read-create STATUS current DESCRIPTION "An indication of whether messages sent on behalf of this user to/from the SNMP engine identified by usmUserEngineID, can be authenticated, and if so, the type of authentication protocol which is used. An instance of this object is created concurrently with the creation of any other object instance for the same user (i.e., as part of the processing of the set operation which creates the first object instance in the same conceptual row). Once created, the value of an instance of this object can not be changed. If a set operation tries to set a value for an unknown or unsupported protocol, then a wrongValue error must be returned. " DEFVAL { usmHMACMD5AuthProtocol } ::= { usmUserEntry 5 } usmUserAuthKeyChange OBJECT-TYPE SYNTAX KeyChange -- typically (SIZE (0..32)) MAX-ACCESS read-create STATUS current DESCRIPTION "An object, which when modified, causes the secret authentication key used for messages sent on behalf of this user to/from the SNMP engine identified by usmUserEngineID, to be modified via a one-way function. The associated protocol is the usmUserAuthProtocol. The associated secret key is the user's secret authentication key (authKey). The associated hash algorithm is the algorithm used by the user's usmUserAuthProtocol. When creating a new user, it is an 'inconsistentName' error for a Set operation to refer to this object unless it is previously or concurrently initialized through a set operation on the corresponding value of usmUserCloneFrom. " DEFVAL { ''H } -- the empty string ::= { usmUserEntry 6 } usmUserOwnAuthKeyChange OBJECT-TYPE SYNTAX KeyChange -- typically (SIZE (0..32)) MAX-ACCESS read-create STATUS current DESCRIPTION "Behaves exactly as usmUserAuthKeyChange, with one notable difference: in order for the Set operation to succeed, the usmUserName of the operation requester must match the usmUserName that indexes the row which is targeted by this operation. The idea here is that access to this column can be public, since it will only allow a user to change his own secret authentication key (authKey). " DEFVAL { ''H } -- the empty string ::= { usmUserEntry 7 } usmUserPrivProtocol OBJECT-TYPE SYNTAX AutonomousType MAX-ACCESS read-create STATUS current DESCRIPTION "An indication of whether messages sent on behalf of this user to/from the SNMP engine identified by usmUserEngineID, can be protected from disclosure, and if so, the type of privacy protocol which is used. An instance of this object is created concurrently with the creation of any other object instance for the same user (i.e., as part of the processing of the set operation which creates the first object instance in the same conceptual row). Once created, the value of an instance of this object can not be changed. If a set operation tries to set a value for an unknown or unsupported protocol, then a wrongValue error must be returned. " DEFVAL { usmNoPrivProtocol } ::= { usmUserEntry 8 } usmUserPrivKeyChange OBJECT-TYPE SYNTAX KeyChange -- typically (SIZE (0..32)) MAX-ACCESS read-create STATUS current DESCRIPTION "An object, which when modified, causes the secret encryption key used for messages sent on behalf of this user to/from the SNMP engine identified by usmUserEngineID, to be modified via a one-way function. The associated protocol is the usmUserPrivProtocol. The associated secret key is the user's secret privacy key (privKey). The associated hash algorithm is the algorithm used by the user's usmUserAuthProtocol. When creating a new user, it is an 'inconsistentName' error for a set operation to refer to this object unless it is previously or concurrently initialized through a set operation on the corresponding value of usmUserCloneFrom. " DEFVAL { ''H } -- the empty string ::= { usmUserEntry 9 } usmUserOwnPrivKeyChange OBJECT-TYPE SYNTAX KeyChange -- typically (SIZE (0..32)) MAX-ACCESS read-create STATUS current DESCRIPTION "Behaves exactly as usmUserPrivKeyChange, with one notable difference: in order for the Set operation to succeed, the usmUserName of the operation requester must match the usmUserName that indexes the row which is targeted by this operation. The idea here is that access to this column can be public, since it will only allow a user to change his own secret privacy key (privKey). " DEFVAL { ''H } -- the empty string ::= { usmUserEntry 10 } usmUserPublic OBJECT-TYPE SYNTAX OCTET STRING (SIZE(0..32)) MAX-ACCESS read-create STATUS current DESCRIPTION "A publicly-readable value which is written as part of the procedure for changing a user's secret authentication and/or privacy key, and later read to determine whether the change of the secret was effected. " DEFVAL { ''H } -- the empty string ::= { usmUserEntry 11 } usmUserStorageType OBJECT-TYPE SYNTAX StorageType MAX-ACCESS read-create STATUS current DESCRIPTION "The storage type for this conceptual row. Conceptual rows having the value 'permanent' must allow write-access at a minimum to: - usmUserAuthKeyChange, usmUserOwnAuthKeyChange and usmUserPublic for a user who employs authentication, and - usmUserPrivKeyChange, usmUserOwnPrivKeyChange and usmUserPublic for a user who employs privacy. Note that any user who employs authentication or privacy must allow its secret(s) to be updated and thus cannot be 'readOnly'. " DEFVAL { nonVolatile } ::= { usmUserEntry 12 } usmUserStatus OBJECT-TYPE SYNTAX RowStatus MAX-ACCESS read-create STATUS current DESCRIPTION "The status of this conceptual row. Until instances of all corresponding columns are appropriately configured, the value of the corresponding instance of the usmUserStatus column is 'notReady'. In particular, a newly created row cannot be made active until the corresponding usmUserCloneFrom, usmUserAuthKeyChange, usmUserOwnAuthKeyChange, usmUserPrivKeyChange and usmUserOwnPrivKeyChange have all been set. The RowStatus TC [RFC1903] requires that this DESCRIPTION clause states under which circumstances other objects in this row can be modified: The value of this object has no effect on whether other objects in this conceptual row can be modified. " ::= { usmUserEntry 13 } -- Conformance Information ******************************************* usmMIBCompliances OBJECT IDENTIFIER ::= { usmMIBConformance 1 } usmMIBGroups OBJECT IDENTIFIER ::= { usmMIBConformance 2 } -- Compliance statements usmMIBCompliance MODULE-COMPLIANCE STATUS current DESCRIPTION "The compliance statement for SNMP engines which implement the SNMP-USER-BASED-SM-MIB. " MODULE -- this module MANDATORY-GROUPS { usmMIBBasicGroup } OBJECT usmUserAuthProtocol MIN-ACCESS read-only DESCRIPTION "Write access is not required." OBJECT usmUserPrivProtocol MIN-ACCESS read-only DESCRIPTION "Write access is not required." ::= { usmMIBCompliances 1 } -- Units of compliance usmMIBBasicGroup OBJECT-GROUP OBJECTS { usmStatsUnsupportedSecLevels, usmStatsNotInTimeWindows, usmStatsUnknownUserNames, usmStatsUnknownEngineIDs, usmStatsWrongDigests, usmStatsDecryptionErrors, usmUserSpinLock, usmUserSecurityName, usmUserCloneFrom, usmUserAuthProtocol, usmUserAuthKeyChange, usmUserOwnAuthKeyChange, usmUserPrivProtocol, usmUserPrivKeyChange, usmUserOwnPrivKeyChange, usmUserPublic, usmUserStorageType, usmUserStatus } STATUS current DESCRIPTION "A collection of objects providing for configuration of an SNMP engine which implements the SNMP User-based Security Model. " ::= { usmMIBGroups 1 } END -- -- Copyright (C) The Internet Society (1997). All Rights Reserved. -- -- This document and translations of it may be copied and furnished to -- others, and derivative works that comment on or otherwise explain it -- or assist in its implementation may be prepared, copied, published -- and distributed, in whole or in part, without restriction of any -- kind, provided that the above copyright notice and this paragraph are -- included on all such copies and derivative works. However, this -- document itself may not be modified in any way, such as by removing -- the copyright notice or references to the Internet Society or other -- Internet organizations, except as needed for the purpose of -- developing Internet standards in which case the procedures for -- copyrights defined in the Internet Standards process must be -- followed, or as required to translate it into languages other than -- English. -- -- The limited permissions granted above are perpetual and will not be -- revoked by the Internet Society or its successors or assigns. -- -- This document and the information contained herein is provided on an -- "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING -- TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING -- BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION -- HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF -- MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.