SnmpEngineImpl


1   /*
2    * @(#)file      SnmpEngineImpl.java
3    * @(#)author    Sun Microsystems, Inc.
4    * @(#)version   1.45
5    * @(#)date      08/02/09
6    *
7    * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
8    * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
9    *
10   */
11  package com.sun.jmx.snmp.internal;
12  
13  import java.net.InetAddress  ;
14  import java.net.UnknownHostException  ;
15  import java.util.Hashtable  ;
16  import java.io.Serializable  ;
17  
18  import com.sun.jmx.snmp.SnmpDefinitions;
19  import com.sun.jmx.snmp.SnmpEngineId;
20  import com.sun.jmx.snmp.SnmpEngine;
21  import com.sun.jmx.snmp.SnmpUsmKeyHandler;
22  import com.sun.jmx.snmp.SnmpEngineFactory;
23  import com.sun.jmx.snmp.SnmpUnknownModelException;
24  
25  import com.sun.jmx.snmp.internal.SnmpTools;
26  import com.sun.jmx.snmp.SnmpBadSecurityLevelException;
27  import com.sun.jmx.trace.Trace;
28  /**
29   * This engine is conformant with the RFC 2571. It is the main object within 
30   * an SNMP entity (agent, manager...). 
31   * To an engine is associated an {@link com.sun.jmx.snmp.SnmpEngineId}. 
32   * The way the engineId is retrieved is linked to the way the engine is 
33   * instantiated. See each <CODE>SnmpEngine</CODE> constructor for more details.
34   * An engine is composed of a set of sub systems 
35   * {@link com.sun.jmx.snmp.internal.SnmpSubSystem}. An <CODE>SNMP</CODE> 
36   * engine can contain a:
37   *<ul>
38   *<li> Message Processing Sub System :  
39   * {@link com.sun.jmx.snmp.internal.SnmpMsgProcessingSubSystem}</li>
40   *<li> Security Sub System : 
41   * {@link com.sun.jmx.snmp.internal.SnmpSecuritySubSystem} </li>
42   *<li> Access Control Sub System : 
43   * {@link com.sun.jmx.snmp.internal.SnmpAccessControlSubSystem}</li>
44   *</ul>
45   *<P> Each sub system contains a set of models. A model is an implementation 
46   * of a particular treatement (eg: the User based Security Model defined in
47   * RFC 2574 is a functional element dealing with authentication and privacy).
48   *</P>
49   * Engine instantiation is based on a factory. This factory, implementing 
50   * mandatorily {@link com.sun.jmx.snmp.SnmpEngineFactory  SnmpEngineFactory}
51   * is set in the method <CODE>setFactory</CODE>.
52   * <p><b>This API is a Sun Microsystems internal API  and is subject 
53   * to change without notice.</b></p>
54   * @since 1.5
55   */
56  public class SnmpEngineImpl implements SnmpEngine, Serializable   {
57      /**
58       * Security level. No authentication, no privacy. Value is 0,
59       * as defined in RFC 2572
60       */
61      public static final int noAuthNoPriv = 0;
62      /**
63       * Security level. Authentication, no privacy. Value is 1, as 
64       * defined in RFC 2572
65       */
66      public static final int authNoPriv = 1;
67      /**
68       * Security level. Authentication, privacy. Value is 3, 
69       * as defined in RFC 2572
70       */
71      public static final int authPriv = 3;
72      /**
73       * Flag that indicates that a report is to be sent. Value is 4, as defined in RFC 2572
74       */
75      public static final int reportableFlag = 4;
76  
77      /**
78       * Mask used to isolate authentication information within a message flag.
79       */    
80      public static final int authMask = 1;
81      /**
82       * Mask used to isolate privacy information within a message flag.
83       */ 
84      public static final int privMask = 2;
85      /**
86       * Mask used to isolate authentication and privacy information within a message flag.
87       */
88      public static final int authPrivMask = 3;
89  
90      private SnmpEngineId engineid = null;
91      private SnmpEngineFactory factory = null;
92      private long startTime = 0;
93  
94      private int boot = 0;
95      private boolean checkOid = false;
96      
97      transient private SnmpUsmKeyHandler usmKeyHandler = null;
98      transient private SnmpLcd lcd = null;
99  
100     transient private SnmpSecuritySubSystem securitySub = null;
101 
102     transient private SnmpMsgProcessingSubSystem messageSub = null;
103 
104     transient private SnmpAccessControlSubSystem accessSub = null;
105 
106     /**
107      * Gets the engine time in seconds. This is the time from the last reboot.
108      * @return The time from the last reboot.
109      */
110     public synchronized int getEngineTime() { 
111     //We do the counter wrap in a lazt way. Each time Engine is asked for his time it checks. So if nobody use the Engine, the time can wrap and wrap again without incrementing nb boot. We can imagine that it is irrelevant due to the amount of time needed to wrap.
112     long delta = (System.currentTimeMillis() / 1000) - startTime;
113     if(delta >  0x7FFFFFFF) {
114         //67 years of running. That is a great thing!
115         //Reinitialize startTime.
116         startTime = System.currentTimeMillis() / 1000;
117 
118         //Can't do anything with this counter.
119         if(boot != 0x7FFFFFFF)
120         boot += 1;
121         //Store for future use.
122         storeNBBoots(boot);
123     }
124     
125     return (int) ((System.currentTimeMillis() / 1000) - startTime); 
126     }
127 
128     /**
129      * Gets the engine Id. This is unique for each engine.
130      * @return The engine Id object.
131      */
132     public SnmpEngineId getEngineId() {
133     return engineid;
134     }
135     
136     /**
137      * Gets the Usm key handler.
138      * @return The key handler.
139      */
140     public SnmpUsmKeyHandler getUsmKeyHandler() {
141     return usmKeyHandler;
142     }
143 
144     /**
145      * Gets the engine Lcd.
146      * @return The engine Lcd.
147      */
148     public SnmpLcd getLcd() {
149     return lcd;
150     }
151     /**
152      * Gets the engine boot number. This is the number of time this engine has rebooted. Each time an <CODE>SnmpEngine</CODE> is instantiated, it will read this value in its Lcd, and store back the value incremented by one.
153      * @return The engine's number of reboot.
154      */
155     public int getEngineBoots() { 
156     return boot; 
157     }
158 
159      /**
160      * Constructor. A Local Configuration Datastore is passed to the engine. It will be used to store and retrieve data (engine Id, engine boots). 
161      * <P> WARNING : The SnmpEngineId is computed as follow:
162      * <ul>
163      * <li> If an lcd file is provided containing the property "localEngineID", this property value is used.</li>.
164      * <li> If not, if the passed engineID is not null, this engine ID is used.</li>
165      * <li> If not, a time based engineID is computed.</li>
166      * </ul>
167      * This constructor should be called by an <CODE>SnmpEngineFactory</CODE>. Don't call it directly.
168      * @param fact The factory used to instantiate this engine.
169      * @param lcd The local configuration datastore.
170      * @param engineid The engine ID to use. If null is provided, an SnmpEngineId is computed using the current time.
171      * @throws UnknownHostException Exception thrown, if the host name located in the property "localEngineID" is invalid.
172      */
173     public SnmpEngineImpl(SnmpEngineFactory fact,
174               SnmpLcd lcd,
175               SnmpEngineId engineid) throws UnknownHostException   {
176     
177     init(lcd, fact);
178     initEngineID();
179     if(this.engineid == null) {
180         if(engineid != null)
181         this.engineid = engineid;
182         else
183         this.engineid = SnmpEngineId.createEngineId();
184     }
185     lcd.storeEngineId(this.engineid);
186     if(isTraceOn()) {
187         trace("SnmpEngine", "LOCAL ENGINE ID: " + this.engineid);
188     }
189     }
190     /**
191      * Constructor. A Local Configuration Datastore is passed to the engine. It will be used to store and retrieve data (engine ID, engine boots). 
192      * <P> WARNING : The SnmpEngineId is computed as follow:
193      * <ul>
194      * <li> If an lcd file is provided containing the property "localEngineID", this property value is used.</li>.
195      * <li> If not, the passed address and port are used to compute one.</li>
196      * </ul>
197      * This constructor should be called by an <CODE>SnmpEngineFactory</CODE>. Don't call it directly.
198      * @param fact The factory used to instantiate this engine.
199      * @param lcd The local configuration datastore.
200      * @param port UDP port to use in order to calculate the engine ID.
201      * @param address An IP address used to calculate the engine ID.
202      * @throws UnknownHostException Exception thrown, if the host name located in the property "localEngineID" is invalid.
203      */
204     public SnmpEngineImpl(SnmpEngineFactory fact,
205               SnmpLcd lcd,
206               InetAddress   address,
207               int port) throws UnknownHostException   {
208     init(lcd, fact);
209     initEngineID();
210     if(engineid == null)
211         engineid = SnmpEngineId.createEngineId(address, port);
212 
213     lcd.storeEngineId(engineid);
214     
215     if(isTraceOn()) {
216         trace("SnmpEngine", "LOCAL ENGINE ID: " + engineid + " / " +
217           "LOCAL ENGINE NB BOOTS: " + boot + " / " +
218           "LOCAL ENGINE START TIME: " + getEngineTime());
219     }
220     }
221 
222     /**
223      * Constructor. A Local Configuration Datastore is passed to the engine. It will be used to store and retrieve data (engine ID, engine boots). 
224      * <P> WARNING : The SnmpEngineId is computed as follow:
225      * <ul>
226      * <li> If an lcd file is provided containing the property "localEngineID", this property value is used.</li>.
227      * <li> If not, The passed port is used to compute one.</li>
228      * </ul>
229      * This constructor should be called by an <CODE>SnmpEngineFactory</CODE>. Don't call it directly.
230      * @param fact The factory used to instantiate this engine.
231      * @param lcd The local configuration datastore
232      * @param port UDP port to use in order to calculate the engine ID.
233      * @throws UnknownHostException Exception thrown, if the host name located in the property "localEngineID" is invalid.
234      */
235     public SnmpEngineImpl(SnmpEngineFactory fact,
236               SnmpLcd lcd,
237               int port) throws UnknownHostException   {
238     init(lcd, fact);
239     initEngineID();
240     if(engineid == null)
241        engineid = SnmpEngineId.createEngineId(port);
242 
243     lcd.storeEngineId(engineid);
244 
245     if(isTraceOn()) {
246         trace("SnmpEngine", "LOCAL ENGINE ID: " + engineid + " / " +
247           "LOCAL ENGINE NB BOOTS: " + boot + " / " +
248           "LOCAL ENGINE START TIME: " + getEngineTime());
249     }
250     }
251 
252     /**
253      * Constructor. A Local Configuration Datastore is passed to the engine. It will be used to store and retrieve data (engine ID, engine boots). 
254      * <P> WARNING : The SnmpEngineId is computed as follow:
255      * <ul>
256      * <li> If an lcd file is provided containing the property "localEngineID", this property value is used.</li>.
257      * <li> If not, a time based engineID is computed.</li>
258      * </ul>
259      * When no configuration nor java property is set for the engine ID value, a unique time based engine ID will be generated.
260      * This constructor should be called by an <CODE>SnmpEngineFactory</CODE>. Don't call it directly.
261      * @param fact The factory used to instantiate this engine.
262      * @param lcd The local configuration datastore.
263      */
264     public SnmpEngineImpl(SnmpEngineFactory fact,
265               SnmpLcd lcd) throws UnknownHostException   {
266     init(lcd, fact);
267     initEngineID();
268     if(engineid == null)
269         engineid = SnmpEngineId.createEngineId();
270     
271     lcd.storeEngineId(engineid);
272 
273 
274     if(isTraceOn()) {
275         trace("SnmpEngine", "LOCAL ENGINE ID: " + engineid + " / " +
276           "LOCAL ENGINE NB BOOTS: " + boot + " / " +
277           "LOCAL ENGINE START TIME: " + getEngineTime());
278     }
279     }
280 
281     /**
282      * Access Control will check the oids. By default is false.
283      */
284     public synchronized void activateCheckOid() {
285     checkOid = true;
286     }
287     
288     /**
289      * Access Control will not check the oids. By default is false.
290      */
291     public synchronized void deactivateCheckOid() {
292     checkOid = false;
293     }
294     
295     /**
296      * Access Control check or not the oids. By default is false.
297      */
298     public synchronized boolean isCheckOidActivated() {
299     return checkOid;
300     }
301 
302     //Do some check and store the nb boots value.
303     private void storeNBBoots(int boot) {
304     if(boot < 0 || boot == 0x7FFFFFFF) {
305         boot = 0x7FFFFFFF;
306         lcd.storeEngineBoots(boot);
307     }
308     else
309         lcd.storeEngineBoots(boot + 1);
310     }
311 
312     // Initialize internal status.
313     private void init(SnmpLcd lcd, SnmpEngineFactory fact) {
314     this.factory = fact;
315     this.lcd = lcd;
316     boot = lcd.getEngineBoots();
317 
318     if(boot == -1 || boot == 0)
319         boot = 1;
320 
321     storeNBBoots(boot);
322 
323     startTime = System.currentTimeMillis() / 1000;
324 
325     }
326     
327     void setUsmKeyHandler(SnmpUsmKeyHandler usmKeyHandler) {
328     this.usmKeyHandler = usmKeyHandler;
329     }
330 
331     //Initialize the engineID.
332     private void initEngineID() throws UnknownHostException   {
333     String   id = lcd.getEngineId();
334     if(id != null) {
335         engineid = SnmpEngineId.createEngineId(id);
336     }
337     }
338 
339   
340     /**
341      * Returns the Message Processing Sub System.
342      * @return The Message Processing Sub System.
343      */
344     public SnmpMsgProcessingSubSystem getMsgProcessingSubSystem() {
345     return messageSub;
346     }
347 
348     /**
349      * Sets the Message Processing Sub System.
350      * @param sys The Message Processing Sub System.
351      */
352     public void setMsgProcessingSubSystem(SnmpMsgProcessingSubSystem sys) {
353     messageSub = sys;
354     }
355     
356      /**
357      * Returns the Security Sub System.
358      * @return The Security Sub System.
359      */
360     public SnmpSecuritySubSystem getSecuritySubSystem() {
361     return securitySub;
362     }
363     /**
364      * Sets the Security Sub System.
365      * @param sys The Security Sub System.
366      */
367     public void setSecuritySubSystem(SnmpSecuritySubSystem sys) {
368     securitySub = sys;
369     }
370      /**
371      * Sets the Access Control Sub System.
372      * @param sys The Access Control Sub System.
373      */
374     public void setAccessControlSubSystem(SnmpAccessControlSubSystem sys) {
375     accessSub = sys;
376     }
377 
378     /**
379      * Returns the Access Control Sub System.
380      * @return The Access Control Sub System.
381      */
382     public SnmpAccessControlSubSystem getAccessControlSubSystem() {
383     return accessSub;
384     }
385     /**
386      * Checks the passed msg flags according to the rules specified in RFC 2572.
387      * @param msgFlags The msg flags.
388      */
389     public static void checkSecurityLevel(byte msgFlags) 
390     throws SnmpBadSecurityLevelException {
391     int secLevel = msgFlags & SnmpDefinitions.authPriv;
392     if((secLevel & SnmpDefinitions.privMask) != 0)
393         if((secLevel & SnmpDefinitions.authMask) == 0) {
394         throw new SnmpBadSecurityLevelException("Security level:"+ 
395                             " noAuthPriv!!!");
396         }
397     }
398     
399     // TRACES & DEBUG
400     //---------------
401     
402     boolean isTraceOn() {
403         return Trace.isSelected(Trace.LEVEL_TRACE, Trace.INFO_SNMP);
404     }
405 
406     void trace(String   clz, String   func, String   info) {
407         Trace.send(Trace.LEVEL_TRACE, Trace.INFO_SNMP, clz, func, info);
408     }
409 
410     void trace(String   func, String   info) {
411         trace(dbgTag, func, info);
412     }
413     
414     boolean isDebugOn() {
415         return Trace.isSelected(Trace.LEVEL_DEBUG, Trace.INFO_SNMP);
416     }
417 
418     void debug(String   clz, String   func, String   info) {
419         Trace.send(Trace.LEVEL_DEBUG, Trace.INFO_SNMP, clz, func, info);
420     }
421 
422     void debug(String   clz, String   func, Throwable   exception) {
423         Trace.send(Trace.LEVEL_DEBUG, Trace.INFO_SNMP, clz, func, exception);
424     }
425 
426     void debug(String   func, String   info) {
427         debug(dbgTag, func, info);
428     }
429     
430     void debug(String   func, Throwable   exception) {
431         debug(dbgTag, func, exception);
432     }
433     
434     String   dbgTag = "SnmpEngineImpl"; 
435 }
436
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags