SNMP Stack 5_1

uk.co.westhawk.snmp.stack
Class SnmpContextv3Basis

java.lang.Object
  |
  +--uk.co.westhawk.snmp.stack.AbstractSnmpContext
        |
        +--uk.co.westhawk.snmp.stack.SnmpContextv3Basis
All Implemented Interfaces:
java.lang.Cloneable, java.util.EventListener, RawPduListener, java.lang.Runnable, SnmpContextBasisFace, SnmpContextv3Face
Direct Known Subclasses:
SnmpContextv3, SnmpContextv3Discovery

public abstract class SnmpContextv3Basis
extends AbstractSnmpContext
implements SnmpContextv3Face, java.lang.Cloneable

This class contains the basis for the SNMP v3 contexts that is needed by every PDU to send a SNMP v3 request.

This class will perform the v3 discovery of the SNMP engine ID and time line if necessary. This is done with the classes TimeWindow and UsmDiscoveryBean.

Now that the stack can send traps and receive requests, it needs to be able to act as an authoritative SNMP engine. This is done via the interface UsmAgent. The DefaultUsmAgent is not guaranteed to work; agents (or rather authoritative engines) should provide a better implementation.

This class will use the User Security Model (USM) as described in SNMP-USER-BASED-SM-MIB. See also RFC 3411.

It is advised to set all the properties of this class before any PDU, using this class, is sent. All properties are being used to encode the message. Some properties are being used to decode the Response or Report PDU. When any of these last properties were changed in between flight there is a possibility the decoding fails, causing a DecodingException.

destroy() should be called when the context is no longer used. This is the only way the threads will be stopped and garbage collected.

Since:
4_14
Version:
$Revision: 3.11 $ $Date: 2006/04/04 12:31:04 $
Author:
Birgit Arkesteijn
See Also:
SnmpContextv3Face, SnmpContextv3Pool, TimeWindow, UsmAgent, DefaultUsmAgent, setUsmAgent(UsmAgent), UsmDiscoveryBean

Field Summary
protected  int authenticationProtocol
           
protected  byte[] contextEngineId
           
protected  java.lang.String contextName
           
protected  boolean useAuthentication
           
protected  boolean usePrivacy
           
protected  java.lang.String userAuthenticationPassword
           
protected  byte[] userAuthKeyMD5
           
protected  byte[] userAuthKeySHA1
           
protected  java.lang.String userName
           
protected  java.lang.String userPrivacyPassword
           
protected  byte[] userPrivKeyMD5
           
protected  byte[] userPrivKeySHA1
           
protected  UsmAgent usmAgent
           
 
Fields inherited from class uk.co.westhawk.snmp.stack.AbstractSnmpContext
anyPduExpectingResponse, bindAddr, hostname, hostPort, isDestroyed, maxRecvSize, pduSupport, trapSupport, typeSocket
 
Fields inherited from interface uk.co.westhawk.snmp.stack.SnmpContextv3Face
Default_ContextName, Default_UserName, MD5_PROTOCOL, ProtocolNames, SHA1_PROTOCOL, SNMPv1_Security_Model, SNMPv2c_Security_Model, USM_Security_Model, version_id
 
Fields inherited from interface uk.co.westhawk.snmp.stack.SnmpContextBasisFace
DEFAULT_PORT, KVM_SOCKET, MAXPDU, MSS, NETSCAPE_SOCKET, STANDARD_SOCKET, TCP_SOCKET
 
Fields inherited from interface uk.co.westhawk.snmp.event.RawPduListener
version_id
 
Constructor Summary
SnmpContextv3Basis(java.lang.String host, int port)
          Constructor.
SnmpContextv3Basis(java.lang.String host, int port, java.lang.String typeSocketA)
          Constructor.
SnmpContextv3Basis(java.lang.String host, int port, java.lang.String bindAddress, java.lang.String typeSocketA)
          Constructor.
 
Method Summary
protected  byte[] actualEncodePacket(byte msg_type, int rId, int errstat, int errind, java.util.Enumeration ve, uk.co.westhawk.snmp.stack.TimeWindowNode node, java.lang.Object obj)
          Does the actual encoding.
 boolean addDiscoveryPdu(DiscoveryPdu pdu)
          Adds a discovery pdu.
 boolean addPdu(Pdu pdu)
          Adds a PDU.
protected  boolean addPdu(Pdu pdu, boolean checkDiscovery)
          Adds a PDU.
 void addRequestPduListener(RequestPduListener l, ListeningContextPool lcontext)
          Adds the specified request pdu listener to receive PDUs on the specified listening context that matches this context.
protected  java.lang.String checkContextSanity()
          Checks the sanity of the context and returns an error message when it is not correct.
 java.lang.Object cloneParameters(SnmpContextv3Face clContext)
          Copies all parameters into another SnmpContextv3.
protected  UsmAgent createUsmAgent()
          Creates the USM agent.
 byte[] encodeDiscoveryPacket(byte msg_type, int rId, int errstat, int errind, java.util.Enumeration ve, java.lang.Object obj)
          Encodes a discovery PDU packet.
 byte[] encodePacket(byte msg_type, int rId, int errstat, int errind, java.util.Enumeration ve, java.lang.Object obj)
          Encodes a PDU.
 int getAuthenticationProtocol()
          Returns the protocol to be used for authentication.
 byte[] getContextEngineId()
          Returns the contextEngineID.
 java.lang.String getContextName()
          Returns the contextName.
 java.lang.String getHashKey()
          Returns the hash key.
 java.lang.String getUserAuthenticationPassword()
          Returns the user authentication password.
 java.lang.String getUserName()
          Returns the username.
 java.lang.String getUserPrivacyPassword()
          Returns the user privacy password.
 UsmAgent getUsmAgent()
          Returns the UsmAgent.
 int getVersion()
          Returns the SNMP version of the context.
protected  boolean isAuthoritative(byte msg_type)
          Returns if we send this PDU in authoritative role or not.
 boolean isUseAuthentication()
          Returns if authentication is used or not.
 boolean isUsePrivacy()
          Returns if privacy is used or not.
protected  void processIncomingResponse(java.io.ByteArrayInputStream in)
          Processes an incoming SNMP v3 response.
 boolean removePdu(int rid)
          Removes a PDU.
 void setAuthenticationProtocol(int protocol)
          Sets the protocol to be used for authentication.
 void setContextEngineId(byte[] newContextEngineId)
          Sets the contextEngineID.
 void setContextName(java.lang.String newContextName)
          Sets the contextName.
 void setUseAuthentication(boolean newUseAuthentication)
          Sets whether authentication has to be used.
 void setUsePrivacy(boolean newUsePrivacy)
          Sets whether privacy has to be used.
 void setUserAuthenticationPassword(java.lang.String newUserAuthPassword)
          Sets the user authentication password.
 void setUserName(java.lang.String newUserName)
          Sets the username.
 void setUserPrivacyPassword(java.lang.String newUserPrivacyPassword)
          Sets the user privacy password.
 void setUsmAgent(UsmAgent agent)
          Sets the UsmAgent, needed when this stack is used as authoritative SNMP engine.
 java.lang.String toString()
          Returns a string representation of the object.
 
