org.snmp4j.security

Class USM

java.lang.Object

org.snmp4j.security.SNMPv3SecurityModel

org.snmp4j.security.USM

All Implemented Interfaces:

SecurityModel

public class USM
extends SNMPv3SecurityModel

The USM class implements the User Based Security Model (USM) as defined in RFC 3414. When a user is added or removed from the USM, a UsmUserEvent is fired and forwarded to registered listeners.

Version:

2.0

Author:

Frank Fock

Field Summary

Fields inherited from class org.snmp4j.security.SNMPv3SecurityModel

localEngineID

Fields inherited from interface org.snmp4j.security.SecurityModel

SECURITY_MODEL_ANY, SECURITY_MODEL_SNMPv1, SECURITY_MODEL_SNMPv2c, SECURITY_MODEL_TSM, SECURITY_MODEL_USM

Constructor Summary

Constructors

Constructor and Description
USM() Default constructor with random engine ID with the default enterprise ID and a zero engineBoots counter.
USM(SecurityProtocols securityProtocols, OctetString localEngineID, int engineBoots) Creates a USM with the support for the supplied security protocols.

Method Summary

Modifier and Type	Method and Description
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	addUser(UsmUser user) Adds an USM user to the internal user name table.
void	addUsmUserEntry(UsmUserEntry usmUserEntry) 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, TransportStateReference tmStateReference) 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 incrementation 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.
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) Looks up a UsmUserEntry by an engine ID and security name.
UsmUserTable	getUserTable() Returns the UsmUserTable instance used by the USM for local storage of USM user information.
boolean	hasAuthoritativeEngineID() Checks whether this SecurityModel has an authoritative engine ID.
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, TransportStateReference tmStateReference, 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.
List<UsmUser>	removeAllUsers(OctetString userName) Removes all USM user from the internal user name table with the specified user name.
List<UsmUser>	removeAllUsers(OctetString userName, OctetString engineID) Removes all USM user from the internal user name table with the specified user name and (optional) engine ID.
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) Deprecated. If the engineID null is provided this method does only delete the generic user. All already localized users will not be deleted. To delete those users too, use removeAllUsers() instead.
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.
boolean	supportsEngineIdDiscovery() Checks whether this SecurityModel supports authoritative engine ID discovery.
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 org.snmp4j.security.SNMPv3SecurityModel

buildMessageBuffer, buildWholeMessage, getLocalEngineID

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

USM

public USM()

Default constructor with random engine ID with the default enterprise ID and a zero engineBoots counter. The security protocols instance defined by SecurityProtocols.getInstance() with the default protocols is used.

Since:

2.2.4

Method Detail

getID

public int getID()

Description copied from interface: SecurityModel

Gets the ID of the security model.

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

supportsEngineIdDiscovery

public boolean supportsEngineIdDiscovery()

Description copied from interface: SecurityModel

Checks whether this SecurityModel supports authoritative engine ID discovery. The USM for instance, returns true whereas TSM returns false. See also RFC 5343 3.2 for details.

Returns:

true if this security model has its own authoritative engine ID discovery mechanism.

hasAuthoritativeEngineID

public boolean hasAuthoritativeEngineID()

Description copied from interface: SecurityModel

Checks whether this SecurityModel has an authoritative engine ID.

Returns:

true if an authoritative engine ID is exchanged between command sender and responder using this security model, false otherwise.

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.

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.

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.

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,
                                  TransportStateReference tmStateReference)
                           throws IOException

Description copied from interface: SecurityModel

Generate a request message.

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.

tmStateReference - the transport model state reference as defined by RFC 5590.

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:

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

getUser

public UsmUserEntry getUser(OctetString engineID,
                            OctetString securityName)

Looks up a UsmUserEntry by an engine ID and security name. If an user exists that is not localized for the provided engine ID, it will be localized and then the localized user entry is returned. If the provided engine ID has a zero length then an empty UsmUserEntry is returned with just the provided securityName set.

Parameters:

engineID - an engine ID.

securityName - a security name.

Returns:

an localized UsmUserEntry if the provided engineID's length is greater than zero and null if the securityName cannot be found in the USM.

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 IOException

Description copied from interface: SecurityModel

Generates a response message.

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:

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,
                              TransportStateReference tmStateReference,
                              OctetString securityEngineID,
                              OctetString securityName,
                              BEROutputStream scopedPDU,
                              Integer32 maxSizeResponseScopedPDU,
                              SecurityStateReference securityStateReference,
                              StatusInformation statusInfo)
                       throws IOException

Description copied from interface: SecurityModel

Processes an incoming message and returns its plaintext payload.

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 received message.

securityLevel - the SecurityLevel ID.

wholeMsg - the BERInputStream containing the whole message as received on the wire.

tmStateReference - the transport model state reference as defined by RFC 5590.

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 maximum 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:

IOException - if an unexpected (internal) or an resource error occurred.

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(UsmUser user)

Adds an USM user to the internal user name table. The user's security name is used as userName.

Parameters:

user - the UsmUser to add.

Since:

2.0

addUsmUserEntry

public void addUsmUserEntry(UsmUserEntry usmUserEntry)

Adds an USM user to the internal user name table. The user's security name is used as userName. The storage type member of the supplied by UsmUserEntry.getStorageType() defines the storage type of the new USM user table entry. Caution: This is a low level call and the provided UsmUserEntry must contain already correctly localized authentication and privacy keys as well as a correct user engine ID.

Parameters:

usmUserEntry - the UsmUserEntry to add.

Since:

2.5.7

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.

The engine ID must be at least MPv3.MINLEN_ENGINE_ID bytes long and not longer than MPv3.MAXLEN_ENGINE_ID.

The security name of the user must be not longer than MAXLEN_USMUSERNAME bytes.

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.

Throws:

IllegalArgumentException - if (a) the length of the engine ID is less than MPv3.MINLEN_ENGINE_ID or more than MPv3.MAXLEN_ENGINE_ID bytes (b) if the security name of the user is longer than MAXLEN_USMUSERNAME.

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

removeAllUsers

public List<UsmUser> removeAllUsers(OctetString userName,
                                    OctetString engineID)

Removes all USM user from the internal user name table with the specified user name and (optional) engine ID. If the engine ID is not provided (null) then any user (including localized) are removed that have the specified user name.

Parameters:

userName - a user name.

engineID - the authoritative engine ID associated with the user by localization, or null if all users with userName should be deleted.

Returns:

the removed UsmUser instances as a List. If the user could be found, an empty list is returned.

Since:

2.2

removeAllUsers

public List<UsmUser> removeAllUsers(OctetString userName)

Removes all USM user from the internal user name table with the specified user name. This is the same as removeAllUsers(org.snmp4j.smi.OctetString, org.snmp4j.smi.OctetString) with engineID set to null.

Parameters:

userName - a user name.

Returns:

the removed UsmUser instances as a List. If the user could be found, an empty list is returned.

Since:

2.2

removeUser

public UsmUser removeUser(OctetString engineID,
                          OctetString userName)

Deprecated. If the engineID null is provided this method does only delete the generic user. All already localized users will not be deleted. To delete those users too, use removeAllUsers() instead.

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 previously 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 incrementation 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.