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.

Field Summary

(package private) static java.util.Stack[]	freePool
(package private) static int	PASS_KEY_LENGTH
(package private) static java.util.Random	rand
(package private) static java.lang.String[]	securityLevels

Constructor Summary

(package private)

USMUtils()

Method Summary

(package private) static void	()
(package private) static void	()
(package private) static void	()
(package private) static boolean	checkDigest(int authProtocol, byte[] authKey, byte[] data, int authPos, byte[] authParms) Verifies the pdu digest
(package private) static void	debugLogging(java.lang.String methodName, java.lang.String className, java.lang.String debugStr)
(package private) static byte[]	decrypt(byte[] data, int offset, byte[] key, int protocol, byte[] privParams, int eb, int et)
(package private) static int	encrypt(byte[] data, int offset, byte[] key, int privProtocol, byte[] privParms, int eb, int et)
(package private) static int	encrypt(byte[] data, int offset, byte[] key, int privProtocol, byte[] privParams, int eb, int et, boolean DEBUG)
(package private) static void	freeDigestImpl(int algo, java.security.MessageDigest md)
(package private) static byte[]	genSalt()
(package private) static byte[]	getbyteArray(int i)
(package private) static byte[]	getCryptKey(byte[] privateKey)
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.
(package private) static byte[]	getIV(byte[] preIV, byte[] salt)
(package private) static byte[]	getIVForAES(byte[] eb, byte[] et, byte[] salt)
(package private) static int	getJavaMajorVersion()
(package private) static int	getJavaMinorVersion()
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
(package private) static byte[]	getpreIV(byte[] privateKey)
(package private) static byte[]	getStoredPassword(byte[] encPass)
(package private) static int[]	getUsmEntryOid(byte[] user, byte[] id, int col)
static void	init_v3_parameters(java.lang.String userName, byte[] engineID, int authProtocol, java.lang.String authPassword, java.lang.String privPassword, ProtocolOptions po, SnmpSession session, boolean validateUser) A comprehensive initialisation routine that creates new SNMPv3 user entries and performs time synchronization.
static void	init_v3_parameters(java.lang.String userName, byte[] engineID, int authProtocol, java.lang.String authPassword, java.lang.String privPassword, ProtocolOptions po, SnmpSession session, boolean validateUser, int privProtocol)
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) Deprecated. This method doesn't throw any Exception and hence doesn't inform the user, in case of any error. As of AdventNet SNMP API 4 SP2 ( Release 4.0.2 ), replaced by init_v3_parameters(String,int,String,String,String,int,SnmpSession)
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) Deprecated. This method doesn't throw any Exception and hence doesn't inform the user, in case of any error. As of AdventNet SNMP API 4 SP2 ( Release 4.0.2 ), replaced by init_v3_parameters(String,int,String,String,String,SnmpSession)
(package private) static boolean	isDebugLog(int level)
(package private) static boolean	isPerformanceLog(int level)
(package private) static void	logErrorMessage(java.lang.String error) This method will log the message in the LogManager through the static "logErrorMessage(String)" method present in the LogManager class.
(package private) static void	logInfoMessage(java.lang.String info) This method will log the message in the LogManager through the static "logInfoMessage(String)" method present in the LogManager class.
(package private) static void	logMessage(java.lang.String message) This method will log the message in the LogManager through the static "logMessage(String)" method present in the LogManager class.
(package private) static void	logMessage(java.lang.String message, int id) This method will log the message in the LogManager through the static "logMessage(String, int)" method present in the LogManager class.
static byte[]	password_to_key(int authProtocol, byte[] password, int passwordlen, byte[] id) The password to key implementation.
(package private) static void	performanceLogging(java.lang.String methodName, java.lang.String className, long timeDiff)
static java.lang.String	printOctets(byte[] data, int length) Prints the octet data in a more readable form.
(package private) static void	signPdu(int authProtocol, byte[] authKey, byte[] data, int authPos) Generates the digest and inserts it at the authPos specified.
(package private) static byte[]	storePassword(byte[] pass, byte[] key, boolean decodeFlag)

Methods inherited from class java.lang.Object

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

Field Detail

securityLevels

static java.lang.String[] securityLevels

freePool

static java.util.Stack[] freePool

rand

static java.util.Random rand

PASS_KEY_LENGTH

static int PASS_KEY_LENGTH

Constructor Detail

USMUtils

USMUtils()

Method Detail

static void ()

getJavaMajorVersion

static int getJavaMajorVersion()

getJavaMinorVersion

static int getJavaMinorVersion()

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.

signPdu

static void signPdu(int authProtocol,
                    byte[] authKey,
                    byte[] data,
                    int authPos)

Generates the digest and inserts it at the authPos specified.

Parameters:

authProtocol - the authentication protocol to be used. Either of MD5_AUTH,SHA,AUTH.

authKey - the authentication key.

data - the data to be signed.

authPos - the position at which the digest needs to be inserted.

checkDigest

static boolean checkDigest(int authProtocol,
                           byte[] authKey,
                           byte[] data,
                           int authPos,
                           byte[] authParms)

Verifies the pdu digest

Parameters:

authProtocol - the authentication protocol to be used. Either of MD5_AUTH,SHA,AUTH.

authKey - the authentication key.

data - the data to be signed.

authPos - the position at which the digest is to start.

authParams - the authentication digest to be compared to.

