snmpcontextv3basis.java

snmp zip 包开发snmp协议

// NAME
//      $RCSfile: SnmpContextv3Basis.java,v $
// DESCRIPTION
//      [given below in javadoc format]
// DELTA
//      $Revision: 3.11 $
// CREATED
//      $Date: 2006/04/04 12:31:04 $
// COPYRIGHT
//      Westhawk Ltd
// TO DO
//

/*
 * Copyright (C) 2005 - 2006 by Westhawk Ltd
 * <a href="www.westhawk.co.uk">www.westhawk.co.uk</a>
 *
 * Permission to use, copy, modify, and distribute this software
 * for any purpose and without fee is hereby granted, provided
 * that the above copyright notices appear in all copies and that
 * both the copyright notice and this permission notice appear in
 * supporting documentation.
 * This software is provided "as is" without express or implied
 * warranty.
 */

package uk.co.westhawk.snmp.stack;

import java.net.*;
import java.io.*;
import java.util.*;

import uk.co.westhawk.snmp.pdu.*;
import uk.co.westhawk.snmp.util.*;
import uk.co.westhawk.snmp.event.*;
import uk.co.westhawk.snmp.beans.*;

/**
 * This class contains the basis for the SNMP v3 contexts that is needed 
 * by every PDU to send a SNMP v3 request.
 *
 * <p>
 * This class will perform the v3 discovery of the SNMP engine ID and
 * time line if necessary. This is done with the classes
 * <code>TimeWindow</code> and <code>UsmDiscoveryBean</code>.
 * </p>
 *
 * <p>
 * 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) <em>should</em> provide a better implementation.
 * </p>
 *
 * <p>
 * This class will use the User Security Model (USM) as described in 
 * <a href="http://www.ietf.org/rfc/rfc3414.txt">SNMP-USER-BASED-SM-MIB</a>.
 * See also <a href="http://www.ietf.org/rfc/rfc3411.txt">RFC 3411</a>.
 * </p>
 *
 * <p>
 * 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
 * <code>DecodingException</code>. 
 * </p>
 * 
 * <p>
 * <code>destroy()</code> should be called when the context is no longer
 * used. This is the only way the threads will be stopped and garbage
 * collected.
 * </p>
 *
 * @see SnmpContextv3Face
 * @see SnmpContextv3Pool
 * @see TimeWindow
 * @see UsmAgent
 * @see DefaultUsmAgent
 * @see #setUsmAgent(UsmAgent)
 * @see uk.co.westhawk.snmp.beans.UsmDiscoveryBean
 *
 * @since 4_14
 * @author <a href="mailto:[e-mail]">Birgit Arkesteijn</a>
 * @version $Revision: 3.11 $ $Date: 2006/04/04 12:31:04 $
 */
public abstract class SnmpContextv3Basis extends AbstractSnmpContext 
implements SnmpContextv3Face, Cloneable
{
    private static final String     version_id =
        "@(#)$Id: SnmpContextv3Basis.java,v 3.11 2006/04/04 12:31:04 birgit Exp $ Copyright Westhawk Ltd";

    protected String userName = Default_UserName;
    protected boolean useAuthentication = false;
    protected String userAuthenticationPassword;
    protected byte[] userAuthKeyMD5 = null;
    protected byte[] userAuthKeySHA1 = null;
    protected int authenticationProtocol = MD5_PROTOCOL;
    protected boolean usePrivacy = false;
    protected String userPrivacyPassword;
    protected byte[] userPrivKeyMD5 = null;
    protected byte[] userPrivKeySHA1 = null;
    protected byte [] contextEngineId = new byte[0];
    protected String contextName = Default_ContextName;
    protected UsmAgent usmAgent = null;

    private Hashtable msgIdHash = new Hashtable(MAXPDU);
    private static int  next_id = 1;

/**
 * Constructor.
 *
 * @param host The host to which the PDU will be sent
 * @param port The port where the SNMP server will be
 * @see AbstractSnmpContext#AbstractSnmpContext(String, int)
 */
public SnmpContextv3Basis(String host, int port) throws java.io.IOException
{
    this(host, port, null, STANDARD_SOCKET);
}

/**
 * Constructor.
 *
 * @param host The host to which the Pdu will be sent
 * @param port The port where the SNMP server will be
 * @param typeSocketA The local address the server will bind to
 *
 * @see AbstractSnmpContext#AbstractSnmpContext(String, int, String)
 */
public SnmpContextv3Basis(String host, int port, String typeSocketA) 
throws java.io.IOException
{
    this(host, port, null, typeSocketA);
}

/**
 * Constructor.
 *
 * @param host The host to which the PDU will be sent
 * @param port The port where the SNMP server will be
 * @param bindAddress The local address the server will bind to
 * @param typeSocketA The type of socket to use. 
 *
 * @see AbstractSnmpContext#AbstractSnmpContext(String, int, String)
 * @see SnmpContextBasisFace#STANDARD_SOCKET
 * @see SnmpContextBasisFace#TCP_SOCKET
 * @see SnmpContextBasisFace#NETSCAPE_SOCKET
 * @see SnmpContextBasisFace#KVM_SOCKET
 * @since 4_14
 */
public SnmpContextv3Basis(String host, int port, String bindAddress, String typeSocketA) 
throws java.io.IOException
{
    super(host, port, bindAddress, typeSocketA);

    if (TimeWindow.getCurrent() == null)
    {
        TimeWindow timew = new TimeWindow();
    }
    setUsmAgent(createUsmAgent());
}

public int getVersion()
{
    return SnmpConstants.SNMP_VERSION_3;
}

/**
 * Returns the username.
 *
 * @return the username
 */
public String getUserName()
{
    return userName;
}

/**
 * Sets the username.
 * This username will be used for all PDUs sent with this context.
 * The username corresponds to the 'msgUserName' in 
 * <a href="http://www.ietf.org/rfc/rfc3414.txt">SNMP-USER-BASED-SM-MIB</a>.
 * The default value is "initial".
 *
 * @param newUserName The new username
 * @see #Default_UserName
 */
public void setUserName(String newUserName)
{
    userName = newUserName;
}

/**
 * Returns if authentication is used or not.
 * By default no authentication will be used.
 *
 * @return true if authentication is used, false if not
 */
public boolean isUseAuthentication()
{
    return useAuthentication;
}

/**
 * Sets whether authentication has to be used. 
 * By default no authentication will be used.
 *
 * @param newUseAuthentication The use of authentication
 */
public void setUseAuthentication(boolean newUseAuthentication)
{
    useAuthentication = newUseAuthentication;
}

/**
 * Returns the user authentication password.
 * This password will be transformed into the user authentication secret key.
 *
 * @return The user authentication password
 */
public String getUserAuthenticationPassword()
{
    return userAuthenticationPassword;
}

/**
 * Sets the user authentication password.
 * This password will be transformed into the user authentication secret
 * key. A user MUST set this password.
 *
 * @param newUserAuthPassword The user authentication password
 */
public void setUserAuthenticationPassword(String newUserAuthPassword)
{
    if (newUserAuthPassword != null
            &&
        newUserAuthPassword.equals(userAuthenticationPassword) == false)
    {
        userAuthenticationPassword = newUserAuthPassword;
        userAuthKeyMD5 = null;
        userAuthKeySHA1 = null;
    }
}

/**
 * Sets the protocol to be used for authentication.
 * This can either be MD5 or SHA-1.
 * By default MD5 will be used.
 *
 * @param protocol The authentication protocol to be used
 * @see #MD5_PROTOCOL
 * @see #SHA1_PROTOCOL
 */
public void setAuthenticationProtocol(int protocol)
throws IllegalArgumentException
{
    if (protocol == MD5_PROTOCOL || protocol == SHA1_PROTOCOL)
    {
        if (protocol != authenticationProtocol)
        {
            authenticationProtocol = protocol;
        }
    }
    else
    {
        throw new IllegalArgumentException("Authentication Protocol "
            + "should be MD5 or SHA1");
    }
}

/**
 * Returns the protocol to be used for authentication.
 * This can either be MD5 or SHA-1.
 * By default MD5 will be used.
 *
 * @return The authentication protocol to be used
 * @see #MD5_PROTOCOL
 * @see #SHA1_PROTOCOL
 */
public int getAuthenticationProtocol()
{
    return authenticationProtocol;
}

byte[] getAuthenticationPasswordKeyMD5()
{
    if (userAuthKeyMD5 == null)
    {
        userAuthKeyMD5 = SnmpUtilities.passwordToKeyMD5(userAuthenticationPassword);
    }
    return userAuthKeyMD5;
}

byte[] getAuthenticationPasswordKeySHA1()
{
    if (userAuthKeySHA1 == null)
    {
        userAuthKeySHA1 = SnmpUtilities.passwordToKeySHA1(userAuthenticationPassword);
    }
    return userAuthKeySHA1;
}


byte[] getPrivacyPasswordKeyMD5()
{
    if (userPrivKeyMD5 == null)
    {
        userPrivKeyMD5 = SnmpUtilities.passwordToKeyMD5(userPrivacyPassword);
    }
    return userPrivKeyMD5;
}

byte[] getPrivacyPasswordKeySHA1()
{
    if (userPrivKeySHA1 == null)
    {
        userPrivKeySHA1 = SnmpUtilities.passwordToKeySHA1(userPrivacyPassword);
    }
    return userPrivKeySHA1;
}


/**
 * Returns if privacy is used or not.
 * By default privacy is not used.
 *
 * @return true if privacy is used, false if not
 */
public boolean isUsePrivacy()
{
    return usePrivacy;
}

/**
 * Sets whether privacy has to be used. 
 * By default privacy is not used.
 * Note, privacy (encryption) without authentication is not allowed.
 *
 * @param newUsePrivacy The use of privacy
 */
public void setUsePrivacy(boolean newUsePrivacy)
{
    usePrivacy = newUsePrivacy;
}

/**
 * Returns the user privacy password.
 * This password will be transformed into the user privacy secret key.
 *
 * @return The user privacy password
 */
public String getUserPrivacyPassword()
{
    return userPrivacyPassword;
}


/**
 * Sets the user privacy password.