com.adventnet.snmp.snmp2.usm
Class USMUserEntry

java.lang.Object
  extended by com.adventnet.snmp.snmp2.SecurityModelEntry
      extended by com.adventnet.snmp.snmp2.usm.USMUserEntry
All Implemented Interfaces:
java.io.Serializable

public class USMUserEntry
extends SecurityModelEntry
implements java.io.Serializable

The USMUserEntry holds the configuration data specific to each user for a given SNMPv3 entity. This class represents the User Based Security Model and has the user security attrubutes like the auth and priv Passwords, protocols and their localized keys in addition to the userName. It also has authentication and the timeSynchronization routines.

A USMUserEntry is created for each user on whose behalf an SNMP request is to be made. A new instance is created with the userName and the engineID, where the engineID is got from a discovery procedure. The SnmpEngineEntry is used to create a new SnmpV3 entity and provide the methods to do discovery. For an agent side implementation, the engineID will be the agent's engineID and hence the discovery process will not be required. All the other user attributes can be added using the set methods of the respective attributes. If the auth/priv password is set, then the auth/priv key(localized key) can be generated using the password_to_key method in the USMUtils class.

This class also provides the Authentication and TimeSynchronization routines. The authentication routine, checks the message digest and updates the time values such as the engine boots, time and also the lastReceivedTime. In case of the agent side implementaion it does the timeliness check.

The USMUserEntry has a reference to the SnmpEngineEntry. So when a new USMUserEntry is created, its corresponding SnmpV3 entity reference should be set in the USMUserEntry. This class provides the methods to access the SnmpEngineEntry.

See Also:
USMUserTable, Serialized Form

Field Summary
(package private) static int ACTIVE
          The below are the various RowStatus constants
(package private)  byte[] authKey
          Authorization key
(package private)  byte[] authParams
           
(package private)  byte[] authPassword
          Authorization Password
(package private)  int authPos
           
(package private)  int authProtocol
          authProtocol for this combination of securityName and snmpEngineID
static int CBC_3DES
          Constant for SNMPV3 usmUser CBC_3DES PrivProtocol.
static int CBC_DES
          Constant for SNMPV3 usmUser CBC_DES PrivProtocol.
static int CFB_AES_128
          Constant for SNMPV3 usmUser CFB_AES PrivProtocol.
static int CFB_AES_192
          Constant for SNMPV3 usmUser CFB_AES_192 PrivProtocol.
static int CFB_AES_256
          Constant for SNMPV3 usmUser CFB_AES_256 PrivProtocol.
(package private) static int CREATEANDGO
           
(package private) static int CREATEANDWAIT
           
(package private) static SnmpOID DECRYPT_ERROR_OID
           
(package private) static int DESTROY
           
(package private)  boolean enableAdd
          If the engineId is set directly on a PDU, then the discovery need not be done.
(package private)  int engineBoots
           
(package private)  SnmpEngineEntry engineEntry
           
(package private)  byte[] engineID
          Engine identifier associated with the SNMP engine
(package private)  int engineTime
           
(package private)  long localTime
           
static int MD5_AUTH
          Constant for SNMPV3 usmUser MD5 AuthProtocol.
static int NO_AUTH
          Constant for SNMPV3 usmNoAuthProtocol.
static int NO_PRIV
          Constant for SNMPV3 usmNoPrivProtocol.
(package private) static int NONVOLATILE
           
(package private) static SnmpOID NOT_TIME_WINDOWS_OID
           
(package private) static int NOTINSERVICE
           
(package private) static int NOTREADY
           
(package private) static int OTHER
          The below are the various StorageType constants
(package private)  boolean ownKeyChange
          A private boolean variable to signify the Own Key change flag.This is required if a OwnKeyChange request comes to the agent in which case the agent needs to encode a proper digest.ie., the digest should be made w.r.t the auth/priv key prior to the change, otherwise a digest failure will occur in the manager.
(package private) static int PERMANENT
           
(package private)  byte[] privKey
          Privacy Key
(package private)  byte[] privParams
           
(package private)  byte[] privPassword
          Privacy Password
(package private)  int privProtocol
          Privacy protocol to be used
(package private) static java.util.Random rand
           
(package private) static int READONLY
           
(package private)  boolean respondToDiscovery
           
(package private)  byte securityLevel
          User's default security Level
(package private)  byte[] securityName
          Model Independent SecurityName
