Author: tn
Date: Fri Aug 17 18:44:06 2012
New Revision: 1374394
URL: http://svn.apache.org/viewvc?rev=1374394&view=rev
Log:
Javadoc cleanup of new crypt classes.
Modified:
commons/proper/codec/trunk/src/main/java/org/apache/commons/codec/digest/Crypt.java
commons/proper/codec/trunk/src/main/java/org/apache/commons/codec/digest/Md5Crypt.java
commons/proper/codec/trunk/src/main/java/org/apache/commons/codec/digest/Sha2Crypt.java
commons/proper/codec/trunk/src/main/java/org/apache/commons/codec/digest/UnixCrypt.java
Modified:
commons/proper/codec/trunk/src/main/java/org/apache/commons/codec/digest/Crypt.java
URL:
http://svn.apache.org/viewvc/commons/proper/codec/trunk/src/main/java/org/apache/commons/codec/digest/Crypt.java?rev=1374394&r1=1374393&r2=1374394&view=diff
==============================================================================
---
commons/proper/codec/trunk/src/main/java/org/apache/commons/codec/digest/Crypt.java
(original)
+++
commons/proper/codec/trunk/src/main/java/org/apache/commons/codec/digest/Crypt.java
Fri Aug 17 18:44:06 2012
@@ -20,7 +20,7 @@ import org.apache.commons.codec.Charsets
/**
* GNU libc crypt(3) compatible hash method.
- *
+ * <p>
* See {@link #crypt(String, String)} for further details.
*
* <p>This class is immutable and thread-safe.</p>
@@ -32,13 +32,13 @@ public class Crypt {
/**
* Encrypts a password in a crypt(3) compatible way.
- *
+ * <p>
* A random salt and the default algorithm (currently SHA-512) are used.
See
* {@link #crypt(String, String)} for details.
*
* @param keyBytes
- * The plaintext password.
- * @return The hash value.
+ * plaintext password
+ * @return hash value
*/
public static String crypt(byte[] keyBytes) throws Exception {
return crypt(keyBytes, null);
@@ -46,15 +46,15 @@ public class Crypt {
/**
* Encrypts a password in a crypt(3) compatible way.
- *
+ * <p>
* A random salt and the default algorithm (currently SHA-512) are used.
See
* {@link #crypt(String, String)} for details.
*
* @param keyBytes
- * The plaintext password.
+ * plaintext password
* @param salt
- * The salt value
- * @return The hash value.
+ * salt value
+ * @return hash value
*/
public static String crypt(byte[] keyBytes, String salt) throws Exception {
if (salt == null) {
@@ -72,13 +72,13 @@ public class Crypt {
/**
* Calculates the digest using the strongest crypt(3) algorithm.
- *
+ * <p>
* A random salt and the default algorithm (currently SHA-512) are used.
*
* @see #crypt(String, String)
* @param key
- * The plaintext password.
- * @return The hash value.
+ * plaintext password
+ * @return hash value
*/
public static String crypt(String key) throws Exception {
return crypt(key, null);
@@ -96,18 +96,22 @@ public class Crypt {
* <li>DES, the traditional UnixCrypt algorithm is used else with only 2
chars
* <li>Only the first 8 chars of the passwords are used in the DES
algorithm!
* </ul>
- * The magic strings "$apr1$" and "$2a$" are not recognised by this method
as its output should be identical with
- * that of the libc implementation.
+ * The magic strings "$apr1$" and "$2a$" are not recognised by this method
as its
+ * output should be identical with that of the libc implementation.
*
* <p>
- * The rest of the salt string is drawn from the set [a-zA-Z0-9./] and is
cut at the maximum length of if a "$" sign
- * is encountered. It is therefore valid to enter a complete hash value as
salt to e.g. verify a password with:
- * storedPwd.equals(crypt(enteredPwd, storedPwd))
+ * The rest of the salt string is drawn from the set [a-zA-Z0-9./] and is
cut at the
+ * maximum length of if a "$" sign is encountered. It is therefore valid
to enter a
+ * complete hash value as salt to e.g. verify a password with:
+ *
+ * <pre>
+ * storedPwd.equals(crypt(enteredPwd, storedPwd))
+ * </pre>
*
* <p>
- * The resulting string starts with the marker string ($6$), continues
with the salt value and ends with a "$" sign
- * followed by the actual hash value. For DES the string only contains the
salt and actual hash. It's toal length is
- * dependend on the algorithm used:
+ * The resulting string starts with the marker string ($6$), continues
with the salt
+ * value and ends with a "$" sign followed by the actual hash value. For
DES the string
+ * only contains the salt and actual hash. It's total length is dependent
on the algorithm used:
* <ul>
* <li>SHA-512: 106 chars
* <li>SHA-256: 63 chars
@@ -123,15 +127,16 @@ public class Crypt {
* crypt("secret", "xx") => "xxWAum7tHdIUw"
* </pre>
*
- * This method comes in a variation that accepts a byte[] array to support
input strings that are not encoded in
- * UTF-8 but e.g. in ISO-8859-1 where equal characters result in different
byte values.
+ * <p>
+ * This method comes in a variation that accepts a byte[] array to support
input strings that
+ * are not encoded in UTF-8 but e.g. in ISO-8859-1 where equal characters
result in different byte values.
*
* @see "The man page of the libc crypt (3) function."
* @param key
- * The plaintext password as entered by the used.
+ * plaintext password as entered by the used
* @param salt
- * The salt value
- * @return The hash value i.e. encrypted password including the salt string
+ * salt value
+ * @return hash value, i.e. encrypted password including the salt string
*/
public static String crypt(String key, String salt) throws Exception {
return crypt(key.getBytes(Charsets.UTF_8), salt);
Modified:
commons/proper/codec/trunk/src/main/java/org/apache/commons/codec/digest/Md5Crypt.java
URL:
http://svn.apache.org/viewvc/commons/proper/codec/trunk/src/main/java/org/apache/commons/codec/digest/Md5Crypt.java?rev=1374394&r1=1374393&r2=1374394&view=diff
==============================================================================
---
commons/proper/codec/trunk/src/main/java/org/apache/commons/codec/digest/Md5Crypt.java
(original)
+++
commons/proper/codec/trunk/src/main/java/org/apache/commons/codec/digest/Md5Crypt.java
Fri Aug 17 18:44:06 2012
@@ -29,15 +29,12 @@ import org.apache.commons.codec.Charsets
* Based on the public domain ("beer-ware") C implementation from Poul-Henning
Kamp which was found at:
* </p>
* <p>
- *
http://www.freebsd.org/cgi/cvsweb.cgi/src/lib/libcrypt/crypt-md5.c?rev=1.1;content-type=text%2Fplain</br>
+ *
http://www.freebsd.org/cgi/cvsweb.cgi/src/lib/libcrypt/crypt-md5.c?rev=1.1;content-type=text%2Fplain<br/>
* Source: $FreeBSD: src/lib/libcrypt/crypt-md5.c,v 1.1 1999/01/21 13:50:09
brandon Exp $
* </p>
- * <p>
- * Conversion to Kotlin and from there to Java in 2012.
- * </p>
- * <p>
- * The C style comments are from the original C code, the ones with "//" from
the port.
- * </p>
+ * <p>Conversion to Kotlin and from there to Java in 2012.</p>
+ *
+ * <p>The C style comments are from the original C code, the ones with "//"
from the port.</p>
*
* <p>This class is immutable and thread-safe.</p>
*
@@ -91,16 +88,17 @@ public class Md5Crypt {
}
/**
- * Generates an Apache htpasswd compatible "$apr1$" MD5 based hash value. *
- *
- * The algorithm is identical to the crypt(3) "$1$" one but produces
different outputs due to the different salt
- * prefix.
+ * Generates an Apache htpasswd compatible "$apr1$" MD5 based hash value.
+ * <p>
+ * The algorithm is identical to the crypt(3) "$1$" one but produces
different
+ * outputs due to the different salt prefix.
*
* @param keyBytes
- * The plaintext string that should be hashed.
+ * plaintext string that should be hashed.
* @param salt
- * Salt string including the prefix and optionally garbage at
the end. Will be generated randomly if
- * null.
+ * salt string including the prefix and optionally garbage at
the end.
+ * Will be generated randomly if null.
+ * @return computed hash value
*/
public static String apr1Crypt(String keyBytes, String salt) throws
Exception {
return apr1Crypt(keyBytes.getBytes(Charsets.UTF_8), salt);
@@ -108,7 +106,7 @@ public class Md5Crypt {
/**
* Generates a libc6 crypt() compatible "$1$" hash value.
- *
+ * <p>
* See {@link Crypt#crypt(String, String)} for details.
*/
public static String md5Crypt(final byte[] keyBytes) throws Exception {
@@ -117,14 +115,15 @@ public class Md5Crypt {
/**
* Generates a libc crypt() compatible "$1$" MD5 based hash value.
- *
+ * <p>
* See {@link Crypt#crypt(String, String)} for details.
*
* @param keyBytes
- * The plaintext string that should be hashed.
+ * plaintext string that should be hashed.
* @param salt
- * Salt string including the prefix and optionally garbage at
the end. Will be generated randomly if
- * null.
+ * salt string including the prefix and optionally garbage at
the end.
+ * Will be generated randomly if null.
+ * @return computed hash value
*/
public static String md5Crypt(byte[] keyBytes, String salt) throws
Exception {
return md5Crypt(keyBytes, salt, MD5_PREFIX);
@@ -132,7 +131,7 @@ public class Md5Crypt {
/**
* Generates a libc6 crypt() "$1$" or Apache htpasswd "$apr1$" hash value.
- *
+ * <p>
* See {@link Crypt#crypt(String, String)} or {@link #apr1Crypt(String,
String)} for details.
*/
public static String md5Crypt(final byte[] keyBytes, final String salt,
final String prefix) throws Exception {
Modified:
commons/proper/codec/trunk/src/main/java/org/apache/commons/codec/digest/Sha2Crypt.java
URL:
http://svn.apache.org/viewvc/commons/proper/codec/trunk/src/main/java/org/apache/commons/codec/digest/Sha2Crypt.java?rev=1374394&r1=1374393&r2=1374394&view=diff
==============================================================================
---
commons/proper/codec/trunk/src/main/java/org/apache/commons/codec/digest/Sha2Crypt.java
(original)
+++
commons/proper/codec/trunk/src/main/java/org/apache/commons/codec/digest/Sha2Crypt.java
Fri Aug 17 18:44:06 2012
@@ -84,7 +84,7 @@ public class Sha2Crypt {
/**
* Generates a libc crypt() compatible "$5$" hash value with random salt.
- *
+ * <p>
* See {@link Crypt#crypt(String, String)} for details.
*/
public static String sha256Crypt(byte[] keyBytes) throws Exception {
@@ -93,7 +93,7 @@ public class Sha2Crypt {
/**
* Generates a libc6 crypt() compatible "$5$" hash value.
- *
+ * <p>
* See {@link Crypt#crypt(String, String)} for details.
*/
public static String sha256Crypt(byte[] keyBytes, String salt) throws
Exception {
@@ -105,23 +105,24 @@ public class Sha2Crypt {
/**
* Generates a libc6 crypt() compatible "$5$" or "$6$" SHA2 based hash
value.
- *
- * This is a nearly line by line conversion of the original C function.
The numbered comments are from the algorithm
- * description, the short C-style ones from the original C code and the
ones with "Remark" from me.
- *
+ * <p>
+ * This is a nearly line by line conversion of the original C function.
The numbered comments
+ * are from the algorithm description, the short C-style ones from the
original C code and the
+ * ones with "Remark" from me.
+ * <p>
* See {@link Crypt#crypt(String, String)} for details.
*
* @param keyBytes
- * The plaintext that should be hashed.
+ * plaintext that should be hashed
* @param salt_string
- * The real salt value without prefix or "rounds=".
+ * real salt value without prefix or "rounds="
* @param saltPrefix
- * Either $5$ or $6$.
+ * either $5$ or $6$
* @param blocksize
- * A value that differs between $5$ and $6$.
+ * a value that differs between $5$ and $6$
* @param algorithm
- * The MessageDigest algorithm identifier string.
- * @return The complete hash value including prefix and salt.
+ * {@link MessageDigest} algorithm identifier string
+ * @return complete hash value including prefix and salt
*/
private static String sha2Crypt(byte[] keyBytes, String salt, String
saltPrefix, int blocksize, String algorithm)
throws Exception {
@@ -494,7 +495,7 @@ public class Sha2Crypt {
/**
* Generates a libc crypt() compatible "$6$" hash value with random salt.
- *
+ * <p>
* See {@link Crypt#crypt(String, String)} for details.
*/
public static String sha512Crypt(byte[] keyBytes) throws Exception {
@@ -503,7 +504,7 @@ public class Sha2Crypt {
/**
* Generates a libc6 crypt() compatible "$6$" hash value.
- *
+ * <p>
* See {@link Crypt#crypt(String, String)} for details.
*/
public static String sha512Crypt(byte[] keyBytes, String salt) throws
Exception {
Modified:
commons/proper/codec/trunk/src/main/java/org/apache/commons/codec/digest/UnixCrypt.java
URL:
http://svn.apache.org/viewvc/commons/proper/codec/trunk/src/main/java/org/apache/commons/codec/digest/UnixCrypt.java?rev=1374394&r1=1374393&r2=1374394&view=diff
==============================================================================
---
commons/proper/codec/trunk/src/main/java/org/apache/commons/codec/digest/UnixCrypt.java
(original)
+++
commons/proper/codec/trunk/src/main/java/org/apache/commons/codec/digest/UnixCrypt.java
Fri Aug 17 18:44:06 2012
@@ -23,15 +23,15 @@ import org.apache.commons.codec.Charsets
/**
* Unix crypt(3) algorithm implementation.
*
- * This class only implements the traditional 56 bit DES based algorithm.
Please
+ * <p>This class only implements the traditional 56 bit DES based algorithm.
Please
* use DigestUtils.crypt() for a method that distinguishes between all the
- * algorithms supported in the current glibc's crypt().
+ * algorithms supported in the current glibc's crypt().</p>
*
- * The Java implementation was taken from the JetSpeed Portal project (see
- * org.apache.jetspeed.services.security.ldap.UnixCrypt).
+ * <p>The Java implementation was taken from the JetSpeed Portal project (see
+ * org.apache.jetspeed.services.security.ldap.UnixCrypt).</p>
*
- * This class is slightly incompatible if the given salt contains characters
- * that are not part of the allowed range [a-zA-Z0-9./].
+ * <p>This class is slightly incompatible if the given salt contains characters
+ * that are not part of the allowed range [a-zA-Z0-9./].</p>
*
* <p>This class is immutable and thread-safe.</p>
*
@@ -342,12 +342,12 @@ public class UnixCrypt {
/**
* Generates a crypt(3) compatible hash using the DES algorithm.
- *
+ * <p>
* As no salt is given, a random one will be used.
*
- * @param original Plaintext password
- *
- * @return A 13 character string starting with the salt string.
+ * @param original
+ * plaintext password
+ * @return a 13 character string starting with the salt string
*/
public static String crypt(byte[] original) {
return crypt(original, null);
@@ -355,15 +355,14 @@ public class UnixCrypt {
/**
* Generates a crypt(3) compatible hash using the DES algorithm.
- *
+ * <p>
* Using unspecified characters as salt results incompatible hash values.
*
- * @param original Plaintext password
- *
- * @param salt A two character string drawn from [a-zA-Z0-9./] or null for
a
- * random one.
- *
- * @return A 13 character string starting with the salt string.
+ * @param original
+ * plaintext password
+ * @param salt
+ * a two character string drawn from [a-zA-Z0-9./] or null for
a random one
+ * @return a 13 character string starting with the salt string
*/
public static String crypt(byte[] original, String salt) {
if (salt == null) {
@@ -424,12 +423,12 @@ public class UnixCrypt {
/**
* Generates a crypt(3) compatible hash using the DES algorithm.
- *
+ * <p>
* As no salt is given, a random one is used.
*
- * @param original Plaintext password
- *
- * @return A 13 character string starting with the salt string.
+ * @param original
+ * plaintext password
+ * @return a 13 character string starting with the salt string
*/
public static String crypt(String original) throws Exception {
return crypt(original.getBytes(Charsets.UTF_8));
@@ -438,10 +437,11 @@ public class UnixCrypt {
/**
* Generates a crypt(3) compatible hash using the DES algorithm.
*
- * @param original Plaintext password
- * @param salt A two character string drawn from [a-zA-Z0-9./] or null for
a
- * random one.
- * @return A 13 character string starting with the salt string.
+ * @param original
+ * plaintext password
+ * @param salt
+ * a two character string drawn from [a-zA-Z0-9./] or null for
a random one
+ * @return a 13 character string starting with the salt string
*/
public static String crypt(String original, String salt) throws Exception {
return crypt(original.getBytes(Charsets.UTF_8), salt);
