org.snmp4j.mp
Class MPv3

java.lang.Object
  extended by org.snmp4j.mp.MPv3
All Implemented Interfaces:
MessageProcessingModel

public class MPv3
extends java.lang.Object
implements MessageProcessingModel

The MPv3 is the message processing model for SNMPv3.

Version:
1.9.2
Author:
Frank Fock

Nested Class Summary
protected static class MPv3.Cache
          The Cache stores state reference information for the MPv3.
protected static class MPv3.CacheEntry
          The CacheEntry class holds state reference information for the MPv3 message processing model for a single message.
protected static class MPv3.HeaderData
          The HeaderData represents the message header information of SNMPv3 message.
 
Field Summary
static int ID
           
protected  PDUFactory incomingPDUFactory
           
static int MAX_MESSAGE_ID
           
static int MAXLEN_ENGINE_ID
           
static int MINLEN_ENGINE_ID
           
static int MPv3_REPORTABLE_FLAG
           
 
Fields inherited from interface org.snmp4j.mp.MessageProcessingModel
MPv1, MPv2c, MPv2u, MPv3
 
Constructor Summary
MPv3()
          Creates a MPv3 with a default local engine ID.
MPv3(byte[] localEngineID)
          Creates a MPv3 with a supplied local engine ID.
MPv3(byte[] localEngineID, PDUFactory incomingPDUFactory)
          Creates a MPv3 with a supplied local engine ID and PDUFactory for incoming messages.
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.
MPv3(USM usm)
          This is a convenience constructor which can be used to create a MPv3 which is bound to a specific USM instance.
 
Method Summary
 boolean addEngineID(Address address, OctetString engineID)
          Adds an engine ID (other than the local engine ID) to the internal storage.
 void addSnmpEngineListener(SnmpEngineListener l)
          Adds a SNMP engine listener that needs to be informed about changes to the engine ID cache.
static byte[] createLocalEngineID()
          Creates a local engine ID based on the local IP address.
static byte[] createLocalEngineID(OctetString id)
          Creates a local engine ID based on the ID string supplied
 PDU createPDU(Target target)
          Creates a PDU class that is used to parse incoming SNMP messages.
protected  void fireEngineChanged(SnmpEngineEvent engineEvent)
          Fires a SNMP engine event the registered listeners.
protected  void fireIncrementCounter(CounterEvent e)
          Fire a counter incrementation event.
 AuthenticationProtocol getAuthProtocol(OID id)
          Gets an authentication protocol for the supplied ID.
 CounterSupport getCounterSupport()
          Gets the counter support instance that can be used to register for counter incrementation events.
protected  int getDefaultSecurityModel()
          Gets the default security model to be used for engine ID discovery.
 OctetString getEngineID(Address address)
          Gets the engine ID associated with the supplied address from the local storage and fires the corresponding SnmpEngineEvent.
static int getEnterpriseID()
          Gets the enterprise ID used for creating the local engine ID.
 int getID()
          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.
 byte[] getLocalEngineID()
          Gets a copy of the local engine ID.
 int getNextMessageID()
          Gets unique message ID.
 PrivacyProtocol getPrivProtocol(OID id)
          Gets an privacy protocol for the supplied ID.
 SecurityModel getSecurityModel(int id)
          Gets the security model for the supplied ID.
 SecurityModels getSecurityModels()
          Gets the security models supported by this MPv3.
 SecurityProtocols getSecurityProtocols()
          Gets the security protocols supported by this MPv3.
 void initDefaults()
          Creates and initializes the default security protocols.
 boolean isProtocolVersionSupported(int version)
          Checks whether the supplied SNMP protocol version is supported by this message processing model.
 int prepareDataElements(MessageDispatcher messageDispatcher, Address transportAddress, BERInputStream wholeMsg, Integer32 messageProcessingModel, Integer32 securityModel, OctetString securityName, Integer32 securityLevel, MutablePDU pdu, PduHandle sendPduHandle, Integer32 maxSizeResponseScopedPDU, StatusInformation statusInformation, MutableStateReference mutableStateReference)
          Prepare data elements from an incoming SNMP message as described in RFC3412 §7.2.
 int prepareOutgoingMessage(Address transportAddress, int maxMessageSize, int messageProcessingModel, int securityModel, byte[] securityName, int securityLevel, PDU pdu, boolean expectResponse, PduHandle sendPduHandle, Address destTransportAddress, BEROutputStream outgoingMessage)
          Prepares an outgoing message as defined in RFC3412 §7.1.
 int prepareResponseMessage(int messageProcessingModel, int maxMessageSize, int securityModel, byte[] securityName, int securityLevel, PDU pdu, int maxSizeResponseScopedPDU, StateReference stateReference, StatusInformation statusInformation, BEROutputStream outgoingMessage)
          Prepares a response message as defined in RFC3412 §7.1.
 void releaseStateReference(PduHandle pduHandle)
          Release the state reference associated with the supplied PduHandle.
 OctetString removeEngineID(Address address)
          Removes an engine ID association from the local storage and fires the corresponding SnmpEngineEvent.
 void removeSnmpEngineListener(SnmpEngineListener l)
          Removes a SNMP engine listener.
 int sendReport(MessageDispatcher messageDispatcher, ScopedPDU pdu, int securityLevel, int securityModel, OctetString securityName, int maxSizeResponseScopedPDU, StateReference stateReference, VariableBinding payload)
          Sends a report message.
 void setCounterSupport(CounterSupport counterSupport)
          Sets the counter support instance.
