Misc release cleanup (#464)

* Release notes to close issue #463

* Changes to replace deprecated method CryptoHelper.arrayCompare() with MessageDigest.isEqual() which is safe in JDK 7.

* Close issue #246

* Close issue #462

* Close issue #364 and general assertion cleanup.

* Close issue #417

* Close issue #465

* Add more details, especially regarding dependency updates to address CVEs.

* Add WARNINGS to javadoc as noted in comment for GitHub issue #233

* Update OWASP Dependency Check from release 2.1.0 to 4.0.1 (i.e., the latest version).

* General clean-up. Add paragraph to discuss CVE-2018-8088 and why ESAPI is not affected.

* Update to mention PR #467 and closing of issue #360

* Fix typo in path for configuration/esapi and add 2.2.0.0 release notes.

* Change release from 2.1.0.2-SNAPSHOT to 2.2.0.0-SNAPSHOT in prep for release. See GitHub issue #471

* Preparation for 2.2.0.0 release. See GitHub issue #471 for details.

* Try to clarify by example the git commands used.

* Added Jeremiah's PR #472

* * Reference issue 188 as being closed.
* Udate status of latest PRs.
* Added 'Basic ESAPI Facts' section.

Author: kwwall

CONTRIBUTING-TO-ESAPI.txt

@@ -85,11 +85,16 @@ Steps to work with ESAPI:
        if this is the first time you have run Dependency-Check for ESAPI,
        expect it to take a while (often 30 minutes or so!).
     7. Commit your changes locally.
-    8. Push your 'issue-#' branch to your personal, forked ESAPI GitHub repo.-
-    9. Go to your personal, forked ESAPI GitHub repo and create a
-       Pull Request from your 'issue-#' branch.
+    8. Push your 'issue-#' branch to your personal, forked ESAPI GitHub repo. E.g.,
+            $ git checkout issue-444
+            $ git remote -v | grep origin       # Confirm 'origin' refers to YOUR PERSONAL GitHub repo
+            $ git push origin issue-444         # Push the committed changes on the 'issue-444' branch
+    9. Go to your personal, forked ESAPI GitHub repo (web interface) and create a
+       'Pull Request' from your 'issue-#' branch.
    10. Back on your local personal laptop / desktop, merge your issue branch with
-       your local 'develop' branch.
+       your local 'develop' branch. I.e.
+            $ git checkout develop
+            $ git merge issue-444
 
 In theory, you can do all this 'git' magic from Eclipse and presumably other
 IDEs like NetBeans or IntelliJ). From Eclipse, it is right-click on the

configuration/esapi/ESAPI.properties

@@ -77,6 +77,9 @@ ESAPI.IntrusionDetector=org.owasp.esapi.reference.DefaultIntrusionDetector
 # Log4JFactory Requires log4j.xml or log4j.properties in classpath - http://www.laliluna.de/log4j-tutorial.html
 ESAPI.Logger=org.owasp.esapi.reference.Log4JLogFactory
 #ESAPI.Logger=org.owasp.esapi.reference.JavaLogFactory
+# To use the new SLF4J logger in ESAPI (see GitHub issue #129), set
+#    ESAPI.Logger=org.owasp.esapi.logging.slf4j.Slf4JLogFactory
+# and do whatever other normal SLF4J configuration that you normally would do for your application.
 ESAPI.Randomizer=org.owasp.esapi.reference.DefaultRandomizer
 ESAPI.Validator=org.owasp.esapi.reference.DefaultValidator
 

documentation/ESAPI-security-bulletin1.docx

@@ -11,7 +11,7 @@ File / Directory                                                        Descript
 |
 +---configuration/                                                      Directory of ESAPI configuration files
 |     |
-|     |---.esapi/
+|     |---esapi/
 |     |     |---waf-policies/                                           Directory containing Web Application Firewall policies
 |     |     |---ESAPI.properties                                        The main ESAPI configuration file
 |     |     `---validation.properties                                   Regular expressions used by the ESAPI validator
@@ -32,6 +32,7 @@ File / Directory                                                        Descript
 |     |---esapi4java-core-2.0-readme-crypto-changes.html                Describes why crypto was changed from what was in ESAPI 1.4
 |     |---esapi4java-core-2.0-symmetric-crypto-user-guide.html          User guide for using symmetric encryption in ESAPI 2.0
 |     |---esapi4java-core-2.1-release-notes.txt                         ESAPI 2.1 release notes
+|     |---esapi4java-core-2.2.0.0-release-notes.txt                     ESAPI 2.2.0.0 release notes
 |     `---esapi4java-waf-2.0-policy-file-spec.pdf                       Describes how to configure ESAPI 2.0's Web Application Firewall
 |
 |---libs/                                                               ESAPI dependencies
@@ -57,4 +58,4 @@ notes.
 Please address comments and questions concerning the API and this document to
 the ESAPI Users mailing list, <[email protected]>.
 
-Copyright (C) 2009-2010 The OWASP Foundation.
+Copyright (C) 2009-2019 The OWASP Foundation.

documentation/ESAPI-security-bulletin1.pdf

@@ -3,7 +3,7 @@
     <modelVersion>4.0.0</modelVersion>
     <groupId>org.owasp.esapi</groupId>
     <artifactId>esapi</artifactId>
