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.lang.Runnable, java.util.EventListener, RawPduListener, 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$ $Date$

Author:

Birgit Arkesteijn

See Also:

SnmpContextv3Face, SnmpContextv3Pool, TimeWindow, UsmAgent, DefaultUsmAgent, setUsmAgent(UsmAgent), UsmDiscoveryBean

Field Summary

Fields

Modifier and Type	Field and Description
protected int	authenticationProtocol
protected byte[]	contextEngineId
protected java.lang.String	contextName
protected int	privacyProtocol
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

AES_ENCRYPT, Default_ContextName, Default_UserName, DES_ENCRYPT, MD5_PROTOCOL, ProtocolNames, SHA1_PROTOCOL, SNMPv1_Security_Model, SNMPv2c_Security_Model, USM_Security_Model

Fields inherited from interface uk.co.westhawk.snmp.stack.SnmpContextBasisFace

DEFAULT_PORT, MAXPDU, MSS, STANDARD_SOCKET, TCP_SOCKET

Constructor Summary

Constructors

Constructor and Description
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

Modifier and Type	Method and Description
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.
int	getPrivacyProtocol() Returns the protocol to be used for privacy.
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 this 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	setPrivacyProtocol(int protocol) Sets the protocol to be used for privacy.
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

privacyProtocol

protected int privacyProtocol

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

Throws:

java.io.IOException

See Also:

AbstractSnmpContext.AbstractSnmpContext(String, int)

SnmpContextv3Basis

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

Constructor. Parameter typeSocketA should be either STANDARD_SOCKET, TCP_SOCKET or a fully qualified classname.

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

Throws:

java.io.IOException

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. Parameter typeSocketA should be either STANDARD_SOCKET, TCP_SOCKET or a fully qualified classname.

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.

Throws:

java.io.IOException

Since:

4_14

See Also:

AbstractSnmpContext.AbstractSnmpContext(String, int, String), SnmpContextBasisFace.STANDARD_SOCKET, SnmpContextBasisFace.TCP_SOCKET

Method Detail

getVersion

public int getVersion()

Description copied from class: AbstractSnmpContext

Returns the SNMP version of this context. Has to be overload by each 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

Throws:

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

setPrivacyProtocol

public void setPrivacyProtocol(int protocol)
                        throws java.lang.IllegalArgumentException

Sets the protocol to be used for privacy. This can either be DES or AES. By default DES will be used.

Specified by:

setPrivacyProtocol in interface SnmpContextv3Face

Parameters:

protocol - The privacy protocol to be used

Throws:

java.lang.IllegalArgumentException

See Also:

SnmpContextv3Face.AES_ENCRYPT, SnmpContextv3Face.DES_ENCRYPT

getPrivacyProtocol

public int getPrivacyProtocol()

Returns the protocol to be used for privacy. This can either be DES or AES. By default DES will be used.

Specified by:

getPrivacyProtocol in interface SnmpContextv3Face

Returns:

The privacy protocol to be used

See Also:

SnmpContextv3Face.AES_ENCRYPT, SnmpContextv3Face.DES_ENCRYPT

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

Throws:

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

Throws:

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

Throws:

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

Throws:

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

Throws:

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

• authoritative, the timeline details are retrieved from the UsmAgent.
• non authoritative, this methods first checks if all the discovery parameters are known;
  • If so, it encodes and returns the bytes.
  • If not, it will throw an EncodingException.

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

Throws:

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.

Throws:

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

Throws:

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

Throws:

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