static int SHA_AUTH
          Constant for SNMPV3 usmUser SHA AuthProtocol.
(package private)  int storageType
          The StorageType variable
(package private)  USMUserEntry tempEntry
          Used for encoding the USM message if own key change is effected, otherwise the digest will fail.
(package private) static SnmpOID UKN_ENGINEID_OID
           
(package private) static SnmpOID UKN_USERNAMES_OID
           
(package private) static SnmpOID UNSUPP_SEC_LEVEL_OID
           
(package private)  int[] userCloneFrom
          The USM UserCloneFrom variable
(package private)  byte[] userName
          User Name : Is same as SecurityName for USM
(package private)  byte[] userPublic
          The USMUserPublic variable
(package private)  int userStatus
          The userStatus variable
static byte USM_SECURITY_MODEL
          Constant for the User Based Security Model.
(package private)  java.lang.Object utils
           
(package private) static int VOLATILE
           
(package private) static SnmpOID WRONG_DIGEST_OID
           
 
Constructor Summary
USMUserEntry()
          Constructs a new USMUserEntry with the default userName of initial.
USMUserEntry(byte[] user, byte[] id)
          Creates a new USMUserEntry using the specified userName and engineID.
 
Method Summary
 int authenticate(Snmp3Message msg)
          This performs the authentication for this user entry.
 void authenticateMessageToSend(Snmp3Message msg, SnmpSession session)
          Performs authentication of the received message as per the security model.
 int authenticateReceivedMessage(Snmp3Message msg, SnmpSession session)
          Performs authentication of the received message as per the USM security model.
(package private)  int checkAuthTimes(int boots, int time, SnmpAPI api)
           
(package private)  int checkNonAuthTimes(int boots, int time)
          Checks the time values for a non-authoritative role packet(localEngineid!=pduEngineId)
(package private)  boolean compare(byte[] a, byte[] b)
          A byte array comparison routine.
 SecurityModelEntry copy()
          Returns a copy of this USMUserEntry.
 SecurityModelEntry copy(byte[] engineID, byte[] userName)
          Returns a copy of this USMUserEntry with the userName and engineID, initialized to the values passed.
 void decodeMsgSecurityParams(Snmp3Message msg, SnmpSession session, ASN1Parser asnParser)
          This method will decode the USM security parameters.
 byte[] decrypt(byte[] data, int spaceLeft, byte[] key, int protocol, byte[] privParms)
          This method is called to decrypt the data.
 boolean encodeMsgSecurityParams(Snmp3Message msg, SnmpAPI API, ASN1Parser asnParser)
          This method will encode the USM message security parameters.
 int encrypt(byte[] data, int spaceLeft, byte[] key, int protocol, byte[] privParms)
          This method is called to encrypt the data.
 byte[] getAuthKey()
          Retrieves the authentication key.
 byte[] getAuthParams()
          Gets the auth params.
 byte[] getAuthPassword()
          Retrieves the authentication password.
 int getAuthProtocol()
          Returns the authentication Protocol used.
 int getEngineBoots()
          Retrieve the engine boots value.
 SnmpEngineEntry getEngineEntry()
          Gets the corresponding SnmpEngineEntry reference.
 byte[] getEngineID()
          Retrieves the Engine identifier associated with the SNMP engine.
(package private)  int getEngineTime()
          Retrieve the corresponding engineTime
 java.lang.Object getKey()
          Retrieve the hash key for this user entry.
static java.lang.Object getKey(byte[] name, byte[] id)
          Retrieve the key for this user object.