Methods inherited from class uk.co.westhawk.snmp.stack.AbstractSnmpContext
activate, addRequestPduListener, addRequestPduListener, addTrapListener, addTrapListener, addTrapListener, clone, destroy, freeTransmitters, getBindAddress, getDebugString, getHost, getHostAddress, getMaxRecvSize, getPort, getReceivedFromHostAddress, getSendToHostAddress, getTypeSocket, isDestroyed, processIncomingPdu, rawPduReceived, removeRequestPduListener, removeRequestPduListener, removeRequestPduListener, removeTrapListener, removeTrapListener, removeTrapListener, run, sendPacket, setMaxRecvSize, stop
 
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface uk.co.westhawk.snmp.stack.SnmpContextBasisFace
addRequestPduListener, addRequestPduListener, addTrapListener, addTrapListener, addTrapListener, clone, destroy, getBindAddress, getHost, getPort, getReceivedFromHostAddress, getSendToHostAddress, getTypeSocket, isDestroyed, processIncomingPdu, removeRequestPduListener, removeRequestPduListener, removeRequestPduListener, removeTrapListener, removeTrapListener, removeTrapListener, sendPacket
 

Field Detail

userName

protected java.lang.String userName

useAuthentication

protected boolean useAuthentication

userAuthenticationPassword

protected java.lang.String userAuthenticationPassword

userAuthKeyMD5

protected byte[] userAuthKeyMD5

userAuthKeySHA1

protected byte[] userAuthKeySHA1

authenticationProtocol

protected int authenticationProtocol

usePrivacy

protected boolean usePrivacy

userPrivacyPassword

protected java.lang.String userPrivacyPassword

userPrivKeyMD5

protected byte[] userPrivKeyMD5

userPrivKeySHA1

protected byte[] userPrivKeySHA1

contextEngineId

protected byte[] contextEngineId

contextName

protected java.lang.String contextName

usmAgent

protected UsmAgent usmAgent
Constructor Detail

SnmpContextv3Basis

public SnmpContextv3Basis(java.lang.String host,
                          int port)
                   throws java.io.IOException
Constructor.

Parameters:
host - The host to which the PDU will be sent
port - The port where the SNMP server will be
See Also:
AbstractSnmpContext.AbstractSnmpContext(String, int)

SnmpContextv3Basis

public SnmpContextv3Basis(java.lang.String host,
                          int port,
                          java.lang.String typeSocketA)
                   throws java.io.IOException
Constructor.

Parameters:
host - The host to which the Pdu will be sent
port - The port where the SNMP server will be
typeSocketA - The local address the server will bind to
See Also:
AbstractSnmpContext.AbstractSnmpContext(String, int, String)

SnmpContextv3Basis

public SnmpContextv3Basis(java.lang.String host,
                          int port,
                          java.lang.String bindAddress,
                          java.lang.String typeSocketA)
                   throws java.io.IOException
Constructor.

Parameters:
host - The host to which the PDU will be sent
port - The port where the SNMP server will be
bindAddress - The local address the server will bind to
typeSocketA - The type of socket to use.
Since:
4_14
See Also:
AbstractSnmpContext.AbstractSnmpContext(String, int, String), SnmpContextBasisFace.STANDARD_SOCKET, SnmpContextBasisFace.TCP_SOCKET, SnmpContextBasisFace.NETSCAPE_SOCKET, SnmpContextBasisFace.KVM_SOCKET
Method Detail

getVersion

public int getVersion()
Description copied from interface: SnmpContextBasisFace
Returns the SNMP version of the context.

Specified by:
getVersion in interface SnmpContextBasisFace
Specified by:
getVersion in class AbstractSnmpContext
Returns:
The version
See Also:
SnmpConstants.SNMP_VERSION_1, SnmpConstants.SNMP_VERSION_2c, SnmpConstants.SNMP_VERSION_3

getUserName

public java.lang.String getUserName()
Returns the username.

Specified by:
getUserName in interface SnmpContextv3Face
Returns:
the username

setUserName

public void setUserName(java.lang.String newUserName)
Sets the username. This username will be used for all PDUs sent with this context. The username corresponds to the 'msgUserName' in SNMP-USER-BASED-SM-MIB. The default value is "initial".

Specified by:
setUserName in interface SnmpContextv3Face
Parameters:
newUserName - The new username
See Also:
SnmpContextv3Face.Default_UserName

isUseAuthentication

