Package 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:

Cloneable, Runnable, EventListener, RawPduListener, SnmpContextBasisFace, SnmpContextv3Face

Direct Known Subclasses:

SnmpContextv3, SnmpContextv3Discovery

public abstract class SnmpContextv3Basis
extends AbstractSnmpContext
implements SnmpContextv3Face, 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.17 $ $Date: 2009/03/05 15:51:42 $

Author:

Birgit Arkesteijn

See Also:

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

Field Summary

Fields

Modifier and Type	Field	Description
static final int	AES128_KEY_LENGTH
static final int	AES192_KEY_LENGTH
static final int	AES256_KEY_LENGTH

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

DEFAULT_PORT, MAXPDU, MSS, STANDARD_SOCKET, TCP_SOCKET

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

AES_ENCRYPT, AES_PRIVACY_PROTOCOLS, AES192_ENCRYPT, AES256_ENCRYPT, AUTH_PROTOCOLS, DEFAULT_CONTEXT_NAME, DEFAULT_USERNAME, DES_ENCRYPT, MD5_PROTOCOL, NO_AUTH_PROTOCOL, PRIVACY_PROTOCOLS, PROTOCOL_NAMES, SHA1_PROTOCOL, SHA224_PROTOCOL, SHA256_PROTOCOL, SHA384_PROTOCOL, SHA512_PROTOCOL, SNMPv1_Security_Model, SNMPv2c_Security_Model, USM_Security_Model

Constructor Summary

Constructors

Constructor	Description
SnmpContextv3Basis(String host, int port)	Constructor.
SnmpContextv3Basis(String host, int port, String typeSocketA)	Constructor.
SnmpContextv3Basis(String host, int port, String bindAddress, String typeSocketA)	Constructor.

Method Summary

Modifier and Type	Method	Description
boolean	addDiscoveryPdu(DiscoveryPdu pdu)	Adds a discovery pdu.
boolean	addPdu(Pdu pdu)	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.
Object	cloneParameters(SnmpContextv3Face clContext)	Copies all parameters into another SnmpContextv3.
byte[]	encodeDiscoveryPacket(byte msg_type, int rId, int errstat, int errind, Enumeration ve, Object obj)	Encodes a discovery PDU packet.
byte[]	encodePacket(byte msg_type, int rId, int errstat, int errind, Enumeration ve, Object obj)	Encodes a PDU.
int	getAuthenticationProtocol()	Returns the protocol to be used for authentication.
byte[]	getContextEngineId()	Returns the contextEngineID.
String	getContextName()	Returns the contextName.
String	getHashKey()	Returns the hash key.
int	getPrivacyProtocol()	Returns the protocol to be used for privacy.
String	getUserAuthenticationPassword()	Returns the user authentication password.
String	getUserName()	Returns the username.
String	getUserPrivacyPassword()	Returns the user privacy password.
UsmAgent	getUsmAgent()	Returns the UsmAgent.
int	getVersion()	Returns the SNMP version of this context.
boolean	isUseAuthentication()	Returns if authentication is used or not.
boolean	isUsePrivacy()	Returns if privacy is used or not.
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(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(String newUserAuthPassword)	Sets the user authentication password.
void	setUserName(String newUserName)	Sets the username.
void	setUserPrivacyPassword(String newUserPrivacyPassword)	Sets the user privacy password.
void	setUsmAgent(UsmAgent agent)	Sets the UsmAgent, needed when this stack is used as authoritative SNMP engine.
String	toString()	Returns a string representation of the object.

Methods inherited from class uk.co.westhawk.snmp.stack.AbstractSnmpContext

addRequestPduListener, addRequestPduListener, addTrapListener, addTrapListener, addTrapListener, clone, destroy, 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, 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 Details

AES128_KEY_LENGTH

public static final int AES128_KEY_LENGTH

See Also:

• Constant Field Values

AES192_KEY_LENGTH

public static final int AES192_KEY_LENGTH

See Also:

• Constant Field Values

AES256_KEY_LENGTH

public static final int AES256_KEY_LENGTH

See Also:

• Constant Field Values

Constructor Details

SnmpContextv3Basis

public SnmpContextv3Basis(String host,
 int port)
                   throws IOException

Constructor.

Parameters:

host - The host to which the PDU will be sent

port - The port where the SNMP server will be

Throws:

IOException

See Also:

• AbstractSnmpContext(String, int)

SnmpContextv3Basis

public SnmpContextv3Basis(String host,
 int port,
 String typeSocketA)
                   throws 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:

IOException

See Also:

• AbstractSnmpContext(String, int, String)

SnmpContextv3Basis

public SnmpContextv3Basis(String host,
 int port,
 String bindAddress,
 String typeSocketA)
                   throws 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:

IOException

Since:

4_14

See Also:

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

Method Details

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 String getUserName()

Returns the username.

Specified by:

getUserName in interface SnmpContextv3Face

Returns:

the username

setUserName

public void setUserName(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 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(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 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:

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 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:

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 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(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 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:

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(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_CONTEXT_NAME

getContextName

public String getContextName()

Returns the contextName.

Specified by:

getContextName in interface SnmpContextv3Face

Returns:

The contextName

addDiscoveryPdu

public boolean addDiscoveryPdu(DiscoveryPdu pdu)
                        throws 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:

IOException

PduException

See Also:

• AbstractSnmpContext.addPdu(Pdu)
• addPdu(Pdu)

addPdu

public boolean addPdu(Pdu pdu)
               throws 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:

IOException

PduException

See Also:

• AbstractSnmpContext.addPdu(Pdu)
• addDiscoveryPdu(DiscoveryPdu)

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)

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,
 Enumeration ve,
 Object obj)
                             throws 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:

IOException

EncodingException

encodePacket

public byte[] encodePacket(byte msg_type,
 int rId,
 int errstat,
 int errind,
 Enumeration ve,
 Object obj)
                    throws 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:

IOException

EncodingException

See Also:

• isAuthoritative(byte)

addRequestPduListener

public void addRequestPduListener(RequestPduListener l,
 ListeningContextPool lcontext)
                           throws 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:

IOException

See Also:

• AbstractSnmpContext.addRequestPduListener(RequestPduListener, ListeningContextPool)

cloneParameters

public Object cloneParameters(SnmpContextv3Face clContext)

Copies all parameters into another SnmpContextv3.

getHashKey

public 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 String toString()

Returns a string representation of the object.

Overrides:

toString in class Object

Returns:

The string