The APEX_ESCAPE package provides functions for escaping special characters in strings to ensure that the data is suitable for further processing.
The APEX_ESCAPE package uses the following constants.
c_ldap_dn_reserved_chars constant varchar2(8) := '"+,;<=>\'; c_ldap_search_reserved_chars constant varchar2(5) := '*()\/'; c_html_whitelist_tags constant varchar2(255) := '<h1>,</h1>,<h2>,</h2>,<h3>,</h3>,<h4>,</h4>,<p>,</p>,<b>,</b>,<strong>,</strong>,<i>,</i>,<ul>,</ul>,<ol>,</ol>,<li>,</li>,<br />,<hr/>';
This function escapes characters which can change the context in an html environment. It is an extended version of the well-known sys.htf.escape_sc.
The function's result depends on the escaping mode that is defined by using apex_escape.set_html_escaping_mode. By default, the escaping mode is "Extended", but it can be overridden by manually calling set_html_escaping_mode or by setting the application security attribute "HTML Escaping Mode" to "Basic". If the mode is "Basic", the function behaves like sys.htf.escape_sc. Otherwise, the rules below apply.
The following table, Table 10-1, depicts ascii characters that the function transforms and their escaped values:
Table 10-1 Escaped Values for Transformed ASCII Characters
| Raw ASCI Characters | Returned Escaped Characters |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
' |
|
|
|
|
APEX_ESCAPE.HTML (
p_string IN VARCHAR2 )
return VARCHAR2;
Table 10-2 describes the parameters available in the HTML function.
This example tests escaping in basic ('B') and extended ('E') mode.
declare
procedure eq(p_str1 in varchar2,p_str2 in varchar2)
is
begin
if p_str1||'.' <> p_str2||'.' then
raise_application_error(-20001,p_str1||' <> '||p_str2);
end if;
end eq;
begin
apex_escape.set_html_escaping_mode('B');
eq(apex_escape.html('hello &"<>''/'), 'hello &"<>''/');
apex_escape.set_html_escaping_mode('E');
eq(apex_escape.html('hello &"<>''/'), 'hello
&"<>'/');
end;
Use this function to escape the values of html entity attributes. It hex escapes everything that is not alphanumeric or in one of the following characters ',' '.' '-' '_' .
APEX_ESCAPE.HTML_ATTRIBUTE (
p_string IN VARCHAR2 )
return VARCHAR2;
Table 10-3describes the parameters available in the HTML_ATTRIBUTE function.
The HTML_TRUNC function escapes html and limits the returned string to p_length characters. This function returns the first p_length characters of an input clob and escapes them. You can use this function if the input clob might be too large to fit in a varchar2 variable and it is sufficient to only display the first part of it.
APEX_ESCAPE.HTML_TRUNC (
p_string IN CLOB,
p_length IN NUMBER DEFAULT 4000 )
return VARCHAR2;
Table 10-4 describes the parameters available in the HTML_TRUNC function.
Table 10-4 HTML_TRUNC Function Parameters
| Parameter | Description |
|---|---|
|
|
The text string that is escaped. |
|
|
The number of characters from |
This example generates a html list of of titles and text bodies. Html entity attributes are escaped with HTML_ATTRIBUTE, whereas normal text is escaped with HTML and HTML_TRUNC.
begin
htp.p('<ul>');
for l_data in ( select title, cls, body
from my_topics )
loop
sys.htp.p('<li><span class="'||
apex_escape.html_attribute(l_data.cls)||'">'||
apex_escape.html(l_data.title)||'</span>');
sys.htp.p(apex_escape.html_trunc(l_data.body));
sys.htp.p('</li>');
end loop;
htp.p('</ul>');
end;
The HTML_WHITELIST function performs HTML escape on all characters in the input text except the specified whitelist tags. This function can be useful if the input text contains simple html markup but a developer wants to ensure that an attacker cannot use malicious tags for cross-site scripting.
APEX_ESCAPE.HTML_WHITELIST (
p_html IN VARCHAR2,
p_whitelist_tags IN VARCHAR2 DEFAULT c_html_whitelist_tags )
return VARCHAR2;
Table 10-5 describes the parameters available in the HTML_WHITELIST function.
Table 10-5 HTML_WHITELIST Function Parameters
| Parameter | Description |
|---|---|
|
|
The text string that is filtered. |
|
|
The comma separated list of tags that stays in |
This example shows how to use HTML_WHITELIST to remove unwanted html markup from a string, while preserving whitelisted tags.
begin sys.htp.p(apex_escape.html_whitelist( '<h1>Hello<script>alert("XSS");</script></h1>')); end;
The JS_LITERAL function escapes and optionally enquotes a javascript string. This function replaces non-immune characters with \xHH or \uHHHH equivalents. The result can be injected into javascript code, within <script> tags or inline ("javascript:xxx"). Immune characters include a through z, A through Z, 0 through 9, commas ",", periods "." and underscores "_".
APEX_ESCAPE.JS_LITERAL (
p_string IN VARCHAR2,
p_quote IN VARCHAR2 DEFAULT "" )
return VARCHAR2;
Table 10-6 describes the parameters available in the JS_LITERAL function.
Table 10-6 JS_LITERAL Function Parameters
| Parameter | Description |
|---|---|
|
|
The text string that is escaped. |
|
|
If not null, this string is placed on the left and right of the result. The quotation character must be a single or a double quotation mark. |
It describes how to use JS_LITERAL to escape special characters in the l_string variable.
declare
l_string varchar2(4000) := 'O''Brien';
begin
sys.htp.p('<script>'||
'alert('||apex_escape.js_literal(l_string)||');'||'</script>');
end;
This function returns p_string with all special characters escaped.
APEX_ESCAPE.JSON (
p_string IN VARCHAR2 )
RETURN VARCHAR2;
The following example prints this: { "name": "O\u0027Brien"}
declare
l_string varchar2(4000) := 'O''Brien';
begin
sys.htp.p('{ "name": "'||apex_escape.json(l_string)||'"}');
end;
The LDAP_DN function escapes reserved characters in an LDAP distinguished name, according to RFC 4514. The RFC describes "+,;<=>\ as reserved characters (see p_reserved_chars). These are escaped by a backslash, for example, " becomes \". Non-printable characters, ascii 0 - 31, and ones with a code > 127 (see p_escape_non_ascii) are escaped as \xx, where xx is the hexadecimal character code. The space character at the beginning or end of the string and a # at the beginning is also escaped with a backslash.
APEX_ESCAPE.LDAP_DN (
p_string IN VARCHAR2,
p_reserved_chars IN VARCHAR2 DEFAULT c_ldap_dn_reserved_chars,
p_escaped_non_ascii IN BOOLEAN DEFAULT TRUE )
return VARCHAR2;
Table 10-9 describes the parameters available in the LDAP_DN function.
Table 10-9 LDAP_DN Function Parameters
| Parameter | Description |
|---|---|
|
|
The text string that is escaped. |
|
|
A list of characters that when found in |
|
|
If TRUE, characters above ascii 127 in |
This example escapes characters in l_name and places the result in l_escaped.
declare
l_name varchar2(4000) := 'Joe+User';
l_escaped varchar2(4000);
begin
l_escaped := apex_escape.ldap_dn(l_name);
htp.p(l_name||' becomes '||l_escaped);
end;
See Also:
"LDAP_SEARCH_FILTER Function"The LDAP_SEARCH_FILTER function escapes reserved characters in an LDAP search filter, according to RFC 4515. The RFC describes *()\/ as reserved characters (see p_reserved_chars). These, non-printable characters (ascii 0 - 31) and ones with a code > 127 (see p_escape_non_ascii) are escaped as \xx, where xx is the hexadecimal character code.
APEX_ESCAPE.LDAP_SEARCH_FILTER (
p_string IN VARCHAR2,
p_reserved_chars IN VARCHAR2 DEFAULT c_ldap_search_reserved_chars,
p_escape_non_ascii IN BOOLEAN DEFAULT TRUE )
return VARCHAR2;
Table 10-10 describes the parameters available in the LDAP_SEARCH_FILTER function.
Table 10-10 LDAP_SEARCH_FILTER Function Parameters
| Parameter | Description |
|---|---|
|
|
The text string that is escaped. |
|
|
A list of characters that when found in |
|
|
If TRUE, characters above ascii 127 in |
This example escapes the text in l_name and places the result in l_escaped.
declare
l_name varchar2(4000) := 'Joe*User';
l_escaped varchar2(4000);
begin
l_escaped := apex_escape.ldap_search_filter(l_name);
htp.p(l_name||' becomes '||l_escaped);
end;
See Also:
"LDAP_DN Function"Return p_string unchanged. Use this function to silence automatic injection detection tests, similar to dbms_assert.noop for SQL injection.
APEX_ESCAPE.NOOP (
p_string IN VARCHAR2)
return VARCHAR2 deterministic;
Table 10-11 describes the parameters available in the NOOP function.
Table 10-11 APEX_ESCAPE.NOOP Function Parameters
| Parameter | Description |
|---|---|
|
|
The input text string. |
This example shows how to use NOOP to show the developer's intention to explicitly not escape text.
begin
sys.htp.p(apex_escape.noop('Cats & Dogs'));
end;
This function escapes characters that can change the context in a regular expression. It should be used to secure user input. The following list depicts ascii characters that the function escapes with a backslash (\):
\.^$*+-?()[]{|
APEX_ESCAPE.REGEXP (
p_string IN VARCHAR2);
Table 10-13 describes the parameters available in the APEX_ESCAPE_REGEXP function.
The following example ensures the special character "-" in Mary-Ann will be escaped and ignored by the regular expression engine.
declare
l_subscribers varchar2(4000) := 'Christina,Hilary,Mary-Ann,Joel';
l_name varchar2(4000) := 'Mary-Ann';
begin
if regexp_instr(l_subscribers,'(^|,)'|| apex_escape.regexp(l_name)||'($|,)')>0
then
sys.htp.p('found');
else
sys.htp.p('not found')
endif;
end
The SET_HTML_ESCAPING_MODE procedure configures HTML escaping mode for wwv_flow_escape.html.
APEX_ESCAPE.SET_HTML_ESCAPING_MODE (
p_mode IN VARCHAR2);
Table 10-13 describes the parameters available in the SET_HTML_ESCAPING_MODE procedure.
Table 10-13 APEX_ESCAPE.SET_HTML_ESCAPING_MODE Procedure Parameters
| Parameter | Description |
|---|---|
|
|
If equal to |
For an example, see "HTML Function."