|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
public interface Encoder
The Encoder interface contains a number of methods for decoding input and encoding output so that it will be safe for a variety of interpreters. To prevent double-encoding, callers should make sure input does not already contain encoded characters by calling canonicalize. Validator implementations should call canonicalize on user input before validating to prevent encoded attacks.
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:
Field Summary | |
---|---|
static char[] |
CHAR_ALPHANUMERICS
Deprecated. Use EncoderConstants.CHAR_ALPHANUMERICS instead |
static char[] |
CHAR_DIGITS
Deprecated. Use EncoderConstants.CHAR_DIGITS instead |
static char[] |
CHAR_LETTERS
Deprecated. Use EncoderConstants.CHAR_LETTERS instead |
static char[] |
CHAR_LOWERS
Deprecated. Use EncoderConstants.CHAR_LOWERS instead |
static char[] |
CHAR_PASSWORD_DIGITS
Deprecated. Use EncoderConstants.CHAR_PASSWORD_DIGITS instead |
static char[] |
CHAR_PASSWORD_LETTERS
Deprecated. Use EncoderConstants.CHAR_PASSWORD_LETTERS instead |
static char[] |
CHAR_PASSWORD_LOWERS
Deprecated. Use EncoderConstants.CHAR_PASSWORD_LOWERS instead |
static char[] |
CHAR_PASSWORD_SPECIALS
Deprecated. Use EncoderConstants.CHAR_PASSWORD_SPECIALS instead |
static char[] |
CHAR_PASSWORD_UPPERS
Deprecated. Use EncoderConstants.CHAR_PASSWORD_UPPERS instead |
static char[] |
CHAR_SPECIALS
Deprecated. Use EncoderConstants.CHAR_SPECIALS instead |
static char[] |
CHAR_UPPERS
Deprecated. Use EncoderConstants.CHAR_UPPERS instead |
Method Summary | |
---|---|
java.lang.String |
canonicalize(java.lang.String input)
This method is equivalent to calling |
java.lang.String |
canonicalize(java.lang.String input,
boolean strict)
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. |
Field Detail |
---|
@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
insteadMethod Detail |
---|
java.lang.String canonicalize(java.lang.String input)
Encoder.canonicalize(input, true);
input
- the text to canonicalize
java.lang.String canonicalize(java.lang.String input, boolean strict)
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. Currently this is not configurable in ESAPI.properties, but it probably should be. Even if you disable "strict" mode, 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);
input
- the text to canonicalizestrict
- true if checking for double encoding is desired, false otherwise
java.lang.String encodeForCSS(java.lang.String input)
input
- the text to encode for CSS
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.
input
- the text to encode for HTML
java.lang.String decodeForHTML(java.lang.String input)
input
- the String
to decode
String
java.lang.String encodeForHTMLAttribute(java.lang.String input)
input
- the text to encode for an HTML attribute
java.lang.String encodeForJavaScript(java.lang.String input)
input
- the text to encode for JavaScript
java.lang.String encodeForVBScript(java.lang.String input)
input
- the text to encode for VBScript
java.lang.String encodeForSQL(Codec codec, java.lang.String input)
codec
- a Codec that declares which database 'input' is being encoded for (ie. MySQL, Oracle, etc.)input
- the text to encode for SQL
java.lang.String encodeForOS(Codec codec, java.lang.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 shell
java.lang.String encodeForLDAP(java.lang.String input)
input
- the text to encode for LDAP
java.lang.String encodeForDN(java.lang.String input)
input
- the text to encode for an LDAP distinguished name
java.lang.String encodeForXPath(java.lang.String input)
input
- the text to encode for XPath
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.
input
- the text to encode for XML
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.
input
- the text to encode for use as an XML attribute
java.lang.String encodeForURL(java.lang.String input) throws EncodingException
input
- the text to encode for use in a URL
EncodingException
- if encoding failsjava.lang.String decodeFromURL(java.lang.String input) throws EncodingException
input
- the text to decode from an encoded URL
EncodingException
- if decoding failsjava.lang.String encodeForBase64(byte[] input, boolean wrap)
input
- the text to encode for Base64wrap
- the encoder will wrap lines every 64 characters of output
byte[] decodeFromBase64(java.lang.String input) throws java.io.IOException
input
- the Base64 text to decode
java.io.IOException
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |