java.lang.Object
org.snmp4j.security.SNMPv3SecurityModel
org.snmp4j.security.USM
- All Implemented Interfaces:
SecurityModel
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
counterSupport, 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
ConstructorDescriptionUSM()
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.USM
(SecurityProtocols securityProtocols, OctetString localEngineID, int engineBoots, CounterSupport counterSupport) Creates a USM with the support for the supplied security protocols. -
Method Summary
Modifier and TypeMethodDescriptionaddLocalizedUser
(byte[] engineID, OctetString userName, OID authProtocol, byte[] authKey, OID privProtocol, byte[] privKey) Adds a localized user to the USM.protected UsmUserEntry
addLocalizedUsmUserEntry
(OctetString engineID, OctetString securityName, UsmUserEntry entry) void
Adds an USM user to the internal username table.void
addUser
(OctetString userName, UsmUser user) Adds an USM user to the internal username table.void
addUser
(OctetString userName, OctetString engineID, UsmUser user) Adds an USM user to the internal username table and associates it with an authoritative engine ID.addUsmUserEntry
(UsmUserEntry usmUserEntry) Adds an USM user to the internal username table.void
Adds aUsmUserListener
that should be informed whenever the internal USM user table is changed.protected void
protected void
Fires aUsmUserEvent
.int
generateRequestMessage
(int snmpVersion, byte[] globalData, int maxMessageSize, int securityModel, byte[] securityEngineID, byte[] securityName, int securityLevel, BERInputStream scopedPDU, SecurityParameters securityParameters, BEROutputStream wholeMsg, TransportStateReference tmStateReference, SecurityStateReference securityStateReference) 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.int
Returns the number of engine boots counted for the local engine ID.int
Returns the number of seconds since the value of the engineBoots object last changed.int
getID()
Gets the ID of the security model.Returns the security protocol collection used by this USM.Returns theUsmTimeTable
instance used by this USM for holding timing information about the local and remote SNMP entities.getUser
(OctetString engineID, OctetString securityName) Looks up aUsmUserEntry
by an engine ID and security name.getUser
(OctetString engineID, OctetString securityName, UsmUser.LocalizationGrant requiredLocalizationGrant) Looks up aUsmUserEntry
by an engine ID and security name.Returns theUsmUserTable
instance used by the USM for local storage of USM user information.boolean
Checks whether thisSecurityModel
has an authoritative engine ID.boolean
hasUser
(OctetString engineID, OctetString securityName) Checks if the specified user is known by this USM.boolean
Checks whether engine ID discovery is enabled or not.Creates a newSecurityParameters
instance that corresponds to this security model.Creates a newSecurityStateReference
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
Removes all users from the USM.removeAllUsers
(OctetString userName) Removes all USM user from the internal username table with the specified username.removeAllUsers
(OctetString userName, OctetString engineID) Removes all USM user from the internal username table with the specified username 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.removeUser
(OctetString engineID, OctetString userName) Deprecated.void
Removes aUsmUserListener
.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
Sets the users of this USM.boolean
Checks whether thisSecurityModel
supports authoritative engine ID discovery.void
updateUser
(UsmUserEntry entry) Updates the USM user entry with the same engine ID and username as the supplied instance and fires an appropriateUsmUserEvent
.Methods inherited from class org.snmp4j.security.SNMPv3SecurityModel
buildMessageBuffer, buildWholeMessage, getCounterSupport, getLocalEngineID, setCounterSupport
-
Field Details
-
RFC3414_11_2_MIN_PASSWORD_LENGTH
public static final int RFC3414_11_2_MIN_PASSWORD_LENGTH- See Also:
-
-
Constructor Details
-
USM
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(SecurityProtocols securityProtocols, OctetString localEngineID, int engineBoots, CounterSupport counterSupport) 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.counterSupport
- theCounterSupport
instance to be used for counting events.- Since:
- 3.5.0
-
USM
public USM()Default constructor with random engine ID with the default enterprise ID and a zero engineBoots counter. The security protocols instance defined bySecurityProtocols.getInstance()
with the default protocols is used.- Since:
- 2.2.4
-
-
Method Details
-
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:
-
supportsEngineIdDiscovery
public boolean supportsEngineIdDiscovery()Description copied from interface:SecurityModel
Checks whether thisSecurityModel
supports authoritative engine ID discovery. TheUSM
for instance, returnstrue
whereasTSM
returnsfalse
. 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 thisSecurityModel
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
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
Description copied from interface:SecurityModel
Creates a newSecurityParameters
instance that corresponds to this security model.- Returns:
- a new
SecurityParameters
instance.
-
newSecurityStateReference
Description copied from interface:SecurityModel
Creates a newSecurityStateReference
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, SecurityStateReference securityStateReference) 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 requestedSecurityLevel
.scopedPDU
- a BERInputStream containing the message (plain text) payload.securityParameters
- returns theSecurityParameters
filled by the security model.wholeMsg
- returns the complete generated message in aBEROutputStream
. The buffer ofwholeMsg
is set tonull
by the caller and must be set by the implementation of this method.tmStateReference
- the transport model state reference as defined by RFC 5590.securityStateReference
- aSecurityStateReference
instance collecting information for response processing, i.e. should benull
if no response is expected. This security state reference will be stored in the message processing model cache for response processing.- Returns:
- the error status of the message generation. On success
SnmpConstants.SNMPv3_USM_OK
is returned, otherwise one of the otherSnmpConstants.SNMPv3_USM_*
values is returned. - Throws:
IOException
- if generation of the message fails because of an internal or an resource error.
-
hasUser
Checks if the specified user is known by this USM.- Parameters:
engineID
- the engineID of the user (may benull
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
Looks up aUsmUserEntry
by an engine ID and security name. If a 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 emptyUsmUserEntry
is returned with just the provided securityName set.- Parameters:
engineID
- an engine ID.securityName
- a security name.- Returns:
- a localized
UsmUserEntry
if the provided engineID's length is greater than zero andnull
if the securityName cannot be found in the USM.
-
getUser
public UsmUserEntry getUser(OctetString engineID, OctetString securityName, UsmUser.LocalizationGrant requiredLocalizationGrant) Looks up aUsmUserEntry
by an engine ID and security name. If a 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 specified requestedUsmUser.LocalizationGrant
is allowed by the foundUsmUser.getLocalizationGrant()
. If the provided engine ID has a zero length then an emptyUsmUserEntry
is returned with just the provided securityName set.- Parameters:
engineID
- an engine ID.securityName
- a security name.requiredLocalizationGrant
- defines the localization grant required to execute a localization on behalf of this operation.- Returns:
- a localized
UsmUserEntry
if the provided engineID's length is greater than zero and the foundUsmUser
provides a localization grant that allows the requested localization. Otherwise, returnnull
if the securityName cannot be found in the USM or localization is not granted. - Since:
- 3.8.0
-
addLocalizedUsmUserEntry
protected UsmUserEntry addLocalizedUsmUserEntry(OctetString engineID, OctetString securityName, UsmUserEntry entry) -
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 requestedSecurityLevel
.scopedPDU
- a BERInputStream containing the message (plain text) payload.securityStateReference
- aSecurityStateReference
instance providing information from original request.securityParameters
- returns theSecurityParameters
filled by the security model.wholeMsg
- returns the complete generated message in aBEROutputStream
. The buffer ofwholeMsg
is set tonull
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 otherSnmpConstants.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 themaxSizeResponseScopedPDU
value.securityParameters
- theSecurityParameters
for the received message.securityModel
- theSecurityModel
instance for the received message.securityLevel
- theSecurityLevel
ID.wholeMsg
- theBERInputStream
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 suppliedBEROutputStream
. The buffer ofscopedPDU
is set tonull
by the caller and must be set by the implementation of this method.maxSizeResponseScopedPDU
- the determined maximum size for a response PDU.securityStateReference
- theSecurityStateReference
information needed for a response.statusInfo
- theStatusInformation
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 otherSnmpConstants.SNMPv3_USM_*
values is returned. - Throws:
IOException
- if an unexpected (internal) or an resource error occurred.
-
fireIncrementCounter
-
addUser
Adds an USM user to the internal username table.- Parameters:
userName
- a username.user
- theUsmUser
to add.
-
addUser
Adds an USM user to the internal username table. The user's security name is used as userName. Since 3.6.1: If theUsmUser
is localized, then that localisation engine ID is used foraddUser(OctetString, OctetString, UsmUser)
as the engine ID parameter. This does not break implementations using this method call in 3.6.0 or before, because such user were not working anyway.- Parameters:
user
- theUsmUser
to add.- Since:
- 2.0
-
addUsmUserEntry
Adds an USM user to the internal username table. The user's security name is used as userName. The storage type member of the supplied byUsmUserEntry.getStorageType()
defines the storage type of the new USM user table entry. Entries with same engineID and securityName will be replaced.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
- theUsmUserEntry
to add.- Returns:
- previous entry registered for the same engineID and securityName or
null
if no such entry exist. - Since:
- 2.5.7
-
addUser
Adds an USM user to the internal username 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
The security name of theMPv3.MINLEN_ENGINE_ID
bytes long and not longer thanMPv3.MAXLEN_ENGINE_ID
.user
must be not longer thanMAXLEN_USMUSERNAME
bytes.- Parameters:
userName
- a username.engineID
- the authoritative engine ID to be associated with this entry. IfengineID
isnull
this method behaves exactly likeaddUser(OctetString userName, UsmUser user)
.user
- theUsmUser
to add.- Throws:
IllegalArgumentException
- if (a) the length of the engine ID is less thanMPv3.MINLEN_ENGINE_ID
or more thanMPv3.MAXLEN_ENGINE_ID
bytes (b) if the security name of theuser
is longer thanMAXLEN_USMUSERNAME
.
-
updateUser
Updates the USM user entry with the same engine ID and username as the supplied instance and fires an appropriateUsmUserEvent
. Note: IfUsmUserEntry.getStorageType()
isnull
, then the storage type of the existing row (if there is one) is copied to the new entry.- Parameters:
entry
- anUsmUserEntry
instance not necessarily the same as an already existing entry.- Since:
- 1.2
-
setUsers
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 emptyUsmUser
array of users.- Since:
- 1.1
-
getUserTable
Returns theUsmUserTable
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 registeredUsmUserListener
s.- Returns:
- the
UsmUserTable
instance containing the users known by this USM.
-
getTimeTable
Returns theUsmTimeTable
instance used by this USM for holding timing information about the local and remote SNMP entities.- Returns:
- UsmTimeTable
- Since:
- 1.6
-
removeAllUsers
Removes all USM user from the internal username table with the specified username and (optional) engine ID. If the engine ID is not provided (null) then any user (including localized) are removed that have the specified username.- Parameters:
userName
- a username.engineID
- the authoritative engine ID associated with the user by localization, ornull
if all users withuserName
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
Removes all USM user from the internal username table with the specified username. This is the same asremoveAllUsers(org.snmp4j.smi.OctetString, org.snmp4j.smi.OctetString)
with engineID set tonull
.- Parameters:
userName
- a username.- Returns:
- the removed
UsmUser
instances as a List. If the user could be found, an empty list is returned. - Since:
- 2.2
-
removeUser
Deprecated.If the engineIDnull
is provided this method does only delete the generic user. All already localized users will not be deleted. To delete those users too, useremoveAllUsers(OctetString, OctetString)
instead.Removes an USM user from the internal username table.- Parameters:
engineID
- the authoritative engine ID associated with the user, ornull
userName
- a username.- Returns:
- the removed
UsmUser
instance associate with the givenuserName
ornull
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
Removes aUsmUserListener
.- Parameters:
l
- a previously addedUsmUserListener
.
-
addUsmUserListener
Adds aUsmUserListener
that should be informed whenever the internal USM user table is changed.- Parameters:
l
- aUsmUserListener
that should be informed aboutUsmUserEvent
events.
-
removeEngineTime
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
Fires aUsmUserEvent
.- Parameters:
e
- theUsmUserEvent
to fire.
-
getSecurityProtocols
Returns the security protocol collection used by this USM.- Returns:
- a
SecurityProtocols
instance which is by default the same instance as returned bySecurityProtocols.getInstance()
. - Since:
- 1.2
-
null
is provided this method does only delete the generic user.