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, 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)
          A comprehensive initialisation routine that creates new SNMPv3 user entries and performs time synchronization.
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)
static byte[] password_to_key(int authProtocol, byte[] password, int passwordlen, byte[] id)
          Deprecated. This method cannot be used to generate localized privacy key if the privacy protocol is other than CBC_DES and CFB_AES_128. As of AdventNet SNMP API 4 SP5 ( Release 4.0.5 ), replaced by password_to_key(int, byte[], int, byte[], int)
static byte[] password_to_key(int authProtocol, byte[] password, int passwordlen, byte[] id, int privProtocol)
          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)
Deprecated. This method cannot be used to generate localized privacy key if the privacy protocol is other than CBC_DES and CFB_AES_128. As of AdventNet SNMP API 4 SP5 ( Release 4.0.5 ), replaced by password_to_key(int, byte[], int, byte[], int)

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.

password_to_key

public static byte[] password_to_key(int authProtocol,
                                     byte[] password,
                                     int passwordlen,
                                     byte[] id,
                                     int privProtocol)
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 are 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.
privProtocol - The privacy protocol. Should be one of the constants, CBC_DES, CFB_AES_128, CFB_AES_192, CFB_AES_256, CBC_3DES or NO_PRIV, defined in USMUserEntry. This should be USMUserEntry.NO_PRIV to generate the localized authKey.
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 and CFB_AES_128, 24 for CFB_AES_192 and 32 for CFB_AES_256 and CBC_3DES.
hashLength - 16 for MD5 and 20 for SHA. This will be 16 for CBC_DES and CFB_AES_128, 24 for CFB_AES_192 and 32 for CFB_AES_256 and CBC_3DES.

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)
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.

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 privacy 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.
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.

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
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 present in 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.
privProtocol - The PrivProtocol value. Should be one of the constants, CBC_DES, CFB_AES_128, CFB_AES_192, CFB_AES_256, CBC_3DES or NO_PRIV, defined in USMUserEntry.
Throws:
SnmpException - is thrown on error.
Since:
AdventNet SNMP API 4 SP4 ( Release 4.0.4 )


Copyright (c)AdventNet Inc., 1996-2006