public boolean isUseAuthentication()
Returns if authentication is used or not. By default no authentication will be used.

Specified by:
isUseAuthentication in interface SnmpContextv3Face
Returns:
true if authentication is used, false if not

setUseAuthentication

public void setUseAuthentication(boolean newUseAuthentication)
Sets whether authentication has to be used. By default no authentication will be used.

Specified by:
setUseAuthentication in interface SnmpContextv3Face
Parameters:
newUseAuthentication - The use of authentication

getUserAuthenticationPassword

public java.lang.String getUserAuthenticationPassword()
Returns the user authentication password. This password will be transformed into the user authentication secret key.

Specified by:
getUserAuthenticationPassword in interface SnmpContextv3Face
Returns:
The user authentication password

setUserAuthenticationPassword

public void setUserAuthenticationPassword(java.lang.String newUserAuthPassword)
Sets the user authentication password. This password will be transformed into the user authentication secret key. A user MUST set this password.

Specified by:
setUserAuthenticationPassword in interface SnmpContextv3Face
Parameters:
newUserAuthPassword - The user authentication password

setAuthenticationProtocol

public void setAuthenticationProtocol(int protocol)
                               throws java.lang.IllegalArgumentException
Sets the protocol to be used for authentication. This can either be MD5 or SHA-1. By default MD5 will be used.

Specified by:
setAuthenticationProtocol in interface SnmpContextv3Face
Parameters:
protocol - The authentication protocol to be used
java.lang.IllegalArgumentException
See Also:
SnmpContextv3Face.MD5_PROTOCOL, SnmpContextv3Face.SHA1_PROTOCOL

getAuthenticationProtocol

public int getAuthenticationProtocol()
Returns the protocol to be used for authentication. This can either be MD5 or SHA-1. By default MD5 will be used.

Specified by:
getAuthenticationProtocol in interface SnmpContextv3Face
Returns:
The authentication protocol to be used
See Also:
SnmpContextv3Face.MD5_PROTOCOL, SnmpContextv3Face.SHA1_PROTOCOL

isUsePrivacy

public boolean isUsePrivacy()
Returns if privacy is used or not. By default privacy is not used.

Specified by:
isUsePrivacy in interface SnmpContextv3Face
Returns:
true if privacy is used, false if not

setUsePrivacy

public void setUsePrivacy(boolean newUsePrivacy)
Sets whether privacy has to be used. By default privacy is not used. Note, privacy (encryption) without authentication is not allowed.

Specified by:
setUsePrivacy in interface SnmpContextv3Face
Parameters:
newUsePrivacy - The use of privacy

getUserPrivacyPassword

public java.lang.String getUserPrivacyPassword()
Returns the user privacy password. This password will be transformed into the user privacy secret key.

Specified by:
getUserPrivacyPassword in interface SnmpContextv3Face
Returns:
The user privacy password

setUserPrivacyPassword

public void setUserPrivacyPassword(java.lang.String newUserPrivacyPassword)
Sets the user privacy password. This password will be transformed into the user privacy secret key. A user must set this password in order to use privacy.

Specified by:
setUserPrivacyPassword in interface SnmpContextv3Face
Parameters:
newUserPrivacyPassword - The user privacy password

setContextEngineId

public void setContextEngineId(byte[] newContextEngineId)
                        throws java.lang.IllegalArgumentException
Sets the contextEngineID. See RFC 3411. A contextEngineID uniquely identifies an SNMP entity that may realize an instance of a context with a particular contextName.

Note, when the stack is an authoritative engine, this parameter should equal the UsmAgent.getSnmpEngineId(). See the StackUsage documentation for an explanation.

If the contextEngineID is of length zero, the encoder will use the (discovered) snmpEngineId.

Specified by:
setContextEngineId in interface SnmpContextv3Face
Parameters:
newContextEngineId - The contextEngineID
java.lang.IllegalArgumentException
See Also:
UsmAgent.getSnmpEngineId()

getContextEngineId

public byte[] getContextEngineId()
Returns the contextEngineID.

Specified by:
getContextEngineId in interface SnmpContextv3Face
Returns:
The contextEngineID

setContextName

public void setContextName(java.lang.String newContextName)
Sets the contextName. See RFC 3411. A contextName is used to name a context. Each contextName MUST be unique within an SNMP entity. By default this is "" (the empty String).

Specified by:
setContextName in interface SnmpContextv3Face
Parameters:
newContextName - The contextName
See Also:
SnmpContextv3Face.Default_ContextName

getContextName

public java.lang.String getContextName()
Returns the contextName.

Specified by:
getContextName in interface SnmpContextv3Face
Returns:
The contextName

addDiscoveryPdu

public boolean addDiscoveryPdu(DiscoveryPdu pdu)
                        throws java.io.IOException,
                               PduException
Adds a discovery pdu. This method adds the PDU (without checking if discovery is needed).

Specified by:
addDiscoveryPdu in interface SnmpContextv3Face
Parameters:
pdu - the discovery pdu
Returns:
pdu is succesful added
java.io.IOException
PduException
See Also:
AbstractSnmpContext.addPdu(Pdu), addPdu(Pdu)

addPdu

public boolean addPdu(Pdu pdu)
               throws java.io.IOException,
                      PduException
Adds a PDU. This method adds the PDU and blocks until it has all the discovery parameters it needs.

Specified by:
addPdu in interface SnmpContextBasisFace
Overrides:
addPdu in class AbstractSnmpContext
Parameters:
pdu - the PDU
Returns:
pdu is succesful added
java.io.IOException
PduException
See Also:
AbstractSnmpContext.addPdu(Pdu), addDiscoveryPdu(DiscoveryPdu)

createUsmAgent

protected UsmAgent createUsmAgent()
Creates the USM agent.

See Also:
DefaultUsmAgent, isAuthoritative(byte)

setUsmAgent

public void setUsmAgent(UsmAgent agent)
Sets the UsmAgent, needed when this stack is used as authoritative SNMP engine. This interface provides authentiation details, like its clock and its Engine ID.

Specified by:
setUsmAgent in interface SnmpContextv3Face
Parameters:
agent - The USM authoritative interface
Since:
4_14
See Also:
DefaultUsmAgent

getUsmAgent

public UsmAgent getUsmAgent()
Returns the UsmAgent.

Specified by:
getUsmAgent in interface SnmpContextv3Face
Since:
4_14
See Also:
setUsmAgent(uk.co.westhawk.snmp.stack.UsmAgent)

addPdu

protected boolean addPdu(Pdu pdu,
                         boolean checkDiscovery)
                  throws java.io.IOException,
                         PduException
Adds a PDU. This method adds the PDU and checks if discovery is needed depending on the parameter checkDiscovery. If discovery is needed this method will block until it has done so. Discovery is only needed if the stack is non authoritative.

This method stores the SNMPv3 msgId and PDU request id in a Hashtable. Since the encoding only happens once and every retry sends the same encoded packet, only one msgId is used.

Parameters:
pdu - the PDU
checkDiscovery - check if discovery is needed
Returns:
pdu is succesful added
java.io.IOException
PduException
See Also:
AbstractSnmpContext.addPdu(Pdu), addDiscoveryPdu(DiscoveryPdu), addPdu(Pdu)

removePdu

public boolean removePdu(int rid)
Removes a PDU. This removes the PDU from the AbstractSnmpContext and clears the link with the SNMPv3 msgId.

Specified by:
removePdu in interface SnmpContextBasisFace
Overrides:
removePdu in class AbstractSnmpContext
Parameters:
rid - the PDU request id
Returns:
whether the PDU has been successfully removed
See Also:
AbstractSnmpContext.removePdu(int)

encodeDiscoveryPacket

public byte[] encodeDiscoveryPacket(byte msg_type,
                                    int rId,
                                    int errstat,
                                    int errind,
                                    java.util.Enumeration ve,
                                    java.lang.Object obj)
                             throws java.io.IOException,
                                    EncodingException
Encodes a discovery PDU packet. This methods encodes without checking if the discovery parameters are all known.

Specified by:
encodeDiscoveryPacket in interface SnmpContextv3Face
Returns:
The encoded packet
java.io.IOException
EncodingException

encodePacket

public byte[] encodePacket(byte msg_type,
                           int rId,
                           int errstat,
                           int errind,
                           java.util.Enumeration ve,
                           java.lang.Object obj)
                    throws java.io.IOException,
                           EncodingException
Encodes a PDU. This is for internal use only and should NOT be called by the developer. This is called by the the PDU itself and is added to the interface to cover the different kind of Contexts.

When the stack is

Specified by:
encodePacket in interface SnmpContextBasisFace
Specified by:
encodePacket in class AbstractSnmpContext
Parameters:
msg_type - The message type
rId - The message id
errstat - The error status
errind - The error index
ve - The varbind list
obj - Additional object (only used in SNMPv3)
Returns:
The encoded packet
java.io.IOException
EncodingException
See Also:
isAuthoritative(byte)

checkContextSanity

protected java.lang.String checkContextSanity()
Checks the sanity of the context and returns an error message when it is not correct.


actualEncodePacket

protected byte[] actualEncodePacket(byte msg_type,
                                    int rId,
                                    int errstat,
                                    int errind,
                                    java.util.Enumeration ve,
                                    uk.co.westhawk.snmp.stack.TimeWindowNode node,
                                    java.lang.Object obj)
                             throws java.io.IOException,
                                    EncodingException
Does the actual encoding.

java.io.IOException
EncodingException
See Also:
encodeDiscoveryPacket(byte, int, int, int, java.util.Enumeration, java.lang.Object), encodePacket(byte, int, int, int, java.util.Enumeration, java.lang.Object)

processIncomingResponse

protected void processIncomingResponse(java.io.ByteArrayInputStream in)
                                throws DecodingException,
                                       java.io.IOException
Processes an incoming SNMP v3 response.

Specified by:
processIncomingResponse in class AbstractSnmpContext
DecodingException
java.io.IOException
See Also:
AbstractSnmpContext.run()

isAuthoritative

protected boolean isAuthoritative(byte msg_type)
Returns if we send this PDU in authoritative role or not. The engine who sends a Response, a Trapv2 or a Report is authoritative.

Returns:
true if authoritative, false if not.
Since:
4_14

addRequestPduListener

public void addRequestPduListener(RequestPduListener l,
                                  ListeningContextPool lcontext)
                           throws java.io.IOException
Adds the specified request pdu listener to receive PDUs on the specified listening context that matches this context. This method will call usmAgent.setSnmpContext(this).

Don't use the TCP_SOCKET when listening for request PDUs. It doesn't provide functionality to send a response back.

Specified by:
addRequestPduListener in interface SnmpContextBasisFace
Overrides:
addRequestPduListener in class AbstractSnmpContext
Parameters:
l - The request PDU listener
lcontext - The listening context
java.io.IOException
See Also:
AbstractSnmpContext.addRequestPduListener(RequestPduListener, ListeningContextPool)

cloneParameters

public java.lang.Object cloneParameters(SnmpContextv3Face clContext)
Copies all parameters into another SnmpContextv3.


getHashKey

public java.lang.String getHashKey()
Returns the hash key. This key is built out of all properties. It serves as key for a hashtable of (v3) contexts.

Specified by:
getHashKey in interface SnmpContextBasisFace
Specified by:
getHashKey in class AbstractSnmpContext
Returns:
The hash key
Since:
4_14

toString

public java.lang.String toString()
Returns a string representation of the object.

Overrides:
toString in class java.lang.Object
Returns:
The string

SNMP Stack 5_1