(package private)  long getLocalTime()
           
 byte[] getPrivKey()
          Retrieves the privacy key value.
 byte[] getPrivParams()
          Retrieve the priv params.
 byte[] getPrivPassword()
          Gets the privacy password.
 int getPrivProtocol()
          Retrieves the privacy protocol value.
 byte[] getSecurityID(byte[] securityName)
          Returns the securityID ( which depends on the security model ).
 byte getSecurityLevel()
          Retrieves the security level value for this user entry.
 int getSecurityModel()
          Returns the securityModel.
 byte[] getSecurityName()
          Gets the security name, which is independent of the security model.
 byte[] getSecurityName(byte[] securityID)
          Gets the security name ( which is independent of the security model ) using the securityID ( which depends on the security model ).
 int getSnmpEngineTime()
           
 int getStorageType()
          Gets the USM StorageType associated with this USMUserEntry.
 int[] getUserCloneFrom()
          Gets the USMUserCloneFrom OID associated with this USMUserEntry.
 byte[] getUserName()
          Gets the userName associated with this user.
 byte[] getUserPublic()
          Gets the USM UserPublic associated with this USMUserEntry.
 int getUserStatus()
          Gets the USM UserStatus associated with this USMUserEntry.
 void init(SnmpSession session, ProtocolOptions po)
           
 void processEncodedMsg(Snmp3Message msg, ASN1Parser asnParser)
          This method is called after encoding the message version.
 int sendTimeSync(SnmpSession session)
          Achieves time sync with remotehost.
 int sendTimeSync(SnmpSession session, ProtocolOptions po, int reqID)
          Achieves time sync with remotehost.
 void setAuthKey(byte[] key)
          Sets the authentication key.
 void setAuthParams(byte[] param)
          Sets the auth params value.
 void setAuthPassword(byte[] passwd)
          Sets the authentication password.
 void setAuthProtocol(int protocol)
          Sets the authentication Protocol to be used.
 void setEngineBoots(int boots)
          Sets the engineBoots corresponding to this user's corresponding engine entry
 void setEngineEntry(SnmpEngineEntry entry)
          Sets the SnmpEngineEntry reference.
(package private)  void setEngineTime(int time)
          Sets the engineTime for this user's engine entry
(package private)  void setLocalTime(long l)
           
 void setOwnKeyChange(boolean flag)
          Sets the ownKeyChange flag.
 void setPrivKey(byte[] key)
          Sets the privacy key.
 void setPrivParams(byte[] param)
          Sets the priv params field.
 void setPrivPassword(byte[] passwd)
          Sets the privacy password.
 void setPrivProtocol(int protocol)
          Sets the privacy protocol to be used.
 void setSecurityLevel(byte level)
          Sets the security level for this user entry.
 void setSecurityName(byte[] name)
          Sets the security name by taking the byte array as argument.
 void setSnmpEngineTime(int et)
           
 void setStorageType(int storageType)
          Sets the USM StorageType associated with this USMUserEntry.
 void setUserCloneFrom(int[] oid)
          Sets the USM UserCloneFrom OID for this USMUserEntry.
(package private)  void setUserName(byte[] name)
           
 void setUserPublic(byte[] userPublic)
          Sets the USM UserPublic associated with this USMUserEntry.
 void setUserStatus(int userStatus)
          Sets the USM UserStatus associated with this USMUserEntry.
 void setUSMUtils(java.lang.Object utils)
          The Utils object should be set, so that it can be used for encryption purpose.
 void timeSync(SnmpSession session)
          Deprecated. This method does not throw any exception and hence does not inform the user, in case of any error. As of AdventNet SNMP API 4 SP2 ( Release 4.0.2 ), replaced by timeSynchronize(SnmpSession,ProtocolOptions)
 void timeSynchronize(SnmpSession session, ProtocolOptions po)
          Achieves time sync with the remote host.
(package private)  void updateTimes(int boots, int time)
           
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

enableAdd

boolean enableAdd
If the engineId is set directly on a PDU, then the discovery need not be done. Hence the SnmpEngineEntry should not be added in the SnmpEngineTable. This boolean is used for enabling/disabling the addition of SnmpEngineEntry in the SnmpEngineTable.


USM_SECURITY_MODEL

public static final byte USM_SECURITY_MODEL
Constant for the User Based Security Model.

See Also:
Constant Field Values

NO_AUTH

public static final int NO_AUTH
Constant for SNMPV3 usmNoAuthProtocol.

See Also:
Constant Field Values

MD5_AUTH

public static final int MD5_AUTH
Constant for SNMPV3 usmUser MD5 AuthProtocol.

See Also:
Constant Field Values

SHA_AUTH

public static final int SHA_AUTH
Constant for SNMPV3 usmUser SHA AuthProtocol.

See Also:
Constant Field Values

NO_PRIV

public static final int NO_PRIV
Constant for SNMPV3 usmNoPrivProtocol.

See Also:
Constant Field Values

CBC_DES

public static final int CBC_DES
Constant for SNMPV3 usmUser CBC_DES PrivProtocol.

See Also:
Constant Field Values

CFB_AES_128

public static final int CFB_AES_128
Constant for SNMPV3 usmUser CFB_AES PrivProtocol.

See Also:
Constant Field Values

CFB_AES_192

public static final int CFB_AES_192
Constant for SNMPV3 usmUser CFB_AES_192 PrivProtocol.

See Also:
Constant Field Values

CFB_AES_256

public static final int CFB_AES_256
Constant for SNMPV3 usmUser CFB_AES_256 PrivProtocol.

See Also:
Constant Field Values

CBC_3DES

public static final int CBC_3DES
Constant for SNMPV3 usmUser CBC_3DES PrivProtocol.

See Also:
Constant Field Values

UNSUPP_SEC_LEVEL_OID

static final SnmpOID UNSUPP_SEC_LEVEL_OID

NOT_TIME_WINDOWS_OID

static final SnmpOID NOT_TIME_WINDOWS_OID

UKN_USERNAMES_OID

static final SnmpOID UKN_USERNAMES_OID

UKN_ENGINEID_OID

static final SnmpOID UKN_ENGINEID_OID

WRONG_DIGEST_OID

static final SnmpOID WRONG_DIGEST_OID

DECRYPT_ERROR_OID

static final SnmpOID DECRYPT_ERROR_OID

engineID

byte[] engineID
Engine identifier associated with the SNMP engine


userName

byte[] userName
User Name : Is same as SecurityName for USM


securityName

byte[] securityName
Model Independent SecurityName


authProtocol

int authProtocol
authProtocol for this combination of securityName and snmpEngineID


authPassword

byte[] authPassword
Authorization Password


authKey

byte[] authKey
Authorization key


privProtocol

int privProtocol
Privacy protocol to be used


privKey

byte[] privKey
Privacy Key


privPassword

byte[] privPassword
Privacy Password


securityLevel

byte securityLevel
User's default security Level


engineBoots

int engineBoots

engineTime

int engineTime

localTime

long localTime

authParams

byte[] authParams

authPos

int authPos

privParams

byte[] privParams

engineEntry

SnmpEngineEntry engineEntry

userCloneFrom

int[] userCloneFrom
The USM UserCloneFrom variable


userPublic

byte[] userPublic
The USMUserPublic variable


OTHER

static final int OTHER
The below are the various StorageType constants

See Also:
Constant Field Values

VOLATILE

static final int VOLATILE
See Also:
Constant Field Values

NONVOLATILE

static final int NONVOLATILE
See Also:
Constant Field Values

PERMANENT

static final int PERMANENT
See Also:
Constant Field Values

READONLY

static final int READONLY
See Also:
Constant Field Values

storageType

int storageType
The StorageType variable


ACTIVE

static final int ACTIVE
The below are the various RowStatus constants

See Also:
Constant Field Values

NOTINSERVICE

static final int NOTINSERVICE
See Also:
Constant Field Values

NOTREADY

static final int NOTREADY
See Also:
Constant Field Values

CREATEANDGO

static final int CREATEANDGO
See Also:
Constant Field Values

CREATEANDWAIT

static final int CREATEANDWAIT
See Also:
Constant Field Values

DESTROY

static final int DESTROY
See Also:
Constant Field Values

userStatus

int userStatus
The userStatus variable


tempEntry

USMUserEntry tempEntry
Used for encoding the USM message if own key change is effected, otherwise the digest will fail.


ownKeyChange

boolean ownKeyChange
A private boolean variable to signify the Own Key change flag.This is required if a OwnKeyChange request comes to the agent in which case the agent needs to encode a proper digest.ie., the digest should be made w.r.t the auth/priv key prior to the change, otherwise a digest failure will occur in the manager.


utils

java.lang.Object utils

rand

static java.util.Random rand

respondToDiscovery

boolean respondToDiscovery
Constructor Detail

USMUserEntry

public USMUserEntry()
Constructs a new USMUserEntry with the default userName of initial. This is used by the Snmp3Message class constructor. The API user should not use this constructor.


USMUserEntry

public USMUserEntry(byte[] user,
                    byte[] id)
Creates a new USMUserEntry using the specified userName and engineID. The engineID can be learned from the discovery, for which a new SnmpV3 entity has to be created using the SnmpEngineEntry. For an agent side implementation, its own engineID is used.

Parameters:
user - The userName, on whose behalf SNMP requests are to be made
id - The engineID of the SnmpV3 entity. In the context of the SnmpV3 entity as a manager, the engineID is that of the peer agent and can be learned from the discovery procedure. In case of the SnmpV3 entity as an agent, the engineID is the agent's engineID.
See Also:
SnmpEngineEntry.
Method Detail

