Merge pull request #688 from kwwall/issue-686

Issues 686 & 689 - Create DefaultEncoder from Encoder.DefaultCodecList and Javadoc clean-up

Author: xeno6696

pom.xml

@@ -439,7 +439,7 @@
             <plugin>
                 <groupId>org.cyclonedx</groupId>
                 <artifactId>cyclonedx-maven-plugin</artifactId>
-                <version>2.6.0</version>
+                <version>2.6.1</version>
                 <executions>
                   <execution>
                     <phase>package</phase>
@@ -787,6 +787,8 @@
                 <configuration>
                     <doclint>none</doclint>
                     <source>8</source>
+                    <failOnError>true</failOnError>
+                    <failOnWarnings>true</failOnWarnings>
                 </configuration>
             </plugin>
             <plugin>

src/main/java/org/owasp/esapi/Encoder.java

@@ -160,11 +160,20 @@ public interface Encoder {
     /**
      * This method is equivalent to calling {@code Encoder.canonicalize(input, restrictMultiple, restrictMixed);}.
      *
-     * The default values for restrictMultiple and restrictMixed come from {@code ESAPI.properties}
+     * The <i>default</i> values for {@code restrictMultiple} and {@code restrictMixed} come from {@code ESAPI.properties}.
      * <pre>
      * Encoder.AllowMultipleEncoding=false
      * Encoder.AllowMixedEncoding=false
      * </pre>
+     * and the default codecs that are used for canonicalization are the list
+     * of codecs that comes from:
+     * <pre>
+     * Encoder.DefaultCodecList=HTMLEntityCodec,PercentCodec,JavaScriptCodec
+     * </pre>
+     * (If the {@code Encoder.DefaultCodecList} property is null or not set,
+     * these same codecs are listed in the same order. Note that you may supply
+     * your own codec by using a fully cqualified class name of a class that
+     * implements {@code org.owasp.esapi.codecs.Codec<T>}.
      *
      * @see #canonicalize(String, boolean, boolean)
      * @see <a href="http://www.w3.org/TR/html4/interact/forms.html#h-17.13.4">W3C specifications</a>
@@ -224,7 +233,25 @@ public interface Encoder {
      *     Encoder encoder = new DefaultEncoder( list );
      *     String clean = encoder.canonicalize( request.getParameter( "input" ));
      * </pre>
-     * In ESAPI, the Validator uses the canonicalize method before it does validation.  So all you need to
+     * or alternately, you can just customize {@code Encoder.DefaultCodecList} property
+     * in the {@code ESAPI.properties} file with your preferred codecs; for
+     * example:
+     * <pre>
+     * Encoder.DefaultCodecList=WindowsCodec,MySQLCodec,PercentCodec
+     * </pre>
+     * and then use:
+     * <pre>
+     *     Encoder encoder = ESAPI.encoder();
+     *     String clean = encoder.canonicalize( request.getParameter( "input" ));
+     * </pre>
+     * as you normally would. However, the downside to using the
+     * {@code ESAPI.properties} file approach does not allow you to vary your
+     * list of codecs that are used each time. The downside to using the
+     * {@code DefaultEncoder} constructor is that your code is now timed to
+     * specific reference implementations rather than just interfaces and those
+     * reference implementations are what is most likely to change in ESAPI 3.x.
+     * </p><p>
+     * In ESAPI, the {@code Validator} uses the {@code canonicalize} method before it does validation.  So all you need to
      * do is to validate as normal and you'll be protected against a host of encoded attacks.
      * <pre>
      *     String input = request.getParameter( "name" );
@@ -253,14 +280,22 @@ public interface Encoder {
      *     // disabling strict mode to allow mixed encoding
      *     String url = ESAPI.encoder().canonicalize( request.getParameter("url"), false, false);
      * </pre>
-     * <b>WARNING!!!</b> Please note that this method is incompatible with URLs and if there exist any HTML Entities
+     * <b>WARNING #1!!!</b> Please note that this method is incompatible with URLs and if there exist any HTML Entities
      * that correspond with parameter values in a URL such as "&amp;para;" in a URL like 
      * "https://foo.com/?bar=foo&amp;parameter=wrong" you will get a mixed encoding validation exception.
      * <p>
      * If you wish to canonicalize a URL/URI use the method {@code Encoder.getCanonicalizedURI(URI dirtyUri);}
+     * </p><p>
+     * <b>WARNING #2!!!</b> Even if you use {@code WindowsCodec} or {@code UnixCodec}
+     * as appropriate, file path names in the {@code input} parameter will <b><i>NOT</i></b>
+     * be canonicalized. It the failure of such file path name canonicalization
+     * presents a potential security issue, consider using one of the
+     * {@code Validator.getValidDirectoryPath()} methods instead of or in addition to this method.
      *
      * @see <a href="http://www.w3.org/TR/html4/interact/forms.html#h-17.13.4">W3C specifications</a>
+     * @see #canonicalize(String)
      * @see #getCanonicalizedURI(URI dirtyUri)
+     * @see org.owasp.esapi.Validator#getValidDirectoryPath(java.lang.String, java.lang.String, java.io.File, boolean)
      *
      * @param input
      *      the text to canonicalize

src/main/java/org/owasp/esapi/SecurityConfiguration.java

@@ -390,17 +390,16 @@ public interface SecurityConfiguration extends EsapiPropertyLoader {
      * especially for any supported cipher mode that is considered a streaming mode
      * (which is basically anything except CBC for modes that support require an IV).
      * For this reason, 'fixed' has now been removed (it was considered <b>deprecated</b>
-     * since release 2.2.0.0). An <b>ESAPI.properties</b> value of {@Code fixed} for the property
-     * {@Code Encryptor.ChooseIVMethod} will now result in a {@Code ConfigurationException}
+     * since release 2.2.0.0). An <b>ESAPI.properties</b> value of {@code fixed} for the property
+     * {@code Encryptor.ChooseIVMethod} will now result in a {@code ConfigurationException}
      * being thrown.
      * 
      * @return A string specifying the IV type. Should be "random". Anything
-     * else should fail with a {@Code ConfigurationException} being thrown.
+     * else should fail with a {@code ConfigurationException} being thrown.
      * 
-     * @see #getFixedIV()
      * @deprecated Use SecurityConfiguration.getStringProp("appropriate_esapi_prop_name") instead.
      *             This method will be removed in a future release as it is now moot since
-     *             it can only legitimately have the single value of "random".
+     *             it can <i>only</i> legitimately have the single value of "random".
      */
     @Deprecated
     String getIVType();

src/main/java/org/owasp/esapi/codecs/AbstractCodec.java

@@ -17,11 +17,15 @@
 
 
 /**
- * The Codec interface defines a set of methods for encoding and decoding application level encoding schemes,
- * such as HTML entity encoding and percent encoding (aka URL encoding). Codecs are used in output encoding
+ * The {@code Coded} interface defines a set of methods for encoding and decoding application level encoding schemes,
+ * such as HTML entity encoding and percent encoding (aka URL encoding). {@code Coded}s are used in output encoding
  * and canonicalization.  The design of these codecs allows for character-by-character decoding, which is
  * necessary to detect double-encoding and the use of multiple encoding schemes, both of which are techniques
  * used by attackers to bypass validation and bury encoded attacks in data.
+ * <p>
+ * Be sure to see the several <b>WARNING</b>s associated with the detailed
+ * method descriptions. You will not find that in the "Method Summary" section
+ * of the javadoc because that only shows the intial sentence.
  * 
  * @author Jeff Williams (jeff.williams .at. aspectsecurity.com) <a
  *         href="http://www.aspectsecurity.com">Aspect Security</a>
@@ -52,15 +56,13 @@ public AbstractCodec() {
     }
 
     /**
-     * WARNING!!  {@code Character} based Codecs will silently transform code points that are not 
+     * {@inheritDoc}
+     * </p><p>
+     * <b>WARNING!!</b>  {@code Character} based {@code Codec}s will silently transform code points that are not 
      * legal UTF code points into garbage data as they will cast them to {@code char}s.  
-     * </br></br>
-     * If you are implementing an {@code Integer} based codec, these will be silently discarded
+     * Also, if you are implementing an {@code Integer} based codec, these will be silently discarded
      * based on the return from {@code Character.isValidCodePoint( int )}.  This is the preferred
      * behavior moving forward.  
-     * 
-     * 
-     * {@inheritDoc}
      */
     @Override
     public String encode(char[] immune, String input) {
@@ -79,19 +81,29 @@ public String encode(char[] immune, String input) {
     }
 
     /**
-     * WARNING!!!!  Passing a standard char to this method will resolve to the 
-     * @see #encodeCharacter( char[], int )
-     * method instead of this one!!!  YOU HAVE BEEN WARNED!!!!
-     * 
      * {@inheritDoc}
+     * <p>
+     * <b>WARNING!!!!</b>  Passing a standard {@code char} rather than {@code Character} to this method will resolve to the 
+     * {@link #encodeCharacter( char[], char )} method, which will throw an {@code IllegalArgumentException} instead.
+     * YOU HAVE BEEN WARNED!!!!
      */
     @Override
     public String encodeCharacter( char[] immune, Character c ) {
         return ""+c;
     }
 
+
+    /**
+     * To prevent accidental footgun usage and calling
+     * {@link #encodeCharacter( char[], int)} when called with {@code char} and
+     * {@code char} is first silently converted to {@code int} and then the
+     * unexpected method is called. 
+     *
+     * @throws IllegalArgumentException to indicate that you called the incorrect method.
+     */
     public String encodeCharacter(char[] immune, char c) {
-        throw new IllegalArgumentException("You tried to call encodeCharacter with a char.  Nope.  Use Character instead!");
+        throw new IllegalArgumentException("You tried to call encodeCharacter() with a char.  Nope.  " +
+                                           "Use 'encodeCharacter( char[] immune, Character c)' instead!");
     }
 
     /* (non-Javadoc)

src/main/java/org/owasp/esapi/codecs/Codec.java

@@ -77,8 +77,8 @@ public interface Codec<T> {
 
     /**
      * Returns the decoded version of the next character from the input string and advances the
-     * current character in the PushbackSequence.  If the current character is not encoded, this 
-     * method MUST reset the PushbackString.
+     * current character in the {@code PushbackSequence}.  If the current character is not encoded, this 
+     * method <i>MUST</i> reset the {@code PushbackString}.
      * 
      * @param input    the Character to decode
      * 
@@ -100,10 +100,25 @@ public interface Codec<T> {
      */
     public String getHexForNonAlphanumeric(int c);
 
+    /**
+     * Convert the {@code char} parameter to its octal representation.
+     * @param c the character for which to return the new representation.
+     * @return the octal representation.
+     */
     public String toOctal(char c);
 
+    /**
+     * Convert the {@code char} parameter to its hexadecimal representation.
+     * @param c the character for which to return the new representation.
+     * @return the hexadecimal representation.
+     */
     public String toHex(char c);
 
+    /**
+     * Convert the {@code int} parameter to its hexadecimal representation.
+     * @param c the character for which to return the new representation.
+     * @return the hexadecimal representation.
+     */
     public String toHex(int c);
 
     /**

src/main/java/org/owasp/esapi/codecs/JavaScriptCodec.java

@@ -80,12 +80,14 @@ public String encodeCharacter( char[] immune, Character c ) {
      * 
      * Returns the decoded version of the character starting at index, or
      * null if no decoding is possible.
-     * See http://www.planetpdf.com/codecuts/pdfs/tutorial/jsspec.pdf 
+     * </p><p>
      * Formats all are legal both upper/lower case:
+     * <pre>
      *   \\a - special characters
      *   \\xHH
      *   \\uHHHH
      *   \\OOO (1, 2, or 3 digits)
+     * </pre>
      */
     public Character decodeCharacter( PushbackSequence<Character> input ) {
         input.mark();
@@ -215,4 +217,4 @@ public Character decodeCharacter( PushbackSequence<Character> input ) {
         return null;
     }
 
-}
+}

src/main/java/org/owasp/esapi/codecs/UnixCodec.java

@@ -17,7 +17,7 @@
 
 
 /**
- * Implementation of the Codec interface for '\' encoding from Unix command shell.
+ * Implementation of the {@code Codec} interface for '\' encoding from Unix command shell (bash lineage, not csh lineage).
  * 
  * @author Jeff Williams (jeff.williams .at. aspectsecurity.com) <a
  *         href="http://www.aspectsecurity.com">Aspect Security</a>
@@ -29,9 +29,11 @@ public class UnixCodec extends AbstractCharacterCodec {
     /**
      * {@inheritDoc}
      * 
-     * Returns backslash-encoded character
+     * @return the backslash-encoded character
      *
-     * @param immune
+     * @param immune Array of characters that should not be encoded. Use with caution! All
+     *               alphanumeric characters are "immune" by default so you needn't
+     *               include them.
      */
     public String encodeCharacter( char[] immune, Character c ) {
         char ch = c.charValue();
@@ -53,13 +55,15 @@ public String encodeCharacter( char[] immune, Character c ) {
 
     /**
      * {@inheritDoc}
-     * 
-     * Returns the decoded version of the character starting at index, or
-     * null if no decoding is possible.
+     *
      * <p>
      * Formats all are legal both upper/lower case:
+     * <pre>
      *   \x - all special characters
-     *   
+     * </pre>
+     * 
+     * @return the decoded version of the character starting at index, or
+     * null if no decoding is possible.
      */
     public Character decodeCharacter( PushbackSequence<Character> input ) {
         input.mark();
@@ -79,4 +83,4 @@ public Character decodeCharacter( PushbackSequence<Character> input ) {
         return second;
     }
 
-}
+}

src/main/java/org/owasp/esapi/crypto/CipherText.java

@@ -798,7 +798,7 @@ protected boolean canEqual(Object other) {
      * proved in 1996 [see http://pssic.free.fr/Extra%20Reading/SEC+/SEC+/hmac-cb.pdf] that
      * HMAC security doesn’t require that the underlying hash function be collision resistant,
      * but only that it acts as a pseudo-random function, which SHA1 satisfies.
-     * @param authKey    The {@Code SecretKey} used with the computed HMAC-SHA1
+     * @param authKey    The {@code SecretKey} used with the computed HMAC-SHA1
      * to ensure authenticity.
      * @return The value for the MAC.
      */ 

src/main/java/org/owasp/esapi/filters/ClickjackFilter.java

@@ -26,39 +26,45 @@
 import javax.servlet.http.HttpServletResponse;
 
 /**
- * The {@code ClickjackFilter} is discussed at
- * @link http://www.owasp.org/index.php/ClickjackFilter_for_Java_EE
+ * The {@code ClickjackFilter} is configured as follows:
  * <pre>
- *     <filter>
- *            <filter-name>ClickjackFilterDeny</filter-name>
- *            <filter-class>org.owasp.filters.ClickjackFilter</filter-class>
- *            <init-param>
- *                <param-name>mode</param-name>
- *                 <param-value>DENY</param-value>
- *             </init-param>
- *         </filter>
+ *
+ *     &lt;filter&gt;
+ *            &lt;filter-name&gt;ClickjackFilterDeny&lt;/filter-name&gt;
+ *            &lt;filter-class&gt;org.owasp.filters.ClickjackFilter&lt;/filter-class&gt;
+ *            &lt;init-param&gt;
+ *                &lt;param-name&gt;mode&lt;/param-name&gt;
+ *                 &lt;param-value&gt;DENY&lt;/param-value&gt;
+ *             &lt;/init-param&gt;
+ *         &lt;/filter&gt;
  *         
- *         <filter>
- *             <filter-name>ClickjackFilterSameOrigin</filter-name>
- *             <filter-class>org.owasp.filters.ClickjackFilter</filter-class>
- *             <init-param>
- *                 <param-name>mode</param-name>
- *                 <param-value>SAMEORIGIN</param-value>
- *             </init-param>
- *         </filter>
+ *         &lt;filter&gt;
+ *             &lt;filter-name&gt;ClickjackFilterSameOrigin&lt;/filter-name&gt;
+ *             &lt;filter-class&gt;org.owasp.filters.ClickjackFilter&lt;/filter-class&gt;
+ *             &lt;init-param&gt;
+ *                 &lt;param-name&gt;mode&lt;/param-name&gt;
+ *                 &lt;param-value&gt;SAMEORIGIN&lt;/param-value&gt;
+ *             &lt;/init-param&gt;
+ *         &lt;/filter&gt;
  *        
- *        <!--  use the Deny version to prevent anyone, including yourself, from framing the page -->
- *        <filter-mapping> 
- *            <filter-name>ClickjackFilterDeny</filter-name>
- *            <url-pattern>/*</url-pattern>
- *        </filter-mapping>
+ *        &lt;!--  use the Deny version to prevent anyone, including yourself, from framing the page --&gt;
+ *        &lt;filter-mapping&gt; 
+ *            &lt;filter-name&gt;ClickjackFilterDeny&lt;/filter-name&gt;
+ *            &lt;url-pattern&gt;/*&lt;/url-pattern&gt;
+ *        &lt;/filter-mapping&gt;
  *         
- *         <!-- use the SameOrigin version to allow your application to frame, but nobody else
- *         <filter-mapping> 
- *            <filter-name>ClickjackFilterSameOrigin</filter-name>
- *             <url-pattern>/*</url-pattern>
- *         </filter-mapping>
+ *         &lt;!-- use the SameOrigin version to allow your application to frame, but nobody else
+ *         &lt;filter-mapping&gt; 
+ *            &lt;filter-name&gt;ClickjackFilterSameOrigin&lt;/filter-name&gt;
+ *             &lt;url-pattern&gt;/*&lt;/url-pattern&gt;
+ *         &lt;/filter-mapping&gt;
  * </pre>
+ *
+ * @see <a href="https://web.archive.org/web/20131020084831/https://www.owasp.org/index.php/ClickjackFilter_for_Java_EE">
+ *          OWASP - Clickjacking Filter for JavaEE</a>
+ * @see <a href="https://owasp.org/www-community/attacks/Clickjacking">OWASP - Clickjacking Attack</a>
+ * @see <a href="https://cheatsheetseries.owasp.org/cheatsheets/Clickjacking_Defense_Cheat_Sheet.html">
+ *          OWASP - Clickjacking Defense Cheat Sheet</a>
  */
 public class ClickjackFilter implements Filter 
 {