Returns:

True if the digest is correct. False otherwise.

static void ()

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.

freeDigestImpl

static void freeDigestImpl(int algo,
                           java.security.MessageDigest md)

static void ()

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.

getUsmEntryOid

static int[] getUsmEntryOid(byte[] user,
                            byte[] id,
                            int col)

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.

encrypt

static int encrypt(byte[] data,
                   int offset,
                   byte[] key,
                   int privProtocol,
                   byte[] privParms,
                   int eb,
                   int et)
            throws SnmpException

encrypt

static int encrypt(byte[] data,
                   int offset,
                   byte[] key,
                   int privProtocol,
                   byte[] privParams,
                   int eb,
                   int et,
                   boolean DEBUG)
            throws SnmpException

getCryptKey

static byte[] getCryptKey(byte[] privateKey)

getpreIV

static byte[] getpreIV(byte[] privateKey)

genSalt

static byte[] genSalt()

getIV

static byte[] getIV(byte[] preIV,
                    byte[] salt)

decrypt

static byte[] decrypt(byte[] data,
                      int offset,
                      byte[] key,
                      int protocol,
                      byte[] privParams,
                      int eb,
                      int et)

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)

Deprecated. This method doesn't throw any Exception and hence doesn't inform the user, in case of any error. As of AdventNet SNMP API 4 SP2 ( Release 4.0.2 ), replaced by init_v3_parameters(String,int,String,String,String,int,SnmpSession)

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_parameters

public static void init_v3_parameters(java.lang.String userName,
                                      byte[] engineID,
                                      int authProtocol,
                                      java.lang.String authPassword,
                                      java.lang.String privPassword,
                                      ProtocolOptions po,
                                      SnmpSession session,
                                      boolean validateUser)
                               throws SnmpException

A comprehensive initialisation routine that creates new SNMPv3 user entries and performs time synchronization. Since the engineID is accepted as an argument, the SNMPv3 discovery will not be done. Hence an SnmpEngineEntry will not be created and added to the SnmpEngineTable. If the engineID specified is null or of zero length then the method will automatically do a discovery and add an SnmpEngineEntry to the SnmpEngineTable. This method will do a time synchronization and hence will create a new USMUserEntry and will add it to the USMUserTable.

After this method is called successfully ( without any exception ) with a proper engineID as the argument, then a valid USMUserEntry will be added to the USMUserTable and no entry will be added to the SnmpEngineTable. Thus whenever an SNMPv3 request is sent for this particular agent, this engineID should be specified in the request using the setEngineID method.

Parameters:

userName - The string representing the SnmpV3 principal.

engineID - The engineID of the remote SNMPv3 entity ( the agent ).

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.

po - The ProtocolOptions instance.

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

validateUser - The boolean value. If this value is set to true, and if this method is called for an

• NO_AUTH_NO_PRIV user, then a get request will be sent to know if the user exits.
• AUTH_PRIV user, then a get request will be sent to know if the priv password is correct.

Throws:

SnmpException - is thrown under the following circumstances.

• In case of Discovery Failure
• In case of Time Synchronization Failure
• If the ProtocolOptions is null
• If the user does not exists on the agent.
• If the authPassword or privPassword is wrong.
• If the EngineID is wrong
• If this Security level is not supported by the agent

Since:

AdventNet SNMP API 4 SP2 ( Release 4.0.2 )

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)

Deprecated. This method doesn't throw any Exception and hence doesn't inform the user, in case of any error. As of AdventNet SNMP API 4 SP2 ( Release 4.0.2 ), replaced by init_v3_parameters(String,int,String,String,String,SnmpSession)

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.

storePassword

static byte[] storePassword(byte[] pass,
                            byte[] key,
                            boolean decodeFlag)

getStoredPassword

static byte[] getStoredPassword(byte[] encPass)

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.

logMessage

static void logMessage(java.lang.String message)

This method will log the message in the LogManager through the static "logMessage(String)" method present in the LogManager class.

logMessage

static void logMessage(java.lang.String message,
                       int id)

This method will log the message in the LogManager through the static "logMessage(String, int)" method present in the LogManager class.

logInfoMessage

static void logInfoMessage(java.lang.String info)

This method will log the message in the LogManager through the static "logInfoMessage(String)" method present in the LogManager class.

logErrorMessage

static void logErrorMessage(java.lang.String error)

This method will log the message in the LogManager through the static "logErrorMessage(String)" method present in the LogManager class.

performanceLogging

static void performanceLogging(java.lang.String methodName,
                               java.lang.String className,
                               long timeDiff)

debugLogging

static void debugLogging(java.lang.String methodName,
                         java.lang.String className,
                         java.lang.String debugStr)

isPerformanceLog

static boolean isPerformanceLog(int level)

isDebugLog

static boolean isDebugLog(int level)

init_v3_parameters

public static void init_v3_parameters(java.lang.String userName,
                                      byte[] engineID,
                                      int authProtocol,
                                      java.lang.String authPassword,
                                      java.lang.String privPassword,
                                      ProtocolOptions po,
                                      SnmpSession session,
                                      boolean validateUser,
                                      int privProtocol)
                               throws SnmpException

getIVForAES

static byte[] getIVForAES(byte[] eb,
                          byte[] et,
                          byte[] salt)

getbyteArray

static byte[] getbyteArray(int i)