Module org.snmp4j
Package org.snmp4j.security

Class UsmUser

java.lang.Object
org.snmp4j.security.UsmUser
All Implemented Interfaces:
Serializable, Cloneable, Comparable<UsmUser>, User
public class UsmUser extends Object implements User, Comparable<UsmUser>, Cloneable
The UsmUser class represents USM user providing information to secure SNMPv3 message exchange. A user is characterized by its security name and optionally by a authentication protocol and passphrase as well as a privacy protocol and passphrase.

There are no setters for the attributes of this class, to prevent inconsistent states in the USM, when a user is changed from outside. Since version 3.8.0, the creator of instances of this class can define for non-localized users for which kind of SNMP processing, i.e., incoming or outgoing, localization is allowed.

Version:
3.8.0
Author:
Frank Fock
See Also:

  • Constructor Details

    • UsmUser

      public UsmUser(OctetString securityName, OID authenticationProtocol, OctetString authenticationPassphrase, OID privacyProtocol, OctetString privacyPassphrase)
      Creates a USM user.
      Parameters:
      securityName - the security name of the user (typically the username).
      authenticationProtocol - the authentication protocol ID to be associated with this user. If set to null, this user only supports unauthenticated messages.
      authenticationPassphrase - the authentication passphrase. If not null, authenticationProtocol must also be not null. RFC3414 §11.2 requires passphrases to have a minimum length of 8 bytes. If the length of authenticationPassphrase is less than 8 bytes an IllegalArgumentException is thrown.
      privacyProtocol - the privacy protocol ID to be associated with this user. If set to null, this user only supports unencrypted messages.
      privacyPassphrase - the privacy passphrase. If not null, privacyProtocol must also be not null. RFC3414 §11.2 requires passphrases to have a minimum length of 8 bytes. If the length of authenticationPassphrase is less than 8 bytes an IllegalArgumentException is thrown.

    • UsmUser

      public UsmUser(OctetString securityName, OID authenticationProtocol, OctetString authenticationPassphrase, OID privacyProtocol, OctetString privacyPassphrase, UsmUser.LocalizationGrant localizationGrant)
      Creates a USM user.
      Parameters:
      securityName - the security name of the user (typically the username).
      authenticationProtocol - the authentication protocol ID to be associated with this user. If set to null, this user only supports unauthenticated messages.
      authenticationPassphrase - the authentication passphrase. If not null, authenticationProtocol must also be not null. RFC3414 §11.2 requires passphrases to have a minimum length of 8 bytes. If the length of authenticationPassphrase is less than 8 bytes an IllegalArgumentException is thrown.
      privacyProtocol - the privacy protocol ID to be associated with this user. If set to null, this user only supports unencrypted messages.
      privacyPassphrase - the privacy passphrase. If not null, privacyProtocol must also be not null. RFC3414 §11.2 requires passphrases to have a minimum length of 8 bytes. If the length of authenticationPassphrase is less than 8 bytes an IllegalArgumentException is thrown.
      localizationGrant - defines for what kind of USM message processing this non-localized user is allowed to be localized. Note: for automatic localization to happen, USM.setEngineDiscoveryEnabled(boolean) must be enabled.
      Since:
      3.8.0

    • UsmUser

      public UsmUser(OctetString securityName, OID authenticationProtocol, OctetString authenticationPassphrase, OID privacyProtocol, OctetString privacyPassphrase, OctetString localizationEngineID)
      Creates a localized USM user.
      Parameters:
      securityName - the security name of the user (typically the username).
      authenticationProtocol - the authentication protcol ID to be associated with this user. If set to null, this user only supports unauthenticated messages.
      authenticationPassphrase - the authentication passphrase. If not null, authenticationProtocol must also be not null. RFC3414 §11.2 requires passphrases to have a minimum length of 8 bytes. If the length of authenticationPassphrase is less than 8 bytes an IllegalArgumentException is thrown.
      privacyProtocol - the privacy protocol ID to be associated with this user. If set to null, this user only supports unencrypted messages.
      privacyPassphrase - the privacy passphrase. If not null, privacyProtocol must also be not null. RFC3414 §11.2 requires passphrases to have a minimum length of 8 bytes. If the length of authenticationPassphrase is less than 8 bytes an IllegalArgumentException is thrown.
      localizationEngineID - if not null, the localizationEngineID specifies the engine ID for which the supplied passphrases are already localized. Such an USM user can only be used with the target whose engine ID equals localizationEngineID.

  • Method Details

    • getSecurityName

      public OctetString getSecurityName()
      Gets the user's security name.
      Returns:
      a clone of the user's security name.

    • getAuthenticationProtocol

      public OID getAuthenticationProtocol()
      Gets the authentication protocol ID.
      Returns:
      a clone of the authentication protocol ID or null.

    • getPrivacyProtocol

      public OID getPrivacyProtocol()
      Gets the privacy protocol ID.
      Returns:
      a clone of the privacy protocol ID or null.

    • getAuthenticationPassphrase

      public OctetString getAuthenticationPassphrase()
      Gets the authentication passphrase.
      Returns:
      a clone of the authentication passphrase or null.

    • getPrivacyPassphrase

      public OctetString getPrivacyPassphrase()
      Gets the privacy passphrase.
      Returns:
      a clone of the privacy passphrase or null.

    • getLocalizationEngineID

      public OctetString getLocalizationEngineID()
      Returns the localization engine ID for which this USM user has been already localized.
      Returns:
      null if this USM user is not localized or the SNMP engine ID of the target for which this user has been localized.
      Since:
      1.6

    • isLocalized

      public boolean isLocalized()
      Indicates whether the passphrases of this USM user need to be localized or not (true is returned in that case).
      Returns:
      true if the passphrases of this USM user represent localized keys.
      Since:
      1.6

    • isLocalizationGranted

      public boolean isLocalizationGranted(UsmUser.LocalizationGrant requiredLocalizationGrant)
      Check if the localization of this user is granted (and not yet done) for the requested localization kind.
      Parameters:
      requiredLocalizationGrant - the requested kind of localization.
      Returns:
      {«code true} if requested localization is granted and this user has not been localized yet. For a required UsmUser.LocalizationGrant.incoming, UsmUser.LocalizationGrant.incoming or UsmUser.LocalizationGrant.any is necessary, for example.
      Since:
      3.8.0

    • getSecurityModel

      public int getSecurityModel()
      Gets the security model ID of the USM.
      Returns:
      USM.getID()

    • compareTo

      public int compareTo(UsmUser other)
      Compares two USM users by their security names.
      Specified by:
      compareTo in interface Comparable<UsmUser>
      Parameters:
      other - another UsmUser instance.
      Returns:
      a negative integer, zero, or a positive integer as this object is less than, equal to, or greater than the specified object.

    • clone

      public Object clone()
      Overrides:
      clone in class Object

    • localizeUser

      public UsmUser localizeUser(OctetString localizationEngineID, OctetString localizedAuthenticationKey, OctetString localizedPrivacyKey, SecurityProtocols securityProtocols)
      Return a copy of the current user with (updated) localized keys.
      Parameters:
      localizationEngineID - the localizationEngineID specifies the engine ID for which the supplied keys are already localized. Such an USM user can only be used with the target whose engine ID equals localizationEngineID. If null, then a NullPointerException will be thrown.
      localizedAuthenticationKey - the optional new (localized) authentication key. If null, then the existing authentication key of this user is preserved and it is returned by UsmUser in its localized representation.
      localizedPrivacyKey - the optional new (localized) privacy key. If null, then the existing privacy key of this user is preserved and it is returned by UsmUser in its localized representation.
      securityProtocols - a collection of SecurityProtocol instances providing security protocols used by the SecurityProtocols.passwordToKey(OID, OctetString, byte[]) operation to localize existing passphrases. If not provided (i.e. null) and at least one of the existing passphrases is not null, then a NullPointerException is thrown.
      Returns:
      a copy of this user but with localized (optionally new) authentication or privacy keys.
      Since:
      3.4.0

    • getLocalizationGrant

      public UsmUser.LocalizationGrant getLocalizationGrant()
      Returns for which kind of USM request processing a localization of this user is allowed.
      Returns:
      the allowed localization options. For already localized users, UsmUser.LocalizationGrant.never is returned.
      Since:
      3.8.0

    • equals

      public boolean equals(Object o)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • toString

      public String toString()
      Overrides:
      toString in class Object