Skip to content

Commit

Permalink
Updating Javadoc and docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@yakovsh
yakovsh committed Sep 28, 2023
1 parent fab2cf8 commit 22c3d4c
Show file tree
Hide file tree
Showing 5 changed files with 147 additions and 71 deletions.
14 changes: 4 additions & 10 deletions src/main/java/org/apache/commons/codec/digest/Crypt.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,6 @@

import java.nio.charset.StandardCharsets;
import java.security.SecureRandom;
import java.util.concurrent.ThreadLocalRandom;

/**
* GNU libc crypt(3) compatible hash method.
Expand All @@ -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
Expand All @@ -65,9 +63,7 @@ public static String crypt(final byte[] keyBytes) {
* 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
Expand Down Expand Up @@ -96,8 +92,7 @@ public static String crypt(final byte[] keyBytes, final String salt) {
* 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)
Expand Down Expand Up @@ -165,8 +160,7 @@ public static String crypt(final String key) {
* 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
Expand Down
34 changes: 13 additions & 21 deletions src/main/java/org/apache/commons/codec/digest/Md5Crypt.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,6 @@
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;

Expand Down Expand Up @@ -87,8 +86,8 @@ public static String apr1Crypt(final byte[] keyBytes) {
* </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)
Expand All @@ -108,8 +107,7 @@ public static String apr1Crypt(final byte[] keyBytes, final Random random) {
* 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
Expand All @@ -127,8 +125,7 @@ public static String apr1Crypt(final byte[] keyBytes, String salt) {
/**
* 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
Expand All @@ -153,8 +150,7 @@ public static String apr1Crypt(final String keyBytes) {
* 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
Expand All @@ -171,8 +167,7 @@ public static String apr1Crypt(final String keyBytes, final String salt) {
* 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.
Expand All @@ -196,8 +191,8 @@ public static String md5Crypt(final byte[] keyBytes) {
* @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.
Expand All @@ -219,8 +214,7 @@ public static String md5Crypt(final byte[] keyBytes, final Random random) {
* 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
Expand All @@ -242,8 +236,7 @@ public static String md5Crypt(final byte[] keyBytes, final String salt) {
* 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
Expand All @@ -266,13 +259,12 @@ public static String md5Crypt(final byte[] keyBytes, final String salt, final St
* 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
Expand Down
18 changes: 7 additions & 11 deletions src/main/java/org/apache/commons/codec/digest/Sha2Crypt.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,6 @@
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;

Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -126,8 +124,8 @@ public static String sha256Crypt(final byte[] keyBytes, String salt) {
* @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
Expand Down Expand Up @@ -551,8 +549,7 @@ private static String sha2Crypt(final byte[] keyBytes, final String salt, final
* 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
Expand Down Expand Up @@ -601,11 +598,10 @@ public static String sha512Crypt(final byte[] keyBytes, String salt) {
* 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
Expand Down
15 changes: 5 additions & 10 deletions src/main/java/org/apache/commons/codec/digest/UnixCrypt.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,6 @@
import java.nio.charset.StandardCharsets;
import java.security.SecureRandom;
import java.util.Arrays;
import java.util.concurrent.ThreadLocalRandom;

/**
* Unix crypt(3) algorithm implementation.
Expand Down Expand Up @@ -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
Expand All @@ -198,15 +196,14 @@ public static String crypt(final byte[] original) {
* 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)];
Expand Down Expand Up @@ -261,8 +258,7 @@ public static String crypt(final byte[] original, String salt) {
/**
* 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
Expand All @@ -280,8 +276,7 @@ public static String crypt(final String original) {
* 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
Expand Down

0 comments on commit 22c3d4c

Please sign in to comment.