com.adventnet.snmp.snmp2.usm
Class USMUtils

java.lang.Object
  |
  +--com.adventnet.snmp.snmp2.usm.USMUtils

public class USMUtils

extends java.lang.Object

This class provides general USM related methods. All the methods in this class are static. There is no need to instantiate this class. The methods include password to key conversion, digest authentication keyChange routines. The init_v3_params provide a simple interface to set up a user configuration for communicating with a v3 entity.

Method Summary

static byte[]	getDigest(int authProtocol, byte[] authKey, byte[] data) Returns the USMUserEntry.MD5_AUTH or USMUserEntry.SHA_AUTH Digest.
static java.security.MessageDigest	getDigestImpl(int algorithm) Returns the MessageDigest Implementation.
static int	getHashLength(int protocol) Returns the length of the hash associated with the protocol.
static byte[]	getKey(int authProtocol, boolean isFixedLen, int keyLength, int hashLength, byte[] keyChange, byte[] keyOld, byte[] random) Gives the new key corresponding to the keyChange value provided
static java.lang.Object	getKey(java.lang.String name, int port, byte[] userName) Retrieves the Hash key associated with the given host, port and userName.
static byte[]	getKeyChange(int authProtocol, boolean isFixedLen, int keyLength, int hashLength, byte[] keyNew, byte[] keyOld, byte[] random) Returns the keyChange value required for a key change operation.
static int	getKeyLength(int protocol) Returns the key Length associated with the protocol
static void	init_v3_parameters(java.lang.String userName, int authProtocol, java.lang.String authPassword, java.lang.String privPassword, java.lang.String targetHost, int port, SnmpSession session) A comprehensive initialization routine that creates new SnmpV3 entities and user entries and performs discovery and time synchronization.
static void	init_v3_parameters(java.lang.String userName, int authProtocol, java.lang.String authPassword, java.lang.String privPassword, java.lang.String engineName, SnmpSession session) A comprehensive initialization routine that creates new SnmpV3 entities and user entries and performs discovery and time synchronization.
static void	init_v3_params(java.lang.String userName, int authProtocol, java.lang.String authPassword, java.lang.String privPassword, java.lang.String targetHost, int port, SnmpSession session) A comprehensive initialization routine that creates new SnmpV3 entities and user entries and performs discovery and time synchronization.
static void	init_v3_params(java.lang.String userName, int authProtocol, java.lang.String authPassword, java.lang.String privPassword, java.lang.String engineName, SnmpSession session) A comprehensive initialization routine that creates new SnmpV3 entities and user entries and performs discovery and time synchronization.
static byte[]	password_to_key(int authProtocol, byte[] password, int passwordlen, byte[] id) The password to key implementation.
static java.lang.String	printOctets(byte[] data, int length) Prints the octet data in a more readable form.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

password_to_key

public static byte[] password_to_key(int authProtocol,
                                     byte[] password,
                                     int passwordlen,
                                     byte[] id)

The password to key implementation. Localizes the password. Supports only USMUserEntry.MD5_AUTH and USMUserEntry.SHA_AUTH. Override this to support additional protocols.

Parameters:

authProtocol - The authentication protocol. Right now only MD5 and SHA is supported.

password - The password to be used for converting to the localized key.

passwordlen - The length of the password.

id - The engineID to be used for converting to the localized key.

Returns:

The localized key.

getDigestImpl

public static java.security.MessageDigest getDigestImpl(int algorithm)
                                                 throws java.security.NoSuchAlgorithmException

Returns the MessageDigest Implementation. Does caching. Cache continuously increases and persists at a max size.

Parameters:

algorithm - The protocol to be used. Right now it is only MD5 or SHA.

Returns:

The messageDigest.

Throws:

java.security.NoSuchAlgorithmException - is thrown on error.

getKeyChange

public static byte[] getKeyChange(int authProtocol,
                                  boolean isFixedLen,
                                  int keyLength,
                                  int hashLength,
                                  byte[] keyNew,
                                  byte[] keyOld,
                                  byte[] random)

