org.snmp4j.security
Class USM

java.lang.Object
  extended by org.snmp4j.security.USM
All Implemented Interfaces:
SecurityModel

public class USM
extends java.lang.Object
implements SecurityModel

The USM class implements the User Based Security Model (USM) as defined in RFC3414.

When a user is added or removed from the USM, a UsmUserEvent is fired and forwarded to registered listeners.

Version:
1.2
Author:
Frank Fock

Field Summary
 
Fields inherited from interface org.snmp4j.security.SecurityModel
SECURITY_MODEL_ANY, SECURITY_MODEL_SNMPv1, SECURITY_MODEL_SNMPv2c, SECURITY_MODEL_USM
 
Constructor Summary
USM(SecurityProtocols securityProtocols, OctetString localEngineID, int engineBoots)
          Creates a USM with the support for the supplied security protocols.
 
Method Summary
 UsmUserEntry addLocalizedUser(byte[] engineID, OctetString userName, OID authProtocol, byte[] authKey, OID privProtocol, byte[] privKey)
          Adds a localized user to the USM.
 void addUser(OctetString userName, OctetString engineID, UsmUser user)
          Adds an USM user to the internal user name table and associates it with an authoritative engine ID.
 void addUser(OctetString userName, UsmUser user)
          Adds an USM user to the internal user name table.
 void addUsmUserListener(UsmUserListener l)
          Adds a UsmUserListener that should be informed whenever the internal USM user table is changed.
protected  void fireIncrementCounter(CounterEvent e)
           
protected  void fireUsmUserChange(UsmUserEvent e)
          Fires a UsmUserEvent.
 int generateRequestMessage(int snmpVersion, byte[] globalData, int maxMessageSize, int securityModel, byte[] securityEngineID, byte[] securityName, int securityLevel, BERInputStream scopedPDU, SecurityParameters securityParameters, BEROutputStream wholeMsg)
          Generate a request message.
 int generateResponseMessage(int snmpVersion, byte[] globalData, int maxMessageSize, int securityModel, byte[] securityEngineID, byte[] securityName, int securityLevel, BERInputStream scopedPDU, SecurityStateReference securityStateReference, SecurityParameters securityParameters, BEROutputStream wholeMsg)
          Generates a response message.
 CounterSupport getCounterSupport()
          Gets the counter support instance that can be used to register for counter incremnetation events.
 int getEngineBoots()
          Returns the number of engine boots counted for the local engine ID.
 int getEngineTime()
          Returns the number of seconds since the value of the engineBoots object last changed.
 int getID()
          Gets the ID of the security model.
 OctetString getLocalEngineID()
          Returns the local engine ID.
 SecurityProtocols getSecurityProtocols()
          Returns the security protocol collection used by this USM.
 UsmTimeTable getTimeTable()
          Returns the UsmTimeTable instance used by this USM for holding timing information about the local and remote SNMP entities.
 UsmUserEntry getUser(OctetString engineID, OctetString securityName)
           
 UsmUserTable getUserTable()
          Returns the UsmUserTable instance used by the USM for local storage of USM user information.
 boolean hasUser(OctetString engineID, OctetString securityName)
          Checks if the specified user is known by this USM.
 boolean isEngineDiscoveryEnabled()
          Checks whether engine ID discovery is enabled or not.
 SecurityParameters newSecurityParametersInstance()
          Creates a new SecurityParameters instance that corresponds to this security model.
 SecurityStateReference newSecurityStateReference()
          Creates a new SecurityStateReference instance that corresponds to this security model.
 int processIncomingMsg(int snmpVersion, int maxMessageSize, SecurityParameters securityParameters, SecurityModel securityModel, int securityLevel, BERInputStream wholeMsg, OctetString securityEngineID, OctetString securityName, BEROutputStream scopedPDU, Integer32 maxSizeResponseScopedPDU, SecurityStateReference securityStateReference, StatusInformation statusInfo)
          Processes an incoming message and returns its plaintext payload.
 void removeAllUsers()
          Removes all users from the USM.
 void removeEngineTime(OctetString engineID)
          Removes the specified engine ID from the internal time cache and thus forces an engine time rediscovery the next time the SNMP engine with the supplied ID is contacted.
 UsmUser removeUser(OctetString engineID, OctetString userName)
          Removes an USM user from the internal user name table.
 void removeUsmUserListener(UsmUserListener l)
          Removes a UsmUserListener.
 void setCounterSupport(CounterSupport counterSupport)
          Sets the counter support instance.
 void setEngineBoots(int engineBoots)
          Sets the number of engine boots.
 void setEngineDiscoveryEnabled(boolean engineDiscoveryEnabled)
          Enables or disables automatic engine ID discovery.
 void setLocalEngine(OctetString localEngineID, int engineBoots, int engineTime)
          Sets the local engine ID, number of boots, and time after boot.
 void setUsers(UsmUser[] users)
          Sets the users of this USM.
 void updateUser(UsmUserEntry entry)
          Updates the USM user entry with the same engine ID and user name as the supplied instance and fires an appropriate UsmUserEvent.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

USM

public USM(SecurityProtocols securityProtocols,
           OctetString localEngineID,
           int engineBoots)
Creates a USM with the support for the supplied security protocols.

Parameters:
securityProtocols - the security protocols to support.
localEngineID - the local engine ID.
engineBoots - the number of engine boots.
Since:
1.2
Method Detail

getID

public int getID()
Description copied from interface: SecurityModel
Gets the ID of the security model.

Specified by:
getID in interface SecurityModel
Returns:
one of the integer constants defined in the SecurityModel interface.
See Also:
SecurityModel.SECURITY_MODEL_ANY, SecurityModel.SECURITY_MODEL_SNMPv1, SecurityModel.SECURITY_MODEL_SNMPv2c, SecurityModel.SECURITY_MODEL_USM

setLocalEngine

public void setLocalEngine(OctetString localEngineID,
                           int engineBoots,
                           int engineTime)
Sets the local engine ID, number of boots, and time after boot.

Parameters:
localEngineID - the local engine ID.
engineBoots - the number of engine boots.
engineTime - the number sendonds since the last boot.

getLocalEngineID

public OctetString getLocalEngineID()
Returns the local engine ID.

Returns:
the local engine ID.
Since:
1.2

setEngineBoots

public void setEngineBoots(int engineBoots)
Sets the number of engine boots.

Parameters:
engineBoots - the number of engine boots.

getEngineBoots

public int getEngineBoots()
Returns the number of engine boots counted for the local engine ID.

Returns:
the number of engine boots (zero based).

getEngineTime

public int getEngineTime()
Returns the number of seconds since the value of the engineBoots object last changed. When incrementing this object's value would cause it to exceed its maximum, engineBoots is incremented as if a re-initialization had occurred, and this object's value consequently reverts to zero.

Returns:
a positive integer value denoting the number of seconds since the engineBoots value has been changed.
Since:
1.2

newSecurityParametersInstance

public SecurityParameters newSecurityParametersInstance()
Description copied from interface: SecurityModel
Creates a new SecurityParameters instance that corresponds to this security model.

Specified by:
newSecurityParametersInstance in interface SecurityModel
Returns:
a new SecurityParameters instance.

newSecurityStateReference

public SecurityStateReference newSecurityStateReference()
Description copied from interface: SecurityModel
Creates a new SecurityStateReference instance that corresponds to this security model.

Specified by:
newSecurityStateReference in interface SecurityModel
Returns:
a new SecurityStateReference instance.

generateRequestMessage

public int generateRequestMessage(int snmpVersion,
                                  byte[] globalData,
                                  int maxMessageSize,
                                  int securityModel,
                                  byte[] securityEngineID,
                                  byte[] securityName,
                                  int securityLevel,
                                  BERInputStream scopedPDU,
                                  SecurityParameters securityParameters,
                                  BEROutputStream wholeMsg)
                           throws java.io.IOException
Description copied from interface: SecurityModel
Generate a request message.

Specified by:
generateRequestMessage in interface SecurityModel
Parameters:
snmpVersion - the ID of the message processing model (SNMP version) to use.
globalData - the message header and admin data.
maxMessageSize - the maximum message size of the sending (this) SNMP entity for the selected transport mapping (determined by the message processing model).
securityModel - the security model for the outgoing message.
securityEngineID - the authoritative SNMP entity.
securityName - the principal on behalf of this message is generated.
securityLevel - the requested SecurityLevel.
scopedPDU - a BERInputStream containing the message (plain text) payload.
securityParameters - returns the SecurityParameters filled by the security model.
wholeMsg - returns the complete generated message in a BEROutputStream. The buffer of wholeMsg is set to null by the caller and must be set by the implementation of this method.
Returns:
the error status of the message generation. On success SnmpConstants.SNMPv3_USM_OK is returned, otherwise one of the other SnmpConstants.SNMPv3_USM_* values is returned.
Throws:
java.io.IOException - if generation of the message fails because of an internal or an resource error.

hasUser

public boolean hasUser(OctetString engineID,
                       OctetString securityName)
Checks if the specified user is known by this USM.

Parameters:
engineID - the engineID of the user (may be null if any target should match).
securityName - the security name of the user to earch for.
Returns:
true if the user is either known for the specified engine ID or without a specific engine ID (discovery only).
Since:

getUser

public UsmUserEntry getUser(OctetString engineID,
                            OctetString securityName)

generateResponseMessage

public int generateResponseMessage(int snmpVersion,
                                   byte[] globalData,
                                   int maxMessageSize,
                                   int securityModel,
                                   byte[] securityEngineID,
                                   byte[] securityName,
                                   int securityLevel,
                                   BERInputStream scopedPDU,
                                   SecurityStateReference securityStateReference,
                                   SecurityParameters securityParameters,
                                   BEROutputStream wholeMsg)
                            throws java.io.IOException
Description copied from interface: SecurityModel
Generates a response message.

Specified by:
generateResponseMessage in interface SecurityModel
Parameters:
snmpVersion - the ID of the message processing model (SNMP version) to use.
globalData - the message header and admin data.
maxMessageSize - the maximum message size of the sending (this) SNMP entity for the selected transport mapping (determined by the message processing model).
securityModel - the security model for the outgoing message.
securityEngineID - the authoritative SNMP entity.
securityName - the principal on behalf of this message is generated.
securityLevel - the requested SecurityLevel.
scopedPDU - a BERInputStream containing the message (plain text) payload.
securityStateReference - a SecurityStateReference instance providing information from original request.
securityParameters - returns the SecurityParameters filled by the security model.
wholeMsg - returns the complete generated message in a BEROutputStream. The buffer of wholeMsg is set to null by the caller and must be set by the implementation of this method.
Returns:
the error status of the message generation. On success SnmpConstants.SNMPv3_USM_OK is returned, otherwise one of the other SnmpConstants.SNMPv3_USM_* values is returned.
Throws:
java.io.IOException - if generation of the message fails because of an internal or an resource error.

processIncomingMsg

public int processIncomingMsg(int snmpVersion,
                              int maxMessageSize,
                              SecurityParameters securityParameters,
                              SecurityModel securityModel,
                              int securityLevel,
                              BERInputStream wholeMsg,
                              OctetString securityEngineID,
                              OctetString securityName,
                              BEROutputStream scopedPDU,
                              Integer32 maxSizeResponseScopedPDU,
                              SecurityStateReference securityStateReference,
                              StatusInformation statusInfo)
                       throws java.io.IOException
Description copied from interface: SecurityModel
Processes an incoming message and returns its plaintext payload.

Specified by:
processIncomingMsg in interface SecurityModel
Parameters:
snmpVersion - the ID of the message processing model (SNMP version) to use.
maxMessageSize - the maximum message size of the message processing model for the transport mapping associated with this message's source address less the length of the maximum header length of the message processing model. This value is used by the security model to determine the maxSizeResponseScopedPDU value.
securityParameters - the SecurityParameters for the received message.
securityModel - the SecurityModel instance for the receied message.
securityLevel - the SecurityLevel ID.
wholeMsg - the BERInputStream containing the whole message as recieved on the wire.
securityEngineID - the authoritative SNMP entity.
securityName - the identification of the principal.
scopedPDU - returns the message (plaintext) payload into the supplied BEROutputStream. The buffer of scopedPDU is set to null by the caller and must be set by the implementation of this method.
maxSizeResponseScopedPDU - the determined maxmimum size for a response PDU.
securityStateReference - the SecurityStateReference information needed for a response.
statusInfo - the StatusInformation needed to generate reports if processing of the incoming message failed.
Returns:
the error status of the message processing. On success SnmpConstants.SNMPv3_USM_OK is returned, otherwise one of the other SnmpConstants.SNMPv3_USM_* values is returned.
Throws:
java.io.IOException - if an unexpected (internal) or an resource error occured.

fireIncrementCounter

protected void fireIncrementCounter(CounterEvent e)

addUser

public void addUser(OctetString userName,
                    UsmUser user)
Adds an USM user to the internal user name table.

Parameters:
userName - a user name.
user - the UsmUser to add.

addUser

public void addUser(OctetString userName,
                    OctetString engineID,
                    UsmUser user)
Adds an USM user to the internal user name table and associates it with an authoritative engine ID. This user can only be used with the specified engine ID - other engine IDs cannot be discovered on behalf of this entry.

