It makes no sense to adopt a one-size-fits-all
approach to
filtersets: therefore, users must be able to define their own sets of
allowed
elements, as well as switch in-between doctypes of HTML.
Our goals are to let the user:
By default, users will use a doctype-based, permissive but secure whitelist. They must define a doctype, and this serves as the first method of determining a filterset.
This identifier is based on the name the W3C has given to the document type and not the DTD identifier.
This parameter is set via the configuration object:
$config->set('HTML', 'Doctype', 'XHTML 1.0 Transitional');
However, selecting this doctype doesn't mean much, because if we adhered exactly to the definition we would be letting XSS and other nasties through. HTML Purifier must, in its filterset, allow a subset of the doctype, which we shall call a filterset.
By default, HTML Purifier will use the Rich filterset, which allows as many elements as possible with untrusted sources. Other possible filtersets could be:
Extension-authors would be able to define custom filtersets for other users to use.
A possible call to select a filterset would be:
$config->set('HTML', 'Filterset', 'Rich');
Within filtersets, there are various modes of operation. These indicate variant behaviors that, while not strictly changing the allowed set of elements and attributes, will definitely affect the output. Currently, we have two modes, which may be used together:
center
tag would be turned into a div
with the CSS property
text-align:center;
, but in XHTML 1.0 Transitional
the tag would be preserved. This mode is on by default.center
tag would
be transformed in both cases. However, tags without a
reasonable standards-compliant alternative will be preserved
in their form. This mode is on by default. It may have
various levels of operation.A possible call to select modes would be:
$config->set('HTML', 'Mode', array('correctional', 'lenient'));
If modes have extra parameters, a hash might work well:
$config->set('HTML', 'Mode', array( 'correctional' => 9, // strongest level 'lenient' => true // this one's just boolean ));
Modes may possibly be wrapped up with the filterset declaration:
$config->set('HTML', 'Filterset', 'Rich: correctional, lenient');
Further investigation in this field is necessary.
If this cookie cutter approach doesn't appeal to a user, they may decide to roll their own filterset by selecting modules, tags and attributes to allow.
This would make use of the same facilities
as a filterset author would use, except that it would go under an
anonymous
filterset that would be auto-selected if any of the
relevant module/tag/attribute selection configuration directives were
non-null.
On the highest level, a user will usually be most interested in directly specifying which elements and attributes are desired. For example:
$config->set('HTML', 'AllowedElements', 'a,b,em,p,blockquote,code,i');
Attribute declarations could be merged into this declaration as such:
$config->set('HTML', 'Allowed', 'a[href,title],b,em,p[class],blockquote[cite],code,i');
...or be kept separate:
$config->set('HTML', 'AllowedAttributes', 'a.href,a.title,p.class,blockquote.cite');
Considering that, internally speaking, as mandated by the XHTML 1.1 Modularization specification, we have organized our elements around modules, considerable gymnastics will be needed to get this sort of functionality working.
A user may also specify a module to load a class of elements and attributes into their filterest:
$config->set('HTML', 'Allowed', 'Hypertext,Core');
The granularity of these modules is too coarse for
the average user (for example, the core module loads everything from
the essential p
tag to the not-so-safe h1
tag). How do we make this still a viable solution?
Because selecting each and every one of these configuration options is a chore, we may wish to offer a specialized configuration method for selecting a filterset. Possibility:
function selectFilter($doctype, $filterset, $mode)
...which is simply a light wrapper over the individual configuration calls. A custom config file format or text format could also be adopted.