com.google.template.soy.parsepasses.contextautoesc

Enum Context.UriType

java.lang.Object

java.lang.Enum<Context.UriType>

com.google.template.soy.parsepasses.contextautoesc.Context.UriType

All Implemented Interfaces:

Serializable, Comparable<Context.UriType>

Enclosing class:

Context

public static enum Context.UriType
extends Enum<Context.UriType>

Describes the type or context of a URI that is currently being or about to be parsed.

This distinguishes between the types of URI safety concerns, which vary between images, scripts, and other types.

Enum Constant Summary

Enum Constants

Enum Constant and Description
MEDIA Image URL type.
NONE Not in or about to be in a URI.
NORMAL General URI context suitable for most URI types.
TRUSTED_RESOURCE A URI which loads resources.
TRUSTED_RESOURCE_BLOCK Same as TRUSTED_RESOURCE but with slightly different semantics.

Method Summary

Modifier and Type	Method and Description
static Context.UriType	valueOf(String name) Returns the enum constant of this type with the specified name.
static Context.UriType[]	values() Returns an array containing the constants of this enum type, in the order they are declared.

Methods inherited from class java.lang.Enum

clone, compareTo, equals, finalize, getDeclaringClass, hashCode, name, ordinal, toString, valueOf

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Enum Constant Detail

NONE

public static final Context.UriType NONE

Not in or about to be in a URI.

Note the URI type can be set even if we haven't entered the URI itself yet.

NORMAL

public static final Context.UriType NORMAL

General URI context suitable for most URI types.

The biggest use-case here is for anchors, where we want to prevent Javascript URLs that can cause XSS. However, this grabs other types of URIs such as stylesheets, prefetch, SEO metadata, and attributes that look like they're supposed to contain URIs but might just be harmless metadata because they end with "url".

It's expected that this will be split up over time to address the different safety levels of the different URI types.

MEDIA

public static final Context.UriType MEDIA

Image URL type.

Here, we can relax some some rules. For example, a data URI in an image is unlikely to do anything that loading an image from a 3rd party http/https site.

At present, note that Soy doesn't do anything to prevent referer[r]er leakage. At some future point, we may want to provide configuration options to avoid 3rd party or http-in-the-clear image loading.

In the future, this might also encompass video and audio, if we can find ways to reduce the risk of social engineering.

TRUSTED_RESOURCE

public static final Context.UriType TRUSTED_RESOURCE

A URI which loads resources. This is intended to be used in scripts, stylesheets, etc which should not be in attacker control.

TRUSTED_RESOURCE_BLOCK

public static final Context.UriType TRUSTED_RESOURCE_BLOCK

Same as TRUSTED_RESOURCE but with slightly different semantics.

This is applied to kind="trusted_resource_uri" blocks/templates and it changes the semantics for composing a trusted resource uri.

• Constant strings are allowed
• If the uri has a fixed scheme+host+path, then we can allow the remaining parts to be interpolated as long as they are percent encoded.
• If the prefix is dynamic then we require it to be a trusted_resource_uri.

These semantics are not compatible with the current TRUSTED_RESOURCE because that mode requires every part to be a trusted_resource_uri even though concatenating multiple such URIs is not obviously safe.

TODO(b/72493024): apply these same, superior semantics to TRUSTED_RESOURCE

Method Detail

values

public static Context.UriType[] values()

Returns an array containing the constants of this enum type, in the order they are declared. This method may be used to iterate over the constants as follows:

for (Context.UriType c : Context.UriType.values())
    System.out.println(c);

Returns:

an array containing the constants of this enum type, in the order they are declared

valueOf

public static Context.UriType valueOf(String name)

Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)

Parameters:

name - the name of the enum constant to be returned.

Returns:

the enum constant with the specified name

Throws:

IllegalArgumentException - if this enum type has no constant with the specified name

NullPointerException - if the argument is null