org.apache.sling.xss

Interface XSSAPI

@ProviderType
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
String	encodeForCSSString(String source) Encodes a source string for writing to CSS string content.
String	encodeForHTML(String source) Encodes a source string for HTML element content.
String	encodeForHTMLAttr(String source) Encodes a source string for writing to an HTML attribute value.
String	encodeForJSString(String source) Encodes a source string for writing to JavaScript string content.
String	encodeForXML(String source) Encodes a source string for XML element content.
String	encodeForXMLAttr(String source) Encodes a source string for writing to an XML attribute value.
String	filterHTML(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).
String	getValidCSSColor(String color, String defaultColor) Validate a CSS color value.
String	getValidDimension(String dimension, 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.
Double	getValidDouble(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.
String	getValidHref(String url) Sanitizes a URL for writing as an HTML href or src attribute value.
Integer	getValidInteger(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.
String	getValidJSON(String json, String defaultJson) Validate a JSON string
String	getValidJSToken(String token, String defaultValue) Validate a Javascript token.
Long	getValidLong(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.
String	getValidMultiLineComment(String comment, String defaultComment) Validate multi-line comment to be used inside a <script>...</script> or <style>...</style> block.
String	getValidStyleToken(String token, String defaultValue) Validate a style/CSS token.
String	getValidXML(String xml, String defaultXml) Validate an XML string

Method Detail

getValidInteger

@Nullable
Integer getValidInteger(@Nullable
                                  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

@Nullable
Long getValidLong(@Nullable
                            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

@Nullable
Double getValidDouble(@Nullable
                                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

@Nullable
String getValidDimension(@Nullable
                                   String dimension,
                                   @Nullable
                                   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

@Nonnull
String getValidHref(@Nullable
                             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

@Nullable
String getValidJSToken(@Nullable
                                 String token,
                                 @Nullable
                                 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

@Nullable
String getValidStyleToken(@Nullable
                                    String token,
                                    @Nullable
                                    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

@Nullable
String getValidCSSColor(@Nullable
                                  String color,
                                  @Nullable
                                  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

String getValidMultiLineComment(@Nullable
                                String comment,
                                @Nullable
                                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

String getValidJSON(@Nullable
                    String json,
                    @Nullable
                    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

String getValidXML(@Nullable
                   String xml,
                   @Nullable
                   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

@Nullable
String encodeForHTML(@Nullable
                               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

@Nullable
String encodeForHTMLAttr(@Nullable
                                   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

@Nullable
String encodeForXML(@Nullable
                              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

@Nullable
String encodeForXMLAttr(@Nullable
                                  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

@Nullable
String encodeForJSString(@Nullable
                                   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

@Nullable
String encodeForCSSString(@Nullable
                                    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

@Nonnull
String filterHTML(@Nullable
                           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