Menu
▾
▴
[Wonder-cvs] SF.net SVN: wonder:[9996] trunk/Wonder/Frameworks/Core/ERExtensions/Sources /er/extensions/foundation/ERXRandomGUID.java
|
From: <ms...@us...> - 2009-09-29 17:34:09
|
Revision: 9996
http://wonder.svn.sourceforge.net/wonder/?rev=9996&view=rev
Author: mschrag
Date: 2009-09-29 17:33:27 +0000 (Tue, 29 Sep 2009)
Log Message:
-----------
WONDER-322 Javadocs for ERXRandomGUID.java
Modified Paths:
--------------
trunk/Wonder/Frameworks/Core/ERExtensions/Sources/er/extensions/foundation/ERXRandomGUID.java
Modified: trunk/Wonder/Frameworks/Core/ERExtensions/Sources/er/extensions/foundation/ERXRandomGUID.java
===================================================================
--- trunk/Wonder/Frameworks/Core/ERExtensions/Sources/er/extensions/foundation/ERXRandomGUID.java 2009-09-29 17:30:59 UTC (rev 9995)
+++ trunk/Wonder/Frameworks/Core/ERExtensions/Sources/er/extensions/foundation/ERXRandomGUID.java 2009-09-29 17:33:27 UTC (rev 9996)
@@ -1,26 +1,7 @@
package er.extensions.foundation;
-/*
- * the following code was copies from w.javaexchange.com
- * see the javadoc for more information
- *
- * RandomGUID
- * @version 1.2.1 11/05/02
- * @author Marc A. Mnich
- *
- * From www.JavaExchange.com, Open Software licensing
- *
- * 11/05/02 -- Performance enhancement from Mike Dubman.
- * Moved InetAddr.getLocal to static block. Mike has measured
- * a 10 fold improvement in run time.
- * 01/29/02 -- Bug fix: Improper seeding of nonsecure Random object
- * caused duplicate GUIDs to be produced. Random object
- * is now only created once per JVM.
- * 01/19/02 -- Modified random seeding and added new constructor
- * to allow secure random feature.
- * 01/14/02 -- Added random function seeding with JVM run time
- *
- */
+// This class was copied from www.javaexchange.com, under the terms of
+// the author's license. See the Javadocs for more information.
import java.net.InetAddress;
import java.net.UnknownHostException;
@@ -29,74 +10,114 @@
import java.security.SecureRandom;
import java.util.Random;
-/*
- * In the multitude of java GUID generators, I found none that
- * guaranteed randomness. GUIDs are guaranteed to be globally unique
- * by using ethernet MACs, IP addresses, time elements, and sequential
- * numbers. GUIDs are not expected to be random and most often are
- * easy/possible to guess given a sample from a given generator.
- * SQL Server, for example generates GUID that are unique but
- * sequencial within a given instance.
- *
- * GUIDs can be used as security devices to hide things such as
- * files within a filesystem where listings are unavailable (e.g. files
- * that are served up from a Web server with indexing turned off).
- * This may be desireable in cases where standard authentication is not
- * appropriate. In this scenario, the RandomGUIDs are used as directories.
- * Another example is the use of GUIDs for primary keys in a database
- * where you want to ensure that the keys are secret. Random GUIDs can
- * then be used in a URL to prevent hackers (or users) from accessing
+/**
+ * <p>
+ * In the multitude of java GUID generators, I found none that guaranteed
+ * randomness. GUIDs are guaranteed to be globally unique by using ethernet
+ * MACs, IP addresses, time elements, and sequential numbers. GUIDs are not
+ * expected to be random and most often are easy/possible to guess given a
+ * sample from a given generator. SQL Server, for example generates GUID that
+ * are unique but sequencial within a given instance.
+ * </p>
+ *
+ * <p>
+ * GUIDs can be used as security devices to hide things such as files within a
+ * filesystem where listings are unavailable (e.g. files that are served up from
+ * a Web server with indexing turned off). This may be desireable in cases where
+ * standard authentication is not appropriate. In this scenario, the RandomGUIDs
+ * are used as directories. Another example is the use of GUIDs for primary keys
+ * in a database where you want to ensure that the keys are secret. Random GUIDs
+ * can then be used in a URL to prevent hackers (or users) from accessing
* records by guessing or simply by incrementing sequential numbers.
- *
- * There are many other possiblities of using GUIDs in the realm of
- * security and encryption where the element of randomness is important.
- * This class was written for these purposes but can also be used as a
- * general purpose GUID generator as well.
- *
- * RandomGUID generates truly random GUIDs by using the system's
- * IP address (name/IP), system time in milliseconds (as an integer),
- * and a very large random number joined together in a single String
- * that is passed through an MD5 hash. The IP address and system time
- * make the MD5 seed globally unique and the random number guarantees
- * that the generated GUIDs will have no discernable pattern and
- * cannot be guessed given any number of previously generated GUIDs.
- * It is generally not possible to access the seed information (IP, time,
- * random number) from the resulting GUIDs as the MD5 hash algorithm
+ * </p>
+ *
+ * <p>
+ * There are many other possiblities of using GUIDs in the realm of security and
+ * encryption where the element of randomness is important. This class was
+ * written for these purposes but can also be used as a general purpose GUID
+ * generator as well.
+ * </p>
+ *
+ * <p>
+ * {@code RandomGUID} generates truly random GUIDs by using the system's IP
+ * address (name/IP), system time in milliseconds (as an integer), and a very
+ * large random number joined together in a single String that is passed through
+ * an MD5 hash. The IP address and system time make the MD5 seed globally unique
+ * and the random number guarantees that the generated GUIDs will have no
+ * discernable pattern and cannot be guessed given any number of previously
+ * generated GUIDs. It is generally not possible to access the seed information
+ * (IP, time, random number) from the resulting GUIDs as the MD5 hash algorithm
* provides one way encryption.
- *
- * ----> Security of RandomGUID: <-----
- * RandomGUID can be called one of two ways -- with the basic java Random
- * number generator or a cryptographically strong random generator
- * (SecureRandom). The choice is offered because the secure random
- * generator takes about 3.5 times longer to generate its random numbers
- * and this performance hit may not be worth the added security
- * especially considering the basic generator is seeded with a
- * cryptographically strong random seed.
- *
- * Seeding the basic generator in this way effectively decouples
- * the random numbers from the time component making it virtually impossible
- * to predict the random number component even if one had absolute knowledge
- * of the System time. Thanks to Ashutosh Narhari for the suggestion
- * of using the static method to prime the basic random generator.
- *
+ * </p>
+ *
+ * <h2>Security of {@code RandomGUID}</h2>
+ * <p>
+ * {@code RandomGUID} can be called one of two ways -- with the basic java
+ * {@link Random} number generator or a cryptographically strong random
+ * generator ({@link SecureRandom}). The choice is offered because the secure
+ * random generator takes about 3.5 times longer to generate its random numbers
+ * and this performance hit may not be worth the added security especially
+ * considering the basic generator is seeded with a cryptographically strong
+ * random seed.
+ * </p>
+ *
+ * <p>
+ * Seeding the basic generator in this way effectively decouples the random
+ * numbers from the time component making it virtually impossible to predict the
+ * random number component even if one had absolute knowledge of the System
+ * time. Thanks to Ashutosh Narhari for the suggestion of using the static
+ * method to prime the basic random generator.
+ * </p>
+ *
+ * <p>
* Using the secure random option, this class compies with the statistical
- * random number generator tests specified in FIPS 140-2, Security
- * Requirements for Cryptographic Modules, secition 4.9.1.
- *
- * I converted all the pieces of the seed to a String before handing
- * it over to the MD5 hash so that you could print it out to make
- * sure it contains the data you expect to see and to give a nice
- * warm fuzzy. If you need better performance, you may want to stick
- * to byte[] arrays.
- *
- * I believe that it is important that the algorithm for
- * generating random GUIDs be open for inspection and modification.
- * This class is free for all uses.
- *
- *
- * - Marc
+ * random number generator tests specified in FIPS 140-2, Security Requirements
+ * for Cryptographic Modules, secition 4.9.1.
+ * </p>
+ *
+ * <p>
+ * I converted all the pieces of the seed to a {@code String} before handing it
+ * over to the MD5 hash so that you could print it out to make sure it contains
+ * the data you expect to see and to give a nice warm fuzzy. If you need better
+ * performance, you may want to stick to {@code byte[]} arrays.
+ * </p>
+ *
+ * <p>
+ * I believe that it is important that the algorithm for generating random GUIDs
+ * be open for inspection and modification. This class is free for all uses.
+ * </p>
+ *
+ * <h2>History</h2>
+ * <table>
+ * <tr>
+ * <td>11/05/02</td>
+ * <td>Performance enhancement from Mike Dubman. Moved {@code InetAddr.getLocal}
+ * to static block. Mike has measured a 10 fold improvement in run time.</td>
+ * </tr>
+ * <tr>
+ * <td>01/29/02</td>
+ * <td>Bug fix: Improper seeding of nonsecure Random object caused duplicate
+ * GUIDs to be produced. Random object is now only created once per JVM.</td>
+ * </tr>
+ * <tr>
+ * <td>01/19/02</td>
+ * <td>Modified random seeding and added new constructor to allow secure random
+ * feature.</td>
+ * </tr>
+ * <tr>
+ * <td>01/14/02</td>
+ * <td>Added random function seeding with JVM run time</td>
+ * </tr>
+ * </table>
+ *
+ * <h2>License</h2>
+ * <p>
+ * From www.JavaExchange.com, Open Software licensing
+ * </p>
+ *
+ * @version 1.2.1 11/05/02
+ * @author Marc A. Mnich
*/
-
public class ERXRandomGUID extends Object {
public String valueBeforeMD5 = "";
@@ -106,14 +127,13 @@
private static String s_id;
- /*
- * Static block to take care of one time secureRandom seed.
- * It takes a few seconds to initialize SecureRandom. You might
- * want to consider removing this static block or replacing
- * it with a "time since first loaded" seed to reduce this time.
- * This block will run only once per JVM instance.
- */
-
+ /**
+ * Static block to take care of one time {@link SecureRandom} seed. It takes
+ * a few seconds to initialize {@code SecureRandom}. You might want to
+ * consider removing this static block or replacing it with a
+ * "time since first loaded" seed to reduce this time. This block will run
+ * only once per JVM instance.
+ */
static {
mySecureRand = new SecureRandom();
long secureInitializer = mySecureRand.nextLong();
@@ -127,27 +147,35 @@
}
- /*
- * Default constructor. With no specification of security option,
- * this constructor defaults to lower security, high performance.
- */
+ /**
+ * Default constructor. With no specification of security option, this
+ * constructor defaults to lower security, high performance.
+ */
public ERXRandomGUID() {
getRandomGUID(false);
}
- /*
- * Constructor with security option. Setting secure true
- * enables each random number generated to be cryptographically
- * strong. Secure false defaults to the standard Random function seeded
- * with a single cryptographically strong random number.
- */
+ /**
+ * Constructor with security option. Setting {@code secure} {@code true}
+ * enables each random number generated to be cryptographically strong.
+ * {@code secure} {@code false} defaults to the standard {@link Random}
+ * function seeded with a single cryptographically strong random number.
+ *
+ * @param secure
+ * {@code true} use a random number from {@link SecureRandom}, or
+ * {@code false} use a random number from {@link Random}
+ */
public ERXRandomGUID(boolean secure) {
getRandomGUID(secure);
}
- /*
- * Method to generate the random GUID
- */
+ /**
+ * Method to generate the random GUID
+ *
+ * @param secure
+ * {@code true} use a random number from {@link SecureRandom}, or
+ * {@code false} use a random number from {@link Random}
+ */
private void getRandomGUID(boolean secure) {
MessageDigest md5 = null;
StringBuffer sbValueBeforeMD5 = new StringBuffer();
@@ -199,11 +227,12 @@
}
- /*
- * Convert to the standard format for GUID
- * (Useful for SQL Server UniqueIdentifiers, etc.)
- * Example: C2FEEEAC-CFCD-11D1-8B05-00600806D9B6
- */
+ /**
+ * Convert to the standard format for GUID (Useful for SQL Server
+ * UniqueIdentifiers, etc.) Example: C2FEEEAC-CFCD-11D1-8B05-00600806D9B6
+ *
+ * @return a {@code String} representation of this object
+ */
public String toString() {
String raw = valueAfterMD5.toUpperCase();
StringBuffer sb = new StringBuffer();
@@ -220,9 +249,12 @@
return sb.toString();
}
- /*
- * Demonstraton and self test of class
- */
+ /**
+ * Demonstration and self test of class.
+ *
+ * @param args
+ * No arguments
+ */
public static void main(String args[]) {
for (int i=0; i< 100; i++) {
ERXRandomGUID myGUID = new ERXRandomGUID();
@@ -232,6 +264,13 @@
}
}
+ /**
+ * Returns the {@code String} representation of a new {@code ERXRandomGUID}
+ * object.
+ *
+ * @return the {@code String} representation of a new {@code ERXRandomGUID}
+ * object
+ */
public static String newGid() {
return new ERXRandomGUID().toString();
}
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|