Returns the keyChange value required for a key change operation. The procedure is long and might be slow. Both the key lengths should match the hashLength.

Parameters:

authProtocol - The authentication scheme. USMUserEntry.MD5_AUTH or USMUserEntry.SHA_AUTH

isFixedLen - fixed/variable. Both MD5 & SHA have fixed secret key length.

keyLength - 16 for MD5 and 20 for SHA. This will be 16 for CBC-DES.

hashLength - 16 for MD5 and 20 for SHA.

getKey

public static byte[] getKey(int authProtocol,
                            boolean isFixedLen,
                            int keyLength,
                            int hashLength,
                            byte[] keyChange,
                            byte[] keyOld,
                            byte[] random)

Gives the new key corresponding to the keyChange value provided

Parameters:

authProtocol - the authentication protocol.

isFixedLen - indicates whether the length of the key is fixed for the protocol. true for both MD5 and SHA.

keyLength - the length of the key associated with this protocol.

hashLength - the length of the hash associated with the protocol.

keyChange - the key change value.

keyOld - the original key value.

Returns:

the new key.

printOctets

public static java.lang.String printOctets(byte[] data,
                                           int length)

Prints the octet data in a more readable form. The data is printed in the hex format. The input parameter is a byte array of octet data.

Parameters:

data - the byte array representing the data to be printed.

length - the number of bytes of data to be printed in hex format.

Returns:

A String which contains the data in hex.

getDigest

public static byte[] getDigest(int authProtocol,
                               byte[] authKey,
                               byte[] data)

Returns the USMUserEntry.MD5_AUTH or USMUserEntry.SHA_AUTH Digest.

Parameters:

authProtocol - The authentication protocol. Right now only MD5 and SHA is supported.

authKey - The localized authentication key.

data - The pdu data over which the digest is to be computed.

Returns:

The computed digest.

getKeyLength

public static int getKeyLength(int protocol)

Returns the key Length associated with the protocol

getHashLength

public static int getHashLength(int protocol)

Returns the length of the hash associated with the protocol.

init_v3_params

public static void init_v3_params(java.lang.String userName,
                                  int authProtocol,
                                  java.lang.String authPassword,
                                  java.lang.String privPassword,
                                  java.lang.String targetHost,
                                  int port,
                                  SnmpSession session)

A comprehensive initialization routine that creates new SnmpV3 entities and user entries and performs discovery and time synchronization. The method requires an open SnmpSession instance. This method creates a new SnmpV3 entity i.e., SnmpEngineEntry, performs an engineID discovery, creates a new USMUserEnrty for a user, on whose behalf the SNMP requests will be made. This also performs the timeSynchronization, provided that the user entry is authenticated. The newely created SnmpEngineEntry and USMUserEntry are populated in the SnmpEngineTable and in the USMUserTable respectively. This method uses the passwords to convert into localized private key.

Parameters:

userName - The string representing the SnmpV3 principal.

authProtocol - The authentication protocol. Should be one of the constants, MD5_AUTH, SHA_AUTH or NO_AUTH. These constants are defined in USMUserEntry.

authPassword - The authentication password, which is converted to a localized key.

privPassword - The privacy password, which is converted into a localized private key. The only supported protocol is CBC_DES.

targetHost - The hostName of the SNMP peer.

port - The port of the SNMP peer.

session - The SnmpSession instance. This should be in an open state. The discovery and timeSync messages are sent over this session.

init_v3_parameters

public static void init_v3_parameters(java.lang.String userName,
                                      int authProtocol,
                                      java.lang.String authPassword,
                                      java.lang.String privPassword,
                                      java.lang.String targetHost,
                                      int port,
                                      SnmpSession session)
                               throws SnmpException

A comprehensive initialization routine that creates new SnmpV3 entities and user entries and performs discovery and time synchronization. The method requires an open SnmpSession instance. This method creates a new SnmpV3 entity i.e., SnmpEngineEntry, performs an engineID discovery, creates a new USMUserEnrty for a user, on whose behalf the SNMP requests will be. This also performs the timeSynchronization provided that the user entry is authenticated. The newely created SnmpEngineEntry and USMUserEntry are populated in the SnmpEngineTable and in the USMUserTable respectively. This method uses the passwords to convert into a localized private key.