getEngineID

public byte[] getEngineID()
Retrieves the Engine identifier associated with the SNMP engine.

Specified by:
getEngineID in class SecurityModelEntry

getUserName

public byte[] getUserName()
Gets the userName associated with this user.


setUserName

void setUserName(byte[] name)

getSecurityName

public byte[] getSecurityName()
Gets the security name, which is independent of the security model.

Specified by:
getSecurityName in class SecurityModelEntry
Returns:
the security name.

getSecurityName

public byte[] getSecurityName(byte[] securityID)
Gets the security name ( which is independent of the security model ) using the securityID ( which depends on the security model ).

Specified by:
getSecurityName in class SecurityModelEntry
Returns:
the securityID.

getSecurityID

public byte[] getSecurityID(byte[] securityName)
Returns the securityID ( which depends on the security model ).

Specified by:
getSecurityID in class SecurityModelEntry

setSecurityName

public void setSecurityName(byte[] name)
Sets the security name by taking the byte array as argument. This byte array is the security name, which is independent of the security model. The securityID ( which depends on the security model ) should also be set as a result of this operation.

Specified by:
setSecurityName in class SecurityModelEntry

getSecurityModel

public int getSecurityModel()
Returns the securityModel.

Specified by:
getSecurityModel in class SecurityModelEntry

getAuthProtocol

public int getAuthProtocol()
Returns the authentication Protocol used. The values are one of the constants, NO_AUTH, MD5_AUTH, SHA_AUTH defined in this class.

Returns:
The authentication Protocol used.

setAuthProtocol

public void setAuthProtocol(int protocol)
Sets the authentication Protocol to be used. It should be one of the constants NO_AUTH, MD5_AUTH, or SHA_AUTH defined in this class.

Parameters:
protocol - The authentication Protocol to be used.

getAuthPassword

public byte[] getAuthPassword()
Retrieves the authentication password. The authPassword contains only the password and not the localized key.

Returns:
The authPassword used for authentication.

setAuthPassword

public void setAuthPassword(byte[] passwd)
Sets the authentication password. The authPassword contains only the password and not the localized key.

Parameters:
passwd - The authPassword to be used.

getAuthKey

public byte[] getAuthKey()
Retrieves the authentication key. The authentication key is the localized key. This is a secret key shared between the user and the authoritative SNMP engine.

Returns:
The localized secret authentication key.

setAuthKey

public void setAuthKey(byte[] key)
Sets the authentication key. The authentication key is the localized key which is a secret one shared between the user and the authoritative SNMP engine.

Parameters:
key - The localized authentication key

getPrivProtocol

public int getPrivProtocol()
Retrieves the privacy protocol value. Currently valid value is CBC_DES.

Returns:
The privProtocol used.

setPrivProtocol

public void setPrivProtocol(int protocol)
Sets the privacy protocol to be used. Currently valid value is CBC-DES. This privacy protocol is used by encryptive/decryptive algorithm.

Parameters:
protocol - The privProtocol to be used.

getPrivKey

public byte[] getPrivKey()
Retrieves the privacy key value. The privacy key is the localized private privKey used by the encryptive/decryptive algorithm.

Returns:
The localized secret privacy key.

setPrivKey

public void setPrivKey(byte[] key)
Sets the privacy key. The privacy key is the localized private privKey used by the encryptive/decryptive algorithm.

Parameters:
key - The localized secret privacy key.

getPrivPassword

public byte[] getPrivPassword()
Gets the privacy password. The privPassword contains only the password and not the localized key.

Returns:
The privacy password.

setPrivPassword

public void setPrivPassword(byte[] passwd)
Sets the privacy password. The privPassword contains only the password and not the localized key.

Parameters:
passwd - The privacy password.

getSecurityLevel

public byte getSecurityLevel()
Retrieves the security level value for this user entry.

Specified by:
getSecurityLevel in class SecurityModelEntry
Returns:
The securityLevel used by this user entry.

setSecurityLevel

public void setSecurityLevel(byte level)
Sets the security level for this user entry.

Specified by:
setSecurityLevel in class SecurityModelEntry
Parameters:
level - The securityLevel to be used for this user entry.

setEngineBoots

public void setEngineBoots(int boots)
Sets the engineBoots corresponding to this user's corresponding engine entry


getEngineBoots

public int getEngineBoots()
Retrieve the engine boots value.


setEngineTime

void setEngineTime(int time)
Sets the engineTime for this user's engine entry


getEngineTime

int getEngineTime()
Retrieve the corresponding engineTime


getLocalTime

long getLocalTime()

setLocalTime

void setLocalTime(long l)

getSnmpEngineTime

public int getSnmpEngineTime()

setSnmpEngineTime

public void setSnmpEngineTime(int et)

setAuthParams

public void setAuthParams(byte[] param)
Sets the auth params value. The authParams are the msgAuthentication parameters. This is used by encoding/decoding routines. API user doesn't need to call this, unless he is writing his own encoding/decoding methods.

Parameters:
param - The msgAuthentication parameters.

getAuthParams

public byte[] getAuthParams()
Gets the auth params. The authParams are the msgAuthentication parameters. This is used by encoding/decoding routines. API user doesn't need to call this, unless he is writing his own encoding/decoding methods.

Returns:
The msgAuthentication parameters.

setPrivParams

public void setPrivParams(byte[] param)
Sets the priv params field. The privParams are the msgPrivacyParameters. This is used by encoding/decoding routines. API user doesn't need to call this unless he is writing his own encoding/decoding methods.

Parameters:
param - The msgPrivacyParameters.

getPrivParams

public byte[] getPrivParams()
Retrieve the priv params. The privParams are the msgPrivacyParameters. This is used by encoding/decoding routines. API user doesn't need to call this, unless he is writing his own encoding/decoding methods.

Returns:
The msgPrivacyParameters.

setEngineEntry

public void setEngineEntry(SnmpEngineEntry entry)
Sets the SnmpEngineEntry reference. When a new USMUserEntry is created its corresponding SnmpV3 entity i.e the SnmpEngineEntry should be set. This is because the SnmpEngineEntry maintains the timeliness values and these are used for the authentication purpose.

Parameters:
entry - The SnmpEngineEntry to be set.

getEngineEntry

public SnmpEngineEntry getEngineEntry()
Gets the corresponding SnmpEngineEntry reference. When a new USMUserEntry is created its corresponding SnmpV3 entity i.e., the SnmpEngineEntry should be set. This is because the SnmpEngineEntry maintains the timeliness values and these are used for the authentication purpose.

Returns:
The SnmpEngineEntry associated with this object.

getUserCloneFrom

public int[] getUserCloneFrom()
Gets the USMUserCloneFrom OID associated with this USMUserEntry. This is basically used, incase of an agent side implementation.

Returns:
the clone from OID.

setUserCloneFrom

public void setUserCloneFrom(int[] oid)
Sets the USM UserCloneFrom OID for this USMUserEntry. This is basically used incase of an agent side implementation.

Parameters:
oid - The clone from OID to set.

getUserPublic

public byte[] getUserPublic()
Gets the USM UserPublic associated with this USMUserEntry. This is used in case of an agent side mplementation.

Returns:
the usmUserPublic value.

setUserPublic

public void setUserPublic(byte[] userPublic)
Sets the USM UserPublic associated with this USMUserEntry. This is used in case of an agent side implementation.

Parameters:
userPublic - The usmUserPublic value to be used to set on this entry.

getStorageType

public int getStorageType()
Gets the USM StorageType associated with this USMUserEntry.


setStorageType

public void setStorageType(int storageType)
Sets the USM StorageType associated with this USMUserEntry.


getUserStatus

public int getUserStatus()
Gets the USM UserStatus associated with this USMUserEntry.


setUserStatus

public void setUserStatus(int userStatus)
Sets the USM UserStatus associated with this USMUserEntry. This is used in case of an agent side mplementation.

Parameters:
userStatus - The row status value to be set on this entry.

setOwnKeyChange

public void setOwnKeyChange(boolean flag)
Sets the ownKeyChange flag. This flag needs to be set only in case of an agent side implementation, where, if an OwnKeyChange request comes to the agent, it needs to encode a proper digest. .ie., the digest should be made w.r.t the auth/priv key prior to the change. This flag will enable to form a proper digest in the response PDU.

Parameters:
flag - the flag value shlould be true if an ownKeyChange is to be performed. The default value is false.

setUSMUtils

public void setUSMUtils(java.lang.Object utils)
The Utils object should be set, so that it can be used for encryption purpose.


getKey

public java.lang.Object getKey()
Retrieve the hash key for this user entry.