-    <version>2.1.0.2-SNAPSHOT</version>
+    <version>2.2.0.0-SNAPSHOT</version>
     <packaging>jar</packaging>
 
     <prerequisites>
@@ -369,7 +369,7 @@
             <plugin>
                 <groupId>org.owasp</groupId>
                 <artifactId>dependency-check-maven</artifactId>
-                <version>2.1.0</version>
+                <version>4.0.1</version>
                 <configuration>
                     <!-- <failBuildOnCVSS>5.9</failBuildOnCVSS> -->
                     <suppressionFile>./suppressions.xml</suppressionFile>

documentation/esapi4java-2.0-readme.txt

@@ -111,8 +111,10 @@ public interface Authenticator {
 
 	/**
 	 * Verify that the supplied password matches the password for this user. Password should
-	 * be stored as a hash. It is recommended you use the hashPassword(password, accountName) method
-	 * in this class.
+	 * be stored as a hash. By default, this method verifies password hashes created via the
+     * {@code hashPassword(password, accountName)} method in this class, however see WARNING
+     * the {@code hashPassword} method.
+     * <p>
 	 * This method is typically used for "reauthentication" for the most sensitive functions, such
 	 * as transactions, changing email address, and changing other account information.
 	 * 
@@ -123,6 +125,8 @@ public interface Authenticator {
 	 * 
 	 * @return 
 	 * 		true, if the password is correct for the specified user
+     *
+     * @see #hashPassword(String password, String accountName)
 	 */
 	boolean verifyPassword(User user, String password);
 
@@ -141,6 +145,13 @@ public interface Authenticator {
 	 * Two copies of the new password are required to encourage user interface designers to
 	 * include a "re-type password" field in their forms. Implementations should verify that 
 	 * both are the same. 
+     * <p>
+     * <b>WARNING:</b> The implementation of this method as defined in the
+     * default reference implementation class, {@code FileBasedAuthenticator},
+     * uses a password hash algorthim that is known to be weak. You are advised
+     * to replace the default reference implementation class with your own custom
+     * implementation that uses a stronger password hashing algorithm.
+     * See class comments in * {@code FileBasedAuthenticator} for further details.
 	 * 
 	 * @param accountName 
 	 * 		the account name of the new user
@@ -257,6 +268,13 @@ public interface Authenticator {
 	 * This method specifies the use of the user's account name as the "salt"
 	 * value. The Encryptor.hash method can be used if a different salt is
 	 * required.
+     * <p>
+     * <b>WARNING:</b> The implementation of this method as defined in the
+     * default reference implementation class, {@code FileBasedAuthenticator},
+     * is know to be extremely weak. The reference implementation class was
+     * meant to be an example implementation and generally should be avoided
+     * and replaced with your own implementation. See class comments in
+     * {@code FileBasedAuthenticator} for further details.
 	 * 
 	 * @param password
 	 *            the password to hash
@@ -266,6 +284,9 @@ public interface Authenticator {
 	 * @return 
      * 		the hashed password
      * @throws EncryptionException
+     *
+     * @see org.owasp.esapi.reference.FileBasedAuthenticator FileBasedAuthenticator,
+     *                          the default reference implementation of this interface.
 	 */
 	String hashPassword(String password, String accountName) throws EncryptionException;
 

documentation/esapi4java-core-2.2.0.0-release-notes.txt

@@ -350,8 +350,8 @@ public boolean equals(Object other) {
                       NullSafe.equals(this.cipher_xform_, that.cipher_xform_) &&
                       this.keySize_ == that.keySize_ &&
                       this.blockSize_ == that.blockSize_ &&
-                        // Comparison safe from timing attacks.
-                      CryptoHelper.arrayCompare(this.iv_, that.iv_) );
+                        // In all versions of JDK 7 and later, comparison safe from timing attacks.
+                      java.security.MessageDigest.isEqual(this.iv_, that.iv_) );
         }
         return result;
     }

pom.xml

@@ -470,7 +470,7 @@ public boolean validateMAC(SecretKey authKey) {
                                 "computed MAC len: " + mac.length +
                                 ", received MAC len: " + separate_mac_.length);
             }
-	        return CryptoHelper.arrayCompare(mac, separate_mac_); // Safe compare!!!
+	        return java.security.MessageDigest.isEqual(mac, separate_mac_); // Safe compare in JDK 7 and later
 	    } else if ( ! requiresMAC ) {           // Doesn't require a MAC
 	        return true;
 	    } else {
@@ -712,8 +712,8 @@ public String toString() {
                 result = (that.canEqual(this) &&
                           this.cipherSpec_.equals(that.cipherSpec_) &&
                             // Safe comparison, resistant to timing attacks
-                          CryptoHelper.arrayCompare(this.raw_ciphertext_, that.raw_ciphertext_) &&
-                          CryptoHelper.arrayCompare(this.separate_mac_, that.separate_mac_) &&
+                          java.security.MessageDigest.isEqual(this.raw_ciphertext_, that.raw_ciphertext_) &&
+                          java.security.MessageDigest.isEqual(this.separate_mac_, that.separate_mac_) &&
                           this.encryption_timestamp_ == that.encryption_timestamp_ );
             } else {
                 logger.warning(Logger.EVENT_FAILURE, "CipherText.equals(): Cannot compare two " +