org.apache.sling.xss

## Interface XSSAPI

All Known Implementing Classes:
  XSSAPIImpl

    @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

All Methods Instance Methods Abstract Methods Deprecated Methods
`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).
`XSSAPI` `getRequestSpecificAPI(org.apache.sling.api.SlingHttpServletRequest request)` Deprecated.
`XSSAPI` `getResourceResolverSpecificAPI(org.apache.sling.api.resource.ResourceResolver resourceResolver)` Deprecated.
`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

#### getRequestSpecificAPI

    @Deprecated
    XSSAPI getRequestSpecificAPI(org.apache.sling.api.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(org.apache.sling.api.resource.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.