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

Method Detail

getValidInteger

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

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

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

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

@NotNull
@NotNull java.lang.String getValidHref(@Nullable
                                                @Nullable 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

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

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

@Nullable
@Nullable java.lang.String getValidCSSColor(@Nullable
                                                      @Nullable java.lang.String color,
                                                      @Nullable
                                                      @Nullable 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(@Nullable
                                          @Nullable java.lang.String comment,
                                          @Nullable
                                          @Nullable 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(@Nullable
                              @Nullable java.lang.String json,
                              @Nullable
                              @Nullable 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(@Nullable
                             @Nullable java.lang.String xml,
                             @Nullable
                             @Nullable 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

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

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

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

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

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

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

@NotNull
@NotNull java.lang.String filterHTML(@Nullable
                                              @Nullable 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