RFC 2574
User-based Security Model (USM) for version 3 of the Simple Network Management Protocol (SNMPv3)
4. Discovery
The User-based Security Model requires that a discovery process obtains sufficient information about other SNMP engines in order to communicate with them. Discovery requires an non-authoritative SNMP engine to learn the authoritative SNMP engine's snmpEngineID value before communication may proceed. This may be accomplished by generating a Request message with a securityLevel of noAuthNoPriv, a msgUserName of zero-length, a msgAuthoritativeEngineID value of zero length, and the varBindList left empty. The response to this message will be a Report message containing the snmpEngineID of the authoritative SNMP engine as the value of the msgAuthoritativeEngineID field within the msgSecurityParameters field. It contains a Report PDU with the usmStatsUnknownEngineIDs counter in the varBindList.
If authenticated communication is required, then the discovery process should also establish time synchronization with the authoritative SNMP engine. This may be accomplished by sending an authenticated Request message with the value of msgAuthoritativeEngineID set to the newly learned snmpEngineID and with the values of msgAuthoritativeEngineBoots and msgAuthoritativeEngineTime set to zero. For an authenticated Request message, a valid userName must be used in the msgUserName field. The response to this authenticated message will be a Report message containing the up to date values of the authoritative SNMP engine's snmpEngineBoots and snmpEngineTime as the value of the msgAuthoritativeEngineBoots and msgAuthoritativeEngineTime fields respectively. It also contains the usmStatsNotInTimeWindows counter in the varBindList of the Report PDU. The time synchronization then happens automatically as part of the procedures in section 3.2 step 7b. See also section 2.3.5. Definitions
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 "9901200000Z" -- 20 Jan 1999, midnight ORGANIZATION "SNMPv3 Working Group" CONTACT-INFO "WG-email: snmpv3@lists.tislabs.com Subscribe: majordomo@lists.tislabs.com In msg body: subscribe snmpv3 Chair: Russ Mundy Trusted Information Systems postal: 3060 Washington Rd Glenwood MD 21738 USA email: mundy@tislabs.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.
"
-- Revision history
REVISION "9901200000Z" -- 20 Jan 1999, midnight
DESCRIPTION "Clarifications, published as RFC2574"
REVISION "9711200000Z" -- 20 Nov 1997, midnight
DESCRIPTION "Initial version, published as RFC2274"
::= { snmpModules 15 }
-- 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 requester 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 keyNew 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 recipient 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
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.
Note that the keyOld and keyNew are the localized keys.
Note that it is probably wise that when an SNMP entity sends
a SetRequest to change a key, that it keeps a copy of the old
key until it has confirmed that the key change actually
succeeded.
"
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).
To create a new user (i.e., to instantiate a new
conceptual row in this table), it is recommended to
follow this procedure:
1) GET(usmUserSpinLock.0) and save in sValue.
2) SET(usmUserSpinLock.0=sValue,
usmUserCloneFrom=templateUser,
usmUserStatus=createAndWait)
You should use a template user to clone from
which has the proper auth/priv protocol defined.
If the new user is to use privacy:
3) generate the keyChange value based on the secret
privKey of the clone-from user and the secret key
to be used for the new user. Let us call this
pkcValue.
4) GET(usmUserSpinLock.0) and save in sValue.
5) SET(usmUserSpinLock.0=sValue,
usmUserPrivKeyChange=pkcValue
usmUserPublic=randomValue1)
6) GET(usmUserPulic) and check it has randomValue1.
If not, repeat steps 4-6.
If the new user will never use privacy:
7) SET(usmUserPrivProtocol=usmNoPrivProtocol)
If the new user is to use authentication:
8) generate the keyChange value based on the secret
authKey of the clone-from user and the secret key
to be used for the new user. Let us call this
akcValue.
9) GET(usmUserSpinLock.0) and save in sValue.
10) SET(usmUserSpinLock.0=sValue,
usmUserAuthKeyChange=akcValue
usmUserPublic=randomValue2)
11) GET(usmUserPulic) and check it has randomValue2.
If not, repeat steps 9-11.
If the new user will never use authentication:
12) SET(usmUserAuthProtocol=usmNoAuthProtocol)
Finally, activate the new user:
13) SET(usmUserStatus=active)
The new user should now be available and ready to be
used for SNMPv3 communication. Note however that access
to MIB data must be provided via configuration of the
SNMP-VIEW-BASED-ACM-MIB.
The use of usmUserSpinlock is to avoid conflicts with
another SNMP command responder application which may
also be acting on the usmUserTable.
"
::= { 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 must be
cloned from its clone-from user. These parameters are:
- authentication protocol (usmUserAuthProtocol)
- privacy protocol (usmUserPrivProtocol)
They will be copied regardless of what the current
value is.
Cloning also causes the initial values of the secret
authentication key (authKey) and the secret encryption
key (privKey) of the new user to be set to the same
value as the corresponding secret of the 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 does not exist or is not in an active
state when the cloning process is invoked.
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).
If an initial set operation (i.e. at row creation time)
tries to set a value for an unknown or unsupported
protocol, then a 'wrongValue' error must be returned.
The value will be overwritten/set when a set operation
is performed on the corresponding instance of
usmUserCloneFrom.
Once instantiated, the value of such an instance of
this object can only be changed via a set operation to
the value of the usmNoAuthProtocol.
If a set operation tries to change the value of an
existing instance of this object to any value other
than usmNoAuthProtocol, then an 'inconsistentValue'
error must be returned.
If a set operation tries to set the value to the
usmNoAuthProtocol while the usmUserPrivProtocol value
in the same row is not equal to usmNoPrivProtocol,
then an 'inconsistentValue' error must be returned.
That means that an SNMP command generator application
must first ensure that the usmUserPrivProtocol is set
to the usmNoPrivProtocol value before it can set
the usmUserAuthProtocol value to usmNoAuthProtocol.
"
DEFVAL { usmNoAuthProtocol }
::= { usmUserEntry 5 }
usmUserAuthKeyChange OBJECT-TYPE
SYNTAX KeyChange -- typically (SIZE (0 | 32)) for HMACMD5
-- typically (SIZE (0 | 40)) for HMACSHA
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 instance
of usmUserCloneFrom.
When the value of the corresponding usmUserAuthProtocol
is usmNoAuthProtocol, then a set is successful, but
effectively is a no-op.
When this object is read, the zero-length (empty)
string is returned.
The recommended way to do a key change is as follows:
1) GET(usmUserSpinLock.0) and save in sValue.
2) generate the keyChange value based on the old
(existing) secret key and the new secret key,
let us call this kcValue.
If you do the key change on behalf of another user:
3) SET(usmUserSpinLock.0=sValue,
usmUserAuthKeyChange=kcValue
usmUserPublic=randomValue)
If you do the key change for yourself:
4) SET(usmUserSpinLock.0=sValue,
usmUserOwnAuthKeyChange=kcValue
usmUserPublic=randomValue)
If you get a response with error-status of noError,
then the SET succeeded and the new key is active.
If you do not get a response, then you can issue a
GET(usmUserPublic) and check if the value is equal
to the randomValue you did send in the SET. If so, then
the key change succeeded and the new key is active
(probably the response got lost). If not, then the SET
request probably never reached the target and so you
can start over with the procedure above.
"
DEFVAL { ''H } -- the empty string
::= { usmUserEntry 6 }
usmUserOwnAuthKeyChange OBJECT-TYPE
SYNTAX KeyChange -- typically (SIZE (0 | 32)) for HMACMD5
-- typically (SIZE (0 | 40)) for HMACSHA
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.
In addition, the USM security model must be
used for 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).
Note that this can only be done once the row is active.
When a set is received and the usmUserName of the
requester is not the same as the umsUserName that
indexes the row which is targeted by this operation,
then a 'noAccess' error must be returned.
When a set is received and the security model in use
is not USM, then a 'noAccess' error must be returned.
"
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).
If an initial set operation (i.e. at row creation time)
tries to set a value for an unknown or unsupported
protocol, then a 'wrongValue' error must be returned.
The value will be overwritten/set when a set operation
is performed on the corresponding instance of
usmUserCloneFrom.
Once instantiated, the value of such an instance of
this object can only be changed via a set operation to
the value of the usmNoPrivProtocol.
If a set operation tries to change the value of an
existing instance of this object to any value other
than usmNoPrivProtocol, then an 'inconsistentValue'
error must be returned.
Note that if any privacy protocol is used, then you
must also use an authentication protocol. In other
words, if usmUserPrivProtocol is set to anything else
than usmNoPrivProtocol, then the corresponding instance
of usmUserAuthProtocol cannot have a value of
usmNoAuthProtocol. If it does, then an
'inconsistentValue' error must be returned.
"
DEFVAL { usmNoPrivProtocol }
::= { usmUserEntry 8 }
usmUserPrivKeyChange OBJECT-TYPE
SYNTAX KeyChange -- typically (SIZE (0 | 32)) for DES
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 instance
of usmUserCloneFrom.
When the value of the corresponding usmUserPrivProtocol
is usmNoPrivProtocol, then a set is successful, but
effectively is a no-op.
When this object is read, the zero-length (empty)
string is returned.
See the description clause of usmUserAuthKeyChange for
a recommended procedure to do a key change.
"
DEFVAL { ''H } -- the empty string
::= { usmUserEntry 9 }
usmUserOwnPrivKeyChange OBJECT-TYPE
SYNTAX KeyChange -- typically (SIZE (0 | 32)) for DES
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.
In addition, the USM security model must be
used for 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).
Note that this can only be done once the row is active.
When a set is received and the usmUserName of the
requester is not the same as the umsUserName that
indexes the row which is targeted by this operation,
then a 'noAccess' error must be returned.
When a set is received and the security model in use
is not USM, then a 'noAccess' error must be returned.
"
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 can be 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'.
If an initial set operation tries to set the value to
'readOnly' for a user who employs authentication or
privacy, then an 'inconsistentValue' error must be
returned. Note that if the value has been previously
set (implicit or explicit) to any value, then the rules
as defined in the StorageType Textual Convention apply.
It is an implementation issue to decide if a SET for
a readOnly or permanent row is accepted at all. In some
contexts this may make sense, in others it may not. If
a SET for a readOnly or permanent row is not accepted
at all, then a 'wrongValue' error must be returned.
"
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 for a user who
employs authentication, cannot be made active until the
corresponding usmUserCloneFrom and usmUserAuthKeyChange
have been set.
Further, a newly created row for a user who also
employs privacy, cannot be made active until the
usmUserPrivKeyChange has been set.
The RowStatus TC [RFC2579] 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,
except for usmUserOwnAuthKeyChange and
usmUserOwnPrivKeyChange. For these 2 objects, the
value of usmUserStatus MUST be active.
"
::= { 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
6. HMAC-MD5-96 Authentication Protocol
This section describes the HMAC-MD5-96 authentication protocol. This authentication protocol is the first defined for the User-based Security Model. It uses MD5 hash-function which is described in [MD5], in HMAC mode described in [RFC2104], truncating the output to 96 bits. This protocol is identified by usmHMACMD5AuthProtocol. Over time, other authentication protocols may be defined either as a replacement of this protocol or in addition to this protocol.6.1. Mechanisms
- In support of data integrity, a message digest algorithm is required. A digest is calculated over an appropriate portion of an SNMP message and included as part of the message sent to the recipient. - In support of data origin authentication and data integrity, a secret value is prepended to SNMP message prior to computing the digest; the calculated digest is partially inserted into the SNMP message prior to transmission, and the prepended value is not transmitted. The secret value is shared by all SNMP engines authorized to originate messages on behalf of the appropriate user.6.1.1. Digest Authentication Mechanism
The Digest Authentication Mechanism defined in this memo provides for: - verification of the integrity of a received message, i.e., the message received is the message sent. The integrity of the message is protected by computing a digest over an appropriate portion of the message. The digest is computed by the originator of the message, transmitted with the message, and verified by the recipient of the message. - verification of the user on whose behalf the message was generated. A secret value known only to SNMP engines authorized to generate messages on behalf of a user is used in HMAC mode (see [RFC2104]). It also recommends the hash-function output used as Message Authentication Code, to be truncated.
This protocol uses the MD5 [MD5] message digest algorithm. A 128-bit MD5 digest is calculated in a special (HMAC) way over the designated portion of an SNMP message and the first 96 bits of this digest is included as part of the message sent to the recipient. The size of the digest carried in a message is 12 octets. The size of the private authentication key (the secret) is 16 octets. For the details see section 6.3.6.2. Elements of the Digest Authentication Protocol
This section contains definitions required to realize the authentication module defined in this section of this memo.6.2.1. Users
Authentication using this authentication protocol makes use of a defined set of userNames. For any user on whose behalf a message must be authenticated at a particular SNMP engine, that SNMP engine must have knowledge of that user. An SNMP engine that wishes to communicate with another SNMP engine must also have knowledge of a user known to that engine, including knowledge of the applicable attributes of that user. A user and its attributes are defined as follows: <userName> A string representing the name of the user. <authKey> A user's secret key to be used when calculating a digest. It MUST be 16 octets long for MD5.6.2.2. msgAuthoritativeEngineID
The msgAuthoritativeEngineID value contained in an authenticated message specifies the authoritative SNMP engine for that particular message (see the definition of SnmpEngineID in the SNMP Architecture document [RFC2571]). The user's (private) authentication key is normally different at each authoritative SNMP engine and so the snmpEngineID is used to select the proper key for the authentication process.6.2.3. SNMP Messages Using this Authentication Protocol
Messages using this authentication protocol carry a msgAuthenticationParameters field as part of the msgSecurityParameters. For this protocol, the
msgAuthenticationParameters field is the serialized OCTET STRING representing the first 12 octets of the HMAC-MD5-96 output done over the wholeMsg. The digest is calculated over the wholeMsg so if a message is authenticated, that also means that all the fields in the message are intact and have not been tampered with.6.2.4. Services provided by the HMAC-MD5-96 Authentication Module
This section describes the inputs and outputs that the HMAC-MD5-96 Authentication module expects and produces when the User-based Security module calls the HMAC-MD5-96 Authentication module for services.6.2.4.1. Services for Generating an Outgoing SNMP Message
The HMAC-MD5-96 authentication protocol assumes that the selection of the authKey is done by the caller and that the caller passes the secret key to be used. Upon completion the authentication module returns statusInformation and, if the message digest was correctly calculated, the wholeMsg with the digest inserted at the proper place. The abstract service primitive is: statusInformation = -- success or failure authenticateOutgoingMsg( IN authKey -- secret key for authentication IN wholeMsg -- unauthenticated complete message OUT authenticatedWholeMsg -- complete authenticated message ) The abstract data elements are: statusInformation An indication of whether the authentication process was successful. If not it is an indication of the problem. authKey The secret key to be used by the authentication algorithm. The length of this key MUST be 16 octets. wholeMsg The message to be authenticated. authenticatedWholeMsg The authenticated message (including inserted digest) on output.
Note, that authParameters field is filled by the authentication module and this module and this field should be already present in the wholeMsg before the Message Authentication Code (MAC) is generated.6.2.4.2. Services for Processing an Incoming SNMP Message
The HMAC-MD5-96 authentication protocol assumes that the selection of the authKey is done by the caller and that the caller passes the secret key to be used. Upon completion the authentication module returns statusInformation and, if the message digest was correctly calculated, the wholeMsg as it was processed. The abstract service primitive is: statusInformation = -- success or failure authenticateIncomingMsg( IN authKey -- secret key for authentication IN authParameters -- as received on the wire IN wholeMsg -- as received on the wire OUT authenticatedWholeMsg -- complete authenticated message ) The abstract data elements are: statusInformation An indication of whether the authentication process was successful. If not it is an indication of the problem. authKey The secret key to be used by the authentication algorithm. The length of this key MUST be 16 octets. authParameters The authParameters from the incoming message. wholeMsg The message to be authenticated on input and the authenticated message on output. authenticatedWholeMsg The whole message after the authentication check is complete.6.3. Elements of Procedure
This section describes the procedures for the HMAC-MD5-96 authentication protocol.
6.3.1. Processing an Outgoing Message
This section describes the procedure followed by an SNMP engine whenever it must authenticate an outgoing message using the usmHMACMD5AuthProtocol. 1) The msgAuthenticationParameters field is set to the serialization, according to the rules in [RFC1906], of an OCTET STRING containing 12 zero octets. 2) From the secret authKey, two keys K1 and K2 are derived: a) extend the authKey to 64 octets by appending 48 zero octets; save it as extendedAuthKey b) obtain IPAD by replicating the octet 0x36 64 times; c) obtain K1 by XORing extendedAuthKey with IPAD; d) obtain OPAD by replicating the octet 0x5C 64 times; e) obtain K2 by XORing extendedAuthKey with OPAD. 3) Prepend K1 to the wholeMsg and calculate MD5 digest over it according to [MD5]. 4) Prepend K2 to the result of the step 4 and calculate MD5 digest over it according to [MD5]. Take the first 12 octets of the final digest - this is Message Authentication Code (MAC). 5) Replace the msgAuthenticationParameters field with MAC obtained in the step 4. 6) The authenticatedWholeMsg is then returned to the caller together with statusInformation indicating success.6.3.2. Processing an Incoming Message
This section describes the procedure followed by an SNMP engine whenever it must authenticate an incoming message using the usmHMACMD5AuthProtocol. 1) If the digest received in the msgAuthenticationParameters field is not 12 octets long, then an failure and an errorIndication (authenticationError) is returned to the calling module. 2) The MAC received in the msgAuthenticationParameters field is saved. 3) The digest in the msgAuthenticationParameters field is replaced by the 12 zero octets.
4) From the secret authKey, two keys K1 and K2 are derived:
a) extend the authKey to 64 octets by appending 48 zero
octets; save it as extendedAuthKey
b) obtain IPAD by replicating the octet 0x36 64 times;
c) obtain K1 by XORing extendedAuthKey with IPAD;
d) obtain OPAD by replicating the octet 0x5C 64 times;
e) obtain K2 by XORing extendedAuthKey with OPAD.
5) The MAC is calculated over the wholeMsg:
a) prepend K1 to the wholeMsg and calculate the MD5 digest
over it;
b) prepend K2 to the result of step 5.a and calculate the
MD5 digest over it;
c) first 12 octets of the result of step 5.b is the MAC.
The msgAuthenticationParameters field is replaced with the MAC
value that was saved in step 2.
6) Then the newly calculated MAC is compared with the MAC
saved in step 2. If they do not match, then an failure and an
errorIndication (authenticationFailure) is returned to the
calling module.
7) The authenticatedWholeMsg and statusInformation indicating
success are then returned to the caller.
7. HMAC-SHA-96 Authentication Protocol
This section describes the HMAC-SHA-96 authentication protocol. This
protocol uses the SHA hash-function which is described in [SHA-NIST],
in HMAC mode described in [RFC2104], truncating the output to 96
bits.
This protocol is identified by usmHMACSHAAuthProtocol.
Over time, other authentication protocols may be defined either as a
replacement of this protocol or in addition to this protocol.
7.1. Mechanisms
- In support of data integrity, a message digest algorithm is
required. A digest is calculated over an appropriate portion of an
SNMP message and included as part of the message sent to the
recipient.
- In support of data origin authentication and data integrity,
a secret value is prepended to the SNMP message prior to computing
the digest; the calculated digest is then partially inserted into
the message prior to transmission. The prepended secret is not
transmitted. The secret value is shared by all SNMP engines
authorized to originate messages on behalf of the appropriate user.
7.1.1. Digest Authentication Mechanism
The Digest Authentication Mechanism defined in this memo provides
for:
- verification of the integrity of a received message, i.e., the
the message received is the message sent.
The integrity of the message is protected by computing a digest
over an appropriate portion of the message. The digest is computed
by the originator of the message, transmitted with the message, and
verified by the recipient of the message.
- verification of the user on whose behalf the message was generated.
A secret value known only to SNMP engines authorized to generate
messages on behalf of a user is used in HMAC mode (see [RFC2104]).
It also recommends the hash-function output used as Message
Authentication Code, to be truncated.
This mechanism uses the SHA [SHA-NIST] message digest algorithm. A
160-bit SHA digest is calculated in a special (HMAC) way over the
designated portion of an SNMP message and the first 96 bits of this
digest is included as part of the message sent to the recipient. The
size of the digest carried in a message is 12 octets. The size of the
private authentication key (the secret) is 20 octets. For the details
see section 7.3.
7.2. Elements of the HMAC-SHA-96 Authentication Protocol
This section contains definitions required to realize the
authentication module defined in this section of this memo.
7.2.1. Users
Authentication using this authentication protocol makes use of a
defined set of userNames. For any user on whose behalf a message
must be authenticated at a particular SNMP engine, that SNMP engine
must have knowledge of that user. An SNMP engine that wishes to
communicate with another SNMP engine must also have knowledge of a
user known to that engine, including knowledge of the applicable
attributes of that user.
A user and its attributes are defined as follows:
<userName>
A string representing the name of the user.
<authKey>
A user's secret key to be used when calculating a digest.
It MUST be 20 octets long for SHA.
7.2.2. msgAuthoritativeEngineID
The msgAuthoritativeEngineID value contained in an authenticated
message specifies the authoritative SNMP engine for that particular
message (see the definition of SnmpEngineID in the SNMP Architecture
document [RFC2571]).
The user's (private) authentication key is normally different at each
authoritative SNMP engine and so the snmpEngineID is used to select
the proper key for the authentication process.
7.2.3. SNMP Messages Using this Authentication Protocol
Messages using this authentication protocol carry a
msgAuthenticationParameters field as part of the
msgSecurityParameters. For this protocol, the
msgAuthenticationParameters field is the serialized OCTET STRING
representing the first 12 octets of HMAC-SHA-96 output done over the
wholeMsg.
The digest is calculated over the wholeMsg so if a message is
authenticated, that also means that all the fields in the message are
intact and have not been tampered with.
7.2.4. Services provided by the HMAC-SHA-96 Authentication Module
This section describes the inputs and outputs that the HMAC-SHA-96
Authentication module expects and produces when the User-based
Security module calls the HMAC-SHA-96 Authentication module for
services.
7.2.4.1. Services for Generating an Outgoing SNMP Message
HMAC-SHA-96 authentication protocol assumes that the selection of the
authKey is done by the caller and that the caller passes the secret
key to be used.
Upon completion the authentication module returns statusInformation
and, if the message digest was correctly calculated, the wholeMsg
with the digest inserted at the proper place. The abstract service
primitive is:
statusInformation = -- success or failure
authenticateOutgoingMsg(
IN authKey -- secret key for authentication
IN wholeMsg -- unauthenticated complete message
OUT authenticatedWholeMsg -- complete authenticated message
)
The abstract data elements are:
statusInformation
An indication of whether the authentication process was
successful. If not it is an indication of the problem.
authKey
The secret key to be used by the authentication algorithm.
The length of this key MUST be 20 octets.
wholeMsg
The message to be authenticated.
authenticatedWholeMsg
The authenticated message (including inserted digest) on output.
Note, that authParameters field is filled by the authentication
module and this field should be already present in the wholeMsg
before the Message Authentication Code (MAC) is generated.
7.2.4.2. Services for Processing an Incoming SNMP Message
HMAC-SHA-96 authentication protocol assumes that the selection of the
authKey is done by the caller and that the caller passes the secret
key to be used.
Upon completion the authentication module returns statusInformation
and, if the message digest was correctly calculated, the wholeMsg as
it was processed. The abstract service primitive is:
statusInformation = -- success or failure
authenticateIncomingMsg(
IN authKey -- secret key for authentication
IN authParameters -- as received on the wire
IN wholeMsg -- as received on the wire
OUT authenticatedWholeMsg -- complete authenticated message
)
The abstract data elements are:
statusInformation
An indication of whether the authentication process was
successful. If not it is an indication of the problem.
authKey
The secret key to be used by the authentication algorithm.
The length of this key MUST be 20 octets.
authParameters
The authParameters from the incoming message.
wholeMsg
The message to be authenticated on input and the authenticated
message on output.
authenticatedWholeMsg
The whole message after the authentication check is complete.
7.3. Elements of Procedure
This section describes the procedures for the HMAC-SHA-96
authentication protocol.
7.3.1. Processing an Outgoing Message
This section describes the procedure followed by an SNMP engine
whenever it must authenticate an outgoing message using the
usmHMACSHAAuthProtocol.
1) The msgAuthenticationParameters field is set to the
serialization, according to the rules in [RFC1906], of an OCTET
STRING containing 12 zero octets.
2) From the secret authKey, two keys K1 and K2 are derived:
a) extend the authKey to 64 octets by appending 44 zero
octets; save it as extendedAuthKey
b) obtain IPAD by replicating the octet 0x36 64 times;
c) obtain K1 by XORing extendedAuthKey with IPAD;
d) obtain OPAD by replicating the octet 0x5C 64 times;
e) obtain K2 by XORing extendedAuthKey with OPAD.
3) Prepend K1 to the wholeMsg and calculate the SHA digest over it
according to [SHA-NIST].
4) Prepend K2 to the result of the step 4 and calculate SHA digest
over it according to [SHA-NIST]. Take the first 12 octets of the
final digest - this is Message Authentication Code (MAC).
5) Replace the msgAuthenticationParameters field with MAC obtained
in the step 5.
6) The authenticatedWholeMsg is then returned to the caller
together with statusInformation indicating success.
7.3.2. Processing an Incoming Message
This section describes the procedure followed by an SNMP engine
whenever it must authenticate an incoming message using the
usmHMACSHAAuthProtocol.
1) If the digest received in the msgAuthenticationParameters field
is not 12 octets long, then an failure and an errorIndication
(authenticationError) is returned to the calling module.
2) The MAC received in the msgAuthenticationParameters field
is saved.
3) The digest in the msgAuthenticationParameters field is
replaced by the 12 zero octets.
4) From the secret authKey, two keys K1 and K2 are derived:
a) extend the authKey to 64 octets by appending 44 zero
octets; save it as extendedAuthKey
b) obtain IPAD by replicating the octet 0x36 64 times;
c) obtain K1 by XORing extendedAuthKey with IPAD;
d) obtain OPAD by replicating the octet 0x5C 64 times;
e) obtain K2 by XORing extendedAuthKey with OPAD.
5) The MAC is calculated over the wholeMsg:
a) prepend K1 to the wholeMsg and calculate the SHA digest
over it;
b) prepend K2 to the result of step 5.a and calculate the
SHA digest over it;
c) first 12 octets of the result of step 5.b is the MAC.
The msgAuthenticationParameters field is replaced with the MAC
value that was saved in step 2.
6) The the newly calculated MAC is compared with the MAC saved in
step 2. If they do not match, then a failure and an
errorIndication (authenticationFailure) are returned to the
calling module.
7) The authenticatedWholeMsg and statusInformation indicating
success are then returned to the caller.
(page 61 continued on part 3)
