uk.co.westhawk.snmp.stack
Class SnmpContextv3

java.lang.Object
  |
  +--uk.co.westhawk.snmp.stack.AbstractSnmpContext
        |
        +--uk.co.westhawk.snmp.stack.SnmpContextv3

All Implemented Interfaces:

java.lang.Cloneable, java.util.EventListener, java.lang.Runnable, SnmpContextBasisFace, SnmpContextv3Face, TrapListener

public class SnmpContextv3

extends AbstractSnmpContext

implements SnmpContextv3Face, java.lang.Cloneable

This class contains the SNMP v3 context 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, 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 RFC 2574. See also RFC 2571.

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

Version:

$Revision: 3.20 $ $Date: 2002/10/23 11:48:01 $

Author:

Birgit Arkesteijn

See Also:

SnmpContextv3Face, SnmpContextv3Pool, TimeWindow, UsmAgent, UsmDiscoveryBean

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

hostAddr, hostPort, isDestroyed, maxRecvSize, 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

Fields inherited from interface uk.co.westhawk.snmp.event.TrapListener

version_id

Constructor Summary

SnmpContextv3(java.lang.String host, int port)
Constructor.

SnmpContextv3(java.lang.String host, int port, 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) Does the actual encoding.
boolean	addDiscoveryPdu(DiscoveryPdu pdu) Adds an discovery pdu.
boolean	addPdu(Pdu pdu) Adds an pdu.
protected boolean	addPdu(Pdu pdu, boolean checkDiscovery) Adds an pdu.
java.lang.Object	clone() Returns a clone of this SnmpContextv3.
protected UsmAgent	createUsmAgent() Creates the USM agent.
byte[]	encodeDiscoveryPacket(byte msg_type, int rId, int errstat, int errind, java.util.Enumeration ve) Encodes a discovery pdu packet.
byte[]	encodePacket(byte msg_type, int rId, int errstat, int errind, java.util.Enumeration ve) Encodes a pdu packet.
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	getUserAuthenticationPassword() Returns the user authentication password.
java.lang.String	getUserName() Returns the username.
java.lang.String	getUserPrivacyPassword() Returns the user privacy password.
int	getVersion() Return 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() Return if authentication is used or not.
boolean	isUsePrivacy() Return if privacy is used or not.
protected void	ProcessIncomingMessage(uk.co.westhawk.snmp.stack.AsnDecoder rpdu, java.io.ByteArrayInputStream in) Processes an incoming SNMP v3 message.
Pdu	processIncomingTrap(byte[] message) Processes an incoming trap.
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 used.
void	setUsePrivacy(boolean newUsePrivacy) Sets whether privacy has to 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.
static 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, addTrapListener, destroy, getDebugString, getHost, getHostAddress, getMaxRecvSize, getPort, getTypeSocket, removeTrapListener, run, sendPacket, setMaxRecvSize, stop, trapReceived

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

addTrapListener, destroy, getHost, getPort, getTypeSocket, removeTrapListener, sendPacket

Constructor Detail

SnmpContextv3

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

Constructor.

Parameters:

host - The host to which the Pdu will send

port - The port where the SNMP server will be

See Also:

AbstractSnmpContext.AbstractSnmpContext(String, int)

SnmpContextv3

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

Constructor.

Parameters:

host - The host to which the Pdu will send

port - The port where the SNMP server will be

typeSocketA - The type of socket to use.

See Also:

AbstractSnmpContext.AbstractSnmpContext(String, int, String), SnmpContextBasisFace.STANDARD_SOCKET, SnmpContextBasisFace.NETSCAPE_SOCKET, SnmpContextBasisFace.KVM_SOCKET

Method Detail

getVersion

public int getVersion()

Description copied from interface: SnmpContextBasisFace

Return the SNMP version of the context.

Specified by:

getVersion in interface SnmpContextBasisFace

Overrides:

getVersion in class AbstractSnmpContext

Following copied from interface: uk.co.westhawk.snmp.stack.SnmpContextBasisFace

Returns:

The version

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 PDU send with this context. The username corresponds to the 'msgUserName' in RFC 2574. 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()

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

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

