Package org.faceless.publisher.type

Interface EgressFilter

public interface EgressFilter

An interface which can be used to limit access to a resource at a particular URL. This can be set on the ReportFactory via ReportFactory.setEgressFilter(org.faceless.publisher.type.EgressFilter)

Field Summary

Fields

Modifier and Type	Field	Description
static final boolean	DEBUG
static final EgressFilter	DEFAULT	An EgressFilter equivalent to EgressFilter.parse("trustworthy or from-file or not file or from-api") that has the following restrictions: special URLs such as those with the schemes about: or data: can always be accessed URLs specified programatically (by way of an API call) can always be accessed file and jar URLs can only ever be accessed from file and jar URLs otherwise all access is allowed

Method Summary

Modifier and Type	Method	Description
static EgressFilter	and(EgressFilter... filters)	Return an EgressFilter built from a sequence of other EgressFilters.
static EgressFilter	matchOrReplace(Pattern pattern, String replace)	Return an EgressFilter the equivalent of match(pattern) or replace(pattern, replace) without having to worry about escaping.
static EgressFilter	not(EgressFilter a)	Return an EgressFilter which "inverts" the supplied filter.
static EgressFilter	or(EgressFilter... filters)	Return an EgressFilter built from a sequence of other EgressFilters.
static EgressFilter	parse(String s)	Parse an expression string describing an EgressFilter.
static EgressFilter	path(Path... path)	Return an EgressFilter the equivalent of path(path...), without having to worry about escaping the path.
URL2	rewrite(URL2 url, URL2 from)	This method will be supplied with the URL about to be loaded, and the URL of the document, stylesheet, other resource loading it.
static EgressFilter	then(EgressFilter a, EgressFilter b)	Return an EgressFilter which implements the "then" logical operation.

Field Details

DEBUG

static final boolean DEBUG

DEFAULT

static final EgressFilter DEFAULT

An EgressFilter equivalent to EgressFilter.parse("trustworthy or from-file or not file or from-api") that has the following restrictions:

• special URLs such as those with the schemes about: or data: can always be accessed
• URLs specified programatically (by way of an API call) can always be accessed
• file and jar URLs can only ever be accessed from file and jar URLs
• otherwise all access is allowed

Method Details

parse

static EgressFilter parse(String s)

Parse an expression string describing an EgressFilter. The expression uses the terms "and", "or", "not", "then" (for the implies logical condition) and parentheses to group filters, and allows several individual filters to be named. They are:

• relative - the URL has the same scheme, host and port as the from-URL
• trustworthy - the URL is potentially trustworthy (it has a scheme of data, about, or some others used internally by BFO Publisher
• file - the URL has a scheme of file, jar or anything else that would result in file-system access
• network - the URL has a scheme of http, https, ftp or anything else that would result in -system access
• lan - a subset of network that matches only non-routable addresses such as http://127.0.0.1, http://192.168.0.1, http://server.local, http://server, http://[::1], http://[fd02::1] or http://169.254.0.1
• internet - a subset of network that matches only routable addresses: the opposite of lan
• from-file - as for file but tests the from-URL
• from-network - as for network but tests the from-URL
• from-lan - as for lan but tests the from-URL
• from-internet - as for internet but tests the from-URL
• from-api - if the URL was supplied by an API call or from the web-service. Should normally be true
• path(arg ...) - if the URL is a scheme of file, it's path must begin with one of the arguments (non-file URLs are always accepted)
• type(arg ...) - if the URL is a scheme of file, it's Media-Type must match one of the arguments (non-file URLs are always accepted)
• scheme(arg ...) - the URL scheme must match one of the arguments
• from-scheme(arg ...) - the from-URL scheme must match one of the arguments
• match(search) - the URL must match the search argument, which is a Java-syntax regular expression
• replace(search, replace) - the URL is modified by replacing every subsequence that matches the regular expression search with the given replacement string
• default - shorthand for the DEFAULT policy
• fail - the URL is not accepted

Note the "from-api" should normally be accepted for proper use. Some examples:

• trustworthy or from-file or not file or from-api
  The default policy, which always allows trustworthy URLs, but only allows file access from other file URLs
• trustworthy or from-file or (lan and from-lan) or (not file and not lan)
  Similar to the default policy, but disallows access to local URLs unless the source is also a local URL
• default and type("image/*", "font/*", "text/css")
  Restricts the default policy to only allow image, font and CSS files from the local filesystem
• default and path("/www/public")
  Restricts the default policy to only allow files from a certain directory
• default and not scheme("pkcs11")
  Restricts the default policy to always disallow PKCS#11 URLs
• default and replace("^(http|https)://a.example.com)", "$1://b.example.com")
  Rewrite any HTTP or HTTPS URLs for a.example.com to b.example.com
• (match("http://evil.com) then fail) or default
  Always disallow references to a particular URL, but otherwise use the default policy

Since:

1.4

and

static EgressFilter and(EgressFilter... filters)

Return an EgressFilter built from a sequence of other EgressFilters. Each is applied in turn, so if any of the filters disallows the URL it will be disallowed.

Parameters:

filters - a sequence of one or more EgressFilters

Returns:

an EgressFilter combining the list

Since:

1.4

or

static EgressFilter or(EgressFilter... filters)

Return an EgressFilter built from a sequence of other EgressFilters. Each is checked in turn, and the first to return a non-null value will be used as the value for this filter. returned immediately.

Parameters:

filters - a sequence of one or more EgressFilters

Returns:

an EgressFilter combining the list

Since:

1.4

not

static EgressFilter not(EgressFilter a)

Return an EgressFilter which "inverts" the supplied filter. The rewrite(url, from) method looks like return filter.rewrite(url, from) == null ? url : null

Parameters:

filter - the filter to invert

Returns:

an EgressFilter inverting the list

Since:

1.4

then

static EgressFilter then(EgressFilter a,
 EgressFilter b)

Return an EgressFilter which implements the "then" logical operation. The rewrite(url, from) method looks like return a.rewrite(url, from) != null ? b.rewrite(url, from) : url

Parameters:

a - the filter to test the url

b - the filter to apply to the URL if the first filter returns not-null

Returns:

an EgressFilter implementing the described operation

Since:

1.4

rewrite

URL2 rewrite(URL2 url,
 URL2 from)

This method will be supplied with the URL about to be loaded, and the URL of the document, stylesheet, other resource loading it. It can return the URL as it is to load it, a rewritten URL to load a new resource instead, or null to disallow the load.

Parameters:

url - the URL being loaded

from - the URL that is the origin of the URL being loaded - the URL of the document or stylesheet.

Returns:

the URL to load, or null to disallow access

path

static EgressFilter path(Path... path)

Return an EgressFilter the equivalent of path(path...), without having to worry about escaping the path.

Parameters:

path - a list of zero or more paths to match against

Returns:

the EgressFilter

Since:

1.5

matchOrReplace

static EgressFilter matchOrReplace(Pattern pattern,
 String replace)

Return an EgressFilter the equivalent of match(pattern) or replace(pattern, replace) without having to worry about escaping.

Parameters:

pattern - the pattern

replace - if not null this the replace parameter, otherwise this is a match

Returns:

the EgressFilter

Since:

1.5