------------------ ---------------
usmUserEngineID localEngineID localEngineID
usmUserName "templateMD5" "templateMD5"
usmUserSecurityName "templateMD5" "templateMD5"
usmUserCloneFrom ZeroDotZero ZeroDotZero
usmUserAuthProtocol usmHMACMD5AuthProtocol usmHMACMD5AuthProtocol
usmUserAuthKeyChange "" ""
usmUserOwnAuthKeyChange "" ""
usmUserPrivProtocol none usmDESPrivProtocol
usmUserPrivKeyChange "" ""
usmUserOwnPrivKeyChange "" ""
usmUserPublic "" ""
usmUserStorageType permanent permanent
usmUserStatus active active
no privacy support privacy support
------------------ ---------------
usmUserEngineID localEngineID localEngineID
usmUserName "templateSHA" "templateSHA"
usmUserSecurityName "templateSHA" "templateSHA"
usmUserCloneFrom ZeroDotZero ZeroDotZero
usmUserAuthProtocol usmHMACSHAAuthProtocol usmHMACSHAAuthProtocol
usmUserAuthKeyChange "" ""
usmUserOwnAuthKeyChange "" ""
usmUserPrivProtocol none usmDESPrivProtocol
usmUserPrivKeyChange "" ""
usmUserOwnPrivKeyChange "" ""
usmUserPublic "" ""
usmUserStorageType permanent permanent
usmUserStatus active active
A.2. Password to Key Algorithm
A sample code fragment (section A.2.1) demonstrates the password to
key algorithm which can be used when mapping a password to an
authentication or privacy key using MD5. The reference source code
of MD5 is available in [RFC1321].
Another sample code fragment (section A.2.2) demonstrates the
password to key algorithm which can be used when mapping a password
to an authentication or privacy key using SHA (documented in
SHA-NIST).
An example of the results of a correct implementation is provided
(section A.3) which an implementor can use to check if his
implementation produces the same result.
A.2.1. Password to Key Sample Code for MD5
void password_to_key_md5(
u_char *password, /* IN */
u_int passwordlen, /* IN */
u_char *engineID, /* IN - pointer to snmpEngineID */
u_int engineLength,/* IN - length of snmpEngineID */
u_char *key) /* OUT - pointer to caller 16-octet buffer */
{
MD5_CTX MD;
u_char *cp, password_buf[64];
u_long password_index = 0;
u_long count = 0, i;
MD5Init (&MD); /* initialize MD5 */
/**********************************************/
/* Use while loop until we've done 1 Megabyte */
/**********************************************/
while (count < 1048576) {
cp = password_buf;
for (i = 0; i < 64; i++) {
/*************************************************/
/* Take the next octet of the password, wrapping */
/* to the beginning of the password as necessary.*/
/*************************************************/
*cp++ = password[password_index++ % passwordlen];
}
MD5Update (&MD, password_buf, 64);
count += 64;
}
MD5Final (key, &MD); /* tell MD5 we're done */
/*****************************************************/
/* Now localize the key with the engineID and pass */
/* through MD5 to produce final key */
/* May want to ensure that engineLength <= 32, */
/* otherwise need to use a buffer larger than 64 */
/*****************************************************/
memcpy(password_buf, key, 16);
memcpy(password_buf+16, engineID, engineLength);
memcpy(password_buf+16+engineLength, key, 16);
MD5Init(&MD);
MD5Update(&MD, password_buf, 32+engineLength);
MD5Final(key, &MD);
return;
}
A.2.2. Password to Key Sample Code for SHA
void password_to_key_sha(
u_char *password, /* IN */
u_int passwordlen, /* IN */
u_char *engineID, /* IN - pointer to snmpEngineID */
u_int engineLength,/* IN - length of snmpEngineID */
u_char *key) /* OUT - pointer to caller 20-octet buffer */
{
SHA_CTX SH;
u_char *cp, password_buf[72];
u_long password_index = 0;
u_long count = 0, i;
SHAInit (&SH); /* initialize SHA */
/**********************************************/
/* Use while loop until we've done 1 Megabyte */
/**********************************************/
while (count < 1048576) {
cp = password_buf;
for (i = 0; i < 64; i++) {
/*************************************************/
/* Take the next octet of the password, wrapping */
/* to the beginning of the password as necessary.*/
/*************************************************/
*cp++ = password[password_index++ % passwordlen];
}
SHAUpdate (&SH, password_buf, 64);
count += 64;
}
SHAFinal (key, &SH); /* tell SHA we're done */
/*****************************************************/
/* Now localize the key with the engineID and pass */
/* through SHA to produce final key */
/* May want to ensure that engineLength <= 32, */
/* otherwise need to use a buffer larger than 72 */
/*****************************************************/
memcpy(password_buf, key, 20);
memcpy(password_buf+20, engineID, engineLength);
memcpy(password_buf+20+engineLength, key, 20);
SHAInit(&SH);
SHAUpdate(&SH, password_buf, 40+engineLength);
SHAFinal(key, &SH);
return;
}
A.3. Password to Key Sample Results
A.3.1. Password to Key Sample Results using MD5
The following shows a sample output of the password to key algorithm
for a 16-octet key using MD5.
With a password of "maplesyrup" the output of the password to key
algorithm before the key is localized with the SNMP engine's
snmpEngineID is:
'9f af 32 83 88 4e 92 83 4e bc 98 47 d8 ed d9 63'H
After the intermediate key (shown above) is localized with the
snmpEngineID value of:
'00 00 00 00 00 00 00 00 00 00 00 02'H
the final output of the password to key algorithm is:
'52 6f 5e ed 9f cc e2 6f 89 64 c2 93 07 87 d8 2b'H
A.3.2. Password to Key Sample Results using SHA
The following shows a sample output of the password to key
algorithm for a 20-octet key using SHA.
With a password of "maplesyrup" the output of the password to key
algorithm before the key is localized with the SNMP engine's
snmpEngineID is:
'9f b5 cc 03 81 49 7b 37 93 52 89 39 ff 78 8d 5d 79 14 52 11'H
After the intermediate key (shown above) is localized with the
snmpEngineID value of:
'00 00 00 00 00 00 00 00 00 00 00 02'H
the final output of the password to key algorithm is:
'66 95 fe bc 92 88 e3 62 82 23 5f c7 15 1f 12 84 97 b3 8f 3f'H
A.4. Sample encoding of msgSecurityParameters
The msgSecurityParameters in an SNMP message are represented as an
OCTET STRING. This OCTET STRING should be considered opaque outside a
specific Security Model.
The User-based Security Model defines the contents of the OCTET
STRING as a SEQUENCE (see section 2.4).
Given these two properties, the following is an example of the
msgSecurityParameters for the User-based Security Model, encoded as
an OCTET STRING:
04 <length>
30 <length>
04 <length> <msgAuthoritativeEngineID>
02 <length> <msgAuthoritativeEngineBoots>
02 <length> <msgAuthoritativeEngineTime>
04 <length> <msgUserName>
04 0c <HMAC-MD5-96-digest>
04 08 <salt>
Here is the example once more, but now with real values (except for
the digest in msgAuthenticationParameters and the salt in
msgPrivacyParameters, which depend on variable data that we have not
defined here):
Hex Data Description
-------------- -----------------------------------------------
04 39 OCTET STRING, length 57
30 37 SEQUENCE, length 55
04 0c 80000002 msgAuthoritativeEngineID: IBM
01 IPv4 address
09840301 9.132.3.1
02 01 01 msgAuthoritativeEngineBoots: 1
02 02 0101 msgAuthoritativeEngineTime: 257
04 04 62657274 msgUserName: bert
04 0c 01234567 msgAuthenticationParameters: sample value
89abcdef
fedcba98
04 08 01234567 msgPrivacyParameters: sample value
89abcdef
A.5. Sample keyChange Results
A.5.1. Sample keyChange Results using MD5
Let us assume that a user has a current password of "maplesyrup" as
in section A.3.1. and let us also assume the snmpEngineID of 12
octets:
'00 00 00 00 00 00 00 00 00 00 00 02'H
If we now want to change the password to "newsyrup", then we first
calculate the key for the new password. It is as follows:
'01 ad d2 73 10 7c 4e 59 6b 4b 00 f8 2b 1d 42 a7'H
If we localize it for the above snmpEngineID, then the localized new
key becomes:
'87 02 1d 7b d9 d1 01 ba 05 ea 6e 3b f9 d9 bd 4a'H
If we then use a (not so good, but easy to test) random value of:
'00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00'H
Then the value we must send for keyChange is:
'00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
88 05 61 51 41 67 6c c9 19 61 74 e7 42 a3 25 51'H
If this were for the privacy key, then it would be exactly the same.
A.5.2. Sample keyChange Results using SHA
Let us assume that a user has a current password of "maplesyrup" as
in section A.3.2. and let us also assume the snmpEngineID of 12
octets:
'00 00 00 00 00 00 00 00 00 00 00 02'H
If we now want to change the password to "newsyrup", then we first
calculate the key for the new password. It is as follows:
'3a 51 a6 d7 36 aa 34 7b 83 dc 4a 87 e3 e5 5e e4 d6 98 ac 71'H
If we localize it for the above snmpEngineID, then the localized new
key becomes:
'78 e2 dc ce 79 d5 94 03 b5 8c 1b ba a5 bf f4 63 91 f1 cd 25'H
If we then use a (not so good, but easy to test) random value of:
'00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00'H
Then the value we must send for keyChange is:
'00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
9c 10 17 f4 fd 48 3d 2d e8 d5 fa db f8 43 92 cb 06 45 70 51'
For the key used for privacy, the new nonlocalized key would be:
'3a 51 a6 d7 36 aa 34 7b 83 dc 4a 87 e3 e5 5e e4 d6 98 ac 71'H
For the key used for privacy, the new localized key would be (note
that they localized key gets truncated to 16 octets for DES):
'78 e2 dc ce 79 d5 94 03 b5 8c 1b ba a5 bf f4 63'H
If we then use a (not so good, but easy to test) random value of:
'00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00'H
Then the value we must send for keyChange for the privacy key is:
'00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
'7e f8 d8 a4 c9 cd b2 6b 47 59 1c d8 52 ff 88 b5'H
B. Change Log
Changes made since RFC2274:
- Fixed msgUserName to allow size of zero and explain that this can
be used for snmpEngineID discovery.
- Clarified section 3.1 steps 4.b, 5, 6 and 8.b.
- Clarified section 3.2 paragraph 2.
- Clarified section 3.2 step 7.a last paragraph, step 7.b.1 second
bullet and step 7.b.2 third bullet.
- Clarified section 4 to indicate that discovery can use a userName
of zero length in unAuthenticated messages, whereas a valid userName
must be used in authenticated messages.
- Added REVISION clauses to MODULE-IDENTITY
- Clarified KeyChange TC by adding a note that localized keys must be
used when calculating a KeyChange value.
- Added clarifying text to the DESCRIPTION clause of usmUserTable.
Added text describes a recommended procedure for adding a new user.
- Clarified the use of usmUserCloneFrom object.
- Clarified how and under which conditions the usmUserAuthProtocol
and usmUserPrivProtocol can be initialized and/or changed.
- Added comment on typical sizes for usmUserAuthKeyChange and
usmUserPrivKeyChange. Also for usmUserOwnAuthKeyChange and
usmUserOwnPrivKeyChange.
- Added clarifications to the DESCRIPTION clauses of
usmUserAuthKeyChange, usmUserOwnAuthKeychange, usmUserPrivKeyChange
and usmUserOwnPrivKeychange. - Added clarification to DESCRIPTION
clause of usmUserStorageType. - Added clarification to DESCRIPTION
clause of usmUserStatus.
- Clarified IV generation procedure in section 8.1.1.1 and in
addition clarified section 8.3.1 step 1 and section 8.3.2. step 3.
- Clarified section 11.2 and added a warning that different size
passwords with repetitive strings may result in same key.
- Added template users to appendix A for cloning process.
- Fixed C-code examples in Appendix A.
- Fixed examples of generated keys in Appendix A.
- Added examples of KeyChange values to Appendix A.
- Used PDU Classes instead of RFC1905 PDU types.
- Added text in the security section about Reports and Access Control
to the MIB
- Removed a incorrect note at the end of section 3.2 step 7.
- Added a note in section 3.2 step 3.
- Corrected various spelling errors and typos.
- Corrected procedure for 3.2 step 2.a)
- various clarifications.
- Fixed references to new/revised documents
- Change to no longer cache data that is not used
C. Full Copyright Statement
Copyright (C) The Internet Society (1999). 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.
Acknowledgement
Funding for the RFCEditor function is currently provided by
the Internet Society.