From 17c32087ad475b043e373e56f2a489d79046334d Mon Sep 17 00:00:00 2001 From: Gary Gregory Date: Tue, 20 Aug 2024 08:06:12 -0400 Subject: [PATCH] Random[String]Utils.secure() now uses SecureRandom() instead of SecureRandom.getInstanceStrong() - RandomStringUtils.secure() now uses SecureRandom() instead of SecureRandom.getInstanceStrong() - RandomUtils.secure() now uses SecureRandom() instead of SecureRandom.getInstanceStrong() - Add RandomStringUtils.secureStrong() - Add RandomUtils.secureStrong() --- src/changes/changes.xml | 4 + .../commons/lang3/RandomStringUtils.java | 102 +++++++++++------- .../org/apache/commons/lang3/RandomUtils.java | 77 +++++++------ 3 files changed, 109 insertions(+), 74 deletions(-) diff --git a/src/changes/changes.xml b/src/changes/changes.xml index dbf97ce76..bcdddf6d0 100644 --- a/src/changes/changes.xml +++ b/src/changes/changes.xml @@ -50,8 +50,12 @@ The type attribute can be add,update,fix,remove. Using RandomStringUtils.insecure() still leads to using the secure() random. Deprecate static RandomUtils.next*() methods in favor or .secure() and .insecure() versions. Deprecate static RandomStringUtils.random*() methods in favor or .secure() and .insecure() versions. + RandomUtils.secure() now uses SecureRandom() instead of SecureRandom.getInstanceStrong(). + RandomStringUtils.secure() now uses SecureRandom() instead of SecureRandom.getInstanceStrong(). Make RandomUtils.insecure() public. + Add RandomUtils.secureStrong(). + Add RandomStringUtils.secureStrong(). Bump org.hamcrest:hamcrest from 2.2 to 3.0 #1255. Bump org.easymock:easymock from 5.3.0 to 5.4.0 #1256. diff --git a/src/main/java/org/apache/commons/lang3/RandomStringUtils.java b/src/main/java/org/apache/commons/lang3/RandomStringUtils.java index 65569230a..dfa711ac6 100644 --- a/src/main/java/org/apache/commons/lang3/RandomStringUtils.java +++ b/src/main/java/org/apache/commons/lang3/RandomStringUtils.java @@ -25,39 +25,42 @@ import java.util.function.Supplier; /** * Generates random {@link String}s. *