Return if privacy is used or not.

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 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 2571. A contextEngineID uniquely identifies an SNMP entity that may realize an instance of a context with a particular contextName.

Specified by:

setContextEngineId in interface SnmpContextv3Face

Parameters:

newContextEngineId - The contextEngineID

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 2571. A contextName is used to name a context. Each contextName MUST be unique within an SNMP entity. By default this is "".

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

See Also:

AbstractSnmpContext.addPdu(Pdu), addPdu(Pdu)

addPdu

public boolean addPdu(Pdu pdu)
               throws java.io.IOException,
                      PduException

Adds an pdu. This method adds the Pdu and block 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

See Also:

AbstractSnmpContext.addPdu(Pdu), addDiscoveryPdu(DiscoveryPdu)

createUsmAgent

protected UsmAgent createUsmAgent()

Creates the USM agent.

setUsmAgent

public static 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.

Parameters:

agent - The USM authoritative interface

addPdu

protected boolean addPdu(Pdu pdu,
                         boolean checkDiscovery)
                  throws java.io.IOException,
                         PduException

Adds an 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 have done so. Discovery is only needed if the stack is non authoritative.

Parameters:

pdu - the pdu

checkDiscovery - check if discovery is needed

Returns:

pdu is succesful added

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 clear 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)
                             throws java.io.IOException,
                                    EncodingException

Encodes a discovery pdu packet. This methods encodes without checking is the discovery paramters are all known.

Specified by:

encodeDiscoveryPacket in interface SnmpContextv3Face

Following copied from interface: uk.co.westhawk.snmp.stack.SnmpContextv3Face

Returns:

The encoded packet

encodePacket

public byte[] encodePacket(byte msg_type,
                           int rId,
                           int errstat,
                           int errind,
                           java.util.Enumeration ve)
                    throws java.io.IOException,
                           EncodingException

Encodes a pdu packet. If the stack is authoritative, the timeline details are retrieved from the usmAgent. If not, this methods first checks if all the discovery paramters are all known, if not it will throw an EncodingException. If so, it encodes and returns the bytes.

Specified by:

encodePacket in interface SnmpContextBasisFace

Overrides:

encodePacket in class AbstractSnmpContext

Following copied from interface: uk.co.westhawk.snmp.stack.SnmpContextBasisFace

Returns:

The encoded packet

actualEncodePacket

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

Does the actual encoding. 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.

See Also:

encodeDiscoveryPacket(byte, int, int, int, java.util.Enumeration), encodePacket(byte, int, int, int, java.util.Enumeration)

ProcessIncomingMessage

protected void ProcessIncomingMessage(uk.co.westhawk.snmp.stack.AsnDecoder rpdu,
                                      java.io.ByteArrayInputStream in)
                               throws DecodingException,
                                      java.io.IOException

Processes an incoming SNMP v3 message.

Overrides:

ProcessIncomingMessage in class AbstractSnmpContext

Following copied from class: uk.co.westhawk.snmp.stack.AbstractSnmpContext

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.

processIncomingTrap

public Pdu processIncomingTrap(byte[] message)
                        throws DecodingException,
                               java.io.IOException

Description copied from interface: SnmpContextBasisFace

Processes an incoming trap. The context will try to process the incoming trap, using the SNMP version and other security parameters. If any of these do not correspond, a DecodingException will be thrown.

Specified by:

processIncomingTrap in interface SnmpContextBasisFace

Overrides:

processIncomingTrap in class AbstractSnmpContext

Following copied from class: uk.co.westhawk.snmp.stack.AbstractSnmpContext

See Also:

AbstractSnmpContext.trapReceived(uk.co.westhawk.snmp.event.TrapEvent)

clone

public java.lang.Object clone()
                       throws java.lang.CloneNotSupportedException

Returns a clone of this SnmpContextv3.

Overrides:

clone in class java.lang.Object

Throws:

java.lang.CloneNotSupportedException - Thrown when the constructor generates an IOException

toString

public java.lang.String toString()

Returns a string representation of the object.

Overrides:

toString in class java.lang.Object

Returns:

The string