org.apache.sling.xss

Interface XSSAPI

public interface XSSAPI

A service providing validators and encoders for XSS protection during the composition of HTML pages.

Note: in general, validators are safer than encoders. Encoding only ensures that content within the encoded context cannot break out of said context. It requires that there be a context (for instance, a string context in Javascript), and that damage cannot be done from within the context (for instance, a javascript: URL within a href attribute.

When in doubt, use a validator.

Method Summary

Modifier and Type	Method and Description
java.lang.String	encodeForCSSString(java.lang.String source) Encodes a source string for writing to CSS string content.
java.lang.String	encodeForHTML(java.lang.String source) Encodes a source string for HTML element content.
java.lang.String	encodeForHTMLAttr(java.lang.String source) Encodes a source string for writing to an HTML attribute value.
java.lang.String	encodeForJSString(java.lang.String source) Encodes a source string for writing to JavaScript string content.
java.lang.String	encodeForXML(java.lang.String source) Encodes a source string for XML element content.
java.lang.String	encodeForXMLAttr(java.lang.String source) Encodes a source string for writing to an XML attribute value.
java.lang.String	filterHTML(java.lang.String source) Filters potentially user-contributed HTML to meet the AntiSamy policy rules currently in effect for HTML output (see the XSSFilter service for details).
XSSAPI	getRequestSpecificAPI(SlingHttpServletRequest request) Deprecated.
XSSAPI	getResourceResolverSpecificAPI(ResourceResolver resourceResolver) Deprecated.
java.lang.String	getValidCSSColor(java.lang.String color, java.lang.String defaultColor) Validate a CSS color value.
java.lang.String	getValidDimension(java.lang.String dimension, java.lang.String defaultValue) Validate a string which should contain a dimension, returning a default value if the source is empty, can't be parsed, or contains XSS risks.
java.lang.Double	getValidDouble(java.lang.String source, double defaultValue) Validate a string which should contain an double, returning a default value if the source is null, empty, can't be parsed, or contains XSS risks.
java.lang.String	getValidHref(java.lang.String url) Sanitizes a URL for writing as an HTML href or src attribute value.
java.lang.Integer	getValidInteger(java.lang.String integer, int defaultValue) Validate a string which should contain an integer, returning a default value if the source is null, empty, can't be parsed, or contains XSS risks.
java.lang.String	getValidJSON(java.lang.String json, java.lang.String defaultJson) Validate a JSON string
java.lang.String	getValidJSToken(java.lang.String token, java.lang.String defaultValue) Validate a Javascript token.
java.lang.Long	getValidLong(java.lang.String source, long defaultValue) Validate a string which should contain a long, returning a default value if the source is null, empty, can't be parsed, or contains XSS risks.
java.lang.String	getValidMultiLineComment(java.lang.String comment, java.lang.String defaultComment) Validate multi-line comment to be used inside a <script>...</script> or <style>...</style> block.
java.lang.String	getValidStyleToken(java.lang.String token, java.lang.String defaultValue) Validate a style/CSS token.
java.lang.String	getValidXML(java.lang.String xml, java.lang.String defaultXml) Validate an XML string

Method Detail

getValidInteger

java.lang.Integer getValidInteger(java.lang.String integer,
                                  int defaultValue)

Validate a string which should contain an integer, returning a default value if the source is null, empty, can't be parsed, or contains XSS risks.

Parameters:

integer - the source integer

defaultValue - a default value if the source can't be used, is null or an empty string

Returns:

a sanitized integer

getValidLong

java.lang.Long getValidLong(java.lang.String source,
                            long defaultValue)

Validate a string which should contain a long, returning a default value if the source is null, empty, can't be parsed, or contains XSS risks.

Parameters:

source - the source long

defaultValue - a default value if the source can't be used, is null or an empty string

Returns:

a sanitized integer

getValidDouble

java.lang.Double getValidDouble(java.lang.String source,
                                double defaultValue)

Validate a string which should contain an double, returning a default value if the source is null, empty, can't be parsed, or contains XSS risks.

Parameters:

source - the source double

defaultValue - a default value if the source can't be used, is null or an empty string

Returns:

a sanitized double

getValidDimension

java.lang.String getValidDimension(java.lang.String dimension,
                                   java.lang.String defaultValue)

Validate a string which should contain a dimension, returning a default value if the source is empty, can't be parsed, or contains XSS risks. Allows integer dimensions and the keyword "auto".

Parameters:

dimension - the source dimension

defaultValue - a default value if the source can't be used, is null or an empty string

Returns:

a sanitized dimension

getValidHref

java.lang.String getValidHref(java.lang.String url)

Sanitizes a URL for writing as an HTML href or src attribute value.

Parameters:

url - the source URL

Returns:

a sanitized URL (possibly empty)

getValidJSToken

java.lang.String getValidJSToken(java.lang.String token,
                                 java.lang.String defaultValue)

Validate a Javascript token. The value must be either a single identifier, a literal number, or a literal string.

Parameters:

token - the source token

defaultValue - a default value to use if the source is null, an empty string, or doesn't meet validity constraints.

Returns:

a string containing a single identifier, a literal number, or a literal string token

getValidStyleToken

java.lang.String getValidStyleToken(java.lang.String token,
                                    java.lang.String defaultValue)

Validate a style/CSS token. Valid CSS tokens are specified at http://www.w3.org/TR/css3-syntax/

Parameters:

token - the source token

defaultValue - a default value to use if the source is null, an empty string, or doesn't meet validity constraints.

Returns:

a string containing sanitized style token

getValidCSSColor

java.lang.String getValidCSSColor(java.lang.String color,
                                  java.lang.String defaultColor)

Validate a CSS color value. Color values as specified at http://www.w3.org/TR/css3-color/#colorunits are safe and definitively allowed. Vulnerable constructs will be disallowed. Currently known vulnerable constructs include url(...), expression(...), and anything with a semicolon.

Parameters:

color - the color value to be used.

defaultColor - a default value to use if the input color value is null, an empty string, doesn't meet validity constraints.

Returns:

a string a css color value.

getValidMultiLineComment

java.lang.String getValidMultiLineComment(java.lang.String comment,
                                          java.lang.String defaultComment)

Validate multi-line comment to be used inside a <script>...</script> or <style>...</style> block. Multi-line comment end block is disallowed.

Parameters:

comment - the comment to be used

defaultComment - a default value to use if the comment is null or not valid.

Returns:

a valid multi-line comment

getValidJSON

java.lang.String getValidJSON(java.lang.String json,
                              java.lang.String defaultJson)

Validate a JSON string

Parameters:

json - the JSON string to validate

defaultJson - the default value to use if json is null or not valid

Returns:

a valid JSON string

getValidXML

java.lang.String getValidXML(java.lang.String xml,
                             java.lang.String defaultXml)

Validate an XML string

Parameters:

xml - the XML string to validate

defaultXml - the default value to use if xml is null or not valid

Returns:

a valid XML string

encodeForHTML

java.lang.String encodeForHTML(java.lang.String source)

Encodes a source string for HTML element content. DO NOT USE FOR WRITING ATTRIBUTE VALUES!

Parameters:

source - the input to encode

Returns:

an encoded version of the source

encodeForHTMLAttr

java.lang.String encodeForHTMLAttr(java.lang.String source)

Encodes a source string for writing to an HTML attribute value. DO NOT USE FOR ACTIONABLE ATTRIBUTES (href, src, event handlers); YOU MUST USE A VALIDATOR FOR THOSE!

Parameters:

source - the input to encode

Returns:

an encoded version of the source

encodeForXML

java.lang.String encodeForXML(java.lang.String source)

Encodes a source string for XML element content. DO NOT USE FOR WRITING ATTRIBUTE VALUES!

Parameters:

source - the input to encode

Returns:

an encoded version of the source

encodeForXMLAttr

java.lang.String encodeForXMLAttr(java.lang.String source)

Encodes a source string for writing to an XML attribute value.

Parameters:

source - the input to encode

Returns:

an encoded version of the source

encodeForJSString

java.lang.String encodeForJSString(java.lang.String source)

Encodes a source string for writing to JavaScript string content. DO NOT USE FOR WRITING TO ARBITRARY JAVASCRIPT; YOU MUST USE A VALIDATOR FOR THAT. (Encoding only ensures that the source material cannot break out of its context.)

Parameters:

source - the input to encode

Returns:

an encoded version of the source

encodeForCSSString

java.lang.String encodeForCSSString(java.lang.String source)

Encodes a source string for writing to CSS string content. DO NOT USE FOR WRITING OUT ARBITRARY CSS TOKENS; YOU MUST USE A VALIDATOR FOR THAT! (Encoding only ensures the source string cannot break out of its context.)

Parameters:

source - the input to encode

Returns:

an encoded version of the source

filterHTML

java.lang.String filterHTML(java.lang.String source)

Filters potentially user-contributed HTML to meet the AntiSamy policy rules currently in effect for HTML output (see the XSSFilter service for details).

Parameters:

source - a string containing the source HTML

Returns:

a string containing the sanitized HTML which may be an empty string if source is null or empty

getRequestSpecificAPI

@Deprecated
XSSAPI getRequestSpecificAPI(SlingHttpServletRequest request)

Deprecated.

Returns an XSSAPI instance capable of mapping resource URLs. EITHER THIS OR THE RESOURCERESOLVER VERSION MUST BE USED WHEN VALIDATING HREFs!

Parameters:

request - the request from which to obtain the XSSAPI

Returns:

an XSSAPI service capable of validating hrefs.

getResourceResolverSpecificAPI

@Deprecated
XSSAPI getResourceResolverSpecificAPI(ResourceResolver resourceResolver)

Deprecated.

Returns an XSSAPI instance capable of mapping resource URLs. EITHER THIS OR THE REQUEST VERSION MUST BE USED WHEN VALIDATING HREFs!

Parameters:

resourceResolver - the resolver from which to obtain the XSSAPI

Returns:

an XSSAPI service capable of validating hrefs.