Module org.snmp4j
Package org.snmp4j.mp

Class MPv3

    • Constructor Detail

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

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

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

      • setSecurityProtocols

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

      • 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

      • 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