Overview | Package | Class | Tree | Deprecated | Index | Help
| SNMP Stack 4_12
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

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

Overview | Package | Class | Tree | Deprecated | Index | Help
| SNMP Stack 4_12
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD