public class MPv3 extends Object implements MessageProcessingModel, EngineIdCacheSize
MPv3
is the message processing model for SNMPv3.Modifier and Type | Class and Description |
---|---|
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. |
static interface |
MPv3.EngineIdCacheFactory
The
EngineIdCacheFactory creates an engine ID cache with upper limit. |
static class |
MPv3.HeaderData
The
HeaderData represents the message header information
of SNMPv3 message. |
Modifier and Type | Field and Description |
---|---|
protected MPv3.EngineIdCacheFactory |
engineIdCacheFactory |
static int |
ID |
protected PDUFactory |
incomingPDUFactory |
static OctetString |
LOCAL_ENGINE_ID
Local engine ID constant for context engineID discovery
as defined by RFC 5343.
|
static int |
MAX_MESSAGE_ID |
static int |
MAXLEN_ENGINE_ID |
static int |
MINLEN_ENGINE_ID |
static int |
MPv3_REPORTABLE_FLAG |
MPv1, MPv2c, MPv2u, MPv3
Constructor and Description |
---|
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.
|
Modifier and Type | Method and Description |
---|---|
boolean |
addEngineID(Address address,
OctetString engineID)
Adds an engine ID (other than the local engine ID) to the internal storage.
|
protected OctetString |
addEngineIdToCache(Address address,
OctetString engineID)
Put the engine ID for the given address into the internal cache.
|
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 and additional four random bytes.
|
static byte[] |
createLocalEngineID(OctetString id)
Creates a local engine ID based on the ID string supplied
|
PDU |
createPDU(Target target)
Deprecated.
|
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.
|
OctetString |
getEngineID(Address address)
Gets the engine ID associated with the supplied address from the local
storage and fires the corresponding
SnmpEngineEvent . |
MPv3.EngineIdCacheFactory |
getEngineIdCacheFactory()
Returns the enging ID factory that was used to create the current engine ID cache.
|
int |
getEngineIdCacheSize()
Get the number of cached engine IDs.
|
static int |
getEnterpriseID()
Deprecated.
Use
SNMP4JSettings.getEnterpriseID() instead. |
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 |
getMaxEngineIdCacheSize()
Gets the maximum number of transport address to engineID mappings to be hold in the cache.
|
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,
TransportStateReference tmStateReference,
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,
TransportStateReference tmStateReference)
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.
|
void |
setEngineIdCacheFactory(MPv3.EngineIdCacheFactory engineIdCacheFactory)
Sets the engine ID cache factory and resets (clears) the current cache.
|
static void |
setEnterpriseID(int newEnterpriseID)
Deprecated.
Use
SNMP4JSettings.setEnterpriseID(int) instead. |
void |
setLocalEngineID(byte[] engineID)
Sets the local engine ID.
|
void |
setMaxEngineIdCacheSize(int maxEngineIdCacheSize)
Sets the upper limit for the engine ID cache.
|
void |
setSecurityModels(SecurityModels securityModels)
Sets the security models supported by this MPv3.
|
void |
setSecurityProtocols(SecurityProtocols securityProtocols)
Sets the security protocols for this
MPv3 . |
public static final int ID
public static final int MPv3_REPORTABLE_FLAG
public static final int MAX_MESSAGE_ID
public static final OctetString LOCAL_ENGINE_ID
public static final int MAXLEN_ENGINE_ID
public static final int MINLEN_ENGINE_ID
protected MPv3.EngineIdCacheFactory engineIdCacheFactory
protected PDUFactory incomingPDUFactory
public MPv3()
public MPv3(byte[] localEngineID)
localEngineID
- the local engine ID. Its length must be >= 5 and <= 32.public MPv3(byte[] localEngineID, PDUFactory incomingPDUFactory)
PDUFactory
for incoming messages.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.public MPv3(USM usm)
Snmp
instances are used within a VM.usm
- an USM instance.public MPv3(byte[] localEngineID, PDUFactory incomingPDUFactory, SecurityProtocols secProtocols, SecurityModels secModels, CounterSupport counterSupport)
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()
.public MPv3.EngineIdCacheFactory getEngineIdCacheFactory()
MPv3.EngineIdCacheFactory
implementation.public void setEngineIdCacheFactory(MPv3.EngineIdCacheFactory engineIdCacheFactory)
getMaxEngineIdCacheSize()
as this implements the EngineIdCacheSize
interface. By default the maximum cache size SNMP4JSettings.getMaxEngineIdCacheSize()
is used.engineIdCacheFactory
- a MPv3.EngineIdCacheFactory
implementation that is used to create a new cache.public int getMaxEngineIdCacheSize()
EngineIdCacheSize
getMaxEngineIdCacheSize
in interface EngineIdCacheSize
public void setMaxEngineIdCacheSize(int maxEngineIdCacheSize)
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.public static byte[] createLocalEngineID()
public static byte[] createLocalEngineID(OctetString id)
id
- an ID string.public void setLocalEngineID(byte[] engineID)
engineID
- the local engine ID. Its length must be >= 5 and <= 32.public byte[] getLocalEngineID()
public void initDefaults()
SecurityProtocols.addDefaultProtocols()
public AuthenticationProtocol getAuthProtocol(OID id)
id
- an authentication protocol OID.AuthenticationProtocol
instance if the supplied ID
is supported, otherwise null
is returned.public PrivacyProtocol getPrivProtocol(OID id)
id
- an privacy protocol OID.PrivacyProtocol
instance if the supplied ID
is supported, otherwise null
is returned.public SecurityModel getSecurityModel(int id)
id
- a security model ID.SecurityModel
instance if the supplied ID
is supported, otherwise null
is returned.public int getID()
MessageProcessingModel
getID
in interface MessageProcessingModel
public boolean isProtocolVersionSupported(int version)
MessageProcessingModel
isProtocolVersionSupported
in interface MessageProcessingModel
version
- the SNMP protocol version.true
if the supplied SNMP protocol is supported,
false
otherwise.public boolean addEngineID(Address address, OctetString engineID)
address
- the Address
of the remote SNMP engine.engineID
- the engine ID of the remote SNMP engine.true
if the engine ID has been added, false
otherwise (if the supplied engineID
equals the local one).protected OctetString addEngineIdToCache(Address address, OctetString engineID)
address
- the address of the engine IDengineID
- the engine ID to cache.null
if there was no engine ID
cached for the given address.IllegalArgumentException
- when the local maximum cache size is exceeded.public OctetString getEngineID(Address address)
SnmpEngineEvent
.address
- the Address
of the remote SNMP engine.null
if there
is no entry for address
in the local storage.public OctetString removeEngineID(Address address)
SnmpEngineEvent
.address
- the Address
of the remote SNMP engine for whose engine ID
is to be removed.null
if
there is no entry for address
in the local storage.public int getNextMessageID()
MAX_MESSAGE_ID
.public SecurityProtocols getSecurityProtocols()
MPv3
.SecurityProtocols
.public void setSecurityProtocols(SecurityProtocols securityProtocols)
MPv3
.securityProtocols
- SecurityProtocolspublic void releaseStateReference(PduHandle pduHandle)
MessageProcessingModel
PduHandle
.releaseStateReference
in interface MessageProcessingModel
pduHandle
- a PduHandle
.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, TransportStateReference tmStateReference) throws IOException
MessageProcessingModel
prepareOutgoingMessage
in interface MessageProcessingModel
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.tmStateReference
- the transport model state reference as defined by RFC 5590.SnmpConstants.SNMP_MP_OK
is returned if on success, otherwise any of the
SnmpConstants.SNMP_MP_*
values may be returned.IOException
- if the supplied PDU could not be encoded to the
outgoingMessage
public int prepareResponseMessage(int messageProcessingModel, int maxMessageSize, int securityModel, byte[] securityName, int securityLevel, PDU pdu, int maxSizeResponseScopedPDU, StateReference stateReference, StatusInformation statusInformation, BEROutputStream outgoingMessage) throws IOException
MessageProcessingModel
prepareResponseMessage
in interface MessageProcessingModel
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.SnmpConstants.SNMP_MP_OK
is returned if on success, otherwise any of the
SnmpConstants.SNMP_MP_*
values may be returned.IOException
- if an internal error or a resource exception occured.public int sendReport(MessageDispatcher messageDispatcher, ScopedPDU pdu, int securityLevel, int securityModel, OctetString securityName, int maxSizeResponseScopedPDU, StateReference stateReference, VariableBinding payload)
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.public int prepareDataElements(MessageDispatcher messageDispatcher, Address transportAddress, BERInputStream wholeMsg, TransportStateReference tmStateReference, Integer32 messageProcessingModel, Integer32 securityModel, OctetString securityName, Integer32 securityLevel, MutablePDU pdu, PduHandle sendPduHandle, Integer32 maxSizeResponseScopedPDU, StatusInformation statusInformation, MutableStateReference mutableStateReference)
MessageProcessingModel
prepareDataElements
in interface MessageProcessingModel
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.SnmpConstants.SNMP_MP_OK
is returned on success, otherwise any of the
SnmpConstants.SNMP_MP_*
values may be returned.public void setSecurityModels(SecurityModels securityModels)
securityModels
- a SecurityModels
instance.public SecurityModels getSecurityModels()
SecurityModels
instance.public static int getEnterpriseID()
SNMP4JSettings.getEnterpriseID()
instead.public static void setEnterpriseID(int newEnterpriseID)
SNMP4JSettings.setEnterpriseID(int)
instead.createLocalEngineID()
.newEnterpriseID
- an enterprise ID as registered by the IANA (see http://www.iana.org).protected void fireIncrementCounter(CounterEvent e)
e
- CounterEventpublic CounterSupport getCounterSupport()
CounterSupport
instance that is used to fire
CounterEvent
.public void setCounterSupport(CounterSupport counterSupport)
CounterSupport
instance is used.counterSupport
- a CounterSupport
subclass instance.public void addSnmpEngineListener(SnmpEngineListener l)
l
- a SnmpEngineListener
instance.public void removeSnmpEngineListener(SnmpEngineListener l)
l
- a SnmpEngineListener
instance.public int getEngineIdCacheSize()
public PDU createPDU(Target target)
DefaultPDUFactory.createPDU(MessageProcessingModel, int)
instead.target
- the target
parameter must be ignored.ScopedPDU
instance by default.protected void fireEngineChanged(SnmpEngineEvent engineEvent)
engineEvent
- the SnmpEngineEvent
instance to fire.Copyright © 2023 SNMP4J.org. All rights reserved.