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

## Method Details

### getValidInteger

@Nullable @Nullable Integer getValidInteger(@Nullable @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 @Nullable Long getValidLong(@Nullable @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 @Nullable Double getValidDouble(@Nullable @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 @Nullable String getValidDimension(@Nullable @Nullable String dimension, @Nullable @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

@NotNull @NotNull String getValidHref(@Nullable @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 @Nullable String getValidJSToken(@Nullable @Nullable String token, @Nullable @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 @Nullable String getValidStyleToken(@Nullable @Nullable String token, @Nullable @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 @Nullable String getValidCSSColor(@Nullable @Nullable String color, @Nullable @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 @Nullable String comment, @Nullable @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 @Nullable String json, @Nullable @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 @Nullable String xml, @Nullable @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 @Nullable String encodeForHTML(@Nullable @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 @Nullable String encodeForHTMLAttr(@Nullable @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 @Nullable String encodeForXML(@Nullable @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 @Nullable String encodeForXMLAttr(@Nullable @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 @Nullable String encodeForJSString(@Nullable @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 @Nullable String encodeForCSSString(@Nullable @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

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