2 Usage
(to top)
- htmLawed should work with PHP 4.3 and higher. Either
include() the
htmLawed.php file or copy-paste the entire code.
+ htmLawed works in PHP version 4.4 or higher. Either
include() the
htmLawed.php file, or copy-paste the entire code. To use with PHP 4.3, have the following code included:
+
+
+
if(!function_exists('ctype_digit')){
+
+
+
function ctype_digit($var){
+
+
+
return ((int) $var == $var);
+
+
+
}
+
+
+
}
- To easily
test htmLawed using a form-based interface, use the provided
demo (
htmLawed.php and
htmLawedTest.php should be in the same directory on the web-server).
2.1 Simple
@@ -268,7 +293,13 @@ A PHP Labware internal utility - $processed = htmLawed($text);
- Note: If input is from a $_GET or $_POST value, and magic quotes are enabled on the PHP setup, run stripslashes() on the input before passing to htmLawed.
+ With the htmLawed class (section 1.6), usage is:
+
+
+ $processed = htmLawed::hl($text);
+
+
+ Notes: (1) If input is from a $_GET or $_POST value, and magic quotes are enabled on the PHP setup, run stripslashes() on the input before passing to htmLawed. (2) htmLawed does not have support for head-level elements, body, and the frame-level elements, frameset, frame and noframes.
By default, htmLawed will process the text allowing all valid HTML elements/tags, secure URL scheme/CSS style properties, etc. It will allow CDATA sections and HTML comments, balance tags, and ensure proper nesting of elements. Such actions can be configured using two other optional arguments -- $config and $spec:
@@ -276,9 +307,7 @@ A PHP Labware internal utility - $processed = htmLawed($text, $config, $spec);
- These extra parameters are detailed below. Some examples are shown in section 2.9.
-
- Note: For maximum protection against XSS and other scripting attacks (e.g., by disallowing Javascript code), consider using the safe parameter; see section 3.6.
+ The $config and $spec arguments are detailed below. Some examples are shown in section 2.9. For maximum protection against XSS and other scripting attacks (e.g., by disallowing Javascript code), consider using the safe parameter; see section 3.6.
@@ -318,13 +347,13 @@ A PHP Labware internal utility - section 3.4.7
0 - no measure taken *
- array("regex1", "regex2") - will ensure a rel attribute with nofollow in its value in case the href attribute value matches the regular expression pattern regex1, and/or will remove href if its value matches the regular expression pattern regex2. E.g., array("/./", "/://\W*(?!(abc\.com|xyz\.org))/"); see section 3.4.7 for more.
+ array("regex1", "regex2") - will ensure a rel attribute with nofollow in its value in case the href attribute value matches the regular expression pattern regex1, and/or will remove href if its value matches the regular expression pattern regex2. E.g., array("/./", "/://\W*(?!(abc\.com|xyz\.org))/"); see section 3.4.7 for more.
anti_mail_spam
Anti-mail-spam measure; see section 3.4.7
0 - no measure taken *
- word - @ in mail address in href attribute value is replaced with specified word
+ word - @ in mail address in href attribute value is replaced with specified word
balance
Balance tags for well-formedness and proper nesting; see section 3.3.3
@@ -368,9 +397,15 @@ A PHP Labware internal utility - section 3.4
0 - none *
- string - dictated by values in string
+ string - dictated by values in string
on* (like onfocus) attributes not allowed - "
+ direct_nest_list
+ Allow direct nesting of a list within another without requiring it to be a list item; see section 3.3.4
+
+ 0 - no *
+ 1 - yes
+
elements
Allowed HTML elements; see section 3.3
@@ -388,13 +423,13 @@ A PHP Labware internal utility - $config or $spec before htmLawed starts its main work; see section 3.7
0 - no hook function *
- name - name is name of the hook function (kses_hook ^)
+ name - name is name of the hook function (kses_hook ^)
hook_tag
Name of an optional hook function to alter tag content finalized by htmLawed; see section 3.4.9
0 - no hook function *
- name - name is name of the hook function
+ name - name is name of the hook function
keep_bad
Neutralize bad tags by converting < and > to entities, or remove them; see section 3.3.3
@@ -441,11 +476,11 @@ A PHP Labware internal utility - 1 - will auto-adjust other relevant $config parameters (indicated by " in this list)
schemes
- Array of attribute-specific, comma-separated, lower-cased list of schemes (protocols) allowed in attributes accepting URLs; * covers all unspecified attributes; see section 3.4.3
+ Array of attribute-specific, comma-separated, lower-cased list of schemes (protocols) allowed in attributes accepting URLs (or ! to deny any URL); * covers all unspecified attributes; see section 3.4.3
href: aim, feed, file, ftp, gopher, http, https, irc, mailto, news, nntp, sftp, ssh, telnet; *:file, http, https *
*: ftp, gopher, http, https, mailto, news, nntp, telnet ^
- href: aim, feed, file, ftp, gopher, http, https, irc, mailto, news, nntp, sftp, ssh, telnet; style: nil; *:file, http, https "
+ href: aim, feed, file, ftp, gopher, http, https, irc, mailto, news, nntp, sftp, ssh, telnet; style: !; *:file, http, https "
show_setting
Name of a PHP variable to assign the finalized $config and $spec values; see section 3.8
@@ -468,7 +503,7 @@ A PHP Labware internal utility - 0 - no ^
1 - remove duplicate and/or invalid ones *
- word - remove invalid ones and replace duplicate ones with new and unique ones based on the word; the admin-specified word, like my_, should begin with a letter (a-z) and can contain letters, digits, ., _, -, and :.
+ word - remove invalid ones and replace duplicate ones with new and unique ones based on the word; the admin-specified word, like my_, should begin with a letter (a-z) and can contain letters, digits, ., _, -, and :.
valid_xhtml
Magic parameter to make input the most valid XHTML without needing to specify other relevant $config parameters; see section 3.5
@@ -488,7 +523,7 @@ A PHP Labware internal utility - 2.3 Extra HTML specifications using the $spec parameter
(to top)
- The
$spec argument can be used to disallow an otherwise legal attribute for an element, or to restrict the attribute's values. This can also be helpful as a security measure (e.g., in certain versions of browsers, certain values can cause buffer overflows and denial of service attacks), or in enforcing admin policy compliance.
$spec is specified as a string of text containing one or more
rules, with multiple rules separated from each other by a semi-colon (
;). E.g.,
+ The
$spec argument of htmLawed can be used to disallow an otherwise legal attribute for an element, or to restrict the attribute's values. This can also be helpful as a security measure (e.g., in certain versions of browsers, certain values can cause buffer overflows and denial of service attacks), or in enforcing admin policies.
$spec is specified as a string of text containing one or more
rules, with multiple rules separated from each other by a semi-colon (
;). E.g.,
$spec = 'i=-*; td, tr=style, id, -*; a=id(match="/[a-z][a-z\d.:\-`"]*/i"/minval=2), href(maxlen=100/minlen=34); img=-width,-alt';
@@ -517,7 +552,7 @@ A PHP Labware internal utility -
a=-*, href, title - none except href and title
* a=-*, -id, href, title - none except href and title
- Rules regarding attribute values are optionally specified inside round brackets after attribute names in slash ('/')-separated parameter = value pairs. E.g., title(maxlen=30/minlen=5). None, or one or more of the following parameters may be specified:
+ Rules regarding attribute values are optionally specified inside round brackets after attribute names in slash ('/')-separated parameter = value pairs. E.g., title(maxlen=30/minlen=5). None or one or more of the following parameters may be specified:
* oneof - one or more choices separated by | that the value should match; if only one choice is provided, then the value must match that choice
@@ -541,7 +576,7 @@ A PHP Labware internal utility - input=title(), value(maxval=8/default=6)
Output: <input title="WIDTH" value="6" /><input title="length" value="5" />
- Rule: input=title(nomatch=$w.d$i), value(match=$em$/default=6em)
+ Rule: input=title(nomatch=%w.d%i), value(match=%em%/default=6em)
Output: <input value="10em" /><input title="length" value="6em" />
Rule: input=title(oneof=height|depth/default=depth), value(noneof=5|6)
@@ -549,14 +584,22 @@ A PHP Labware internal utility - ;, ,, /, (, ), |, ~ and space have special meanings in the rules. Words in the rules that use such characters, or the characters themselves, should be escaped by enclosing in pairs of double-quotes ("). A back-tick (`) can be used to escape a literal ". An example rule illustrating this is input=value(maxlen=30/match="/^\w/"/default="your `"ID`"").
- Note: To deny an attribute for all elements for which it is legal, $config["deny_attribute"] (see section 3.4) can be used instead of
$spec. Also, attributes can be allowed element-specifically through
$spec while being denied globally through
$config["deny_attribute"]. The
hook_tag parameter (
section 3.4.9) can also be used to implement the
$spec functionality.
+
Note: To deny an attribute for all elements for which it is legal,
$config["deny_attribute"] (see
section 3.4) can be used instead of
$spec. Also, attributes can be allowed element-specifically through
$spec while being denied globally through
$config["deny_attribute"]. The
hook_tag parameter (
section 3.4.9) can also be possibly used to implement a functionality like that achieved using
$spec functionality.
+
+
$spec can also be used to permit custom, non-standard attributes as well as custom rules for standard attributes. Thus, the following value of
$spec will permit the custom uses of the standard
rel attribute in
input (not permitted as per standards) and of a non-standard attribute,
vFlag, in
img.
+
+
+
$spec = 'img=vFlag; input=rel'
+
+
+ The attribute names can contain alphabets, colons (:) and hyphens (-), but they must start with an alphabet.
2.4 Performance time & memory usage
(to top)
- The time and memory used by htmLawed depends on its configuration and the size of the input, and the amount, nestedness and well-formedness of the HTML markup within it. In particular, tag balancing and beautification each can increase the processing time by about a quarter.
+ The time and memory consumed during text processing by htmLawed depends on its configuration, the size of the input, and the amount, nestedness and well-formedness of the HTML markup within the input. In particular, tag balancing and beautification each can increase the processing time by about a quarter.
The htmLawed
demo can be used to evaluate the performance and effects of different types of input and
$config.
@@ -565,17 +608,21 @@ A PHP Labware internal utility -
2.5 Some security risks to keep in mind
(to top)
- When setting the parameters/arguments (like those to allow certain HTML elements) for use with htmLawed, one should bear in mind that the setting may let through potentially
dangerous HTML code. (This may not be a problem if the authors are trusted.)
-
- For example, following increase security risks:
+ When setting the parameters/arguments (like those to allow certain HTML elements) for use with htmLawed, one should bear in mind that the setting may let through potentially
dangerous HTML code which is meant to steal user-data, deface a website, render a page non-functional, etc. Unless end-users, either people or software, supplying the content are completely trusted, security issues arising from the degree of HTML usage permitted through htmLawed's setting should be considered. For example, following increase security risks:
* Allowing
script,
applet,
embed,
iframe or
object elements, or certain of their attributes like
allowscriptaccess
* Allowing HTML comments (some Internet Explorer versions are vulnerable with, e.g.,
<!--[if gte IE 4]><script>alert("xss");</script><![endif]-->
- * Allowing dynamic CSS expressions (a feature of the IE browser)
+ * Allowing dynamic CSS expressions (some Internet Explorer versions are vulnerable)
+
+ * Allowing the
style attribute
+
+ To remove
unsecure HTML, code-developers using htmLawed must set
$config appropriately. E.g.,
$config["elements"] = "* -script" to deny the
script element (
section 3.3),
$config["safe"] = 1 to auto-configure ceratin htmLawed parameters for maximizing security (
section 3.6), etc.
-
Unsafe HTML can be removed by setting
$config appropriately. E.g.,
$config["elements"] = "* -script" (
section 3.3),
$config["safe"] = 1 (
section 3.6), etc.
+ Permitting the
*style* attribute brings in risks of
click-jacking,
phishing, web-page overlays, etc.,
even when the
safe parameter is enabled (see
section 3.6). Except for URLs and a few other things like CSS dynamic expressions, htmLawed currently does not check every CSS style property. It does provide ways for the code-developer implementing htmLawed to do such checks through htmLawed's
$spec argument, and through the
hook_tag parameter (see
section 3.4.8 for more). Disallowing
style completely and relying on CSS classes and stylesheet files is recommended.
+
+ htmLawed does not check or correct the character
encoding of the input it receives. In conjunction with permissive circumstances, such as when the character encoding is left undefined through HTTP headers or HTML
meta tags, this can allow for an exploit (like Google's
UTF-7/XSS vulnerability of the past).
@@ -644,7 +691,7 @@ A PHP Labware internal utility - 2.7 Tolerance for ill-written HTML
(to top)
- htmLawed can work with ill-written HTML code in the input. However, HTML that is too ill-written may not be
read as HTML, and be considered mere plain text instead. Following statements indicate the degree of
looseness that htmLawed can work with, and can be provided in instructions to writers:
+ htmLawed can work with ill-written HTML code in the input. However, HTML that is too ill-written may not be
read as HTML, and may therefore get identified as mere plain text. Following statements indicate the degree of
looseness that htmLawed can work with, and can be provided in instructions to writers:
* Tags must be flanked by
< and
> with no
> inside -- any needed
> should be put in as
>. It is possible for tag content (element name and attributes) to be spread over many lines instead of being on one. A space may be present between the tag content and
>, like
<div > and
<img / >, but not after the
<.
@@ -652,13 +699,13 @@ A PHP Labware internal utility -
 , &x07ff;) with 0 is okay as long as the number of characters between between the & and the ; does not exceed 8. All entities must end with ; though.
- * Named character entities must be properly cased. E.g., ≪ or &TILDE; will not be let through without modification.
+ * Named character entities must be properly cased. Thus, ≪ or &TILDE; will not be recognized as entities and will be neutralized.
- * HTML comments should not be inside element tags (okay between tags), and should begin with <!-- and end with -->. Characters like <, >, and & may be allowed inside depending on $config, but any --> inside should be put in as -->. Any -- inside will be automatically converted to -, and a space will be added before the comment delimiter -->.
+ * HTML comments should not be inside element tags (they can be between tags), and should begin with <!-- and end with -->. Characters like <, >, and & may be allowed inside depending on $config, but any --> inside should be put in as -->. Any -- inside will be automatically converted to -, and a space will be added before the comment delimiter -->.
* CDATA sections should not be inside element tags, and can be in element content only if plain text is allowed for that element. They should begin with <[CDATA[ and end with ]]>. Characters like <, >, and & may be allowed inside depending on $config, but any ]]> inside should be put in as ]]>.
@@ -673,22 +720,22 @@ A PHP Labware internal utility - $config["unique_ids"] not 0 and the id attribute being permitted, writers should carefully avoid using duplicate or invalid id values as even though htmLawed will correct/remove the values, the final output may not be the one desired. E.g., when <a id="home"></a><input id="home" /><label for="home"></label> is processed into
<a id="home"></a><input id="prefix_home" /><label for="home"></label>.
- * Note that even if intended HTML is lost in a highly ill-written input, the processed output will be more secure and standard-compliant.
+ * Even if intended HTML is lost from an ill-written input, the processed output will be more secure and standard-compliant.
* For URLs, unless $config["scheme"] is appropriately set, writers should avoid using escape characters or entities in schemes. E.g., http (which many browsers will read as the harmless http) may be considered bad by htmLawed.
- * htmLawed will attempt to put plain text present directly inside blockquote, form, map and noscript elements (illegal as per the specs) inside auto-generated div elements.
+ * htmLawed will attempt to put plain text present directly inside blockquote, form, map and noscript elements (illegal as per the specifications) inside auto-generated div elements.
2.8 Limitations & work-arounds
(to top)
- htmLawed's main objective is to make the input text
more standard-compliant, secure for web-page readers, and free of HTML elements and attributes considered undesirable by the administrator. Some of its current limitations, regardless of this objective, are noted below along with work-arounds.
+ htmLawed's main objective is to make the input text
more standard-compliant, secure for readers, and free of HTML elements and attributes considered undesirable by the administrator. Some of its current limitations, regardless of this objective, are noted below along with work-arounds.
- It should be borne in mind that no browser application is 100% standard-compliant, and that some of the standard specs (like asking for normalization of white-spacing within
textarea elements) are clearly wrong. Regarding security, note that
unsafe HTML code is not necessarily legally invalid.
+ It should be borne in mind that no browser application is 100% standard-compliant, and that some of the standard specifications (like asking for normalization of white-spacing within
textarea elements) are clearly wrong. Regarding security, note that
unsafe HTML code is not legally invalid per se.
- * htmLawed is meant for input that goes into the
body of HTML documents. HTML's head-level elements are not supported, nor are the frameset elements
frameset,
frame and
noframes.
+ * htmLawed is meant for input that goes into the
body of HTML documents. HTML's head-level elements are not supported, nor are the frameset elements
frameset,
frame and
noframes. Content of the latter elements can, however, be individually filtered through htmLawed.
* It cannot transform the non-standard
embed elements to the standard-compliant
object elements. Yet, it can allow
embed elements if permitted (
embed is widely used and supported). Admins can certainly use the
hook_tag parameter (
section 3.4.9) to deploy a custom embed-to-object converter function.
@@ -698,7 +745,7 @@ A PHP Labware internal utility -
width="20m" with the dimension in non-standard m is let through. Implementing universal and strict attribute value checks can make htmLawed slow and resource-intensive. Admins should look at the hook_tag parameter (section 3.4.9) or
$spec to enforce finer checks.
- * The attributes, deprecated (which can be transformed too) or not, that it supports are largely those that are in the specs. Only a few of the proprietary attributes are supported.
+ * The attributes, deprecated (which can be transformed too) or not, that it supports are largely those that are in the specifications. Only a few of the proprietary attributes are supported.
* Except for contained URLs and dynamic expressions (also optional), htmLawed does not check CSS style property values. Admins should look at using the
hook_tag parameter (
section 3.4.9) or
$spec for finer checks. Perhaps the best option is to disallow
style but allow
class attributes with the right
oneof or
match values for
class, and have the various class style properties in
.css CSS stylesheet files.
@@ -710,11 +757,11 @@ A PHP Labware internal utility -
http to https. Having absolute URLs may be a standard-requirement, e.g., when HTML is embedded in email messages, whereas altering URLs for other purposes is beyond htmLawed's goals. Admins may be able to use a custom hook function to enforce such checks (hook_tag parameter; see section 3.4.9).
- * Pairs of opening and closing tags that do not enclose any content (like
<em></em>) are not removed. This may be against the standard specs for certain elements (e.g.,
table). However, presence of such standard-incompliant code will not break the display or layout of content. Admins can also use simple regex-based code to filter out such code.
+ * Pairs of opening and closing tags that do not enclose any content (like
<em></em>) are not removed. This may be against the standard specifications for certain elements (e.g.,
table). However, presence of such standard-incompliant code will not break the display or layout of content. Admins can also use simple regex-based code to filter out such code.
- * htmLawed does not check for certain element orderings described in the standard specs (e.g., in a
table,
tbody is allowed before
tfoot). Admins may be able to use a custom hook function to enforce such checks (
hook_tag parameter; see
section 3.4.9).
+ * htmLawed does not check for certain element orderings described in the standard specifications (e.g., in a
table,
tbody is allowed before
tfoot). Admins may be able to use a custom hook function to enforce such checks (
hook_tag parameter; see
section 3.4.9).
- * htmLawed does not check the number of nested elements. E.g., it will allow two
caption elements in a
table element, illegal as per the specs. Admins may be able to use a custom hook function to enforce such checks (
hook_tag parameter; see
section 3.4.9).
+ * htmLawed does not check the number of nested elements. E.g., it will allow two
caption elements in a
table element, illegal as per the specifications. Admins may be able to use a custom hook function to enforce such checks (
hook_tag parameter; see
section 3.4.9).
* htmLawed might convert certain entities to actual characters and remove backslashes and CSS comment-markers (
/*) in
style attribute values in order to detect malicious HTML like crafted IE-specific dynamic expressions like
expression.... If this is too harsh, admins can allow CSS expressions through htmLawed core but then use a custom function through the
hook_tag parameter (
section 3.4.9) to more specifically identify CSS expressions in the
style attribute values. Also, using
$config["style_pass"], it is possible to have htmLawed pass
style attribute values without even looking at them (
section 3.4.8).
@@ -722,14 +769,110 @@ A PHP Labware internal utility -
section 3.1).
+ * htmLawed does not check or correct the character encoding of the input it receives. In conjunction with permitting circumstances such as when the character encoding is left undefined through HTTP headers or HTML
meta tags, this can permit an exploit (like Google's
UTF-7/XSS vulnerability of the past). Also, htmLawed can mangle input text if it is not well-formed in terms of character encoding. Administrators can consider using code available elsewhere to check well-formedness of input text characters to correct any defect.
+
+ * htmLawed is expected to work with input texts in ASCII-compatible single byte encodings such as national variants of ASCII (like ISO-646-DE/German of the ISO 646 standard), extended ASCII variants (like ISO 8859-10/Turkish of the ISO 8859/ISO Latin standard), ISO 8859-based Windows variants (like Windows 1252), EBCDIC, Shift JIS (Japanese), GB-Roman (Chinese), and KS-Roman (Korean). It should also properly handle texts with variable byte encodings like UTF-7 (Unicode) and UTF-8 (Unicode). However, htmLawed may mangle input texts with double byte encodings like UTF-16 (Unicode), JIS X 0208:1997 (Japanese) and K SX 1001:1992 (Korean), or the UTF-32 (Unicode) quadruple byte encoding. If an input text has such an encoding, administrators can use PHP's
iconv functions, or some other mean, to convert text to UTF-8 before passing it to htmLawed.
+
* Like any script using PHP's PCRE regex functions, PHP setup-specific low PCRE limit values can cause htmLawed to at least partially fail with very long input texts.
-2.9 Examples
+2.9 Examples of usage
(to top)
-
1. A blog administrator wants to allow only
a,
em,
strike,
strong and
u in comments, but needs
strike and
u transformed to
span for better XHTML 1-strict compliance, and, he wants the
a links to be to
http or
https resources:
+ Safest, allowing only
safe HTML markup --
+
+
+
$config = array('safe'=>1);
+
+
+
$out = htmLawed($in);
+
+
+ Simplest, allowing all valid HTML markup except
javascript: --
+
+
+
$out = htmLawed($in);
+
+
+ Allowing all valid HTML markup including
javascript: --
+
+
+
$config = array('schemes'=>'*:*');
+
+
+
$out = htmLawed($in, $config);
+
+
+ Allowing only
safe HTML and the elements
a,
em, and
strong --
+
+
+
$config = array('safe'=>1, 'elements'=>'a, em, strong');
+
+
+
$out = htmLawed($in, $config);
+
+
+ Not allowing elements
script and
object --
+
+
+
$config = array('elements'=>'* -script -object');
+
+
+
$out = htmLawed($in, $config);
+
+
+ Not allowing attributes
id and
style --
+
+
+
$config = array('deny_attribute'=>'id, style');
+
+
+
$out = htmLawed($in, $config);
+
+
+ Permitting only attributes
title and
href --
+
+
+
$config = array('deny_attribute'=>'* -title -href');
+
+
+
$out = htmLawed($in, $config);
+
+
+ Remove bad/disallowed tags altogether instead of converting them to entities --
+
+
+
$config = array('keep_bad'=>0);
+
+
+
$out = htmLawed($in, $config);
+
+
+ Allowing attribute
title only in
a and not allowing attributes
id,
style, or scriptable
on* attributes like
onclick --
+
+
+
$config = array('deny_attribute'=>'title, id, style, on*');
+
+
+
$spec = 'a=title';
+
+
+
$out = htmLawed($in, $config, $spec);
+
+
+ Allowing a custom attribute,
vFlag, in
img and permitting custom use of the standard attribute,
rel, in
input --
+
+
+
$spec = 'img=vFlag; input=rel';
+
+
+
$out = htmLawed($in, $config, $spec);
+
+
+ Some case-studies are presented below.
+
+
1. A blog administrator wants to allow only
a,
em,
strike,
strong and
u in comments, but needs
strike and
u transformed to
span for better XHTML 1-strict compliance, and, he wants the
a links to point only to
http or
https resources:
$processed = htmLawed($in, array('elements'=>'a, em, strike, strong, u', 'make_tag_strict'=>1, 'safe'=>1, 'schemes'=>'*:http, https'), 'a=href');
@@ -772,14 +915,14 @@ A PHP Labware internal utility -
$config["clean_ms_char"] parameter need not be used if authors do not copy-paste Microsoft-created text or if the input text is not believed to use the Windows 1252 or a similar encoding. Further, the input form and the web-pages displaying it or its content should have the character encoding appropriately marked-up.
+ The $config["clean_ms_char"] parameter should not be used if authors do not copy-paste Microsoft-created text, or if the input text is not believed to use the Windows 1252 (Cp-1252) or a similar encoding like Cp-1251 (otherwise, for example when UTF-8 encoding is in use, Japanese or Korean characters can get mangled). Further, the input form and the web-pages displaying it or its content should have the character encoding appropriately marked-up.
3.2 Character references/entities
(to top)
- Valid character entities take the form
&*; where
* is
#x followed by a hexadecimal number (hexadecimal numeric entity; like
  for non-breaking space), or alphanumeric like
gt (external or named entity; like
for non-breaking space), or
# followed by a number (decimal numeric entity; like
  for non-breaking space). Character entities referring to the soft-hyphen character (the
­ or
\xad character; hexadecimal code-point
ad [decimal
173]) in attribute values are always replaced with spaces; soft-hyphens in attribute values introduce vulnerabilities in some older versions of the Opera and Mozilla [Firefox] browsers.
+ Valid character entities take the form
&*; where
* is
#x followed by a hexadecimal number (hexadecimal numeric entity; like
  for non-breaking space), or alphanumeric like
gt (external or named entity; like
for non-breaking space), or
# followed by a number (decimal numeric entity; like
  for non-breaking space). Character entities referring to the soft-hyphen character (the
­ or
\xad character; hexadecimal code-point
ad [decimal
173]) in URL-accepting attribute values are always replaced with spaces; soft-hyphens in attribute values introduce vulnerabilities in some older versions of the Opera and Mozilla [Firefox] browsers.
htmLawed (function
hl_ent()):
@@ -1059,7 +1202,7 @@ A PHP Labware internal utility -
1 is useful, e.g., when a writer previews his submission, whereas one like 3 is useful before content is finalized and made available to all.
- Note: In the example above, unlike <*>, <xml> gets considered as a tag (even though there is no HTML element named xml). In general, text matching the regular expression pattern <(/?)([a-zA-Z][a-zA-Z1-6]*)([^>]*?)\s?> is considered a tag (phrase enclosed by the angled brackets < and >, and starting [with an optional slash preceding] with an alphanumeric word that starts with an alphabet...).
+ Note: In the example above, unlike <*>, <xml> gets considered as a tag (even though there is no HTML element named xml). Thus, the keep_bad parameter's value affects <xml> but not <*>. In general, text matching the regular expression pattern <(/?)([a-zA-Z][a-zA-Z1-6]*)([^>]*?)\s?> is considered a tag (phrase enclosed by the angled brackets < and >, and starting [with an optional slash preceding] with an alphanumeric word that starts with an alphabet...), and is subjected to the keep_bad value.
Nesting/content rules for each of the 86 elements in htmLawed's default set (see section 3.3) are defined in function
hl_bal(). This means that if a non-standard element besides
embed is being permitted through
$config["elements"], the element's tag content will end up getting removed if
$config["balance"] is set to
1.
@@ -1079,6 +1222,8 @@ A PHP Labware internal utility -
table can have 0 or 1 caption, tbody, tfoot, and thead, but they must be in this order: caption, thead, tfoot, tbody.
htmLawed currently does not check for conformance to these rules. Note that any non-compliance in this regard will not introduce security vulnerabilities, crash browser applications, or affect the rendering of web-pages.
+
+ With $config["direct_list_nest"] set to 1, htmLawed will allow direct nesting of an ol or ul list within another ol or ul without requiring the child list to be within an li of the parent list. While this is not standard-compliant, directly nested lists are rendered properly by almost all browsers. The parameter $config["direct_list_nest"] has no effect if tag-balancing (section 3.3.3) is turned off.
@@ -1105,7 +1250,7 @@ A PHP Labware internal utility - 3.4 Attributes
(to top)
- htmLawed will only permit attributes described in the HTML specs (including deprecated ones). It also permits some attributes for use with the
embed element (the non-standard
embed element is supported in htmLawed because of its widespread use), and the the
xml:space attribute (valid only in XHTML 1.1). A list of such 111 attributes and the elements they are allowed in is in
section 5.2.
+ htmLawed will only permit attributes described in the HTML specs (including deprecated ones). It also permits some attributes for use with the
embed element (the non-standard
embed element is supported in htmLawed because of its widespread use), and the the
xml:space attribute (valid only in XHTML 1.1). A list of such 111 attributes and the elements they are allowed in is in
section 5.2. Using the
$spec argument, htmLawed can be forced to permit custom, non-standard attributes as well as custom rules for standard attributes (
section 2.3).
When
$config["deny_attribute"] is not set, or set to
0, or empty (
""), all the 111 attributes are permitted. Otherwise,
$config["deny_attribute"] can be set as a list of comma-separated names of the denied attributes.
on* can be used to refer to the group of potentially dangerous, script-accepting attributes:
onblur,
onchange,
onclick,
ondblclick,
onfocus,
onkeydown,
onkeypress,
onkeyup,
onmousedown,
onmousemove,
onmouseout,
onmouseover,
onmouseup,
onreset,
onselect and
onsubmit.
@@ -1188,6 +1333,8 @@ A PHP Labware internal utility -
style: * useful as URLs in style attributes can be specified in a variety of ways, and the patterns that htmLawed uses to identify URLs may mistakenly identify non-URL text.
+ ! can be put in the list of schemes to disallow all protocols as well as local URLs. Thus, with href: http, style: !, '<a href="http://cnn.com" style="background-image: url('local.jpg');">CNN</a>' will become '<a href="http://cnn.com" style="background-image: url('denied:local.jpg');">CNN</a>'.
+
Note: If URL-accepting attributes other than those listed above are being allowed, then the scheme will not be checked unless the attribute name contains the string src (e.g., dynsrc) or starts with o (e.g., onbeforecopy).
With $config["safe"] = 1, all URLs are disallowed in the style attribute values.
@@ -1405,7 +1552,7 @@ A PHP Labware internal utility - 3.4.8 Inline style properties
(to top)
- htmLawed can check URL schemes and dynamic expressions (to guard against Javascript, etc., script-based insecurities) in inline CSS style property values in the
style attributes. (CSS properties like
background-image that accept URLs in their values are noted in
section 5.3.) Dynamic CSS expressions that allow scripting in the IE browser, and can be a vulnerability, can be removed from property values by setting
$config["css_expression"] to
1 (default setting).
+ htmLawed can check URL schemes and dynamic expressions (to guard against Javascript, etc., script-based insecurities) in inline CSS style property values in the
style attributes. (CSS properties like
background-image that accept URLs in their values are noted in
section 5.3.) Dynamic CSS expressions that allow scripting in the IE browser, and can be a vulnerability, can be removed from property values by setting
$config["css_expression"] to
1 (default setting). Note that when
$config["css_expression"] is set to
1, htmLawed will remove
/* from the
style values.
Note: Because of the various ways of representing characters in attribute values (URL-escapement, entitification, etc.), htmLawed might alter the values of the
style attribute values, and may even falsely identify dynamic CSS expressions and URL schemes in them. If this is an important issue, checking of URLs and dynamic expressions can be turned off (
$config["schemes"] = "...style:*...", see
section 3.4.3, and
$config["css_expression"] = 0). Alternately, admins can use their own custom function for finer handling of
style values through the
hook_tag parameter (see
section 3.4.9).
@@ -1420,14 +1567,30 @@ A PHP Labware internal utility -
$config parameter hook_tag is set to the name of a function, htmLawed (function hl_tag()) will pass on the element name, and the finalized attribute name-value pairs as array elements to the function. The function is expected to return the full opening tag string like <element_name attribute_1_name="attribute_1_value"...> (for empty elements like img and input, the element-closing slash / should also be included).
+ When $config parameter hook_tag is set to the name of a function, htmLawed (function hl_tag()) will pass on the element name, and, in the case of an opening tag, the finalized attribute name-value pairs as array elements to the function. The function, after completing a task such as filtering or tag transformation, will typically return an empty string, the full opening tag string like <element_name attribute_1_name="attribute_1_value"...> (for empty elements like img and input, the element-closing slash / should also be included), etc.
+
+ Any hook_tag function, since htmLawed version 1.1.11, also receives names of elements in closing tags, such as a in the closing </a> tag of the element <a href="http://cnn.com">CNN</a>. Unlike for opening tags, no other value (i.e., the attribute name-value array) is passed to the function since a closing tag contains only element names. Typically, the function will return an empty string or a full closing tag (like </a>).
This is a powerful functionality that can be exploited for various objectives: consolidate-and-convert inline style attributes to class, convert embed elements to object, permit only one caption element in a table element, disallow embedding of certain types of media, inject HTML, use CSSTidy to sanitize
style attribute values, etc.
As an example, the custom hook code below can be used to force a series of specifically ordered
id attributes on all elements, and a specific
param element inside all
object elements:
-
function my_tag_function($element, $attribute_array){
+
function my_tag_function($element, $attribute_array=0){
+
+
+
+
// If second argument is not received, it means a closing tag is being handled
+
+
+
if(is_numeric($attribute_array)){
+
+
+
return "</$element>";
+
+
+
}
+
static $id = 0;
@@ -1487,6 +1650,11 @@ A PHP Labware internal utility -
}
+
+
+ static $empty_elements = array('area'=>1, 'br'=>1, 'col'=>1, 'embed'=>1, 'hr'=>1, 'img'=>1, 'input'=>1, 'isindex'=>1, 'param'=>1);
+
+
return "<{$element}{$string}". (isset($in_array($element, $empty_elements) ? ' /' : ''). '>'. $new_element;
@@ -1515,7 +1683,7 @@ A PHP Labware internal utility - $config["safe"] to auto-adjust multiple $config parameters (such as elements which declares the allowed element-set), which otherwise would have to be manually set. The relevant parameters are indicated by " in section 2.2). Thus, one can pass the
$config argument with a simpler value.
- With the value of
1, htmLawed considers
CDATA sections and HTML comments as plain text, and prohibits the
applet,
embed,
iframe,
object and
script elements, and the
on* attributes like
onclick. ( There are
$config parameters like
css_expression that are not affected by the value set for
safe but whose default values still contribute towards a more
safe output.) Further, URLs with schemes (see
section 3.4.3) are neutralized so that, e.g.,
style="moz-binding:url(http://danger)" becomes
style="moz-binding:url(denied:http://danger)" while
style="moz-binding:url(ok)" remains intact.
+ With the value of
1, htmLawed considers
CDATA sections and HTML comments as plain text, and prohibits the
applet,
embed,
iframe,
object and
script elements, and the
on* attributes like
onclick. ( There are
$config parameters like
css_expression that are not affected by the value set for
safe but whose default values still contribute towards a more
safe output.) Further, URLs with schemes (see
section 3.4.3) are neutralized so that, e.g.,
style="moz-binding:url(http://danger)" becomes
style="moz-binding:url(denied:http://danger)".
Admins, however, may still want to completely deny the
style attribute, e.g., with code like
@@ -1523,6 +1691,8 @@ A PHP Labware internal utility -
$processed = htmLawed($text, array('safe'=>1, 'deny_attribute'=>'style'));
+ Permitting the style attribute brings in risks of click-jacking, etc. CSS property values can render a page non-functional or be used to deface it. Except for URLs, dynamic expressions, and some other things, htmLawed does not completely check style values. It does provide ways for the code-developer implementing htmLawed to do such checks through the $spec argument, and through the hook_tag parameter (see section 3.4.8 for more). Disallowing style completely and relying on CSS classes and stylesheet files is recommended.
+
If a value for a parameter auto-set through
safe is still manually provided, then that value can over-ride the auto-set value. E.g., with
$config["safe"] = 1 and
$config["elements"] = "*+script",
script, but not
applet, is allowed.
A page illustrating the efficacy of htmLawed's anti-XSS abilities with
safe set to
1 against XSS vectors listed by
RSnake may be available
here.
@@ -1554,7 +1724,7 @@ A PHP Labware internal utility -
3.9 Retaining non-HTML tags in input with mixed markup
(to top)
- htmLawed does not remove certain characters that though invalid are nevertheless discouraged in HTML documents as per the specs (see
section 5.1). This can be utilized to deal with input that contains mixed markup. Input that may have HTML markup as well as some other markup that is based on the
<,
> and
& characters is considered to have mixed markup. The non-HTML markup can be rather proprietary (like markup for emoticons/smileys), or standard (like MathML or SVG). Or it can be programming code meant for execution/evaluation (such as embedded PHP code).
+ htmLawed does not remove certain characters that, though invalid, are nevertheless
discouraged in HTML documents as per the specifications (see
section 5.1). This can be utilized to deal with input that contains mixed markup. Input that may have HTML markup as well as some other markup that is based on the
<,
> and
& characters is considered to have mixed markup. The non-HTML markup can be rather proprietary (like markup for emoticons/smileys), or standard (like MathML or SVG). Or it can be programming code meant for execution/evaluation (such as embedded PHP code).
To deal with such mixed markup, the input text can be pre-processed to hide the non-HTML markup by specifically replacing the
<,
> and
& characters with some of the HTML-discouraged characters (see
section 3.1.2). Post-htmLawed processing, the replacements are reverted.
@@ -1583,7 +1753,7 @@ A PHP Labware internal utility -
4.1 Support
(to top)
- A careful re-reading of this documentation will very likely answer your questions.
+ A careful reading of this documentation may provide an answer.
Software updates and forum-based community-support may be found at
http://www.bioinformatics.org/phplabware/internal_utilities/htmLawed. For general PHP issues (not htmLawed-specific), support may be found through internet searches and at
http://php.net.
@@ -1593,18 +1763,48 @@ A PHP Labware internal utility -
(to top)
See
section 2.8.
-
- Readers are advised to cross-check information given in this document.
4.3 Change-log
(to top)
- (The release date for the downloadable package of files containing documentation, demo script, test-cases, etc., besides the
htmLawed.php file may be updated independently if the secondary files are revised.)
+ (The release date for the downloadable package of files containing documentation, demo script, test-cases, etc., besides the
htmLawed.php file, may be updated without a change-log entry if the secondary files, but not htmLawed per se, are revised.)
Version number - Release date. Notes
+ 1.1.19 - 19 January 2015. Fix for a bug in cleaning of soft-hyphens in URL values, etc.
+
+ 1.1.18 - 2 August 2014. Fix for a potential security vulnerability arising from specially encoded text with serial opening tags
+
+ 1.1.17 - 11 March 2014. Removed use of PHP function preg_replace with
e modifier for compatibility with PHP 5.5
+
+ 1.1.16 - 29 August 2013. Fix for a potential security vulnerability arising from specially encoded space characters in URL schemes/protocols
+
+ 1.1.15 - 11 August 2013. Improved tidying/prettifying functionality
+
+ 1.1.14 - 8 August 2012. Fix for possible segmental loss of incremental indentation during
tidying when
balance is disabled; fix for non-effectuation under some circumstances of a corrective behavior to preserve plain text within elements like
blockquote.
+
+ 1.1.13 - 22 July 2012. Added feature allowing use of custom, non-standard attributes or custom rules for standard attributes
+
+ 1.1.12 - 5 July 2012. Fix for a bug in identifying an unquoted value of the
face attribute
+
+ 1.1.11 - 5 June 2012. Fix for possible problem with handling of multi-byte characters in attribute values in an mbstring.func_overload environment.
$config["hook_tag"], if specified, now receives names of elements in closing tags.
+
+ 1.1.10 - 22 October 2011. Fix for a bug in the
tidy functionality that caused the entire input to be replaced with a single space; new parameter,
$config["direct_list_nest"] to allow direct descendence of a list in a list. (5 April 2012. Dual licensing from LGPLv3 to LGPLv3 and GPLv2+.)
+
+ 1.1.9.5 - 6 July 2011. Minor correction of a rule for nesting of
li within
dir
+
+ 1.1.9.4 - 3 July 2010. Parameter
schemes now accepts
! so any URL, even a local one, can be
denied. An issue in which a second URL value in
style properties was not checked was fixed.
+
+ 1.1.9.3 - 17 May 2010. Checks for correct nesting of
param
+
+ 1.1.9.2 - 26 April 2010. Minor fix regarding rendering of denied URL schemes
+
+ 1.1.9.1 - 26 February 2010. htmLawed now uses the LGPL version 3 license; support for
flashvars attribute for
embed
+
+ 1.1.9 - 22 December 2009. Soft-hyphens are now removed only from URL-accepting attribute values
+
1.1.8.1 - 16 July 2009. Minor code-change to fix a PHP error notice
1.1.8 - 23 April 2009. Parameter
deny_attribute now accepts the wild-card
*, making it simpler to specify its value when all but a few attributes are being denied; fixed a bug in interpreting
$spec
@@ -1617,11 +1817,11 @@ A PHP Labware internal utility -
$config["hook_tag"] and $config["format"] introduced for custom tag/attribute check/modification/injection and output compaction/beautification; fixed a regex-in-$spec parsing bug
+ 1.1 - 29 June 2008. $config["hook_tag"] and $config["tidy"] introduced for custom tag/attribute check/modification/injection and output compaction/beautification; fixed a regex-in-$spec parsing bug
- 1.0.9 - 11 June 2008. Fixed bug in invalid HTML code-point entity check
+ 1.0.9 - 11 June 2008. Fix for a bug in checks for invalid HTML code-point entities
- 1.0.8 - 15 May 2008. bordercolor attribute for table, td and tr
+ 1.0.8 - 15 May 2008. Permit bordercolor attribute for table, td and tr
1.0.7 - 1 May 2008. Support for wmode attribute for embed; $config["show_setting"] introduced; improved $config["elements"] evaluation
@@ -1631,7 +1831,7 @@ A PHP Labware internal utility - blockquote, form, map and noscript
- 1.0.3 - 3 March 2008. Character entities for soft-hyphens are now replaced with spaces (instead of being removed); a bug allowing td directly inside table fixed; safe $config parameter added
+ 1.0.3 - 3 March 2008. Character entities for soft-hyphens are now replaced with spaces (instead of being removed); fix for a bug allowing td directly inside table; $config["safe"] introduced
1.0.2 - 13 February 2008. Improved implementation of $config["keep_bad"]
@@ -1653,6 +1853,10 @@ A PHP Labware internal utility - htmLawed.php (assuming it was not modified for customized features). As htmLawed output is almost always used in static documents, upgrading should not affect old, finalized content.
+ Important The following upgrades may affect the functionality of a specific htmLawed installation:
+
+ (1) From version 1.1-1.1.10 to 1.1.11 (or later), if a hook_tag function is in use: In version 1.1.11, elements in closing tags (and not just the opening tags) are also passed to the function. There are no attribute names/values to pass, so a hook_tag function receives only the element name. The hook_tag function therefore may have to be edited. See section 3.4.9.
+
Old versions of htmLawed may be available online. E.g., for version 1.0, check
http://www.bioinformatics.org/phplabware/downloads/htmLawed1.zip, for 1.1.1, htmLawed111.zip, and for 1.1.10, htmLawed1110.zip.
@@ -1660,7 +1864,7 @@ A PHP Labware internal utility -
4.6 Comparison with
HTMLPurifier
(to top)
- The HTMLPurifier PHP library by Edward Yang is a very good HTML filtering script that uses object oriented PHP code. Compared to htmLawed, it:
+ The HTMLPurifier PHP library by Edward Yang is a very good HTML filtering script that uses object oriented PHP code. Compared to htmLawed, it (as of year 2010):
* does not support PHP versions older than 5.0 (HTMLPurifier dropped PHP 4 support after version 2)
@@ -1704,7 +1908,7 @@ A PHP Labware internal utility -
4.10 Acknowledgements
(to top)
- Bryan Blakey, Ulf Harnhammer, Gareth Heyes, Lukasz Pilorz, Shelley Powers, Edward Yang, and many anonymous users.
+ Nicholas Alipaz, Bryan Blakey, Pádraic Brady, Dac Chartrand, Ulf Harnhammer, Gareth Heyes, Klaus Leithoff, Lukasz Pilorz, Shelley Powers, Psych0tr1a, Lincoln Russell, Tomas Sykorka, Harro Verton, Edward Yang, and many anonymous users.
Thank you!
@@ -1726,7 +1930,7 @@ A PHP Labware internal utility -
5.2 Valid attribute-element combinations
(to top)
- Valid attribute-element combinations as per W3C specs.
+ Valid attribute-element combinations as per
W3C specs.
* includes deprecated attributes (marked
^), attributes for the non-standard
embed element (marked
*), and the proprietary
bordercolor (marked
~)
* only non-frameset, HTML body elements
@@ -1771,6 +1975,7 @@ A PHP Labware internal utility -
Function arguments for htmLawed are:
- *
$in - 1st argument; a text string; the
input text to be processed. Any extraneous slashes added by PHP when
magic quotes are enabled should be removed beforehand using PHP's
stripslashes() function.
+ *
$in - first argument; a text string; the
input text to be processed. Any extraneous slashes added by PHP when
magic quotes are enabled should be removed beforehand using PHP's
stripslashes() function.
- *
$config - 2nd argument; an associative array; optional (named
$C in htmLawed code). The array has keys with names like
balance and
keep_bad, and the values, which can be boolean, string, or array, depending on the key, are read to accordingly set the
configurable parameters (indicated by the keys). All configurable parameters receive some default value if the value to be used is not specified by the user through
$config.
Finalized $config is thus a filtered and possibly larger array.
+ *
$config - second argument; an associative array; optional; named
$C within htmLawed code. The array has keys with names like
balance and
keep_bad, and the values, which can be boolean, string, or array, depending on the key, are read to accordingly set the
configurable parameters (indicated by the keys). All configurable parameters receive some default value if the value to be used is not specified by the user through
$config.
Finalized $config is thus a filtered and possibly larger array.
- *
$spec - 3rd argument; a text string; optional. The string has rules, written in an htmLawed-designated format,
specifying element-specific attribute and attribute value restrictions. Function
hl_spec() is used to convert the string to an associative-array for internal use.
Finalized $spec is thus an array.
+ *
$spec - third argument; a text string; optional. The string has rules, written in an htmLawed-designated format,
specifying element-specific attribute and attribute value restrictions. Function
hl_spec() is used to convert the string to an associative-array, named
$S within htmLawed code, for internal use.
Finalized $spec is thus an array.
Finalized $config and
$spec are made
global variables while htmLawed is at work. Values of any pre-existing global variables with same names are noted, and their values are restored after htmLawed finishes processing the input (to capture the
finalized values, the
show_settings parameter of
$config should be used). Depending on
$config, another global variable
hl_Ids, to track
id attribute values for uniqueness, may be set. Unlike the other two variables, this one is not reset (or unset) post-processing.
@@ -1966,13 +2171,13 @@ A PHP Labware internal utility -
htmLawed() identifies tags using regex and processes them with the help of hl_tag() -- a large function that analyzes tag content, filtering it as per HTML standards, $config and $spec. Among other things, hl_tag() transforms deprecated elements using hl_tag2(), removes attributes from closing tags, checks attribute values as per $spec rules using hl_attrval(), and checks URL protocols using hl_prot(). htmLawed() performs tag balancing and nesting checks with a call to hl_bal(), and optionally compacts/beautifies the output with proper white-spacing with a call to hl_tidy(). The latter temporarily replaces white-space, and <, > and & characters inside pre, script and textarea elements, and HTML comments and CDATA sections with control characters (code-points 1 to 5, and 7).
- htmLawed permits the use of custom code or hook functions at two stages. The first, called inside htmLawed(), allows the input text as well as the finalized $config and $spec values to be altered right after the initial processing (see section 3.7). The second is called by
hl_tag() once the tag content is finalized (see
section 3.4.9).
+ htmLawed permits the use of custom code or
hook functions at two stages. The first, called inside
htmLawed(), allows the input text as well as the finalized
$config and
$spec values to be altered right after the initial processing (see
section 3.7). The second is called by
hl_tag() once the tag content is finalized (see
section 3.4.9).
- Being dictated by the external and stable HTML standard, htmLawed's objective is very clear-cut and less concerned with tweakability. The code is only minimally annotated with comments -- it is not meant to instruct; PHP developers familiar with the HTML specs will see the logic, and others can always refer to the htmLawed documentation. The compact structuring of the statements is meant to aid in quickly grasping the logic, at least when viewed with code syntax highlighted.
+ The functionality of htmLawed is dictated by the external HTML standard. It is thus coded for a clear-cut objective with not much concern for tweakability. The code is only minimally annotated with comments -- it is not meant to instruct; PHP developers familiar with the HTML specifications will see the logic, and others can always refer to the htmLawed documentation. The compact structuring of the statements is meant to aid a quick grasp of the logic.
-htmLawed 1.1.8.1, 16 July 2009
+
+htmLawed 1.1.19, 19 January 2015
Copyright Santosh Patnaik
-GPL v3 license
+Dual licensed with LGPL 3 and GPL 2+
A PHP Labware internal utility - http://www.bioinformatics.org/phplabware/internal_utilities/htmLawed
@@ -121,9 +121,9 @@ A PHP Labware internal utility - 1 About htmLawed (to top)
- htmLawed is a highly customizable single-file PHP script to make text secure, and standard- and admin policy-compliant for use in the body of HTML 4, XHTML 1 or 1.1, or generic XML documents. It is thus a configurable input (X)HTML filter, processor, purifier, sanitizer, beautifier, etc., and an alternative to the HTMLTidy application.
+ htmLawed is a PHP script to process text with HTML markup to make it more compliant with HTML standards and administrative policies. It works by making HTML well-formed with balanced and properly nested tags, neutralizing code that may be used for cross-site scripting (XSS) attacks, allowing only specified HTML tags and attributes, and so on. Such lawing in of HTML in text used in (X)HTML or XML documents ensures that it is in accordance with the aesthetics, safety and usability requirements set by administrators.
- The lawing in of input text is needed to ensure that HTML code in the text is standard-compliant, does not introduce security vulnerabilities, and does not break the aesthetics, design or layout of web-pages. htmLawed tries to do this by, for example, making HTML well-formed with balanced and properly nested tags, neutralizing code that may be used for cross-site scripting (XSS) attacks, and allowing only specified HTML elements/tags and attributes.
+ htmLawed is highly customizable, and fast with low memory usage. Its free and open-source code is in one small file, does not require extensions or libraries, and works in older versions of PHP as well. It is a good alternative to the HTML Tidy application.
1.1 Example uses @@ -151,8 +151,8 @@ A PHP Labware internal utility - img ^`
(to top)+ * can restrict elements ^~`
+ * ensures proper closure of empty elements like img ^`
* transform deprecated elements like u ^~`
* HTML comments and CDATA sections can be permitted ^~`
* elements like script, object and form can be permitted ~
@@ -161,7 +161,7 @@ A PHP Labware internal utility - alt for image ^`
- * transform deprecated attributes ^~`
+ * transforms deprecated attributes ^~`
* attributes declared only once ^`
* restrict attribute values, including element-specifically ^~`
@@ -170,6 +170,7 @@ A PHP Labware internal utility - id attribute values ^~`
* double-quote attribute values ^
* lower-case standard attribute values like password ^`
+ * permit custom, non-standard attributes as well as custom rules for standard attributes ~`
* attribute-specific URL protocol/scheme restriction *~`
* disable dynamic expressions in style values *~`
@@ -180,7 +181,7 @@ A PHP Labware internal utility - Word that are discouraged in HTML or XML ^~`
@@ -213,50 +214,74 @@ A PHP Labware internal utility - 1.3 History
- htmLawed was developed for use with LabWiki, a wiki software developed at PHP Labware, as a suitable software could not be found. Existing PHP software like Kses and HTMLPurifier were deemed inadequate, slow, resource-intensive, or dependent on external applications like HTML Tidy.
+ htmLawed was created in 2007 for use with LabWiki, a wiki software developed at PHP Labware, as a suitable software could not be found. Existing PHP software like Kses and HTMLPurifier were deemed inadequate, slow, resource-intensive, or dependent on an extension or external application like HTML Tidy. The core logic of htmLawed, that of identifying HTML elements and attributes, was based on the Kses (version 0.2.2) HTML filter software of Ulf Harnhammar (it can still be used with code that uses Kses; see section 2.6.).
- htmLawed started as a modification of Ulf Harnhammar's Kses (version 0.2.2) software, and is compatible with code that uses Kses; see section 2.6.
+ See section 4.3 for a detailed log of changes in htmLawed over the years, and section 4.10 for acknowledgements.
1.4 License & copyright
(to top)- htmLawed is free and open-source software licensed under GPL license version 3, and copyrighted by Santosh Patnaik, MD, PhD.
+ htmLawed is free and open-source software dual copyrighted by Santosh Patnaik, MD, PhD, and licensed under LGPL license version 3, and GPL license version 2 (or later).
1.5 Terms used here
(to top)- * administrator - or admin; person setting up the code to pass input through htmLawed; also, user
+ In this document, only HTML body-level elements are considered. htmLawed does not have support for head-level elements, body, and the frame-level elements, frameset, frame and noframes, and these elements are ignored here.
+
+ * administrator - or admin; person setting up the code that utilizes htmLawed; also, user
* attributes - name-value pairs like href="http://x.com" in opening tags
- * author - writer
+ * author - see writer
* character - atomic unit of text; internally represented by a numeric code-point as specified by the encoding or charset in use
* entity - markup like > and   used to refer to a character
* element - HTML element like a and img
- * element content - content between the opening and closing tags of an element, like click of <a href="x">click</a>
+ * element content - content between the opening and closing tags of an element, like click of the <a href="x">click</a> element
* HTML - implies XHTML unless specified otherwise
- * input - text string given to htmLawed to process
+ * HTML body - Complete HTML documents typically have a head and a body container. Information in head specifies title of the document, etc., whereas that in the body informs what is to be displayed on a web-page; it is only the elements for body, except frames, frameset and noframes that htmLawed is concerned with
+ * input - text given to htmLawed to process
* processing - involves filtering, correction, etc., of input
- * safe - absence or reduction of certain characters and HTML elements and attributes in the input that can otherwise potentially and circumstantially expose web-site users to security vulnerabilities like cross-site scripting attacks (XSS)
- * scheme - URL protocol like http and ftp
- * specs - standard specifications
+ * safe - absence or reduction of certain characters and HTML elements and attributes in HTML of text that can otherwise potentially, and circumstantially, expose text readers to security vulnerabilities like cross-site scripting attacks (XSS)
+ * scheme - a URL protocol like http and ftp
+ * specifications - standard specifications, for HTML4, HTML5, Ruby, etc.
* style property - terms like border and height for which declarations are made in values for the style attribute of elements
* tag - markers like <a href="x"> and </a> delineating element content; the opening tag can contain attributes
* tag content - consists of tag markers < and >, element names like div, and possibly attributes
* user - administrator
* writer - end-user like a blog commenter providing the input that is to be processed; also, author
+
+1.6 Availability +
(to top)+
+ htmLawed can be downloaded for free at its website. Besides the htmLawed.php file, the download has the htmLawed documentation (this document) in plain text and HTML formats, a script for testing, and a text file for test-cases. htmLawed is also available as a PHP class (OOP code) on its website.
+