Parameters:
userName - a user name.
engineID - the authoritative engine ID to be associated with this entry. If engineID is null this method behaves exactly like addUser(OctetString userName, UsmUser user).
user - the UsmUser to add.

updateUser

public void updateUser(UsmUserEntry entry)
Updates the USM user entry with the same engine ID and user name as the supplied instance and fires an appropriate UsmUserEvent. If the corresponding user entry does not yet exist then it will be added.

Parameters:
entry - an UsmUserEntry instance not necessarily the same as an already existing entry.
Since:
1.2

setUsers

public void setUsers(UsmUser[] users)
Sets the users of this USM. All previously added users and all localized user information will be discarded and replaced by the supplied users.

Parameters:
users - a possibly empty UsmUser array of users.
Since:
1.1

getUserTable

public UsmUserTable getUserTable()
Returns the UsmUserTable instance used by the USM for local storage of USM user information. The returned table should not be modified, because modifications will not be reported to registered UsmUserListeners.

Returns:
the UsmUserTable instance containing the users known by this USM.

getTimeTable

public UsmTimeTable getTimeTable()
Returns the UsmTimeTable instance used by this USM for holding timing information about the local and remote SNMP entities.

Returns:
UsmTimeTable
Since:
1.6

removeUser

public UsmUser removeUser(OctetString engineID,
                          OctetString userName)
Removes an USM user from the internal user name table.

Parameters:
engineID - the authoritative engine ID associated with the user, or null
userName - a user name.
Returns:
the removed UsmUser instance associate with the given userName or null if such a user could not be found.

removeAllUsers

public void removeAllUsers()
Removes all users from the USM.


addLocalizedUser

public UsmUserEntry addLocalizedUser(byte[] engineID,
                                     OctetString userName,
                                     OID authProtocol,
                                     byte[] authKey,
                                     OID privProtocol,
                                     byte[] privKey)
Adds a localized user to the USM.

Parameters:
engineID - the engine ID for which the user has been localized.
userName - the user's name.
authProtocol - the authentication protocol ID.
authKey - the authentication key.
privProtocol - the privacy protocol ID.
privKey - the privacy key.
Returns:
the added UsmUserEntry.

isEngineDiscoveryEnabled

public boolean isEngineDiscoveryEnabled()
Checks whether engine ID discovery is enabled or not. If enabled, the USM will try to discover unknown engine IDs "on-the-fly" while processing the message.

Returns:
true if discovery is enabled, false otherwise.

setEngineDiscoveryEnabled

public void setEngineDiscoveryEnabled(boolean engineDiscoveryEnabled)
Enables or disables automatic engine ID discovery.

Parameters:
engineDiscoveryEnabled - true if discovery should be enabled, false otherwise.

removeUsmUserListener

public void removeUsmUserListener(UsmUserListener l)
Removes a UsmUserListener.

Parameters:
l - a proeviously added UsmUserListener.

addUsmUserListener

public void addUsmUserListener(UsmUserListener l)
Adds a UsmUserListener that should be informed whenever the internal USM user table is changed.

Parameters:
l - a UsmUserListener that should be informed about UsmUserEvent events.

removeEngineTime

public void removeEngineTime(OctetString engineID)
Removes the specified engine ID from the internal time cache and thus forces an engine time rediscovery the next time the SNMP engine with the supplied ID is contacted.

Parameters:
engineID - the SNMP engine ID whose engine time to remove.
Since:
1.6

fireUsmUserChange

protected void fireUsmUserChange(UsmUserEvent e)
Fires a UsmUserEvent.

Parameters:
e - the UsmUserEvent to fire.

getCounterSupport

public CounterSupport getCounterSupport()
Gets the counter support instance that can be used to register for counter incremnetation events.

Returns:
a CounterSupport instance that is used to fire CounterEvent.

getSecurityProtocols

public SecurityProtocols getSecurityProtocols()
Returns the security protocol collection used by this USM.

Returns:
a SecurityProtocols instance which is by default the same instance as returned by SecurityProtocols.getInstance().
Since:
1.2

setCounterSupport

public void setCounterSupport(CounterSupport counterSupport)
Sets the counter support instance. By default, the singleton instance provided by the CounterSupport instance is used.

Parameters:
counterSupport - a CounterSupport subclass instance.

Copyright 2005-2010 Frank Fock (SNMP4J.org)

Copyright © 2011 SNMP4J.org. All Rights Reserved.