public interface Encoder
All of the methods must use a "whitelist" or "positive" security model. For the encoding methods, this means that all characters should be encoded, except for a specific list of "immune" characters that are known to be safe.
The Encoder performs two key functions, encoding and decoding. These functions rely on a set of codecs that can be found in the org.owasp.esapi.codecs package. These include:
Modifier and Type | Method and Description |
---|---|
String |
canonicalize(String input)
This method is equivalent to calling
|
String |
canonicalize(String input,
boolean strict)
This method is the equivalent to calling
|
String |
canonicalize(String input,
boolean restrictMultiple,
boolean restrictMixed)
Canonicalization is simply the operation of reducing a possibly encoded
string down to its simplest form.
|
String |
decodeForHTML(String input)
Decodes HTML entities.
|
byte[] |
decodeFromBase64(String input)
Decode data encoded with BASE-64 encoding.
|
String |
decodeFromURL(String input)
Decode from URL.
|
String |
encodeForBase64(byte[] input,
boolean wrap)
Encode for Base64.
|
String |
encodeForCSS(String input)
Encode data for use in Cascading Style Sheets (CSS) content.
|
String |
encodeForDN(String input)
Encode data for use in an LDAP distinguished name.
|
String |
encodeForHTML(String input)
Encode data for use in HTML using HTML entity encoding
|
String |
encodeForHTMLAttribute(String input)
Encode data for use in HTML attributes.
|
String |
encodeForJavaScript(String input)
Encode data for insertion inside a data value or function argument in JavaScript.
|
String |
encodeForLDAP(String input)
Encode data for use in LDAP queries.
|
String |
encodeForOS(Codec codec,
String input)
Encode for an operating system command shell according to the selected codec (appropriate codecs include the WindowsCodec and UnixCodec).
|
String |
encodeForSQL(Codec codec,
String input)
Encode input for use in a SQL query, according to the selected codec
(appropriate codecs include the MySQLCodec and OracleCodec).
|
String |
encodeForURL(String input)
Encode for use in a URL.
|
String |
encodeForVBScript(String input)
Encode data for insertion inside a data value in a Visual Basic script.
|
String |
encodeForXML(String input)
Encode data for use in an XML element.
|
String |
encodeForXMLAttribute(String input)
Encode data for use in an XML attribute.
|
String |
encodeForXPath(String input)
Encode data for use in an XPath query.
|
@Deprecated static final char[] CHAR_LOWERS
EncoderConstants.CHAR_LOWERS
instead@Deprecated static final char[] CHAR_UPPERS
EncoderConstants.CHAR_UPPERS
instead@Deprecated static final char[] CHAR_DIGITS
EncoderConstants.CHAR_DIGITS
instead@Deprecated static final char[] CHAR_SPECIALS
EncoderConstants.CHAR_SPECIALS
instead@Deprecated static final char[] CHAR_LETTERS
EncoderConstants.CHAR_LETTERS
instead@Deprecated static final char[] CHAR_ALPHANUMERICS
EncoderConstants.CHAR_ALPHANUMERICS
instead@Deprecated static final char[] CHAR_PASSWORD_LOWERS
EncoderConstants.CHAR_PASSWORD_LOWERS
instead@Deprecated static final char[] CHAR_PASSWORD_UPPERS
EncoderConstants.CHAR_PASSWORD_UPPERS
instead@Deprecated static final char[] CHAR_PASSWORD_DIGITS
EncoderConstants.CHAR_PASSWORD_DIGITS
instead@Deprecated static final char[] CHAR_PASSWORD_SPECIALS
EncoderConstants.CHAR_PASSWORD_SPECIALS
instead@Deprecated static final char[] CHAR_PASSWORD_LETTERS
EncoderConstants.CHAR_PASSWORD_LETTERS
insteadString canonicalize(String input)
Encoder.canonicalize(input, restrictMultiple, restrictMixed);The default values for restrictMultiple and restrictMixed come from ESAPI.properties
Encoder.AllowMultipleEncoding=false Encoder.AllowMixedEncoding=false
input
- the text to canonicalizecanonicalize
,
W3C specificationsString canonicalize(String input, boolean strict)
Encoder.canonicalize(input, strict, strict);
input
- the text to canonicalizestrict
- true if checking for multiple and mixed encoding is desired, false otherwisecanonicalize
,
W3C specificationsString canonicalize(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);
input
- the text to canonicalizerestrictMultiple
- true if checking for multiple encoding is desired, false otherwiserestrictMixed
- true if checking for mixed encoding is desired, false otherwiseString encodeForCSS(String input)
input
- the text to encode for CSSString encodeForHTML(String input)
Note that the following characters: 00-08, 0B-0C, 0E-1F, and 7F-9F
cannot be used in HTML.
input
- the text to encode for HTMLString decodeForHTML(String input)
input
- the String
to decodeString
String encodeForHTMLAttribute(String input)
input
- the text to encode for an HTML attributeString encodeForJavaScript(String input)
<script> window.setInterval('<%= EVEN IF YOU ENCODE UNTRUSTED DATA YOU ARE XSSED HERE %>'); </script>
input
- the text to encode for JavaScriptString encodeForVBScript(String input)
input
- the text to encode for VBScriptString encodeForSQL(Codec codec, String input)
codec
- a Codec that declares which database 'input' is being encoded for (ie. MySQL, Oracle, etc.)input
- the text to encode for SQLString encodeForOS(Codec codec, String input)
codec
- a Codec that declares which operating system 'input' is being encoded for (ie. Windows, Unix, etc.)input
- the text to encode for the command shellString encodeForLDAP(String input)
input
- the text to encode for LDAPString encodeForDN(String input)
input
- the text to encode for an LDAP distinguished nameString encodeForXPath(String input)
input
- the text to encode for XPathString encodeForXML(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.
input
- the text to encode for XMLString encodeForXMLAttribute(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.
input
- the text to encode for use as an XML attributeString encodeForURL(String input) throws EncodingException
input
- the text to encode for use in a URLEncodingException
- if encoding failsString decodeFromURL(String input) throws EncodingException
input
- the text to decode from an encoded URLEncodingException
- if decoding failsString encodeForBase64(byte[] input, boolean wrap)
input
- the text to encode for Base64wrap
- the encoder will wrap lines every 64 characters of outputbyte[] decodeFromBase64(String input) throws IOException
input
- the Base64 text to decodeIOException
Copyright © 2016 The Open Web Application Security Project (OWASP). All rights reserved.