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