1. /*
  2. * @(#)file SnmpEngineId.java
  3. * @(#)author Sun Microsystems, Inc.
  4. * @(#)version 1.30
  5. * @(#)date 04/09/15
  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;
  12. import java.net.InetAddress;
  13. import java.io.Serializable;
  14. import java.net.UnknownHostException;
  15. import java.util.StringTokenizer;
  16. import java.util.Arrays;
  17. import java.util.NoSuchElementException;
  18. import com.sun.jmx.snmp.internal.SnmpTools;
  19. /**
  20. * This class is handling an <CODE>SnmpEngineId</CODE> data. It copes with binary as well as <CODE>String</CODE> representation of an engine Id. A string format engine is an hex string starting with 0x.
  21. * <p><b>This API is a Sun Microsystems internal API and is subject
  22. * to change without notice.</b></p>
  23. * @since 1.5
  24. */
  25. public class SnmpEngineId implements Serializable {
  26. byte[] engineId = null;
  27. String hexString = null;
  28. String humanString = null;
  29. /**
  30. * New <CODE>SnmpEngineId</CODE> with an hex string value. Can handle engine Id format <host>:<port>.
  31. * @param hexString Hexa string.
  32. */
  33. SnmpEngineId(String hexString) {
  34. engineId = SnmpTools.ascii2binary(hexString);
  35. this.hexString = hexString.toLowerCase();
  36. }
  37. /**
  38. * New <CODE>SnmpEngineId</CODE> with a binary value. You can use <CODE> SnmpTools </CODE> to convert from hex string to binary format.
  39. * @param bin Binary value
  40. */
  41. SnmpEngineId(byte[] bin) {
  42. engineId = bin;
  43. hexString = SnmpTools.binary2ascii(bin).toLowerCase();
  44. }
  45. /**
  46. * If a string of the format <address>:<port>:<IANA number> has been provided at creation time, this string is returned.
  47. * @return The Id as a readable string or null if not provided.
  48. */
  49. public String getReadableId() {
  50. return humanString;
  51. }
  52. /**
  53. * Returns a string format engine Id.
  54. * @return String format value.
  55. */
  56. public String toString() {
  57. return hexString;
  58. }
  59. /**
  60. * Returns a binary engine Id.
  61. * @return Binary value.
  62. */
  63. public byte[] getBytes() {
  64. return engineId;
  65. }
  66. /**
  67. * In order to store the string used to create the engineId.
  68. */
  69. void setStringValue(String val) {
  70. humanString = val;
  71. }
  72. static void validateId(String str) throws IllegalArgumentException {
  73. byte[] arr = SnmpTools.ascii2binary(str);
  74. validateId(arr);
  75. }
  76. static void validateId(byte[] arr) throws IllegalArgumentException {
  77. if(arr.length < 5) throw new IllegalArgumentException("Id size lower than 5 bytes.");
  78. if(arr.length > 32) throw new IllegalArgumentException("Id size greater than 32 bytes.");
  79. //octet strings with very first bit = 0 and length != 12 octets
  80. if( ((arr[0] & 0x80) == 0) && arr.length != 12)
  81. throw new IllegalArgumentException("Very first bit = 0 and length != 12 octets");
  82. byte[] zeroedArrays = new byte[arr.length];
  83. if(Arrays.equals(zeroedArrays, arr)) throw new IllegalArgumentException("Zeroed Id.");
  84. byte[] FFArrays = new byte[arr.length];
  85. Arrays.fill(FFArrays, (byte)0xFF);
  86. if(Arrays.equals(FFArrays, arr)) throw new IllegalArgumentException("0xFF Id.");
  87. }
  88. /**
  89. * Generates an engine Id based on the passed array.
  90. * @return The created engine Id or null if given arr is null or its length == 0;
  91. * @exception IllegalArgumentException when:
  92. * <ul>
  93. * <li>octet string lower than 5 bytes.</li>
  94. * <li>octet string greater than 32 bytes.</li>
  95. * <li>octet string = all zeros.</li>
  96. * <li>octet string = all 'ff'H.</li>
  97. * <li>octet strings with very first bit = 0 and length != 12 octets</li>
  98. * </ul>
  99. */
  100. public static SnmpEngineId createEngineId(byte[] arr) throws IllegalArgumentException {
  101. if( (arr == null) || arr.length == 0) return null;
  102. validateId(arr);
  103. return new SnmpEngineId(arr);
  104. }
  105. /**
  106. * Generates an engine Id that is unique to the host the agent is running on. The engine Id unicity is system time based. The creation algorithm uses the SUN Microsystems IANA number (42).
  107. * @return The generated engine Id.
  108. */
  109. public static SnmpEngineId createEngineId() {
  110. byte[] address = null;
  111. byte[] engineid = new byte[13];
  112. int iana = 42;
  113. long mask = 0xFF;
  114. long time = System.currentTimeMillis();
  115. engineid[0] = (byte) ( (iana & 0xFF000000) >> 24 );
  116. engineid[0] |= 0x80;
  117. engineid[1] = (byte) ( (iana & 0x00FF0000) >> 16 );
  118. engineid[2] = (byte) ( (iana & 0x0000FF00) >> 8 );
  119. engineid[3] = (byte) (iana & 0x000000FF);
  120. engineid[4] = 0x05;
  121. engineid[5] = (byte) ( (time & (mask << 56)) >>> 56 );
  122. engineid[6] = (byte) ( (time & (mask << 48) ) >>> 48 );
  123. engineid[7] = (byte) ( (time & (mask << 40) ) >>> 40 );
  124. engineid[8] = (byte) ( (time & (mask << 32) ) >>> 32 );
  125. engineid[9] = (byte) ( (time & (mask << 24) ) >>> 24 );
  126. engineid[10] = (byte) ( (time & (mask << 16) ) >>> 16 );
  127. engineid[11] = (byte) ( (time & (mask << 8) ) >>> 8 );
  128. engineid[12] = (byte) (time & mask);
  129. return new SnmpEngineId(engineid);
  130. }
  131. /**
  132. * Translates an engine Id in an SnmpOid format. This is useful when dealing with USM MIB indexes.
  133. * The oid format is : <engine Id length>.<engine Id binary octet1>....<engine Id binary octetn - 1>.<engine Id binary octetn>
  134. * Eg: "0x8000002a05819dcb6e00001f96" ==> 13.128.0.0.42.5.129.157.203.110.0.0.31.150
  135. *
  136. * @return SnmpOid The oid.
  137. */
  138. public SnmpOid toOid() {
  139. long[] oid = new long[engineId.length + 1];
  140. oid[0] = engineId.length;
  141. for(int i = 1; i <= engineId.length; i++)
  142. oid[i] = (long) (engineId[i-1] & 0xFF);
  143. return new SnmpOid(oid);
  144. }
  145. /**
  146. * <P>Generates a unique engine Id. Hexadecimal strings as well as a textual description are supported. The textual format is as follow:
  147. * <BR> <address>:<port>:<IANA number></P>
  148. * <P>The allowed formats :</P>
  149. * <ul>
  150. * <li> <address>:<port>:<IANA number>
  151. * <BR> All these parameters are used to generate the Id. WARNING, this method is not compliant with IPv6 address format. Use { @link com.sun.jmx.snmp.SnmpEngineId#createEngineId(java.lang.String,java.lang.String) } instead.</li>
  152. * <li> <address>:<port>
  153. * <BR> The IANA number will be the SUN Microsystems one (42). </li>
  154. * <li> address
  155. * <BR> The port 161 will be used to generate the Id. IANA number will be the SUN Microsystems one (42). </li>
  156. * <li> :port
  157. * <BR> The host to use is localhost. IANA number will be the SUN Microsystems one (42). </li>
  158. * <li> ::<IANA number>    
  159. * <BR> The port 161 and localhost will be used to generate the Id. </li>
  160. * <li> :<port>:<IANA number>
  161. * <BR> The host to use is localhost. </li>
  162. * <li> <address>::<IANA number>
  163. * <BR> The port 161 will be used to generate the Id. </li>
  164. * <li> ::    
  165. * <BR> The port 161, localhost and the SUN Microsystems IANA number will be used to generate the Id. </li>
  166. * </ul>
  167. * @exception UnknownHostException if the host name contained in the textual format is unknown.
  168. * @exception IllegalArgumentException when :
  169. * <ul>
  170. * <li>octet string lower than 5 bytes.</li>
  171. * <li>octet string greater than 32 bytes.</li>
  172. * <li>octet string = all zeros.</li>
  173. * <li>octet string = all 'ff'H.</li>
  174. * <li>octet strings with very first bit = 0 and length != 12 octets</li>
  175. * <li>An IPv6 address format is used in conjonction with the ":" separator</li>
  176. * </ul>
  177. * @param str The string to parse.
  178. * @return The generated engine Id or null if the passed string is null.
  179. *
  180. */
  181. public static SnmpEngineId createEngineId(String str)
  182. throws IllegalArgumentException, UnknownHostException {
  183. return createEngineId(str, null);
  184. }
  185. /**
  186. * Idem { @link
  187. * com.sun.jmx.snmp.SnmpEngineId#createEngineId(java.lang.String) }
  188. * with the ability to provide your own separator. This allows IPv6
  189. * address format handling (eg: providing @ as separator).
  190. * @param str The string to parse.
  191. * @param separator the separator to use. If null is provided, the default
  192. * separator ":" is used.
  193. * @return The generated engine Id or null if the passed string is null.
  194. * @exception UnknownHostException if the host name contained in the
  195. * textual format is unknown.
  196. * @exception IllegalArgumentException when :
  197. * <ul>
  198. * <li>octet string lower than 5 bytes.</li>
  199. * <li>octet string greater than 32 bytes.</li>
  200. * <li>octet string = all zeros.</li>
  201. * <li>octet string = all 'ff'H.</li>
  202. * <li>octet strings with very first bit = 0 and length != 12 octets</li>
  203. * <li>An IPv6 address format is used in conjonction with the ":"
  204. * separator</li>
  205. * </ul>
  206. * @since 1.5
  207. */
  208. public static SnmpEngineId createEngineId(String str, String separator)
  209. throws IllegalArgumentException, UnknownHostException {
  210. if(str == null) return null;
  211. if(str.startsWith("0x") || str.startsWith("0X")) {
  212. validateId(str);
  213. return new SnmpEngineId(str);
  214. }
  215. separator = separator == null ? ":" : separator;
  216. StringTokenizer token = new StringTokenizer(str,
  217. separator,
  218. true);
  219. String address = null;
  220. String port = null;
  221. String iana = null;
  222. int objPort = 161;
  223. int objIana = 42;
  224. InetAddress objAddress = null;
  225. SnmpEngineId eng = null;
  226. try {
  227. //Deal with address
  228. try {
  229. address = token.nextToken();
  230. }catch(NoSuchElementException e) {
  231. throw new IllegalArgumentException("Passed string is invalid : ["+str+"]");
  232. }
  233. if(!address.equals(separator)) {
  234. objAddress = InetAddress.getByName(address);
  235. try {
  236. token.nextToken();
  237. }catch(NoSuchElementException e) {
  238. //No need to go further, no port.
  239. eng = SnmpEngineId.createEngineId(objAddress,
  240. objPort,
  241. objIana);
  242. eng.setStringValue(str);
  243. return eng;
  244. }
  245. }
  246. else
  247. objAddress = InetAddress.getLocalHost();
  248. //Deal with port
  249. try {
  250. port = token.nextToken();
  251. }catch(NoSuchElementException e) {
  252. //No need to go further, no port.
  253. eng = SnmpEngineId.createEngineId(objAddress,
  254. objPort,
  255. objIana);
  256. eng.setStringValue(str);
  257. return eng;
  258. }
  259. if(!port.equals(separator)) {
  260. objPort = Integer.parseInt(port);
  261. try {
  262. token.nextToken();
  263. }catch(NoSuchElementException e) {
  264. //No need to go further, no iana.
  265. eng = SnmpEngineId.createEngineId(objAddress,
  266. objPort,
  267. objIana);
  268. eng.setStringValue(str);
  269. return eng;
  270. }
  271. }
  272. //Deal with iana
  273. try {
  274. iana = token.nextToken();
  275. }catch(NoSuchElementException e) {
  276. //No need to go further, no port.
  277. eng = SnmpEngineId.createEngineId(objAddress,
  278. objPort,
  279. objIana);
  280. eng.setStringValue(str);
  281. return eng;
  282. }
  283. if(!iana.equals(separator))
  284. objIana = Integer.parseInt(iana);
  285. eng = SnmpEngineId.createEngineId(objAddress,
  286. objPort,
  287. objIana);
  288. eng.setStringValue(str);
  289. return eng;
  290. } catch(Exception e) {
  291. throw new IllegalArgumentException("Passed string is invalid : ["+str+"]. Check that the used separator ["+ separator + "] is compatible with IPv6 address format.");
  292. }
  293. }
  294. /**
  295. * Generates a unique engine Id. The engine Id unicity is based on
  296. * the host IP address and port. The IP address used is the
  297. * localhost one. The creation algorithm uses the SUN Microsystems IANA
  298. * number (42).
  299. * @param port The TCP/IP port the SNMPv3 Adaptor Server is listening to.
  300. * @return The generated engine Id.
  301. * @exception UnknownHostException if the local host name
  302. * used to calculate the id is unknown.
  303. */
  304. public static SnmpEngineId createEngineId(int port)
  305. throws UnknownHostException {
  306. int suniana = 42;
  307. InetAddress address = null;
  308. address = InetAddress.getLocalHost();
  309. return createEngineId(address, port, suniana);
  310. }
  311. /**
  312. * Generates a unique engine Id. The engine Id unicity is based on
  313. * the host IP address and port. The IP address used is the passed
  314. * one. The creation algorithm uses the SUN Microsystems IANA
  315. * number (42).
  316. * @param address The IP address the SNMPv3 Adaptor Server is listening to.
  317. * @param port The TCP/IP port the SNMPv3 Adaptor Server is listening to.
  318. * @return The generated engine Id.
  319. * @exception UnknownHostException. if the provided address is null.
  320. */
  321. public static SnmpEngineId createEngineId(InetAddress address, int port)
  322. throws IllegalArgumentException {
  323. int suniana = 42;
  324. if(address == null)
  325. throw new IllegalArgumentException("InetAddress is null.");
  326. return createEngineId(address, port, suniana);
  327. }
  328. /**
  329. * Generates a unique engine Id. The engine Id unicity is based on
  330. * the host IP address and port. The IP address is the localhost one.
  331. * The creation algorithm uses the passed IANA number.
  332. * @param port The TCP/IP port the SNMPv3 Adaptor Server is listening to.
  333. * @param iana Your enterprise IANA number.
  334. * @exception UnknownHostException if the local host name used to calculate the id is unknown.
  335. * @return The generated engine Id.
  336. */
  337. public static SnmpEngineId createEngineId(int port, int iana) throws UnknownHostException {
  338. InetAddress address = null;
  339. address = InetAddress.getLocalHost();
  340. return createEngineId(address, port, iana);
  341. }
  342. /**
  343. * Generates a unique engine Id. The engine Id unicity is based on the host IP address and port. The IP address is the passed one, it handles IPv4 and IPv6 hosts. The creation algorithm uses the passed IANA number.
  344. * @param addr The IP address the SNMPv3 Adaptor Server is listening to.
  345. * @param port The TCP/IP port the SNMPv3 Adaptor Server is listening to.
  346. * @param iana Your enterprise IANA number.
  347. * @return The generated engine Id.
  348. * @exception UnknownHostException if the provided <CODE>InetAddress </CODE> is null.
  349. */
  350. public static SnmpEngineId createEngineId(InetAddress addr,
  351. int port,
  352. int iana) {
  353. if(addr == null) throw new IllegalArgumentException("InetAddress is null.");
  354. byte[] address = addr.getAddress();
  355. byte[] engineid = new byte[9 + address.length];
  356. engineid[0] = (byte) ( (iana & 0xFF000000) >> 24 );
  357. engineid[0] |= 0x80;
  358. engineid[1] = (byte) ( (iana & 0x00FF0000) >> 16 );
  359. engineid[2] = (byte) ( (iana & 0x0000FF00) >> 8 );
  360. engineid[3] = (byte) (iana & 0x000000FF);
  361. engineid[4] = 0x05;
  362. if(address.length == 4)
  363. engineid[4] = 0x01;
  364. if(address.length == 16)
  365. engineid[4] = 0x02;
  366. for(int i = 0; i < address.length; i++) {
  367. engineid[i + 5] = address[i];
  368. }
  369. engineid[5 + address.length] = (byte) ( (port & 0xFF000000) >> 24 );
  370. engineid[6 + address.length] = (byte) ( (port & 0x00FF0000) >> 16 );
  371. engineid[7 + address.length] = (byte) ( (port & 0x0000FF00) >> 8 );
  372. engineid[8 + address.length] = (byte) ( port & 0x000000FF );
  373. return new SnmpEngineId(engineid);
  374. }
  375. /**
  376. * Generates an engine Id based on an InetAddress. Handles IPv4 and IPv6 addresses. The creation algorithm uses the passed IANA number.
  377. * @param iana Your enterprise IANA number.
  378. * @param addr The IP address the SNMPv3 Adaptor Server is listening to.
  379. * @return The generated engine Id.
  380. * @since 1.5
  381. * @exception UnknownHostException if the provided <CODE>InetAddress </CODE> is null.
  382. */
  383. public static SnmpEngineId createEngineId(int iana, InetAddress addr)
  384. {
  385. if(addr == null) throw new IllegalArgumentException("InetAddress is null.");
  386. byte[] address = addr.getAddress();
  387. byte[] engineid = new byte[5 + address.length];
  388. engineid[0] = (byte) ( (iana & 0xFF000000) >> 24 );
  389. engineid[0] |= 0x80;
  390. engineid[1] = (byte) ( (iana & 0x00FF0000) >> 16 );
  391. engineid[2] = (byte) ( (iana & 0x0000FF00) >> 8 );
  392. engineid[3] = (byte) (iana & 0x000000FF);
  393. if(address.length == 4)
  394. engineid[4] = 0x01;
  395. if(address.length == 16)
  396. engineid[4] = 0x02;
  397. for(int i = 0; i < address.length; i++) {
  398. engineid[i + 5] = address[i];
  399. }
  400. return new SnmpEngineId(engineid);
  401. }
  402. /**
  403. * Generates an engine Id based on an InetAddress. Handles IPv4 and IPv6
  404. * addresses. The creation algorithm uses the sun IANA number (42).
  405. * @param addr The IP address the SNMPv3 Adaptor Server is listening to.
  406. * @return The generated engine Id.
  407. * @since 1.5
  408. * @exception UnknownHostException if the provided
  409. * <CODE>InetAddress</CODE> is null.
  410. */
  411. public static SnmpEngineId createEngineId(InetAddress addr) {
  412. return createEngineId(42, addr);
  413. }
  414. /**
  415. * Tests <CODE>SnmpEngineId</CODE> instance equality. Two <CODE>SnmpEngineId</CODE> are equal if they have the same value.
  416. * @return <CODE>true</CODE> if the two <CODE>SnmpEngineId</CODE> are equals, <CODE>false</CODE> otherwise.
  417. */
  418. public boolean equals(Object a) {
  419. if(!(a instanceof SnmpEngineId) ) return false;
  420. return hexString.equals(((SnmpEngineId) a).toString());
  421. }
  422. public int hashCode() {
  423. return hexString.hashCode();
  424. }
  425. }