com.adventnet.snmp.snmp2.usm
Class USMUserEntry

java.lang.Object
  |
  +--com.adventnet.snmp.snmp2.SecurityModelEntry
        |
        +--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

static int	CBC_DES Constant for SNMPV3 usmUser CBC_DES PrivProtocol.
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.
static int	SHA_AUTH Constant for SNMPV3 usmUser SHA AuthProtocol.
static byte	USM_SECURITY_MODEL Constant for the User Based Security Model.

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.
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.
SnmpEngineEntry	getEngineEntry() Gets the corresponding SnmpEngineEntry reference.
byte[]	getEngineID() Retrieves the Engine identifier associated with the SNMP engine.
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.
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	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	processEncodedMsg(Snmp3Message msg, ASN1Parser asnParser) This method is called after encoding the message version.
int	sendTimeSync(SnmpSession session) 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	setEngineEntry(SnmpEngineEntry entry) Sets the SnmpEngineEntry reference.
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	setStorageType(int storageType) Sets the USM StorageType associated with this USMUserEntry.
void	setUserCloneFrom(int[] oid) Sets the USM UserCloneFrom OID for this USMUserEntry.
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) Achieves time sync with the remote host.

Methods inherited from class java.lang.Object

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

Field Detail

USM_SECURITY_MODEL

public static final byte USM_SECURITY_MODEL

Constant for the User Based Security Model.

NO_AUTH

public static final int NO_AUTH

Constant for SNMPV3 usmNoAuthProtocol.

MD5_AUTH

public static final int MD5_AUTH

Constant for SNMPV3 usmUser MD5 AuthProtocol.

SHA_AUTH

public static final int SHA_AUTH

Constant for SNMPV3 usmUser SHA AuthProtocol.

NO_PRIV

public static final int NO_PRIV

Constant for SNMPV3 usmNoPrivProtocol.

CBC_DES

public static final int CBC_DES

Constant for SNMPV3 usmUser CBC_DES PrivProtocol.

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.

Overrides:

getEngineID in class SecurityModelEntry

getUserName

public byte[] getUserName()

Gets the userName associated with this user.

getSecurityName

public byte[] getSecurityName()

Gets the security name, which is independent of the security model.

Overrides:

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

Overrides:

getSecurityName in class SecurityModelEntry

Returns:

the securityID.

getSecurityID

public byte[] getSecurityID(byte[] securityName)

Returns the securityID ( which depends on the security model ).

Overrides:

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.

Overrides:

setSecurityName in class SecurityModelEntry

getSecurityModel

public int getSecurityModel()

Returns the securityModel.

Overrides:

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.

Overrides:

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.

Overrides:

setSecurityLevel in class SecurityModelEntry

Parameters:

level - The securityLevel to be used for this user entry.

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.

Overrides:

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)

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.

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.

copy

public SecurityModelEntry copy()

Returns a copy of this USMUserEntry.

Overrides:

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.

Overrides:

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.

Overrides:

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.

Overrides:

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.

Overrides:

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.

Overrides:

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.

Overrides:

encrypt in class SecurityModelEntry

Following copied from class: com.adventnet.snmp.snmp2.SecurityModelEntry

Parameters:

data - The data to be encrypt.

spaceleft - The space left in the buffer while encoding.

key - The key value used in encryption.

protocol - The protocol used for encryption.

privParams - The privacy params used in encryption.

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.

Overrides:

decrypt in class SecurityModelEntry

Following copied from class: com.adventnet.snmp.snmp2.SecurityModelEntry

Parameters:

data - The data to be decrypt.

offset - The offset value to be used in decrypt.

key - The key value to be used in decryption.

protocol - The protocol used for decryption.

privParams - The privacy params used in decryption.

Returns:

data The decrypted data.