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."