shiro-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From lhazlew...@apache.org
Subject svn commit: r909162 - in /incubator/shiro/trunk/core/src/main/java/org/apache/shiro/authc/credential: HashedCredentialsMatcher.java SimpleCredentialsMatcher.java
Date Thu, 11 Feb 2010 21:57:44 GMT
Author: lhazlewood
Date: Thu Feb 11 21:57:43 2010
New Revision: 909162

URL: http://svn.apache.org/viewvc?rev=909162&view=rev
Log:
Various spelling and JavaDoc fixes (part 2)

Modified:
    incubator/shiro/trunk/core/src/main/java/org/apache/shiro/authc/credential/HashedCredentialsMatcher.java
    incubator/shiro/trunk/core/src/main/java/org/apache/shiro/authc/credential/SimpleCredentialsMatcher.java

Modified: incubator/shiro/trunk/core/src/main/java/org/apache/shiro/authc/credential/HashedCredentialsMatcher.java
URL: http://svn.apache.org/viewvc/incubator/shiro/trunk/core/src/main/java/org/apache/shiro/authc/credential/HashedCredentialsMatcher.java?rev=909162&r1=909161&r2=909162&view=diff
==============================================================================
--- incubator/shiro/trunk/core/src/main/java/org/apache/shiro/authc/credential/HashedCredentialsMatcher.java
(original)
+++ incubator/shiro/trunk/core/src/main/java/org/apache/shiro/authc/credential/HashedCredentialsMatcher.java
Thu Feb 11 21:57:43 2010
@@ -26,54 +26,48 @@
 import org.apache.shiro.crypto.hash.Hash;
 
 /**
- * A <tt>HashedCredentialMatcher</tt> provides support for hashing of supplied
<tt>AuthenticationToken</tt> credentials
- * before being compared to those in the <tt>AuthenticationInfo</tt> from the
data store.
- *
- * <p>Credential hashing is one of the most common security techniques when safeguarding
a user's private credentials
+ * A {@code HashedCredentialMatcher} provides support for hashing of supplied {@code AuthenticationToken}
credentials
+ * before being compared to those in the {@code AuthenticationInfo} from the data store.
+ * <p/>
+ * Credential hashing is one of the most common security techniques when safeguarding a user's
private credentials
  * (passwords, keys, etc).  Most developers never want to store their users' credentials
in plain form, viewable by
- * anyone, so they often hash the users' credentials before they are saved in the data store.</p>
- *
- * <p>This class (and its subclasses) function as follows:</p>
- *
- * <p>It first hashes the <tt>AuthenticationToken</tt> credentials supplied
by the user during their login.  It then
- * compares this hashed value directly with the <tt>AuthenticationInfo</tt> credentials
stored in the system.  The stored account
+ * anyone, so they often hash the users' credentials before they are saved in the data store.
+ * <p/>
+ * This class (and its subclasses) function as follows:
+ * <p/>
+ * It first hashes the {@code AuthenticationToken} credentials supplied by the user during
their login.  It then
+ * compares this hashed value directly with the {@code AuthenticationInfo} credentials stored
in the system.  The stored account
  * credentials are expected to already be in hashed form.  If these two values are equal,
the submitted credentials
- * match.</p>
- *
+ * match.
  * <h3>Salting and Multiple Hash Iterations</h3>
- *
- * <p>Because simple hashing is sometimes not good enough for many applications, this
class also supports 'salting'
+ * Because simple hashing is sometimes not good enough for many applications, this class
also supports 'salting'
  * and multiple hash iterations.  Please read this excellent
  * <a href="http://www.owasp.org/index.php/Hashing_Java" _target="blank">Hashing Java
article</a> to learn about
  * salting and multiple iterations and why you might want to use them. (Note of sections
5
  * &quot;Why add salt?&quot; and 6 "Hardening against the attacker's attack").
- *
- * <p>We should also note here that all of Shiro's Hash implementations (for example,
+ * <p/>
+ * We should also note here that all of Shiro's Hash implementations (for example,
  * {@link org.apache.shiro.crypto.hash.Md5Hash Md5Hash}, {@link org.apache.shiro.crypto.hash.Sha1Hash
Sha1Hash}, etc)
- * support salting and multiple hash iterations via overloaded constructors.</p>
- *
+ * support salting and multiple hash iterations via overloaded constructors.
  * <h4>Salting</h4>
- *
- * <p>Salting of the authentication token's credentials hash is disabled by default,
but you may enable it by setting
+ * Salting of the authentication token's credentials hash is disabled by default, but you
may enable it by setting
  * {@link #setHashSalted hashSalted} to
- * <tt>true</tt>.  If you do enable it, the value used to salt the hash will
be
+ * {@code true}.  If you do enable it, the value used to salt the hash will be
  * obtained from {@link #getSalt(org.apache.shiro.authc.AuthenticationToken) getSalt(authenticationToken)}.
- *
- * <p>The default <tt>getSalt</tt> implementation merely returns
- * <code>token.getPrincipal()</code>, effectively using the user's identity as
the salt, a most common
+ * <p/>
+ * The default {@code getSalt} implementation merely returns
+ * {@code token.getPrincipal()}, effectively using the user's identity as the salt, a most
common
  * technique.  If you wish to provide the authentication token's salt another way, you may
override this
- * <tt>getSalt</tt> method.
- *
+ * {@code getSalt} method.
  * <h4>Multiple Hash Iterations</h4>
- *
- * <p>If you hash your users' credentials multiple times before persisting to the data
store, you will also need to
- * set this class's {@link #setHashIterations(int) hashIterations} property.</p>
- *
- * <p><b>Note:</b> <a href="http://en.wikipedia.org/wiki/MD5">MD5</a>
and
+ * If you hash your users' credentials multiple times before persisting to the data store,
you will also need to
+ * set this class's {@link #setHashIterations(int) hashIterations} property.
+ * <p/>
+ * <b>Note:</b> <a href="http://en.wikipedia.org/wiki/MD5">MD5</a>
and
  * <a href="http://en.wikipedia.org/wiki/SHA_hash_functions">SHA-1</a> algorithms
are now known to be vulnerable to
  * compromise and/or collisions (read the linked pages for more).  While most applications
are ok with either of these
  * two, if your application mandates high security, use the SHA-256 (or higher) hashing algorithms
and their
- * supporting <code>CredentialsMatcher</code> implementations.</p>
+ * supporting {@code CredentialsMatcher} implementations.
  *
  * @author Les Hazlewood
  * @see org.apache.shiro.crypto.hash.Md5Hash
@@ -88,15 +82,15 @@
     private int hashIterations = 1;
 
     /**
-     * Returns <tt>true</tt> if the system's stored credential hash is Hex encoded,
<tt>false</tt> if it
+     * Returns {@code true} if the system's stored credential hash is Hex encoded, {@code
false} if it
      * is Base64 encoded.
-     *
-     * <p>Default value is <tt>true</tt> for convenience - all of Shiro's
{@link Hash Hash#toString()}
+     * <p/>
+     * Default value is {@code true} for convenience - all of Shiro's {@link Hash Hash#toString()}
      * implementations return Hex encoded values by default, making this class's use with
those implementations
-     * easier.</p>
+     * easier.
      *
-     * @return <tt>true</tt> if the system's stored credential hash is Hex encoded,
<tt>false</tt> if it
-     *         is Base64 encoded.  Default is <tt>true</tt>
+     * @return {@code true} if the system's stored credential hash is Hex encoded, {@code
false} if it
+     *         is Base64 encoded.  Default is {@code true}
      */
     public boolean isStoredCredentialsHexEncoded() {
         return storedCredentialsHexEncoded;
@@ -104,13 +98,13 @@
 
     /**
      * Sets the indicator if this system's stored credential hash is Hex encoded or not.
-     *
-     * <p>A value of <tt>true</tt> will cause this class to decode the
system credential from Hex, a
-     * value of <tt>false</tt> will cause this class to decode the system credential
from Base64.</p>
-     *
-     * <p>Unless overridden via this method, the default value is <tt>true</tt>
for convenience - all of Shiro's
+     * <p/>
+     * A value of {@code true} will cause this class to decode the system credential from
Hex, a
+     * value of {@code false} will cause this class to decode the system credential from
Base64.
+     * <p/>
+     * Unless overridden via this method, the default value is {@code true} for convenience
- all of Shiro's
      * {@link Hash Hash#toString()} implementations return Hex encoded values by default,
making this class's use with
-     * those implementations easier.</p>.
+     * those implementations easier.
      *
      * @param storedCredentialsHexEncoded the indicator if this system's stored credential
hash is Hex
      *                                    encoded or not ('not' automatically implying it
is Base64 encoded).
@@ -120,40 +114,40 @@
     }
 
     /**
-     * Returns <tt>true</tt> if a submitted <tt>AuthenticationToken</tt>'s
credentials should be salted when hashing,
-     * <tt>false</tt> if it should not be salted.
-     *
-     * <p>If enabled, the salt used will be obtained via the {@link #getSalt(AuthenticationToken)
getSalt} method.
+     * Returns {@code true} if a submitted {@code AuthenticationToken}'s credentials should
be salted when hashing,
+     * {@code false} if it should not be salted.
+     * <p/>
+     * If enabled, the salt used will be obtained via the {@link #getSalt(AuthenticationToken)
getSalt} method.
+     * <p/>
+     * The default value is {@code false}.
      *
-     * <p>The default value is <tt>false</tt>.
-     *
-     * @return <tt>true</tt> if a submitted <tt>AuthenticationToken</tt>'s
credentials should be salted when hashing,
-     *         <tt>false</tt> if it should not be salted.
+     * @return {@code true} if a submitted {@code AuthenticationToken}'s credentials should
be salted when hashing,
+     *         {@code false} if it should not be salted.
      */
     public boolean isHashSalted() {
         return hashSalted;
     }
 
     /**
-     * Sets whether or not to salt a submitted <tt>AuthenticationToken</tt>'s
credentials when hashing.
-     *
-     * <p>If enabled, the salt used will be obtained via the {@link #getSalt(org.apache.shiro.authc.AuthenticationToken)
getSalt} method.
+     * Sets whether or not to salt a submitted {@code AuthenticationToken}'s credentials
when hashing.
+     * <p/>
+     * If enabled, the salt used will be obtained via the {@link #getSalt(org.apache.shiro.authc.AuthenticationToken)
getSalt} method.
+     * </p>
+     * The default value is {@code false}.
      *
-     * <p>The default value is <tt>false</tt>.
-     *
-     * @param hashSalted whether or not to salt a submitted <tt>AuthenticationToken</tt>'s
credentials when hashing.
+     * @param hashSalted whether or not to salt a submitted {@code AuthenticationToken}'s
credentials when hashing.
      */
     public void setHashSalted(boolean hashSalted) {
         this.hashSalted = hashSalted;
     }
 
     /**
-     * Returns the number of times a submitted <tt>AuthenticationToken</tt>'s
credentials will be hashed before
+     * Returns the number of times a submitted {@code AuthenticationToken}'s credentials
will be hashed before
      * comparing to the credentials stored in the system.
+     * <p/>
+     * Unless overridden, the default value is {@code 1}, meaning a normal hash execution
will occur.
      *
-     * <p>Unless overridden, the default value is <tt>1</tt>, meaning a
normal hash execution will occur.
-     *
-     * @return the number of times a submitted <tt>AuthenticationToken</tt>'s
credentials will be hashed before
+     * @return the number of times a submitted {@code AuthenticationToken}'s credentials
will be hashed before
      *         comparing to the credentials stored in the system.
      */
     public int getHashIterations() {
@@ -161,15 +155,15 @@
     }
 
     /**
-     * Sets the number of times a submitted <tt>AuthenticationToken</tt>'s credentials
will be hashed before comparing
+     * Sets the number of times a submitted {@code AuthenticationToken}'s credentials will
be hashed before comparing
      * to the credentials stored in the system.
-     *
-     * <p>Unless overridden, the default value is <tt>1</tt>, meaning a
normal single hash execution will occur.
-     *
-     * <p>If this argument is less than 1 (i.e. 0 or negative), the default value of
1 is applied.  There must always be
+     * <p/>
+     * Unless overridden, the default value is {@code 1}, meaning a normal single hash execution
will occur.
+     * <p/>
+     * If this argument is less than 1 (i.e. 0 or negative), the default value of 1 is applied.
 There must always be
      * at least 1 hash iteration (otherwise there would be no hash).
      *
-     * @param hashIterations the number of times to hash a submitted <tt>AuthenticationToken</tt>'s
credentials.
+     * @param hashIterations the number of times to hash a submitted {@code AuthenticationToken}'s
credentials.
      */
     public void setHashIterations(int hashIterations) {
         if (hashIterations < 1) {
@@ -181,8 +175,8 @@
 
     /**
      * Returns a salt value used to hash the token's credentials.
-     *
-     * <p>This default implementation merely returns <code>token.getPrincipal()</code>,
effectively using the user's
+     * <p/>
+     * This default implementation merely returns {@code token.getPrincipal()}, effectively
using the user's
      * identity (username, user id, etc) as the salt, a most common technique.  If you wish
to provide the
      * authentication token's salt another way, you may override this method.
      *
@@ -196,8 +190,8 @@
     /**
      * As this is a HashedCredentialMatcher, this method overrides the parent method by returning
a hashed value
      * of the submitted token's credentials.
-     *
-     * <p>Based on this class's configuration, the return value may be salted and/or
+     * <p/>
+     * Based on this class's configuration, the return value may be salted and/or
      * hashed multiple times (see the class-level JavaDoc for more information on salting
and
      * multiple hash iterations).
      *
@@ -212,22 +206,21 @@
 
     /**
      * Returns a {@link Hash Hash} instance representing the already-hashed AuthenticationInfo
credentials stored in the system.
-     *
-     * <p>This method reconstructs a {@link Hash Hash} instance based on a <code>info.getCredentials</code>
call,
+     * <p/>
+     * This method reconstructs a {@link Hash Hash} instance based on a {@code info.getCredentials}
call,
      * but it does <em>not</em> hash that value - it is expected that method
call will return an already-hashed value.
-     *
-     * <p>This implementation's reconstruction effort functions as follows:
-     *
+     * <p/>
+     * This implementation's reconstruction effort functions as follows:
      * <ol>
-     * <li>Convert <code>account.getCredentials()</code> to a byte array
via the {@link #toBytes convertPrincipalsToBytes} method.
-     * <li>If <code>account.getCredentials()</code> was originally a String
or char[] before <tt>convertPrincipalsToBytes</tt> was
+     * <li>Convert {@code account.getCredentials()} to a byte array via the {@link
#toBytes toBytes} method.
+     * <li>If {@code account.getCredentials()} was originally a String or char[] before
{@code toBytes} was
      * called, check for encoding:
      * <li>If {@link #storedCredentialsHexEncoded storedCredentialsHexEncoded}, Hex
decode that byte array, otherwise
      * Base64 decode the byte array</li>
-     * <li>Set the byte[] array directly on the <tt>Hash</tt> implementation
and return it.</li>
+     * <li>Set the byte[] array directly on the {@code Hash} implementation and return
it.</li>
      * </ol>
      *
-     * @param info the AuthenticationInfo from which to retrive the credentials which assumed
to be in already-hashed form.
+     * @param info the AuthenticationInfo from which to retrieve the credentials which assumed
to be in already-hashed form.
      * @return a {@link Hash Hash} instance representing the given AuthenticationInfo's stored
credentials.
      */
     protected Object getCredentials(AuthenticationInfo info) {
@@ -250,11 +243,11 @@
     }
 
     /**
-     * Hashes the provided credentials a total of <tt>hashIterations</tt> times,
using the given salt.  The hash
+     * Hashes the provided credentials a total of {@code hashIterations} times, using the
given salt.  The hash
      * implementation/algorithm used is left to subclasses.
      *
      * @param credentials    the submitted authentication token's credentials to hash
-     * @param salt           the value to salt the hash, or <tt>null</tt> if
a salt will not be used.
+     * @param salt           the value to salt the hash, or {@code null} if a salt will not
be used.
      * @param hashIterations the number of times to hash the credentials.  At least one hash
will always occur though,
      *                       even if this argument is 0 or negative.
      * @return the hashed value of the provided credentials, according to the specified salt
and hash iterations.

Modified: incubator/shiro/trunk/core/src/main/java/org/apache/shiro/authc/credential/SimpleCredentialsMatcher.java
URL: http://svn.apache.org/viewvc/incubator/shiro/trunk/core/src/main/java/org/apache/shiro/authc/credential/SimpleCredentialsMatcher.java?rev=909162&r1=909161&r2=909162&view=diff
==============================================================================
--- incubator/shiro/trunk/core/src/main/java/org/apache/shiro/authc/credential/SimpleCredentialsMatcher.java
(original)
+++ incubator/shiro/trunk/core/src/main/java/org/apache/shiro/authc/credential/SimpleCredentialsMatcher.java
Thu Feb 11 21:57:43 2010
@@ -83,7 +83,7 @@
      * <tt>accountCredentials</tt> argument.
      * <p/>
      * <p>If both arguments are either a byte array (byte[]), char array (char[]) or
String, they will be both be
-     * converted to raw byte arrays via the {@link #toBytes convertPrincipalsToBytes} method
first, and then resulting byte arrays
+     * converted to raw byte arrays via the {@link #toBytes toBytes} method first, and then
resulting byte arrays
      * are compared via {@link Arrays#equals(byte[], byte[]) Arrays.equals(byte[],byte[])}.</p>
      * <p/>
      * <p>If either argument cannot be converted to a byte array as described, a simple
Object <code>equals</code>



Mime
View raw message