Module org.snmp4j
Package org.snmp4j.mp

Class MPv3

java.lang.Object
org.snmp4j.mp.MPv3
All Implemented Interfaces:
EngineIdCacheSize, MessageProcessingModel
public class MPv3 extends Object implements MessageProcessingModel, EngineIdCacheSize
The MPv3 is the message processing model for SNMPv3.
Version:
1.9.2
Author:
Frank Fock

  • Field Details

    • ID

      public static final int ID
      See Also:

    • MPv3_REPORTABLE_FLAG

      public static final int MPv3_REPORTABLE_FLAG
      See Also:

    • MAX_MESSAGE_ID

      public static final int MAX_MESSAGE_ID
      See Also:

    • LOCAL_ENGINE_ID

      public static final OctetString LOCAL_ENGINE_ID
      Local engine ID constant for context engineID discovery as defined by RFC 5343.

    • MAXLEN_ENGINE_ID

      public static final int MAXLEN_ENGINE_ID
      See Also:

    • MINLEN_ENGINE_ID

      public static final int MINLEN_ENGINE_ID
      See Also:

    • MAX_HEADER_LENGTH

      public static final int MAX_HEADER_LENGTH

    • engineIdCacheFactory

      protected MPv3.EngineIdCacheFactory engineIdCacheFactory

    • incomingPDUFactory

      protected PDUFactory incomingPDUFactory

  • Constructor Details

    • MPv3

      public MPv3()
      Creates a MPv3 with a default local engine ID.

    • MPv3

      public MPv3(byte[] localEngineID)
      Creates a MPv3 with a supplied local engine ID.
      Parameters:
      localEngineID - the local engine ID. Its length must be greater or equal than 5 and less or equal than 32.

    • MPv3

      public MPv3(byte[] localEngineID, PDUFactory incomingPDUFactory)
      Creates a MPv3 with a supplied local engine ID and PDUFactory for incoming messages.
      Parameters:
      localEngineID - the local engine ID. Its length must be greater or equal than 5 and less or equal than 32.
      incomingPDUFactory - a PDUFactory. If null the default factory will be used which creates ScopedPDU instances.
      Since:
      1.9.1

    • MPv3

      public MPv3(USM usm)
      This is a convenience constructor which can be used to create a MPv3 which is bound to a specific USM instance. A dedicated USM instance per MPv3 is necessary if multiple Snmp instances are used within a VM.
      Parameters:
      usm - an USM instance.
      Since:
      1.10

    • MPv3

      public MPv3(byte[] localEngineID, PDUFactory incomingPDUFactory, SecurityProtocols secProtocols, SecurityModels secModels, CounterSupport counterSupport)
      Creates a fully qualified MPv3 instance with custom security protocols and models as well as a custom counter support. The current message ID is set using the USM engine boots counter (if available) according to the RFC3412 §6.2.
      Parameters:
      localEngineID - the local engine ID. Its length must be greater or equal than 5 and less or equal than 32.
      incomingPDUFactory - a PDUFactory. If null the default factory will be used which creates ScopedPDU instances.
      secProtocols - the SecurityProtocols instance to use when looking up a security protocol. To get a default instance, use SecurityProtocols.getInstance().
      secModels - the SecurityModels instance to use when looking up a security model. If you use more than one USM instance, you need to create a SecurityProtocols instance (container) for each such USM instance (and MPv3 combination). To get a default instance, use SecurityProtocols.getInstance().
      counterSupport - The CounterSupport instance to be used to count events created by this MPv3 instance. To get a default instance, use CounterSupport.getInstance().
      Since:
      1.10

  • Method Details

    • getEngineIdCacheFactory

      public MPv3.EngineIdCacheFactory getEngineIdCacheFactory()
      Returns the enging ID factory that was used to create the current engine ID cache.
      Returns:
      a MPv3.EngineIdCacheFactory implementation.
      Since:
      2.3.4

    • setEngineIdCacheFactory

      public void setEngineIdCacheFactory(MPv3.EngineIdCacheFactory engineIdCacheFactory)
      Sets the engine ID cache factory and resets (clears) the current cache. The maximum size of the cache is determined using getMaxEngineIdCacheSize() as this implements the EngineIdCacheSize interface. By default the maximum cache size SNMP4JSettings.getMaxEngineIdCacheSize() is used.
      Parameters:
      engineIdCacheFactory - a MPv3.EngineIdCacheFactory implementation that is used to create a new cache.
      Since:
      2.3.4

    • getMaxEngineIdCacheSize

      public int getMaxEngineIdCacheSize()
      Description copied from interface: EngineIdCacheSize
      Gets the maximum number of transport address to engineID mappings to be hold in the cache.
      Specified by:
      getMaxEngineIdCacheSize in interface EngineIdCacheSize
      Returns:
      the maximum size of the engine ID cache.

    • setMaxEngineIdCacheSize

      public void setMaxEngineIdCacheSize(int maxEngineIdCacheSize)
      Sets the upper limit for the engine ID cache. Modifying this value will not immediately take effect on the cache size.
      Parameters:
      maxEngineIdCacheSize - the maximum number of engine IDs hold in the internal cache. If more than those engine IDs are used by the MPv3, the eldest engine ID is removed from the cache. Eldest means the eldest initial use. A different cache can be implemented by using a custom MPv3.EngineIdCacheFactory and setting it after calling this constructor.

    • createLocalEngineID

      public static byte[] createLocalEngineID()
      Creates a local engine ID based on the local IP address and additional four random bytes. WARNING: Do not use this engine ID generator for a command responder (agent) if you DO NOT persistently save the one time generated engine ID for subsequent use when the agent is restarted.
      Returns:
      a new local engine ID with a random part to avoid engine ID clashes for multiple command generators on the same system.

    • createLocalEngineID

      public static byte[] createLocalEngineID(OctetString id)
      Creates a local engine ID based on the ID string supplied
      Parameters:
      id - an ID string.
      Returns:
      a new local engine ID.

    • setLocalEngineID

      public void setLocalEngineID(byte[] engineID)
      Sets the local engine ID. This value must not be changed after message processing has been started. Note: When setting the local engine ID, the engine boots counter should be known at the same time. Thus, please also call 
         setCurrentMsgID(randomMsgID(engineBoots));
      before starting the message processing.
      Parameters:
      engineID - the local engine ID. Its length must be greater or equal than 5 and less or equal than 32.

    • randomMsgID

      public static int randomMsgID(int engineBoots)
      Creates a random message ID according to the method proposed by RFC3412: "Values for msgID SHOULD be generated in a manner that avoids re-use of any outstanding values. Doing so provides protection against some replay attacks. One possible implementation strategy would be to use the low-order bits of snmpEngineBoots [RFC3411] as the high-order portion of the msgID value and a monotonically increasing integer for the low-order portion of msgID."
      Parameters:
      engineBoots - the number of boot operations already occurred for this SNMP entity.
      Returns:
      the new random message ID.

    • getLocalEngineID

      public byte[] getLocalEngineID()
      Gets a copy of the local engine ID.
      Returns:
      a byte array containing the local engine ID.

    • initDefaults

      public void initDefaults()
      Creates and initializes the default security protocols.
      See Also:

    • getAuthProtocol

      public AuthenticationProtocol getAuthProtocol(OID id)
      Gets an authentication protocol for the supplied ID.
      Parameters:
      id - an authentication protocol OID.
      Returns:
      an AuthenticationProtocol instance if the supplied ID is supported, otherwise null is returned.

    • getPrivProtocol

      public PrivacyProtocol getPrivProtocol(OID id)
      Gets an privacy protocol for the supplied ID.
      Parameters:
      id - an privacy protocol OID.
      Returns:
      an PrivacyProtocol instance if the supplied ID is supported, otherwise null is returned.

    • getSecurityModel

      public SecurityModel getSecurityModel(int id)
      Gets the security model for the supplied ID.
      Parameters:
      id - a security model ID.
      Returns:
      a SecurityModel instance if the supplied ID is supported, otherwise null is returned.

    • getID

      public int getID()
      Description copied from interface: MessageProcessingModel
      Gets the numerical ID of the message processing model as defined by the constants in this interface or by an appropriate constant in the class implementing this interface.
      Specified by:
      getID in interface MessageProcessingModel
      Returns:
      a positive integer value.

    • isProtocolVersionSupported

      public boolean isProtocolVersionSupported(int version)
      Description copied from interface: MessageProcessingModel
      Checks whether the supplied SNMP protocol version is supported by this message processing model.
      Specified by:
      isProtocolVersionSupported in interface MessageProcessingModel
      Parameters:
      version - the SNMP protocol version.
      Returns:
      true if the supplied SNMP protocol is supported, false otherwise.

    • addEngineID

      public boolean addEngineID(Address address, OctetString engineID)
      Adds an engine ID (other than the local engine ID) to the internal storage.
      Parameters:
      address - the Address of the remote SNMP engine.
      engineID - the engine ID of the remote SNMP engine.
      Returns:
      true if the engine ID has been added, false otherwise (if the supplied engineID equals the local one).

    • addEngineIdToCache

      protected OctetString addEngineIdToCache(Address address, OctetString engineID)
      Put the engine ID for the given address into the internal cache. If the cache reached its limit,
      Parameters:
      address - the address of the engine ID
      engineID - the engine ID to cache.
      Returns:
      the previous engine ID or null if there was no engine ID cached for the given address.
      Throws:
      IllegalArgumentException - when the local maximum cache size is exceeded.
      Since:
      2.3.4

    • getEngineID

      public OctetString getEngineID(Address address)
      Gets the engine ID associated with the supplied address from the local storage and fires the corresponding SnmpEngineEvent.
      Parameters:
      address - the Address of the remote SNMP engine.
      Returns:
      the engine ID of the remote SNMP engine or null if there is no entry for address in the local storage.

    • removeEngineID

      public OctetString removeEngineID(Address address)
      Removes an engine ID association from the local storage and fires the corresponding SnmpEngineEvent.
      Parameters:
      address - the Address of the remote SNMP engine for whose engine ID is to be removed.
      Returns:
      the removed engine ID of the remote SNMP engine or null if there is no entry for address in the local storage.

    • getNextMessageID

      public int getNextMessageID()
      Gets unique message ID.
      Returns:
      a message ID greater or equal to one and less or equal MAX_MESSAGE_ID.

    • getSecurityProtocols

      public SecurityProtocols getSecurityProtocols()
      Gets the security protocols supported by this MPv3.
      Returns:
      return a SecurityProtocols.

    • setSecurityProtocols

      public void setSecurityProtocols(SecurityProtocols securityProtocols)
      Sets the security protocols for this MPv3.
      Parameters:
      securityProtocols - SecurityProtocols

    • releaseStateReference

      public void releaseStateReference(PduHandle pduHandle)
      Description copied from interface: MessageProcessingModel
      Release the state reference associated with the supplied PduHandle.
      Specified by:
      releaseStateReference in interface MessageProcessingModel
      Parameters:
      pduHandle - a PduHandle.

    • prepareOutgoingMessage

      public <A extends Address> int prepareOutgoingMessage(A transportAddress, int maxMessageSize, int messageProcessingModel, int securityModel, byte[] securityName, int securityLevel, PDU pdu, boolean expectResponse, PduHandle sendPduHandle, BEROutputStream outgoingMessage, TransportStateReference tmStateReference) throws IOException
      Description copied from interface: MessageProcessingModel
      Prepares an outgoing message as defined in RFC3412 §7.1.
      Specified by:
      prepareOutgoingMessage in interface MessageProcessingModel
      Type Parameters:
      A - the target Address type.
      Parameters:
      transportAddress - the destination transport Address.
      maxMessageSize - the maximum message size the transport mapping for the destination address is capable of.
      messageProcessingModel - the MessageProcessingModel ID (typically, the SNMP version).
      securityModel - the security model ID (see SecurityModel) to use.
      securityName - the principal on behalf the message is to be sent.
      securityLevel - the level of security requested (see SecurityLevel).
      pdu - the PDU to send. For a SNMPv1 trap pdu has to be a PDUv1 instance, for SNMPv3 messages it has to be a ScopedPDU instance.
      expectResponse - indicates if a message expects a response. This has to be true for confirmed class PDUs and false otherwise.
      sendPduHandle - the PduHandle that uniquely identifies the sent message.
      outgoingMessage - returns the message to send.
      tmStateReference - the transport model state reference as defined by RFC 5590.
      Returns:
      the status of the message preparation. SnmpConstants.SNMP_MP_OK is returned if on success, otherwise any of the SnmpConstants.SNMP_MP_* values may be returned.
      Throws:
      IOException - if the supplied PDU could not be encoded to the outgoingMessage

    • prepareResponseMessage

      public <A extends Address> int prepareResponseMessage(int messageProcessingModel, int maxMessageSize, int securityModel, byte[] securityName, int securityLevel, PDU pdu, int maxSizeResponseScopedPDU, StateReference<A> stateReference, StatusInformation statusInformation, BEROutputStream outgoingMessage) throws IOException
      Description copied from interface: MessageProcessingModel
      Prepares a response message as defined in RFC3412 §7.1.
      Specified by:
      prepareResponseMessage in interface MessageProcessingModel
      Type Parameters:
      A - the target Address type.
      Parameters:
      messageProcessingModel - int the MessageProcessingModel ID (typically, the SNMP version).
      maxMessageSize - the maximum message size the transport mapping for the destination address is capable of.
      securityModel - the security model ID (see SecurityModel) to use.
      securityName - the principal on behalf the message is to be sent.
      securityLevel - the level of security requested (see SecurityLevel).
      pdu - the PDU to send. For a SNMPv1 trap pdu has to be a PDUv1 instance, for SNMPv3 messages it has to be a ScopedPDU instance.
      maxSizeResponseScopedPDU - the maximum size of the scoped PDU the sender (of the request) can accept.
      stateReference - reference to state information presented with the request.
      statusInformation - returns success or error indication. When an error occured, the error counter OID and value are included.
      outgoingMessage - returns the message to send.
      Returns:
      the status of the message preparation. SnmpConstants.SNMP_MP_OK is returned if on success, otherwise any of the SnmpConstants.SNMP_MP_* values may be returned.
      Throws:
      IOException - if an internal error or a resource exception occured.

    • sendReport

      public int sendReport(MessageDispatcher messageDispatcher, ScopedPDU pdu, int securityLevel, int securityModel, OctetString securityName, int maxSizeResponseScopedPDU, StateReference<?> stateReference, VariableBinding payload)
      Sends a report message.
      Parameters:
      messageDispatcher - Send the message on behalf the supplied MessageDispatcher instance.
      pdu - ScopedPDU If null, then contextEngineID, contextName, and requestID of the report generated will be zero length and zero respective. Otherwise these values are extracted from the PDU.
      securityLevel - The security level to use when sending this report.
      securityModel - The security model to use when sending this report.
      securityName - The security name to use when sending this report.
      maxSizeResponseScopedPDU - the maximum size of of the report message (will be most likely ignored because a report should always fit in 484 bytes).
      stateReference - the state reference associated with the original message.
      payload - the variable binding to include in the report message.
      Returns:
      an SNMP MPv3 error code or 0 if the report has been send successfully.

    • prepareDataElements

      public <A extends Address> int prepareDataElements(MessageDispatcher messageDispatcher, A transportAddress, BERInputStream wholeMsg, TransportStateReference tmStateReference, Integer32 messageProcessingModel, Integer32 securityModel, OctetString securityName, Integer32 securityLevel, MutablePDU pdu, PduHandle sendPduHandle, Integer32 maxSizeResponseScopedPDU, StatusInformation statusInformation, MutableStateReference<A> mutableStateReference)
      Description copied from interface: MessageProcessingModel
      Prepare data elements from an incoming SNMP message as described in RFC3412 §7.2.
      Specified by:
      prepareDataElements in interface MessageProcessingModel
      Type Parameters:
      A - the target Address type.
      Parameters:
      messageDispatcher - the MessageDispatcher instance to be used to send reports. Thus, messageDispatcher is typically the calling module.
      transportAddress - the origin transport address.
      wholeMsg - the whole message as received from the network.
      tmStateReference - the transport model state reference as defined by RFC 5590.
      messageProcessingModel - returns the message processing model (typically the SNMP version).
      securityModel - returns the security model ID (see SecurityModel.
      securityName - returns the principal.
      securityLevel - returns the requested security level (see SecurityLevel).
      pdu - returns SNMP protocol data unit (the payload of the received message).
      sendPduHandle - returns the handle to match request.
      maxSizeResponseScopedPDU - returns the maximum size of the scoped PDU the sender can accept.
      statusInformation - returns success or error indication. When an error occured, the error counter OID and value are included.
      mutableStateReference - returns the state reference to be used for a possible response. On input the stateReference may contain information about the transport mapping of the incoming request. This allows the MessageProcessingModel to send reports over the same transport as it received them.
      Returns:
      int the status of the message preparation. SnmpConstants.SNMP_MP_OK is returned on success, otherwise any of the SnmpConstants.SNMP_MP_* values may be returned.

    • setSecurityModels

      public void setSecurityModels(SecurityModels securityModels)
      Sets the security models supported by this MPv3.
      Parameters:
      securityModels - a SecurityModels instance.

    • getSecurityModels

      public SecurityModels getSecurityModels()
      Gets the security models supported by this MPv3.
      Returns:
      a SecurityModels instance.

    • fireIncrementCounter

      protected void fireIncrementCounter(CounterEvent e)
      Fire a counter incrementation event.
      Parameters:
      e - CounterEvent

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

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

    • addSnmpEngineListener

      public void addSnmpEngineListener(SnmpEngineListener l)
      Adds a SNMP engine listener that needs to be informed about changes to the engine ID cache.
      Parameters:
      l - a SnmpEngineListener instance.
      Since:
      1.6

    • removeSnmpEngineListener

      public void removeSnmpEngineListener(SnmpEngineListener l)
      Removes a SNMP engine listener.
      Parameters:
      l - a SnmpEngineListener instance.
      Since:
      1.6

    • getEngineIdCacheSize

      public int getEngineIdCacheSize()
      Get the number of cached engine IDs.
      Returns:
      size of the internal engine ID cache.
      Since:
      2.3.4

    • createPDU

      @Deprecated public PDU createPDU(Target<?> target)
      Deprecated.
      Use DefaultPDUFactory.createPDU(MessageProcessingModel, int) instead.
      Creates a PDU class that is used to parse incoming SNMP messages.
      Parameters:
      target - the target parameter must be ignored.
      Returns:
      a ScopedPDU instance by default.
      Since:
      1.9.1

    • getNextMsgID

      public int getNextMsgID()
      Gets the message ID that will be used for the next request to be sent by this message processing model.
      Returns:
      the next message ID used by the MPv3.
      Since:
      2.4.3

    • setCurrentMsgID

      public void setCurrentMsgID(int nextMsgID)
      Sets the next message ID. According to RFC3412, the message ID should be unique across reboots: "Values for msgID SHOULD be generated in a manner that avoids re-use of any outstanding values. Doing so provides protection against some replay attacks. One possible implementation strategy would be to use the low-order bits of snmpEngineBoots [RFC3411] as the high-order portion of the msgID value and a monotonically increasing integer for the low-order portion of msgID."
      Parameters:
      nextMsgID - a message ID that has not been used by this SNMP entity yet (preferably also not used during previous runs).
      Since:
      2.4.3

    • fireEngineChanged

      protected void fireEngineChanged(SnmpEngineEvent engineEvent)
      Fires a SNMP engine event the registered listeners.
      Parameters:
      engineEvent - the SnmpEngineEvent instance to fire.
      Since:
      1.6