Parameters:

userName - The string representing the SnmpV3 principal.

authProtocol - The authentication protocol. Should be one of the constants, MD5_AUTH, SHA_AUTH or NO_AUTH. These constants are defined in USMUserEntry.

authPassword - The authentication password which is converted to a localized key.

privPassword - The privacy password which is converted into a localized private key. The only supported protocol is CBC_DES.

targetHost - The hostName of the SNMP peer.

port - The port of the SNMP peer.

session - The SnmpSession instance. This should be in an open state. The discovery and timeSync messages are sent over this session.

Throws:

SnmpException - is thrown on error.

init_v3_params

public static void init_v3_params(java.lang.String userName,
                                  int authProtocol,
                                  java.lang.String authPassword,
                                  java.lang.String privPassword,
                                  java.lang.String engineName,
                                  SnmpSession session)

A comprehensive initialization routine that creates new SnmpV3 entities and user entries and performs discovery and time synchronization. The method requires an open SnmpSession instance. This method creates a new SnmpV3 entity i.e SnmpEngineEntry, performs an engineID discovery, creates a new USMUserEnrty for a user, on whose behalf the SNMP requests will be made. This also performs the timeSynchronization provided that the user entry is authenticated. The newely created SnmpEngineEntry and USMUserEntry are populated in the SnmpEngineTable and in the USMUserTable respectively. This method uses the passwords to convert into a localized private key.

Parameters:

userName - The string representing the SnmpV3 principal.

authProtocol - The authentication protocol. Should be one of the constants, MD5_AUTH, SHA_AUTH or NO_AUTH. These constants are defined in USMUserEntry.

authPassword - The authentication password which is converted to a localized key.

privPassword - The privacy password which is converted into a localized private key. The only supported protocol is CBC_DES.

engineName - The string value of the engine entry.

session - The SnmpSession instance. This should be in an open state. The discovery and timeSync messages are sent over this session.

init_v3_parameters

public static void init_v3_parameters(java.lang.String userName,
                                      int authProtocol,
                                      java.lang.String authPassword,
                                      java.lang.String privPassword,
                                      java.lang.String engineName,
                                      SnmpSession session)
                               throws SnmpException

A comprehensive initialization routine that creates new SnmpV3 entities and user entries and performs discovery and time synchronization. The method requires an open SnmpSession instance. This method creates a new SnmpV3 entity i.e., SnmpEngineEntry, performs an engineID discovery, creates a new USMUserEnrty for a user, on whose behalf the SNMP requests will be made. This also performs the timeSynchronization provided that the user entry is authenticated. The newely created SnmpEngineEntry and USMUserEntry are populated in the SnmpEngineTable and in the USMUserTable respectively. This method uses the passwords to convert into a localized private key. @param userName The string representing the SnmpV3 principal. @param authProtocol The authentication protocol. Should be one of the constants, MD5_AUTH, SHA_AUTH or NO_AUTH. These constants are defined in USMUserEntry. @param authPassword The authentication password which is converted to a localized key. @param privPassword The privacy password which is converted into a localized private key. The only supported protocol is CBC_DES. @param engineName The string value of the engine entry. @param session The SnmpSession instance. This should be in an open state. The discovery and timeSync messages are sent over this session.

Throws:

SnmpException - is thrown on error.

getKey

public static java.lang.Object getKey(java.lang.String name,
                                      int port,
                                      byte[] userName)

Retrieves the Hash key associated with the given host, port and userName. This method can be used when a user needs to have a configuration table which contains only the security parameters for agents in the case of V3 database.

Parameters:

name - hostName or engineName for UDP/IP or Independent Transport Protocol respectively.

port - the remotePort. -1 in the case of Independent Transport Protocol.

userName - the UserName set in the case of v3.