You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@commons.apache.org by gg...@apache.org on 2023/09/28 21:54:05 UTC
[commons-codec] branch master updated: Updating Javadoc and docs (#208)
This is an automated email from the ASF dual-hosted git repository.
ggregory pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/commons-codec.git
The following commit(s) were added to refs/heads/master by this push:
new 14c2f60a Updating Javadoc and docs (#208)
14c2f60a is described below
commit 14c2f60a605045f4f3f6ca74a97da34c3aac2536
Author: Yakov Shafranovich <ya...@users.noreply.github.com>
AuthorDate: Thu Sep 28 17:53:59 2023 -0400
Updating Javadoc and docs (#208)
Co-authored-by: Yakov Shafranovich <ya...@amazon.com>
---
.../org/apache/commons/codec/digest/Crypt.java | 14 +--
.../org/apache/commons/codec/digest/Md5Crypt.java | 34 ++---
.../org/apache/commons/codec/digest/Sha2Crypt.java | 18 ++-
.../org/apache/commons/codec/digest/UnixCrypt.java | 15 +--
src/site/xdoc/userguide.xml | 137 ++++++++++++++++++---
5 files changed, 147 insertions(+), 71 deletions(-)
diff --git a/src/main/java/org/apache/commons/codec/digest/Crypt.java b/src/main/java/org/apache/commons/codec/digest/Crypt.java
index 529c13b8..04336bbc 100644
--- a/src/main/java/org/apache/commons/codec/digest/Crypt.java
+++ b/src/main/java/org/apache/commons/codec/digest/Crypt.java
@@ -18,7 +18,6 @@ package org.apache.commons.codec.digest;
import java.nio.charset.StandardCharsets;
import java.security.SecureRandom;
-import java.util.concurrent.ThreadLocalRandom;
/**
* GNU libc crypt(3) compatible hash method.
@@ -40,8 +39,7 @@ public class Crypt {
* details.
* </p>
* <p>
- * A salt is generated for you using {@link ThreadLocalRandom}; for more secure salts consider using
- * {@link SecureRandom} to generate your own salts and calling {@link #crypt(byte[], String)}.
+ * A salt is generated for you using {@link SecureRandom}.
* </p>
*
* @param keyBytes
@@ -65,9 +63,7 @@ public class Crypt {
* plaintext password
* @param salt
* real salt value without prefix or "rounds=". The salt may be null,
- * in which case a salt is generated for you using {@link ThreadLocalRandom};
- * for more secure salts consider using {@link SecureRandom} to
- * generate your own salts.
+ * in which case a salt is generated for you using {@link SecureRandom}.
* @return hash value
* @throws IllegalArgumentException
* if the salt does not match the allowed pattern
@@ -96,8 +92,7 @@ public class Crypt {
* A random salt and the default algorithm (currently SHA-512) are used.
* </p>
* <p>
- * A salt is generated for you using {@link ThreadLocalRandom}; for more secure salts consider using
- * {@link SecureRandom} to generate your own salts and calling {@link #crypt(String, String)}.
+ * A salt is generated for you using {@link SecureRandom}.
* </p>
*
* @see #crypt(String, String)
@@ -165,8 +160,7 @@ public class Crypt {
* plaintext password as entered by the used
* @param salt
* real salt value without prefix or "rounds=". The salt may be null, in which case a
- * salt is generated for you using {@link ThreadLocalRandom}; for more secure salts
- * consider using {@link SecureRandom} to generate your own salts.
+ * salt is generated for you using {@link SecureRandom}
* @return hash value, i.e. encrypted password including the salt string
* @throws IllegalArgumentException
* if the salt does not match the allowed pattern
diff --git a/src/main/java/org/apache/commons/codec/digest/Md5Crypt.java b/src/main/java/org/apache/commons/codec/digest/Md5Crypt.java
index 331e8220..af4b6a7a 100644
--- a/src/main/java/org/apache/commons/codec/digest/Md5Crypt.java
+++ b/src/main/java/org/apache/commons/codec/digest/Md5Crypt.java
@@ -21,7 +21,6 @@ import java.security.MessageDigest;
import java.security.SecureRandom;
import java.util.Arrays;
import java.util.Random;
-import java.util.concurrent.ThreadLocalRandom;
import java.util.regex.Matcher;
import java.util.regex.Pattern;
@@ -87,8 +86,8 @@ public class Md5Crypt {
* </p>
*
* @param keyBytes plaintext string to hash. Each array element is set to {@code 0} before returning.
- * @param random the instance of {@link Random} to use for generating the salt. Consider using {@link SecureRandom}
- * or {@link ThreadLocalRandom}.
+ * @param random the instance of {@link Random} to use for generating the salt.
+ * Consider using {@link SecureRandom} for more secure salts.
* @return the hash value
* @throws IllegalArgumentException when a {@link java.security.NoSuchAlgorithmException} is caught. *
* @see #apr1Crypt(byte[], String)
@@ -108,8 +107,7 @@ public class Md5Crypt {
* plaintext string to hash. Each array element is set to {@code 0} before returning.
* @param salt
* An APR1 salt. The salt may be null, in which case a salt is generated for you using
- * {@link ThreadLocalRandom}; for more secure salts consider using {@link SecureRandom} to generate your
- * own salts.
+ * {@link SecureRandom}
* @return the hash value
* @throws IllegalArgumentException
* if the salt does not match the allowed pattern
@@ -127,8 +125,7 @@ public class Md5Crypt {
/**
* See {@link #apr1Crypt(String, String)} for details.
* <p>
- * A salt is generated for you using {@link ThreadLocalRandom}; for more secure salts consider using
- * {@link SecureRandom} to generate your own salts and calling {@link #apr1Crypt(byte[], String)}.
+ * A salt is generated for you using {@link SecureRandom}.
* </p>
*
* @param keyBytes
@@ -153,8 +150,7 @@ public class Md5Crypt {
* plaintext string to hash. Each array element is set to {@code 0} before returning.
* @param salt
* salt string including the prefix and optionally garbage at the end. The salt may be null, in which
- * case a salt is generated for you using {@link ThreadLocalRandom}; for more secure salts consider using
- * {@link SecureRandom} to generate your own salts.
+ * case a salt is generated for you using {@link SecureRandom}.
* @return the hash value
* @throws IllegalArgumentException
* if the salt does not match the allowed pattern
@@ -171,8 +167,7 @@ public class Md5Crypt {
* See {@link #md5Crypt(byte[], String)} for details.
* </p>
* <p>
- * A salt is generated for you using {@link ThreadLocalRandom}; for more secure salts consider using
- * {@link SecureRandom} to generate your own salts and calling {@link #md5Crypt(byte[], String)}.
+ * A salt is generated for you using {@link SecureRandom}.
* </p>
* @param keyBytes
* plaintext string to hash. Each array element is set to {@code 0} before returning.
@@ -196,8 +191,8 @@ public class Md5Crypt {
* @param keyBytes
* plaintext string to hash. Each array element is set to {@code 0} before returning.
* @param random
- * the instance of {@link Random} to use for generating the salt. Consider using {@link SecureRandom}
- * or {@link ThreadLocalRandom}.
+ * the instance of {@link Random} to use for generating the salt.
+ * Consider using {@link SecureRandom} for more secure salts.
* @return the hash value
* @throws IllegalArgumentException
* when a {@link java.security.NoSuchAlgorithmException} is caught.
@@ -219,8 +214,7 @@ public class Md5Crypt {
* plaintext string to hash. Each array element is set to {@code 0} before returning.
* @param salt
* salt string including the prefix and optionally garbage at the end. The salt may be null, in which
- * case a salt is generated for you using {@link ThreadLocalRandom}; for more secure salts consider using
- * {@link SecureRandom} to generate your own salts.
+ * case a salt is generated for you using {@link SecureRandom}.
* @return the hash value
* @throws IllegalArgumentException
* if the salt does not match the allowed pattern
@@ -242,8 +236,7 @@ public class Md5Crypt {
* plaintext string to hash. Each array element is set to {@code 0} before returning.
* @param salt
* real salt value without prefix or "rounds=". The salt may be null, in which case a salt
- * is generated for you using {@link ThreadLocalRandom}; for more secure salts consider
- * using {@link SecureRandom} to generate your own salts.
+ * is generated for you using {@link SecureRandom}.
* @param prefix
* salt prefix
* @return the hash value
@@ -266,13 +259,12 @@ public class Md5Crypt {
* plaintext string to hash. Each array element is set to {@code 0} before returning.
* @param salt
* real salt value without prefix or "rounds=". The salt may be null, in which case a salt
- * is generated for you using {@link ThreadLocalRandom}; for more secure salts consider
- * using {@link SecureRandom} to generate your own salts.
+ * is generated for you using {@link SecureRandom}.
* @param prefix
* salt prefix
* @param random
- * the instance of {@link Random} to use for generating the salt. Consider using {@link SecureRandom}
- * or {@link ThreadLocalRandom}.
+ * the instance of {@link Random} to use for generating the salt.
+ * Consider using {@link SecureRandom} for more secure salts.
* @return the hash value
* @throws IllegalArgumentException
* if the salt does not match the allowed pattern
diff --git a/src/main/java/org/apache/commons/codec/digest/Sha2Crypt.java b/src/main/java/org/apache/commons/codec/digest/Sha2Crypt.java
index 03d6ac66..a816ccfb 100644
--- a/src/main/java/org/apache/commons/codec/digest/Sha2Crypt.java
+++ b/src/main/java/org/apache/commons/codec/digest/Sha2Crypt.java
@@ -22,7 +22,6 @@ import java.security.NoSuchAlgorithmException;
import java.security.SecureRandom;
import java.util.Arrays;
import java.util.Random;
-import java.util.concurrent.ThreadLocalRandom;
import java.util.regex.Matcher;
import java.util.regex.Pattern;
@@ -78,8 +77,7 @@ public class Sha2Crypt {
* See {@link Crypt#crypt(String, String)} for details.
* </p>
* <p>
- * A salt is generated for you using {@link ThreadLocalRandom}; for more secure salts consider using
- * {@link SecureRandom} to generate your own salts and calling {@link #sha256Crypt(byte[], String)}.
+ * A salt is generated for you using {@link SecureRandom}.
* </p>
*
* @param keyBytes
@@ -126,8 +124,8 @@ public class Sha2Crypt {
* @param salt
* real salt value without prefix or "rounds=".
* @param random
- * the instance of {@link Random} to use for generating the salt. Consider using {@link SecureRandom}
- * or {@link ThreadLocalRandom}.
+ * the instance of {@link Random} to use for generating the salt.
+ * Consider using {@link SecureRandom} for more secure salts.
* @return complete hash value including salt
* @throws IllegalArgumentException
* if the salt does not match the allowed pattern
@@ -551,8 +549,7 @@ public class Sha2Crypt {
* See {@link Crypt#crypt(String, String)} for details.
* </p>
* <p>
- * A salt is generated for you using {@link ThreadLocalRandom}; for more secure salts consider using
- * {@link SecureRandom} to generate your own salts and calling {@link #sha512Crypt(byte[], String)}.
+ * A salt is generated for you using {@link SecureRandom}
* </p>
*
* @param keyBytes
@@ -601,11 +598,10 @@ public class Sha2Crypt {
* plaintext to hash. Each array element is set to {@code 0} before returning.
* @param salt
* real salt value without prefix or "rounds=". The salt may be null, in which case a salt
- * is generated for you using {@link ThreadLocalRandom}; for more secure salts consider using
- * {@link SecureRandom} to generate your own salts.
+ * is generated for you using {@link SecureRandom}.
* @param random
- * the instance of {@link Random} to use for generating the salt. Consider using {@link SecureRandom}
- * or {@link ThreadLocalRandom}.
+ * the instance of {@link Random} to use for generating the salt.
+ * Consider using {@link SecureRandom} for more secure salts.
* @return complete hash value including salt
* @throws IllegalArgumentException
* if the salt does not match the allowed pattern
diff --git a/src/main/java/org/apache/commons/codec/digest/UnixCrypt.java b/src/main/java/org/apache/commons/codec/digest/UnixCrypt.java
index a7bad57b..cb814246 100644
--- a/src/main/java/org/apache/commons/codec/digest/UnixCrypt.java
+++ b/src/main/java/org/apache/commons/codec/digest/UnixCrypt.java
@@ -19,7 +19,6 @@ package org.apache.commons.codec.digest;
import java.nio.charset.StandardCharsets;
import java.security.SecureRandom;
import java.util.Arrays;
-import java.util.concurrent.ThreadLocalRandom;
/**
* Unix crypt(3) algorithm implementation.
@@ -176,8 +175,7 @@ public class UnixCrypt {
/**
* Generates a crypt(3) compatible hash using the DES algorithm.
* <p>
- * A salt is generated for you using {@link ThreadLocalRandom}; for more secure salts consider using
- * {@link SecureRandom} to generate your own salts and calling {@link #crypt(byte[], String)}.
+ * A salt is generated for you using {@link SecureRandom}.
* </p>
*
* @param original
@@ -198,15 +196,14 @@ public class UnixCrypt {
* plaintext password
* @param salt
* a two character string drawn from [a-zA-Z0-9./]. The salt may be null, in which case a salt is
- * generated for you using {@link ThreadLocalRandom}; for more secure salts consider using
- * {@link SecureRandom} to generate your own salts.
+ * generated for you using {@link SecureRandom}.
* @return a 13 character string starting with the salt string
* @throws IllegalArgumentException
* if the salt does not match the allowed pattern
*/
public static String crypt(final byte[] original, String salt) {
if (salt == null) {
- final ThreadLocalRandom randomGenerator = ThreadLocalRandom.current();
+ final SecureRandom randomGenerator = new SecureRandom();
final int numSaltChars = SALT_CHARS.length;
salt = "" + SALT_CHARS[randomGenerator.nextInt(numSaltChars)] +
SALT_CHARS[randomGenerator.nextInt(numSaltChars)];
@@ -261,8 +258,7 @@ public class UnixCrypt {
/**
* Generates a crypt(3) compatible hash using the DES algorithm.
* <p>
- * A salt is generated for you using {@link ThreadLocalRandom}; for more secure salts consider using
- * {@link SecureRandom} to generate your own salts and calling {@link #crypt(String, String)}.
+ * A salt is generated for you using {@link SecureRandom}.
* </p>
*
* @param original
@@ -280,8 +276,7 @@ public class UnixCrypt {
* plaintext password
* @param salt
* a two character string drawn from [a-zA-Z0-9./]. The salt may be null, in which case a salt is
- * generated for you using {@link ThreadLocalRandom}; for more secure salts consider using
- * {@link SecureRandom} to generate your own salts.
+ * generated for you using {@link SecureRandom}.
* @return a 13 character string starting with the salt string
* @throws IllegalArgumentException
* if the salt does not match the allowed pattern
diff --git a/src/site/xdoc/userguide.xml b/src/site/xdoc/userguide.xml
index a02dbbbf..6ff2f6dd 100644
--- a/src/site/xdoc/userguide.xml
+++ b/src/site/xdoc/userguide.xml
@@ -32,7 +32,7 @@
</td>
<td>
Provides Base32 encoding and decoding as defined by
- <a href="http://www.ietf.org/rfc/rfc4648.txt">RFC 4648</a>
+ <a href="https://www.ietf.org/rfc/rfc4648.txt">RFC 4648</a>
</td>
</tr>
<tr>
@@ -52,7 +52,7 @@
</td>
<td>
Provides Base64 encoding and decoding as defined by
- <a href="http://www.ietf.org/rfc/rfc2045.txt">RFC 2045</a>
+ <a href="https://www.ietf.org/rfc/rfc2045.txt">RFC 2045</a>
</td>
</tr>
<tr>
@@ -86,20 +86,11 @@
</table>
</subsection>
<subsection name="Digest Encoders">
+ <p>
+ <strong>WARNING:</strong> Some of the functions in this package might not be suitable for cryptography,
+ or are no longer cryptographically-secure.
+ </p>
<table>
- <tr>
- <td width="150">
- <a
- href="apidocs/org/apache/commons/codec/digest/DigestUtils.html">DigestUtils
- </a>
- </td>
- <td>
- Simplifies common
- <a
- href="http://download.oracle.com/javase/6/docs/api/java/security/MessageDigest.html">MessageDigest</a>
- tasks and provides GNU libc crypt(3) compatible password hashing functions.
- </td>
- </tr>
<tr>
<td width="150">
<a href="apidocs/org/apache/commons/codec/digest/Blake3.html">Blake3</a>
@@ -115,11 +106,110 @@
<a href="https://en.wikipedia.org/wiki/Key_derivation_function">key derivation function</a>, and can be
used as the basis for a
<a href="https://en.wikipedia.org/wiki/Cryptographically-secure_pseudorandom_number_generator">
- cryptographically-secure pseudorandom number generator</a>. <strong>WARNING:</strong> Blake3 is
+ cryptographically-secure pseudorandom number generator</a>.
+ <br/>
+ <strong>WARNING:</strong> Blake3 is
<em>not</em> a password hashing algorithm! An algorithm such as
<a href="https://github.com/P-H-C/phc-winner-argon2">Argon2</a> is more appropriate for password hashing.
</td>
</tr>
+ <tr>
+ <td width="150">
+ <a href="apidocs/org/apache/commons/codec/digest/Crypt.html">Crypt</a>
+ </td>
+ <td>
+ GNU libc crypt(3) compatible hash method.
+ </td>
+ </tr>
+ <tr>
+ <td width="150">
+ <a href="apidocs/org/apache/commons/codec/digest/DigestUtils.html">DigestUtils</a>
+ </td>
+ <td>
+ Simplifies common
+ <a
+ href="https://docs.oracle.com/javase/6/docs/api/java/security/MessageDigest.html">MessageDigest</a>
+ tasks and provides GNU libc crypt(3) compatible password hashing functions.
+ </td>
+ </tr>
+ <tr>
+ <td width="150">
+ <a href="apidocs/org/apache/commons/codec/digest/HmacUtils.html">HmacUtils</a>
+ </td>
+ <td>
+ Simplifies common <a href="https://docs.oracle.com/javase/6/docs/api/javax/crypto/Mac.html">Mac</a> tasks.
+ <br/>
+ <strong>Note:</strong> Not all JCE implementations support all algorithms.
+ If not supported, an IllegalArgumentException is thrown.
+ </td>
+ </tr>
+ <tr>
+ <td width="150">
+ <a href="apidocs/org/apache/commons/codec/digest/Md5Crypt.html">Md5Crypt</a>
+ </td>
+ <td>
+ The libc crypt() "$1$" and Apache "$apr1$" MD5-based hash algorithm.
+ </td>
+ </tr>
+ <tr>
+ <td width="150">
+ <a href="apidocs/org/apache/commons/codec/digest/MurmurHash2.html">MurmurHash2</a>
+ </td>
+ <td>
+ Implementation of the MurmurHash2 32-bit and 64-bit hash functions.
+ </td>
+ </tr>
+ <tr>
+ <td width="150">
+ <a href="apidocs/org/apache/commons/codec/digest/MurmurHash3.html">MurmurHash3</a>
+ </td>
+ <td>
+ Implementation of the MurmurHash3 32-bit and 128-bit hash functions.
+ </td>
+ </tr>
+ <tr>
+ <td width="150">
+ <a href="apidocs/org/apache/commons/codec/digest/PureJavaCrc32.html">PureJavaCrc32</a>
+ </td>
+ <td>
+ A pure-java implementation of the CRC32 checksum that uses the same polynomial
+ as the built-in native CRC32.
+ </td>
+ </tr>
+ <tr>
+ <td width="150">
+ <a href="apidocs/org/apache/commons/codec/digest/PureJavaCrc32C.html">PureJavaCrc32C</a>
+ </td>
+ <td>
+ A pure-java implementation of the CRC32 checksum that uses the CRC32-C polynomial,
+ the same polynomial used by iSCSI and implemented on many Intel chipsets supporting SSE 4.2.
+ </td>
+ </tr>
+ <tr>
+ <td width="150">
+ <a href="apidocs/org/apache/commons/codec/digest/Sha2Crypt.html">Sha2Crypt</a>
+ </td>
+ <td>
+ SHA2-based Unix crypt implementation.
+ </td>
+ </tr>
+ <tr>
+ <td width="150">
+ <a href="apidocs/org/apache/commons/codec/digest/UnixCrypt.html">UnixCrypt</a>
+ </td>
+ <td>
+ Unix crypt(3) algorithm implementation.
+ This class only implements the traditional 56 bit DES based algorithm.
+ </td>
+ </tr>
+ <tr>
+ <td width="150">
+ <a href="apidocs/org/apache/commons/codec/digest/XXHash32.html">XXHash32</a>
+ </td>
+ <td>
+ Implementation of the xxHash32 hash algorithm.
+ </td>
+ </tr>
</table>
</subsection>
<subsection name="Language Encoders">
@@ -198,10 +288,19 @@
</td>
<td>
Identical to the Base64 encoding defined by
- <a href="http://www.ietf.org/rfc/rfc1521.txt">RFC 1521</a>
+ <a href="https://www.ietf.org/rfc/rfc1521.txt">RFC 1521</a>
and allows a character set to be specified.
</td>
</tr>
+ <tr>
+ <td width="150">
+ <a href="apidocs/org/apache/commons/codec/net/PercentCodec.html"> PercentCodec
+ </a>
+ </td>
+ <td>
+ Implements the Percent-Encoding scheme, as described in HTTP 1.1 specification.
+ </td>
+ </tr>
<tr>
<td width="150">
<a href="apidocs/org/apache/commons/codec/net/QCodec.html"> QCodec
@@ -210,7 +309,7 @@
<td>
Similar to the Quoted-Printable content-transfer-encoding
defined in
- <a href="http://www.ietf.org/rfc/rfc1521.txt">RFC 1521</a>
+ <a href="https://www.ietf.org/rfc/rfc1521.txt">RFC 1521</a>
and designed to allow text containing mostly ASCII
characters to be decipherable on an ASCII terminal without
decoding.
@@ -224,7 +323,7 @@
</td>
<td>
Codec for the Quoted-Printable section of
- <a href="http://www.ietf.org/rfc/rfc1521.txt">RFC 1521</a>
+ <a href="https://www.ietf.org/rfc/rfc1521.txt">RFC 1521</a>
.
</td>
</tr>