public class DefaultEncoder extends java.lang.Object implements Encoder
Encoder| Modifier and Type | Field and Description |
|---|---|
private java.util.List |
codecs |
private CSSCodec |
cssCodec |
private HTMLEntityCodec |
htmlCodec |
private static char[] |
IMMUNE_CSS |
private static char[] |
IMMUNE_HTML
Character sets that define characters (in addition to alphanumerics) that are
immune from encoding in various formats
|
private static char[] |
IMMUNE_HTMLATTR |
private static char[] |
IMMUNE_JAVASCRIPT |
private static char[] |
IMMUNE_OS |
private static char[] |
IMMUNE_SQL |
private static char[] |
IMMUNE_VBSCRIPT |
private static char[] |
IMMUNE_XML |
private static char[] |
IMMUNE_XMLATTR |
private static char[] |
IMMUNE_XPATH |
private JavaScriptCodec |
javaScriptCodec |
private Logger |
logger |
private PercentCodec |
percentCodec |
private static Encoder |
singletonInstance |
private VBScriptCodec |
vbScriptCodec |
private XMLEntityCodec |
xmlCodec |
CHAR_ALPHANUMERICS, CHAR_DIGITS, CHAR_LETTERS, CHAR_LOWERS, CHAR_PASSWORD_DIGITS, CHAR_PASSWORD_LETTERS, CHAR_PASSWORD_LOWERS, CHAR_PASSWORD_SPECIALS, CHAR_PASSWORD_UPPERS, CHAR_SPECIALS, CHAR_UPPERS| Modifier | Constructor and Description |
|---|---|
private |
DefaultEncoder()
Instantiates a new DefaultEncoder
|
|
DefaultEncoder(java.util.List<java.lang.String> codecNames) |
| Modifier and Type | Method and Description |
|---|---|
java.lang.String |
canonicalize(java.lang.String input)
This method is equivalent to calling
|
java.lang.String |
canonicalize(java.lang.String input,
boolean strict)
This method is the equivalent to calling
|
java.lang.String |
canonicalize(java.lang.String input,
boolean restrictMultiple,
boolean restrictMixed)
Canonicalization is simply the operation of reducing a possibly encoded
string down to its simplest form.
|
java.lang.String |
decodeForHTML(java.lang.String input)
Decodes HTML entities.
|
byte[] |
decodeFromBase64(java.lang.String input)
Decode data encoded with BASE-64 encoding.
|
java.lang.String |
decodeFromURL(java.lang.String input)
Decode from URL.
|
java.lang.String |
encodeForBase64(byte[] input,
boolean wrap)
Encode for Base64.
|
java.lang.String |
encodeForCSS(java.lang.String input)
Encode data for use in Cascading Style Sheets (CSS) content.
|
java.lang.String |
encodeForDN(java.lang.String input)
Encode data for use in an LDAP distinguished name.
|
java.lang.String |
encodeForHTML(java.lang.String input)
Encode data for use in HTML using HTML entity encoding
|
java.lang.String |
encodeForHTMLAttribute(java.lang.String input)
Encode data for use in HTML attributes.
|
java.lang.String |
encodeForJavaScript(java.lang.String input)
Encode data for insertion inside a data value or function argument in JavaScript.
|
java.lang.String |
encodeForLDAP(java.lang.String input)
Encode data for use in LDAP queries.
|
java.lang.String |
encodeForOS(Codec codec,
java.lang.String input)
Encode for an operating system command shell according to the selected codec (appropriate codecs include the WindowsCodec and UnixCodec).
|
java.lang.String |
encodeForSQL(Codec codec,
java.lang.String input)
Encode input for use in a SQL query, according to the selected codec
(appropriate codecs include the MySQLCodec and OracleCodec).
|
java.lang.String |
encodeForURL(java.lang.String input)
Encode for use in a URL.
|
java.lang.String |
encodeForVBScript(java.lang.String input)
Encode data for insertion inside a data value in a Visual Basic script.
|
java.lang.String |
encodeForXML(java.lang.String input)
Encode data for use in an XML element.
|
java.lang.String |
encodeForXMLAttribute(java.lang.String input)
Encode data for use in an XML attribute.
|
java.lang.String |
encodeForXPath(java.lang.String input)
Encode data for use in an XPath query.
|
static Encoder |
getInstance() |
private static volatile Encoder singletonInstance
private java.util.List codecs
private HTMLEntityCodec htmlCodec
private XMLEntityCodec xmlCodec
private PercentCodec percentCodec
private JavaScriptCodec javaScriptCodec
private VBScriptCodec vbScriptCodec
private CSSCodec cssCodec
private final Logger logger
private static final char[] IMMUNE_HTML
private static final char[] IMMUNE_HTMLATTR
private static final char[] IMMUNE_CSS
private static final char[] IMMUNE_JAVASCRIPT
private static final char[] IMMUNE_VBSCRIPT
private static final char[] IMMUNE_XML
private static final char[] IMMUNE_SQL
private static final char[] IMMUNE_OS
private static final char[] IMMUNE_XMLATTR
private static final char[] IMMUNE_XPATH
private DefaultEncoder()
public DefaultEncoder(java.util.List<java.lang.String> codecNames)
public static Encoder getInstance()
public java.lang.String canonicalize(java.lang.String input)
Encoder.canonicalize(input, restrictMultiple, restrictMixed);The default values for restrictMultiple and restrictMixed come from ESAPI.properties
Encoder.AllowMultipleEncoding=false Encoder.AllowMixedEncoding=false
canonicalize in interface Encoderinput - the text to canonicalizecanonicalize,
W3C specificationspublic java.lang.String canonicalize(java.lang.String input,
boolean strict)
Encoder.canonicalize(input, strict, strict);
canonicalize in interface Encoderinput - the text to canonicalizestrict - true if checking for multiple and mixed encoding is desired, false otherwisecanonicalize,
W3C specificationspublic java.lang.String canonicalize(java.lang.String input,
boolean restrictMultiple,
boolean restrictMixed)
Everyone says you shouldn't do validation without canonicalizing the data first. This is easier said than done. The canonicalize method can be used to simplify just about any input down to its most basic form. Note that canonicalize doesn't handle Unicode issues, it focuses on higher level encoding and escaping schemes. In addition to simple decoding, canonicalize also handles:
Using canonicalize is simple. The default is just...
String clean = ESAPI.encoder().canonicalize( request.getParameter("input"));
You need to decode untrusted data so that it's safe for ANY downstream interpreter or decoder. For
example, if your data goes into a Windows command shell, then into a database, and then to a browser,
you're going to need to decode for all of those systems. You can build a custom encoder to canonicalize
for your application like this...
ArrayList list = new ArrayList();
list.add( new WindowsCodec() );
list.add( new MySQLCodec() );
list.add( new PercentCodec() );
Encoder encoder = new DefaultEncoder( list );
String clean = encoder.canonicalize( request.getParameter( "input" ));
In ESAPI, the Validator uses the 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.
String input = request.getParameter( "name" );
String name = ESAPI.validator().isValidInput( "test", input, "FirstName", 20, false);
However, the default canonicalize() method only decodes HTMLEntity, percent (URL) encoding, and JavaScript
encoding. If you'd like to use a custom canonicalizer with your validator, that's pretty easy too.
... setup custom encoder as above
Validator validator = new DefaultValidator( encoder );
String input = request.getParameter( "name" );
String name = validator.isValidInput( "test", input, "name", 20, false);
Although ESAPI is able to canonicalize multiple, mixed, or nested encoding, it's safer to not accept
this stuff in the first place. In ESAPI, the default is "strict" mode that throws an IntrusionException
if it receives anything not single-encoded with a single scheme. This is configurable
in ESAPI.properties using the properties:
Encoder.AllowMultipleEncoding=false Encoder.AllowMixedEncoding=falseThis method allows you to override the default behavior by directly specifying whether to restrict multiple or mixed encoding. Even if you disable restrictions, you'll still get warning messages in the log about each multiple encoding and mixed encoding received.
// disabling strict mode to allow mixed encoding
String url = ESAPI.encoder().canonicalize( request.getParameter("url"), false, false);
canonicalize in interface Encoderinput - the text to canonicalizerestrictMultiple - true if checking for multiple encoding is desired, false otherwiserestrictMixed - true if checking for mixed encoding is desired, false otherwisepublic java.lang.String encodeForHTML(java.lang.String input)
Note that the following characters: 00-08, 0B-0C, 0E-1F, and 7F-9F
cannot be used in HTML.
encodeForHTML in interface Encoderinput - the text to encode for HTMLpublic java.lang.String decodeForHTML(java.lang.String input)
decodeForHTML in interface Encoderinput - the String to decodeStringpublic java.lang.String encodeForHTMLAttribute(java.lang.String input)
encodeForHTMLAttribute in interface Encoderinput - the text to encode for an HTML attributepublic java.lang.String encodeForCSS(java.lang.String input)
encodeForCSS in interface Encoderinput - the text to encode for CSSpublic java.lang.String encodeForJavaScript(java.lang.String input)
<script>
window.setInterval('<%= EVEN IF YOU ENCODE UNTRUSTED DATA YOU ARE XSSED HERE %>');
</script>
encodeForJavaScript in interface Encoderinput - the text to encode for JavaScriptpublic java.lang.String encodeForVBScript(java.lang.String input)
encodeForVBScript in interface Encoderinput - the text to encode for VBScriptpublic java.lang.String encodeForSQL(Codec codec, java.lang.String input)
encodeForSQL in interface Encodercodec - a Codec that declares which database 'input' is being encoded for (ie. MySQL, Oracle, etc.)input - the text to encode for SQLpublic java.lang.String encodeForOS(Codec codec, java.lang.String input)
encodeForOS in interface Encodercodec - a Codec that declares which operating system 'input' is being encoded for (ie. Windows, Unix, etc.)input - the text to encode for the command shellpublic java.lang.String encodeForLDAP(java.lang.String input)
encodeForLDAP in interface Encoderinput - the text to encode for LDAPpublic java.lang.String encodeForDN(java.lang.String input)
encodeForDN in interface Encoderinput - the text to encode for an LDAP distinguished namepublic java.lang.String encodeForXPath(java.lang.String input)
encodeForXPath in interface Encoderinput - the text to encode for XPathpublic java.lang.String encodeForXML(java.lang.String input)
The use of a real XML parser is strongly encouraged. However, in the hopefully rare case that you need to make sure that data is safe for inclusion in an XML document and cannot use a parse, this method provides a safe mechanism to do so.
encodeForXML in interface Encoderinput - the text to encode for XMLpublic java.lang.String encodeForXMLAttribute(java.lang.String input)
The use of a real XML parser is highly encouraged. However, in the hopefully rare case that you need to make sure that data is safe for inclusion in an XML document and cannot use a parse, this method provides a safe mechanism to do so.
encodeForXMLAttribute in interface Encoderinput - the text to encode for use as an XML attributepublic java.lang.String encodeForURL(java.lang.String input)
throws EncodingException
encodeForURL in interface Encoderinput - the text to encode for use in a URLEncodingException - if encoding failspublic java.lang.String decodeFromURL(java.lang.String input)
throws EncodingException
decodeFromURL in interface Encoderinput - the text to decode from an encoded URLEncodingException - if decoding failspublic java.lang.String encodeForBase64(byte[] input,
boolean wrap)
encodeForBase64 in interface Encoderinput - the text to encode for Base64wrap - the encoder will wrap lines every 64 characters of outputpublic byte[] decodeFromBase64(java.lang.String input)
throws java.io.IOException
decodeFromBase64 in interface Encoderinput - the Base64 text to decodejava.io.IOException