Module org.snmp4j
Package 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 Details

    • RFC3414_11_2_MIN_PASSWORD_LENGTH

      public static final int RFC3414_11_2_MIN_PASSWORD_LENGTH
      See Also:

  • Constructor Details

    • 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(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 - the CounterSupport instance to be used for counting events.
      Since:
      3.5.0

    • USM

      public USM(SecurityProtocols securityProtocols, OctetString localEngineID, int engineBoots, CounterSupport counterSupport, UsmUserTable usmUserTable, UsmTimeTable usmTimeTable)
      Creates a USM with the support for the supplied security protocols and with provided UsmTimeTable and UsmUserTable.
      Parameters:
      securityProtocols - the security protocols to support.
      localEngineID - the local engine ID.
      engineBoots - the number of engine boots.
      counterSupport - the CounterSupport instance to be used for counting events.
      usmUserTable - the UsmUserTable to be used by this USM to lockup and store USM users.
      usmTimeTable - the UsmTimeTable to be used to verify engineIDs and their time synchronization.
      Since:
      3.9.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 by SecurityProtocols.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 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, 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 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.
      securityStateReference - a SecurityStateReference instance collecting information for response processing, i.e. should be null 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 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 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 empty UsmUserEntry 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 and null if the securityName cannot be found in the USM.

    • getUser

      public UsmUserEntry getUser(OctetString engineID, OctetString securityName, UsmUser.LocalizationGrant requiredLocalizationGrant)
      Looks up a UsmUserEntry 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 requested UsmUser.LocalizationGrant is allowed by the found UsmUser.getLocalizationGrant(). The localized user entry will be stored in the internal user table for future use. 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.
      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 found UsmUser provides a localization grant that allows the requested localization. Otherwise, return null if the securityName cannot be found in the USM or localization is not granted.
      Since:
      3.8.0

    • getUser

      public UsmUserEntry getUser(OctetString engineID, OctetString securityName, UsmUser.LocalizationGrant requiredLocalizationGrant, boolean readonly)
      Looks up a UsmUserEntry 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 requested UsmUser.LocalizationGrant is allowed by the found UsmUser.getLocalizationGrant(). If the readonly parameter is false, the localized user entry will be stored in the internal user table for future use. If the readonly parameter is true, then even if the localization is not granted for the found user, the localized UsmUserEntry for that user will be returned, because the internal user table is not modified in that case anyway. 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.
      requiredLocalizationGrant - defines the localization grant required to execute localization on behalf of this operation.
      readonly - if true then the internal user table will not be modified even if localization is done for the returned user. For normal operation, this parameter should be false to ensure, that the localization happens only once to safe computation effort.
      Returns:
      a localized UsmUserEntry if the provided engineID's length is greater than zero and the found UsmUser provides a localization grant that allows the requested localization. Otherwise, return null if the securityName cannot be found in the USM or localization is not granted.
      Since:
      3.9.0

    • addLocalizedUsmUserEntry

      protected UsmUserEntry addLocalizedUsmUserEntry(OctetString engineID, OctetString securityName, UsmUserEntry entry, boolean readonly)

    • 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

      @Deprecated public void addUser(OctetString userName, UsmUser user)
      Deprecated.
      Use addUser(UsmUser) instead to make sure user's userName matches securityName.
      Adds an USM user to the internal username table.
      Parameters:
      userName - a username.
      user - the UsmUser to add.

    • addUser

      public void addUser(UsmUser user)
      Adds an USM user to the internal username table. The user's security name is used as userName. Since 3.6.1: If the UsmUser is localized, then that localisation engine ID is used for addUser(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 - the UsmUser to add.
      Since:
      2.0

    • addUsmUserEntry

      public UsmUserEntry addUsmUserEntry(UsmUserEntry usmUserEntry)
      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 by UsmUserEntry.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 - the UsmUserEntry to add.
      Returns:
      previous entry registered for the same engineID and securityName or null if no such entry exist.
      Since:
      2.5.7

    • addUser

      @Deprecated public void addUser(OctetString userName, OctetString engineID, UsmUser user)
      Deprecated.
      Use addUser(UsmUser) instead to make sure that userName matches securityName.
      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 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 username.
      engineID - the authoritative engine ID to be associated with this entry. If engineID is null this method behaves exactly like addUser(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.

    • addUser

      public void addUser(UsmUser user, OctetString engineID)
      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 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:
      user - the UsmUser to add.
      engineID - the authoritative engine ID to be associated with this entry. If engineID is not null this method will try to localize user with this engineID before adding it to the USM. If the given user is already localized, the given engineID will be ignored.
      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.
      Since:
      3.8.1

    • updateUser

      public void updateUser(UsmUserEntry entry)
      Updates the USM user entry with the same engine ID and username as the supplied instance and fires an appropriate UsmUserEvent. Note: If UsmUserEntry.getStorageType() is null, then the storage type of the existing row (if there is one) is copied to the new entry.
      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 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, 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 username table with the specified username. This is the same as removeAllUsers(org.snmp4j.smi.OctetString, org.snmp4j.smi.OctetString) with engineID set to null.
      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 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(OctetString, OctetString) instead.
      Removes an USM user from the internal username table.
      Parameters:
      engineID - the authoritative engine ID associated with the user, or null
      userName - a username.
      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.

    • 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