Issue #31 MySQLCodec Updates (#472)

* MySQLCodec Underscore Escape Tests

Implementing my understanding of the desired tests from the issue.

* MySQLCodec Logic and Test Modifications

I am not sure this is what is desired

Tests showing the MySQLCodec acts as specified for the OWASP
recommendation of MySQL encoding for both ANSI and MySQL (Standard) Modes.

Logic updates to account for divergence from the recommended approach.

* MySQLCodec Logic (Restoring)

Putting back the logic from MySQLCodec removed last commit.  Alphanumerics
under 256 should be returned in their original forms based on OWASP
recommendation being targeted.

* MySQLCodec Test Updates

Correcting tests for the STANDARD handling of characters up to 256
including numbers, upper/lower case letters, special encoded characters,
and any value outside the previously defined sets.

This should now assert the OWASP recommended approach to Encoding STANDARD
MySQL inputs.

* MySQLCodecTest Updates: DECODE

Adding a decode validation to the existing tests to verify that when an
ecoded string is decoded that the original value is the result.

* MySQLCodec Logic Update: Bug Fix

Identified a case in MySQLCodec (STANDARD) where the special-case
character 0x1a was correctly encoding to '//Z', but the decode case was
watching for '//z'.  Encoded value did not decode to original input.

Logic update in decode to alter the lower case z to the upper-case Z.

* MySQLCodec Documentation Update

Updating the URL listed in the class documentation to direct to OWASP
recommended MySQL Escaping.

* MySQLCodecTest Updates Ansi Decode PB_Seq

Adding workflow & behavioral validations for the ANSI handling of decoding
a PushBackSequence reference.

* MySQLCodecTest Updates Ansi Decode PB_Seq

Updating ANSI PushbackSequence tests names to be
better self-documenting.

* MySQLCodecTest Updates Standard Decode PB_Seq

Adding tests for Standard MySQLCodec Decode with PushbackSequence

* MySqlCodecTest Ctr using int

The ctr is deprecated, but still should be tested as long as it is
present.  Adding cases for ANSI and Standard resolution showing mode is
correctly resolved.  Stub of an unsupported int also included, but
currently ignored.

* MySQLCodec Logic & Tests invalid int CTR Arg

Found that implementations would throw NPE's if an invalid int was
provided to the deprecated constructor when trying to encode or decode
values.  Opted to alter the constructor logic to immediately throw a
runtime exception (IllegalArgument) if the constructor parameter cannot
resolve to a valid reference.

It would be a Runtime exception either way, it's just a matter of when
it's thrown.

Alternatively, the mode switches in the encode/decode could have been
surrounded by an if block with an else/fallthrough which retuned null.

It is my opinion that this is a non-obvious failure of misconfiguration
and would be difficult to diagnose and resolve.  The immediate class
failure should provide the end-user with context on how to resolve the
problem and limit the time debugging.

Tests provided to validate workflow.

* MySQLCodecTest Update Method Rename

Renaming static method to be inclusive of the creation of both mode escape
maps.

* MySQLCodec Test Immunity Validations

Tests for handling of encoding with immunity sets for STANDARD and ANSI
modes.

* MySQLCodec Documentation Updates

Updating class documentation to clarify the intended support provided by
the implementation.

* MySQLCodec Code Structure Updates

Making a copy of MySQLCodec in its own subpackage of the codec group.  Breaking
apart the implementation into the codec and a strategy pattern controlled
by the MySQLMode enumeration.

Each piece of this implementation retained the original tests; however,
like the code, the tests have been split up as well.  Now the
responsibilty of the ANSI handing is in the MySQLAnsiSupport class.
Standard behavior is held an tested from the MySQLStandardSupport class.

I feel like this change increases readability and usability of the
baseline.  I am committing this at this time to get another set of
opinions on this approach.  In the interim, the original MySQLCodec and
tests have remained untouched in this effort.

* Cleanup: Removing MySqlCodec Strategy impl

Sample served its purpose and may be revisited later.  Opting to maintain
existing implementation for issue resolution.

* Updating documentation: ANSI_QUOTES Mode

Providing javadoc mapping from the MySQLCodec ANSI mode to the MySQL
Server ANSI_QUOTES mode documentation.

* Removing testMySQLANSIModeQuoteInjection

From research, on issue #31 double quotes within the single quote literals
supported in ANSI_QUOTE modes do not require explicit escape handling.

* Reintroducing  testMySQLANSIModeQuoteInjection

Updating compare to match current expectation and adding comment to
clarify that no special handling for double quotes is needed in
ANSI_QUOTES mode.

Author: jeremiahjstacey

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

@@ -18,13 +18,47 @@
 
 
 /**
- * Implementation of the Codec interface for MySQL strings. See http://mirror.yandex.ru/mirrors/ftp.mysql.com/doc/refman/5.0/en/string-syntax.html
- * for more information.
+ * Codec implementation which can be used to escape string literals in MySQL.
+ * </br>
+ * Implementation accepts 2 Modes as identified by the OWASP Recommended
+ * escaping strategies:
+ * <ul>
+ * <li><b>ANSI</b> <br>
+ * Simply encode all ' (single tick) characters with '' (two single ticks)</li>
+ * <br>
+ * <li><b>Standard</b>
  * 
- * @author Jeff Williams (jeff.williams .at. aspectsecurity.com) <a
- *         href="http://www.aspectsecurity.com">Aspect Security</a>
+ * <pre>
+ *   NUL (0x00) --> \0  [This is a zero, not the letter O]
+ *   BS  (0x08) --> \b
+ *   TAB (0x09) --> \t
+ *   LF  (0x0a) --> \n
+ *   CR  (0x0d) --> \r
+ *   SUB (0x1a) --> \Z
+ *   "   (0x22) --> \"
+ *   %   (0x25) --> \%
+ *   '   (0x27) --> \'
+ *   \   (0x5c) --> \\
+ *   _   (0x5f) --> \_ 
+ *   <br>
+ *   all other non-alphanumeric characters with ASCII values less than 256  --> \c
+ *   where 'c' is the original non-alphanumeric character.
+ * </pre>
+ * 
+ * </li>
+ * 
+ * </ul>
+ * 
+ * @author Jeff Williams (jeff.williams .at. aspectsecurity.com)
+ *         <a href="http://www.aspectsecurity.com">Aspect Security</a>
  * @since June 1, 2007
- * @see org.owasp.esapi.Encoder
+ * 
+ * @see <a href=
+ *      "https://dev.mysql.com/doc/refman/8.0/en/string-literals.html">MySQL 8.0
+ *      String Literals</a>
+ * @see <a href=
+ *      "https://www.owasp.org/index.php/SQL_Injection_Prevention_Cheat_Sheet#MySQL_Escaping">OWASP
+ *      SQL_Injection_Prevention_Cheat_Sheet#MySQL_Escaping</a>
  */
 public class MySQLCodec extends AbstractCharacterCodec {
     /**
@@ -46,13 +80,20 @@ static Mode findByKey(int key) {
                 if ( m.key == key )
                     return m;
             }
-            return null;
+            String message = String.format("No Mode for %s. Valid references are MySQLStandard: %s or ANSI: %s", key, MYSQL_MODE, ANSI_MODE);
+            throw new IllegalArgumentException(message);
         }
     }
 
     /** Target MySQL Server is running in Standard MySQL (Default) mode. */
     public static final int MYSQL_MODE = 0;
-    /** Target MySQL Server is running in {@link "http://dev.mysql.com/doc/refman/5.0/en/ansi-mode.html"} ANSI Mode */
+    /**
+     * Target MySQL Server is running in ANSI_QUOTES Mode
+     * 
+     * @see <a href=
+     *      "https://dev.mysql.com/doc/refman/8.0/en/sql-mode.html#sqlmode_ansi_quotes">
+     *      https://dev.mysql.com/doc/refman/8.0/en/sql-mode.html#sqlmode_ansi_quotes</a>
+     */
     public static final int ANSI_MODE = 1;
 
 	//private int mode = 0;
@@ -100,11 +141,12 @@ public String encodeCharacter( char[] immune, Character c ) {
 			return ""+ch;
 		}
 
+		
 		switch( mode ) {
 			case ANSI: return encodeCharacterANSI( c );
 			case STANDARD: return encodeCharacterMySQL( c );
+			default: return null;
 		}
-		return null;
 	}
 
 	/**
@@ -123,8 +165,7 @@ public String encodeCharacter( char[] immune, Character c ) {
 	private String encodeCharacterANSI( Character c ) {
 		if ( c == '\'' )
         	return "\'\'";
-        if ( c == '\"' )
-            return "";
+     
         return ""+c;
 	}
 
@@ -166,8 +207,8 @@ public Character decodeCharacter( PushbackSequence<Character> input ) {
 		switch( mode ) {
 			case ANSI: return decodeCharacterANSI( input );
 			case STANDARD: return decodeCharacterMySQL( input );
+			default: return null;
 		}
-		return null;
 	}
 
 	/**
@@ -244,7 +285,7 @@ private Character decodeCharacterMySQL( PushbackSequence<Character> input ) {
 			return Character.valueOf( (char)0x0a );
 		} else if ( second.charValue() == 'r' ) {
 			return Character.valueOf( (char)0x0d );
-		} else if ( second.charValue() == 'z' ) {
+		} else if ( second.charValue() == 'Z' ) {
 			return Character.valueOf( (char)0x1a );
 		} else if ( second.charValue() == '\"' ) {
 			return Character.valueOf( (char)0x22 );