static void setEnterpriseID(int newEnterpriseID)
          Sets the IANA enterprise ID to be used for creating local engine ID by createLocalEngineID().
 void setLocalEngineID(byte[] engineID)
          Sets the local engine ID.
 void setSecurityModels(SecurityModels securityModels)
          Sets the security models supported by this MPv3.
 void setSecurityProtocols(SecurityProtocols securityProtocols)
          Sets the security protocols for this MPv3.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

ID

public static final int ID
See Also:
Constant Field Values

MPv3_REPORTABLE_FLAG

public static final int MPv3_REPORTABLE_FLAG
See Also:
Constant Field Values

MAX_MESSAGE_ID

public static final int MAX_MESSAGE_ID
See Also:
Constant Field Values

MAXLEN_ENGINE_ID

public static final int MAXLEN_ENGINE_ID
See Also:
Constant Field Values

MINLEN_ENGINE_ID

public static final int MINLEN_ENGINE_ID
See Also:
Constant Field Values

incomingPDUFactory

protected PDUFactory incomingPDUFactory
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 >= 5 and <= 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 >= 5 and <= 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.

Parameters:
localEngineID - the local engine ID. Its length must be >= 5 and <= 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

createLocalEngineID

public static byte[] createLocalEngineID()
Creates a local engine ID based on the local IP address.

Returns:
a new local engine ID.

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.

Parameters:
engineID - the local engine ID. Its length must be >= 5 and <= 32.

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:
SecurityProtocols.addDefaultProtocols()

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

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 >= 1 and <= 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

getDefaultSecurityModel

protected int getDefaultSecurityModel()
Gets the default security model to be used for engine ID discovery.

Returns:
a security model ID.
See Also:
USM.getID()

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 int prepareOutgoingMessage(Address transportAddress,
                                  int maxMessageSize,
                                  int messageProcessingModel,
                                  int securityModel,
                                  byte[] securityName,
                                  int securityLevel,
                                  PDU pdu,
                                  boolean expectResponse,
                                  PduHandle sendPduHandle,
                                  Address destTransportAddress,
                                  BEROutputStream outgoingMessage)
                           throws java.io.IOException
Description copied from interface: MessageProcessingModel
Prepares an outgoing message as defined in RFC3412 §7.1.

Specified by:
prepareOutgoingMessage in interface MessageProcessingModel
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.
destTransportAddress - returns the destination transport address (currently set always set to transportAddress.
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:
java.io.IOException - if the supplied PDU could not be encoded to the outgoingMessage

prepareResponseMessage

public int prepareResponseMessage(int messageProcessingModel,
                                  int maxMessageSize,
                                  int securityModel,
                                  byte[] securityName,
                                  int securityLevel,
                                  PDU pdu,
                                  int maxSizeResponseScopedPDU,
                                  StateReference stateReference,
                                  StatusInformation statusInformation,
                                  BEROutputStream outgoingMessage)
                           throws java.io.IOException
Description copied from interface: MessageProcessingModel
Prepares a response message as defined in RFC3412 §7.1.

Specified by:
prepareResponseMessage in interface MessageProcessingModel
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:
java.io.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).
payload - the variable binding to include in the report message.
stateReference - the state reference associated with the original message.
Returns:
an SNMP MPv3 error code or 0 if the report has been send successfully.

prepareDataElements

public int prepareDataElements(MessageDispatcher messageDispatcher,
                               Address transportAddress,
                               BERInputStream wholeMsg,
                               Integer32 messageProcessingModel,
                               Integer32 securityModel,
                               OctetString securityName,
                               Integer32 securityLevel,
                               MutablePDU pdu,
                               PduHandle sendPduHandle,
                               Integer32 maxSizeResponseScopedPDU,
                               StatusInformation statusInformation,
                               MutableStateReference 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
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.
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.

getEnterpriseID

public static int getEnterpriseID()
Gets the enterprise ID used for creating the local engine ID.

Returns:
an enterprise ID as registered by the IANA (see http://www.iana.org).

setEnterpriseID

public static void setEnterpriseID(int newEnterpriseID)
Sets the IANA enterprise ID to be used for creating local engine ID by createLocalEngineID().

Parameters:
newEnterpriseID - an enterprise ID as registered by the IANA (see http://www.iana.org).

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

createPDU

public PDU createPDU(Target target)
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

fireEngineChanged

protected void fireEngineChanged(SnmpEngineEvent engineEvent)
Fires a SNMP engine event the registered listeners.

Parameters:
engineEvent - the SnmpEngineEvent instance to fire.
Since:
1.6

Copyright 2005-2010 Frank Fock (SNMP4J.org)

Copyright © 2011 SNMP4J.org. All Rights Reserved.