+ * Use {@link #secure()} to get the singleton instance based on {@link SecureRandom#SecureRandom()} which uses a secure random number generator (RNG) + * implementing the default random number algorithm.. + *

+ *

+ * Use {@link #secureStrong()} to get the singleton instance based on {@link SecureRandom#getInstanceStrong()} which uses an algorithms/providers specified in + * the {@code securerandom.strongAlgorithms} {@link Security} property. + *

+ *

+ * Use {@link #insecure()} to get the singleton instance based on {@link ThreadLocalRandom#current()}; which is not cryptographically secure. + *

+ *

+ * Starting in version 3.17.0, the method {@link #secure()} uses {@link SecureRandom#SecureRandom()} instead of {@link SecureRandom#getInstanceStrong()}, and + * adds {@link #secureStrong()}. + *

+ *

* Starting in version 3.16.0, this class uses {@link #secure()} for static methods and adds {@link #insecure()}. *

*

* Starting in version 3.15.0, this class uses {@link SecureRandom#getInstanceStrong()} for static methods. *

*

- * Before version 3.15.0, this class used {@link ThreadLocalRandom#current()} for static methods, which is not - * cryptographically secure. - *

- *

- * Use {@link #secure()} to get the singleton instance based on {@link SecureRandom#getInstanceStrong()} which uses an - * algorithms/providers specified in the {@code securerandom.strongAlgorithms} {@link Security} property. - *

- *

- * Use {@link #insecure()} to get the singleton instance based on {@link ThreadLocalRandom#current()}; which is not - * cryptographically secure. + * Before version 3.15.0, this class used {@link ThreadLocalRandom#current()} for static methods, which is not cryptographically secure. *

*

* RandomStringUtils is intended for simple use cases. For more advanced use cases consider using Apache Commons Text's - * - * RandomStringGenerator instead. + * RandomStringGenerator + * instead. *

*

- * The Apache Commons project provides Commons RNG - * dedicated to pseudo-random number generation, that may be a better choice for applications with more stringent - * requirements (performance and/or correctness). + * The Apache Commons project provides Commons RNG dedicated to pseudo-random number generation, + * that may be a better choice for applications with more stringent requirements (performance and/or correctness). *

*

- * Note that private high surrogate characters are ignored. These are Unicode characters that fall between the - * values 56192 (db80) and 56319 (dbff) as we don't know how to handle them. High and low surrogates are correctly dealt - * with - that is if a high surrogate is randomly chosen, 55296 (d800) to 56191 (db7f) then it is followed by a low - * surrogate. If a low surrogate is chosen, 56320 (dc00) to 57343 (dfff) then it is placed after a randomly chosen high + * Note that private high surrogate characters are ignored. These are Unicode characters that fall between the values 56192 (db80) and 56319 (dbff) as + * we don't know how to handle them. High and low surrogates are correctly dealt with - that is if a high surrogate is randomly chosen, 55296 (d800) to 56191 + * (db7f) then it is followed by a low surrogate. If a low surrogate is chosen, 56320 (dc00) to 57343 (dfff) then it is placed after a randomly chosen high * surrogate. *

*

@@ -75,6 +78,8 @@ public class RandomStringUtils { private static RandomStringUtils SECURE = new RandomStringUtils(SECURE_SUPPLIER); + private static RandomStringUtils SECURE_STRONG = new RandomStringUtils(RandomUtils::secureStrong); + private static final char[] ALPHANUMERICAL_CHARS = { 'a', 'b', 'c', 'd', 'e', 'f', 'g', 'h', 'i', 'j', 'k', 'l', 'm', 'n', 'o', 'p', 'q', 'r', 's', 't', 'u', 'v', 'w', 'x', 'y', 'z', 'A', 'B', 'C', 'D', 'E', 'F', 'G', 'H', 'I', 'J', 'K', 'L', 'M', 'N', 'O', 'P', 'Q', 'R', 'S', 'T', 'U', 'V', 'W', 'X', 'Y', 'Z', '0', '1', @@ -107,7 +112,7 @@ public class RandomStringUtils { * @param count the length of random string to create * @return the random string * @throws IllegalArgumentException if {@code count} < 0. - * @deprecated Use {@link #secure()} or {@link #insecure()}. + * @deprecated Use {@link #secure()}, {@link #secureStrong()},or {@link #insecure()}. */ @Deprecated public static String random(final int count) { @@ -126,7 +131,7 @@ public class RandomStringUtils { * @param numbers if {@code true}, generated string may include numeric characters * @return the random string * @throws IllegalArgumentException if {@code count} < 0. - * @deprecated Use {@link #secure()} or {@link #insecure()}. + * @deprecated Use {@link #secure()}, {@link #secureStrong()},or {@link #insecure()}. */ @Deprecated public static String random(final int count, final boolean letters, final boolean numbers) { @@ -144,7 +149,7 @@ public class RandomStringUtils { * @param chars the character array containing the set of characters to use, may be null * @return the random string * @throws IllegalArgumentException if {@code count} < 0. - * @deprecated Use {@link #secure()} or {@link #insecure()}. + * @deprecated Use {@link #secure()}, {@link #secureStrong()},or {@link #insecure()}. */ @Deprecated public static String random(final int count, final char... chars) { @@ -165,7 +170,7 @@ public class RandomStringUtils { * @param numbers if {@code true}, generated string may include numeric characters * @return the random string * @throws IllegalArgumentException if {@code count} < 0. - * @deprecated Use {@link #secure()} or {@link #insecure()}. + * @deprecated Use {@link #secure()}, {@link #secureStrong()},or {@link #insecure()}. */ @Deprecated public static String random(final int count, final int start, final int end, final boolean letters, @@ -191,7 +196,7 @@ public class RandomStringUtils { * @return the random string * @throws ArrayIndexOutOfBoundsException if there are not {@code (end - start) + 1} characters in the set array. * @throws IllegalArgumentException if {@code count} < 0. - * @deprecated Use {@link #secure()} or {@link #insecure()}. + * @deprecated Use {@link #secure()}, {@link #secureStrong()},or {@link #insecure()}. */ @Deprecated public static String random(final int count, final int start, final int end, final boolean letters, @@ -371,7 +376,7 @@ public class RandomStringUtils { * @param chars the String containing the set of characters to use, may be null, but must not be empty * @return the random string * @throws IllegalArgumentException if {@code count} < 0 or the string is empty. - * @deprecated Use {@link #secure()} or {@link #insecure()}. + * @deprecated Use {@link #secure()}, {@link #secureStrong()},or {@link #insecure()}. */ @Deprecated public static String random(final int count, final String chars) { @@ -388,7 +393,7 @@ public class RandomStringUtils { * @param count the length of random string to create * @return the random string * @throws IllegalArgumentException if {@code count} < 0. - * @deprecated Use {@link #secure()} or {@link #insecure()}. + * @deprecated Use {@link #secure()}, {@link #secureStrong()},or {@link #insecure()}. */ @Deprecated public static String randomAlphabetic(final int count) { @@ -406,7 +411,7 @@ public class RandomStringUtils { * @param maxLengthExclusive the exclusive maximum length of the string to generate * @return the random string * @since 3.5 - * @deprecated Use {@link #secure()} or {@link #insecure()}. + * @deprecated Use {@link #secure()}, {@link #secureStrong()},or {@link #insecure()}. */ @Deprecated public static String randomAlphabetic(final int minLengthInclusive, final int maxLengthExclusive) { @@ -423,7 +428,7 @@ public class RandomStringUtils { * @param count the length of random string to create * @return the random string * @throws IllegalArgumentException if {@code count} < 0. - * @deprecated Use {@link #secure()} or {@link #insecure()}. + * @deprecated Use {@link #secure()}, {@link #secureStrong()},or {@link #insecure()}. */ @Deprecated public static String randomAlphanumeric(final int count) { @@ -441,7 +446,7 @@ public class RandomStringUtils { * @param maxLengthExclusive the exclusive maximum length of the string to generate * @return the random string * @since 3.5 - * @deprecated Use {@link #secure()} or {@link #insecure()}. + * @deprecated Use {@link #secure()}, {@link #secureStrong()},or {@link #insecure()}. */ @Deprecated public static String randomAlphanumeric(final int minLengthInclusive, final int maxLengthExclusive) { @@ -459,7 +464,7 @@ public class RandomStringUtils { * @param count the length of random string to create * @return the random string * @throws IllegalArgumentException if {@code count} < 0. - * @deprecated Use {@link #secure()} or {@link #insecure()}. + * @deprecated Use {@link #secure()}, {@link #secureStrong()},or {@link #insecure()}. */ @Deprecated public static String randomAscii(final int count) { @@ -478,7 +483,7 @@ public class RandomStringUtils { * @param maxLengthExclusive the exclusive maximum length of the string to generate * @return the random string * @since 3.5 - * @deprecated Use {@link #secure()} or {@link #insecure()}. + * @deprecated Use {@link #secure()}, {@link #secureStrong()},or {@link #insecure()}. */ @Deprecated public static String randomAscii(final int minLengthInclusive, final int maxLengthExclusive) { @@ -497,7 +502,7 @@ public class RandomStringUtils { * @return the random string * @throws IllegalArgumentException if {@code count} < 0. * @since 3.5 - * @deprecated Use {@link #secure()} or {@link #insecure()}. + * @deprecated Use {@link #secure()}, {@link #secureStrong()},or {@link #insecure()}. */ @Deprecated public static String randomGraph(final int count) { @@ -515,7 +520,7 @@ public class RandomStringUtils { * @param maxLengthExclusive the exclusive maximum length of the string to generate * @return the random string * @since 3.5 - * @deprecated Use {@link #secure()} or {@link #insecure()}. + * @deprecated Use {@link #secure()}, {@link #secureStrong()},or {@link #insecure()}. */ @Deprecated public static String randomGraph(final int minLengthInclusive, final int maxLengthExclusive) { @@ -532,7 +537,7 @@ public class RandomStringUtils { * @param count the length of random string to create * @return the random string * @throws IllegalArgumentException if {@code count} < 0. - * @deprecated Use {@link #secure()} or {@link #insecure()}. + * @deprecated Use {@link #secure()}, {@link #secureStrong()},or {@link #insecure()}. */ @Deprecated public static String randomNumeric(final int count) { @@ -550,7 +555,7 @@ public class RandomStringUtils { * @param maxLengthExclusive the exclusive maximum length of the string to generate * @return the random string * @since 3.5 - * @deprecated Use {@link #secure()} or {@link #insecure()}. + * @deprecated Use {@link #secure()}, {@link #secureStrong()},or {@link #insecure()}. */ @Deprecated public static String randomNumeric(final int minLengthInclusive, final int maxLengthExclusive) { @@ -569,7 +574,7 @@ public class RandomStringUtils { * @return the random string * @throws IllegalArgumentException if {@code count} < 0. * @since 3.5 - * @deprecated Use {@link #secure()} or {@link #insecure()}. + * @deprecated Use {@link #secure()}, {@link #secureStrong()},or {@link #insecure()}. */ @Deprecated public static String randomPrint(final int count) { @@ -587,13 +592,28 @@ public class RandomStringUtils { * @param maxLengthExclusive the exclusive maximum length of the string to generate * @return the random string * @since 3.5 - * @deprecated Use {@link #secure()} or {@link #insecure()}. + * @deprecated Use {@link #secure()}, {@link #secureStrong()},or {@link #insecure()}. */ @Deprecated public static String randomPrint(final int minLengthInclusive, final int maxLengthExclusive) { return secure().nextPrint(minLengthInclusive, maxLengthExclusive); } + /** + * Gets the singleton instance based on {@link SecureRandom#SecureRandom()} which uses a secure random number generator (RNG) implementing the default + * random number algorithm. + *

+ * The method {@link SecureRandom#SecureRandom()} is called on-demand. + *

+ * + * @return the singleton instance based on {@link SecureRandom#SecureRandom()}. + * @see SecureRandom#SecureRandom() + * @since 3.16.0 + */ + public static RandomStringUtils secure() { + return SECURE; + } + /** * Gets the singleton instance based on {@link SecureRandom#getInstanceStrong()} which uses an algorithms/providers * specified in the {@code securerandom.strongAlgorithms} {@link Security} property. @@ -603,10 +623,10 @@ public class RandomStringUtils { * * @return the singleton instance based on {@link SecureRandom#getInstanceStrong()}. * @see SecureRandom#getInstanceStrong() - * @since 3.16.0 + * @since 3.17.0 */ - public static RandomStringUtils secure() { - return SECURE; + public static RandomStringUtils secureStrong() { + return SECURE_STRONG; } private final Supplier random; diff --git a/src/main/java/org/apache/commons/lang3/RandomUtils.java b/src/main/java/org/apache/commons/lang3/RandomUtils.java index 5344ae38c..554748362 100644 --- a/src/main/java/org/apache/commons/lang3/RandomUtils.java +++ b/src/main/java/org/apache/commons/lang3/RandomUtils.java @@ -28,27 +28,33 @@ import org.apache.commons.lang3.exception.UncheckedException; /** * Supplements the standard {@link Random} class. *

- * Use {@link #secure()} to get the singleton instance based on {@link SecureRandom#getInstanceStrong()} which uses an - * algorithms/providers specified in the {@code securerandom.strongAlgorithms} {@link Security} property. + * Use {@link #secure()} to get the singleton instance based on {@link SecureRandom#SecureRandom()} which uses a secure random number generator (RNG) + * implementing the default random number algorithm. *

*

- * Use {@link #insecure()} to get the singleton instance based on {@link ThreadLocalRandom#current()}; which is not - * cryptographically secure. + * Use {@link #secureStrong()} to get the singleton instance based on {@link SecureRandom#getInstanceStrong()} which uses an algorithms/providers specified in + * the {@code securerandom.strongAlgorithms} {@link Security} property. *

*

- * Starting in version 3.15.0, this class uses {@link SecureRandom#getInstanceStrong()} for static methods. + * Use {@link #insecure()} to get the singleton instance based on {@link ThreadLocalRandom#current()}; which is not cryptographically secure. + *

+ *

+ * Starting in version 3.17.0, the method {@link #secure()} uses {@link SecureRandom#SecureRandom()} instead of {@link SecureRandom#getInstanceStrong()}, and + * adds {@link #secureStrong()}. *

*

* Starting in version 3.16.0, this class uses {@link #secure()} for static methods and adds {@link #insecure()}. *

*

- * Before version 3.15.0, this class used {@link ThreadLocalRandom#current()} for static methods, which is not - * cryptographically secure. + * Starting in version 3.15.0, this class uses {@link SecureRandom#getInstanceStrong()} for static methods. + *

+ *

+ * Before version 3.15.0, this class used {@link ThreadLocalRandom#current()} for static methods, which is not cryptographically secure. *

*

* Please note that the Apache Commons project provides a component dedicated to pseudo-random number generation, namely - * Commons RNG, that may be a better choice for - * applications with more stringent requirements (performance and/or correctness). + * Commons RNG, that may be a better choice for applications with more stringent requirements + * (performance and/or correctness). *

* * @see RandomStringUtils @@ -58,6 +64,8 @@ public class RandomUtils { private static RandomUtils INSECURE = new RandomUtils(ThreadLocalRandom::current); + private static RandomUtils SECURE = new RandomUtils(SecureRandom::new); + private static final Supplier SECURE_STRONG_SUPPLIER = () -> RandomUtils.SECURE_RANDOM_STRONG.get(); private static RandomUtils SECURE_STRONG = new RandomUtils(SECURE_STRONG_SUPPLIER); @@ -92,7 +100,7 @@ public class RandomUtils { * * @return the random boolean * @since 3.5 - * @deprecated Use {@link #secure()} or {@link #insecure()}. + * @deprecated Use {@link #secure()}, {@link #secureStrong()},or {@link #insecure()}. */ @Deprecated public static boolean nextBoolean() { @@ -105,7 +113,7 @@ public class RandomUtils { * @param count the size of the returned array * @return the random byte array * @throws IllegalArgumentException if {@code count} is negative - * @deprecated Use {@link #secure()} or {@link #insecure()}. + * @deprecated Use {@link #secure()}, {@link #secureStrong()},or {@link #insecure()}. */ @Deprecated public static byte[] nextBytes(final int count) { @@ -118,7 +126,7 @@ public class RandomUtils { * @return the random double * @see #nextDouble(double, double) * @since 3.5 - * @deprecated Use {@link #secure()} or {@link #insecure()}. + * @deprecated Use {@link #secure()}, {@link #secureStrong()},or {@link #insecure()}. */ @Deprecated public static double nextDouble() { @@ -133,7 +141,7 @@ public class RandomUtils { * @throws IllegalArgumentException if {@code startInclusive > endExclusive} or if {@code startInclusive} is * negative * @return the random double - * @deprecated Use {@link #secure()} or {@link #insecure()}. + * @deprecated Use {@link #secure()}, {@link #secureStrong()},or {@link #insecure()}. */ @Deprecated public static double nextDouble(final double startInclusive, final double endExclusive) { @@ -146,7 +154,7 @@ public class RandomUtils { * @return the random float * @see #nextFloat(float, float) * @since 3.5 - * @deprecated Use {@link #secure()} or {@link #insecure()}. + * @deprecated Use {@link #secure()}, {@link #secureStrong()},or {@link #insecure()}. */ @Deprecated public static float nextFloat() { @@ -161,7 +169,7 @@ public class RandomUtils { * @throws IllegalArgumentException if {@code startInclusive > endExclusive} or if {@code startInclusive} is * negative * @return the random float - * @deprecated Use {@link #secure()} or {@link #insecure()}. + * @deprecated Use {@link #secure()}, {@link #secureStrong()},or {@link #insecure()}. */ @Deprecated public static float nextFloat(final float startInclusive, final float endExclusive) { @@ -174,7 +182,7 @@ public class RandomUtils { * @return the random integer * @see #nextInt(int, int) * @since 3.5 - * @deprecated Use {@link #secure()} or {@link #insecure()}. + * @deprecated Use {@link #secure()}, {@link #secureStrong()},or {@link #insecure()}. */ @Deprecated public static int nextInt() { @@ -189,7 +197,7 @@ public class RandomUtils { * @throws IllegalArgumentException if {@code startInclusive > endExclusive} or if {@code startInclusive} is * negative * @return the random integer - * @deprecated Use {@link #secure()} or {@link #insecure()}. + * @deprecated Use {@link #secure()}, {@link #secureStrong()},or {@link #insecure()}. */ @Deprecated public static int nextInt(final int startInclusive, final int endExclusive) { @@ -202,25 +210,13 @@ public class RandomUtils { * @return the random long * @see #nextLong(long, long) * @since 3.5 - * @deprecated Use {@link #secure()} or {@link #insecure()}. + * @deprecated Use {@link #secure()}, {@link #secureStrong()},or {@link #insecure()}. */ @Deprecated public static long nextLong() { return secure().randomLong(); } - /** - * Generates a {@code long} value between 0 (inclusive) and the specified value (exclusive). - * - * @param n Bound on the random number to be returned. Must be positive. - * @return a random {@code long} value between 0 (inclusive) and {@code n} (exclusive). - * @deprecated Use {@link #secure()} or {@link #insecure()}. - */ - @Deprecated - private static long nextLong(final long n) { - return secure().randomLong(n); - } - /** * Generates a random long within the specified range. * @@ -229,13 +225,28 @@ public class RandomUtils { * @throws IllegalArgumentException if {@code startInclusive > endExclusive} or if {@code startInclusive} is * negative * @return the random long - * @deprecated Use {@link #secure()} or {@link #insecure()}. + * @deprecated Use {@link #secure()}, {@link #secureStrong()},or {@link #insecure()}. */ @Deprecated public static long nextLong(final long startInclusive, final long endExclusive) { return secure().randomLong(startInclusive, endExclusive); } + /** + * Gets the singleton instance based on {@link SecureRandom#SecureRandom()} which uses an algorithms/providers + * specified in the {@code securerandom.strongAlgorithms} {@link Security} property. + *

+ * The method {@link SecureRandom#SecureRandom()} is called on-demand. + *

+ * + * @return the singleton instance based on {@link SecureRandom#SecureRandom()}. + * @see SecureRandom#SecureRandom() + * @since 3.16.0 + */ + public static RandomUtils secure() { + return SECURE; + } + /** * Gets the singleton instance based on {@link SecureRandom#getInstanceStrong()} which uses an algorithms/providers * specified in the {@code securerandom.strongAlgorithms} {@link Security} property. @@ -245,9 +256,9 @@ public class RandomUtils { * * @return the singleton instance based on {@link SecureRandom#getInstanceStrong()}. * @see SecureRandom#getInstanceStrong() - * @since 3.16.0 + * @since 3.17.0 */ - public static RandomUtils secure() { + public static RandomUtils secureStrong() { return SECURE_STRONG; }