Specified by:
getKey in class SecurityModelEntry
Returns:
the hash key as a String Object.

getKey

public static java.lang.Object getKey(byte[] name,
                                      byte[] id)
Retrieve the key for this user object.

Returns:
The key as a String Object.

authenticate

public int authenticate(Snmp3Message msg)
This performs the authentication for this user entry. The authentication routine, checks the message digest and updates the time values such as the engine boots, time and also the lastReceivedTime. In case of the agent side implementaion it does the timeliness check. Returns an int value of 1 if the authentication succeeds. Returns a negative value otherwise. This method is called in the context of the SnmpSession receiver thread. The API user need not use this method.

Parameters:
msg - The Snmp3Message instance.
Returns:
  • 0 if authentication succeed i.e., both digest and timeliness check succeed.
  • -1, if digest fails or securityLevel is unsupported.
  • -2, if the timeliness check fails. -3, if the securityLevel is different.

  • timeSync

    public void timeSync(SnmpSession session)
    Deprecated. This method does not throw any exception and hence does not inform the user, in case of any error. As of AdventNet SNMP API 4 SP2 ( Release 4.0.2 ), replaced by timeSynchronize(SnmpSession,ProtocolOptions)

    Achieves time sync with the remote host. This method is synchronous and blocks. The timeSync request is sent over the SnmpSession instance passed as a parameter. Once the response is received, the engineBoots and engneTime is updated in the SnmpEngineEntry.

    Parameters:
    session - The SnmpSession instance, over which the the timeSync request is sent.

    timeSynchronize

    public void timeSynchronize(SnmpSession session,
                                ProtocolOptions po)
                         throws SnmpException
    Achieves time sync with the remote host. This method is synchronous and blocks. The timeSync request is sent over the SnmpSession instance passed as a parameter. Once the response is received, the engineBoots and engneTime is updated in the SnmpEngineEntry.

    Parameters:
    session - The SnmpSession instance, over which the the timeSync request is sent.
    po - The ProtocolOptions instance
    Throws:
    SnmpException
    Since:
    AdventNet SNMP API 4 SP2 ( Release 4.0.2 )

    sendTimeSync

    public int sendTimeSync(SnmpSession session)
    Achieves time sync with remotehost. The method is asynchronous and returns immediately after sending across the time sync pdu. The timeSync request is sent over the SnmpSession instance passed as a parameter. The response to a timeSync which is a report PDU is handled in the SnmpSession receiver thread and the engineBoots and engineTime is updated in the authenticate method.

    Parameters:
    session - The SnmpSession instance, over which the timeSync request is sent.
    Returns:
    messageID of the sent request. Returns -1, if session throws an exception, while sending the timeSync.

    sendTimeSync

    public int sendTimeSync(SnmpSession session,
                            ProtocolOptions po,
                            int reqID)
                     throws SnmpException
    Achieves time sync with remotehost. The method is asynchronous and returns immediately after sending across the time sync pdu. The timeSync request is sent over the SnmpSession instance passed as a parameter. The response to a timeSync which is a report PDU is handled in the SnmpSession receiver thread and the engineBoots and engineTime is updated in the authenticate method.

    Parameters:
    session - The SnmpSession instance, over which the timeSync request is sent.
    po - The ProtocolOptions instance
    Returns:
    messageID of the sent request. Returns -1, if session throws an exception, while sending the timeSync.
    Throws:
    SnmpException

    checkNonAuthTimes

    int checkNonAuthTimes(int boots,
                          int time)
    Checks the time values for a non-authoritative role packet(localEngineid!=pduEngineId)


    checkAuthTimes

    int checkAuthTimes(int boots,
                       int time,
                       SnmpAPI api)

    updateTimes

    void updateTimes(int boots,
                     int time)

    compare

    boolean compare(byte[] a,
                    byte[] b)
    A byte array comparison routine. Returns true if equal.


    copy

    public SecurityModelEntry copy()
    Returns a copy of this USMUserEntry.

    Specified by:
    copy in class SecurityModelEntry
    Returns:
    The copy of this entry.

    copy

    public SecurityModelEntry copy(byte[] engineID,
                                   byte[] userName)
    Returns a copy of this USMUserEntry with the userName and engineID, initialized to the values passed.

    Parameters:
    engineID - The engineID to be set in the cloned entry.
    userName - The userName to be set in the cloned entry.
    Returns:
    The copy of this entry with the userName and engineID initilaized to the values passed.

    authenticateReceivedMessage

    public int authenticateReceivedMessage(Snmp3Message msg,
                                           SnmpSession session)
    Performs authentication of the received message as per the USM security model. This will actually check, if the received message is a
    1. Discovery or timeSysnc message and respond appropriately.
    2. Response to a discovery or timeSync message. i.e discovery/timeSync report message. It will update the security info.
    3. Response to an SNMP request. Here it will authenticate the message.
    The SnmpSession is also passed so that if this module requires the message to be replied(e.g respond to a discovery/timeSync) appropriately.

    Specified by:
    authenticateReceivedMessage in class SecurityModelEntry
    Parameters:
    msg - The Snmp3Message instance.
    session - The SnmpSession instance incase this module requires to reply appropriately.
    Returns:
    0 If authentication successful and pdu is to be enQed
    1 If authentication successful and no need to enQ the pdu
    any negative value if authentication fails or other errors.

    authenticateMessageToSend

    public void authenticateMessageToSend(Snmp3Message msg,
                                          SnmpSession session)
                                   throws SnmpException
    Performs authentication of the received message as per the security model.

    Specified by:
    authenticateMessageToSend in class SecurityModelEntry
    Parameters:
    msg - The Snmp3Message instance.
    session - The SnmpSession instance.
    Throws:
    SnmpException - If the message could not be authenticated properly or particular entry is not available.

    encodeMsgSecurityParams

    public boolean encodeMsgSecurityParams(Snmp3Message msg,
                                           SnmpAPI API,
                                           ASN1Parser asnParser)
    This method will encode the USM message security parameters. This method should also set the message flags in Snmp3Message.

    Specified by:
    encodeMsgSecurityParams in class SecurityModelEntry
    Parameters:
    msg - The Snmp3Message instance.
    API - The SnmpAPI Instance.
    asnParser - The reference to ASN1Parser which has the methods to encode the SnmpPDU.

    decodeMsgSecurityParams

    public void decodeMsgSecurityParams(Snmp3Message msg,
                                        SnmpSession session,
                                        ASN1Parser asnParser)
                                 throws SnmpException,
                                        java.lang.ArrayIndexOutOfBoundsException
    This method will decode the USM security parameters.

    Specified by:
    decodeMsgSecurityParams in class SecurityModelEntry
    Parameters:
    msg - The Snmp3Message instance.
    asnParser - The reference to ASN1Parser, which has the data and methods to encode/decode the SnmpPDU.
    Throws:
    SnmpException - If the security parameters could not be decoded properly.
    java.lang.ArrayIndexOutOfBoundsException - If an unrecognized snmp message.

    processEncodedMsg

    public void processEncodedMsg(Snmp3Message msg,
                                  ASN1Parser asnParser)
    This method is called after encoding the message version. It is useful to calculate the digest over the message.

    Specified by:
    processEncodedMsg in class SecurityModelEntry
    Parameters:
    msg - Snmp3Messgage instance.
    asnParser - The reference to ASN1Parser which has the encoded data and methods to encode SnmpPDU.

    encrypt

    public int encrypt(byte[] data,
                       int spaceLeft,
                       byte[] key,
                       int protocol,
                       byte[] privParms)
                throws SnmpException
    Description copied from class: SecurityModelEntry
    This method is called to encrypt the data.

    Specified by:
    encrypt in class SecurityModelEntry
    Parameters:
    data - The data to be encrypt.
    key - The key value used in encryption.
    protocol - The protocol used for encryption.
    privParms - The privacy params used in encryption.
    Throws:
    SnmpException

    decrypt

    public byte[] decrypt(byte[] data,
                          int spaceLeft,
                          byte[] key,
                          int protocol,
                          byte[] privParms)
    Description copied from class: SecurityModelEntry
    This method is called to decrypt the data.

    Specified by:
    decrypt in class SecurityModelEntry
    Parameters:
    data - The data to be decrypt.
    spaceLeft - The offset value to be used in decrypt.
    key - The key value to be used in decryption.
    protocol - The protocol used for decryption.
    privParms - The privacy params used in decryption.
    Returns:
    data The decrypted data.

    init

    public void init(SnmpSession session,
                     ProtocolOptions po)
              throws SnmpException
    Specified by:
    init in class SecurityModelEntry
    Throws:
    SnmpException