9 APEX_ESCAPE

The APEX_ESCAPE package provides functions for escaping special characters in strings to ensure that the data is suitable for further processing.

Topics:

Constants

The APEX_ESCAPE package uses the following constants.

SPACE# constant binary_integer := 32; 
HASH# constant binary_integer := 35; 
COMMA# constant binary_integer := 44; 
HYPHEN# constant binary_integer := 45; 
DOT# constant binary_integer := 46; 
ZERO# constant binary_integer := 48; 
NINE# constant binary_integer := 57; 
UP_A# constant binary_integer := 65; 
UP_Z# constant binary_integer := 90; 
BACKSLASH# constant binary_integer := 92; 
UNDERSCORE# constant binary_integer := 95; 
LOW_A# constant binary_integer := 97; 
LOW_Z# constant binary_integer := 122; 
 
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/>';

HTML Function

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 9-1, depicts ascii characters that the function transforms and their escaped values:

Table 9-1 Escaped Values for Transformed ASCII Characters

Raw ASCI Characters Returned Escaped Characters

&

&amp;

"

&quot;

<

&lt;

>

&gt;

'

&#x27;

/

&#x2F;


Syntax

APEX_ESCAPE.HTML (
    p_string IN VARCHAR2 )
    return VARCHAR2;

Parameters

Table 9-2 describes the parameters available in the HTML function.

Table 9-2 HTML Function Parameters

Parameter Description

p_string

The string text that is escaped


Example

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 &amp;&quot;&lt;&gt;''/'); 
    apex_escape.set_html_escaping_mode('E'); 
    eq(apex_escape.html('hello &"<>''/'), 'hello
    &amp;&quot;&lt;&gt;&#x27;&#x2F;'); 
end; 

HTML_ATTRIBUTE Function

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 ',' '.' '-' '_' .

Syntax

APEX_ESCAPE.HTML_ATTRIBUTE (
    p_string IN VARCHAR2 )
    return VARCHAR2;

Parameters

Table 9-3describes the parameters available in the HTML_ATTRIBUTE function.

Table 9-3 HTML_ATTRIBUTE Function Parameters

Parameter Description

p_string

The text string that is escaped.


Example

See "HTML_TRUNC Function".

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

Syntax

APEX_ESCAPE.HTML_TRUNC (
    p_string IN CLOB,
    p_length IN NUMBER DEFAULT 4000 )
    return VARCHAR2;

Parameters

Table 9-4 describes the parameters available in the HTML_TRUNC function.

Table 9-4 HTML_TRUNC Function Parameters

Parameter Description

p_string

The text string that is escaped.

p_length

The number of characters from p_string that are escaped.


Example

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; 

HTML_WHITELIST Function

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.

Syntax

APEX_ESCAPE.HTML_WHITELIST (
    p_html IN VARCHAR2,
    p_whitelist_tags IN VARCHAR2 DEFAULT c_html_whitelist_tags )
    return VARCHAR2;

Parameters

Table 9-5 describes the parameters available in the HTML_WHITELIST function.

Table 9-5 HTML_WHITELIST Function Parameters

Parameter Description

p_html

The text string that is filtered.

p_whitelist_tags

The comma separated list of tags that stays in p_html.


Example

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;

JS_LITERAL Function

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

Syntax

APEX_ESCAPE.JS_LITERAL (
    p_string IN VARCHAR2,
    p_quote  IN VARCHAR2 DEFAULT "" )
    return VARCHAR2;

Parameters

Table 9-6 describes the parameters available in the JS_LITERAL function.

Table 9-6 JS_LITERAL Function Parameters

Parameter Description

p_string

The text string that is escaped.

p_quote

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.


Example

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;

LDAP_DN Function

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.

Syntax

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;

Parameters

Table 9-7 describes the parameters available in the LDAP_DN function.

Table 9-7 LDAP_DN Function Parameters

Parameter Description

p_string

The text string that is escaped.

p_reserved_chars

A list of characters that when found in p_string is escaped with a backslash.

p_escaped_non_ascii

If true, characters above ascii 127 in p_string are escaped with a backslash. This is supported by RFCs 4514 and 2253, but may cause errors with older LDAP servers and Microsoft AD.


Example

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;

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.

Syntax

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;

Parameters

Table 9-8 describes the parameters available in the LDAP_SEARCH_FILTER function.

Table 9-8 LDAP_SEARCH_FILTER Function Parameters

Parameter Description

p_string

The text string that is escaped.

p_reserved_chars

A list of characters that when found in p_string is escaped with \xx where xx is the character's ASCII hexadecimal code.

p_escape_non_ascii

If true, characters above ascii 127 in p_string are escaped with \xx where xx is the character's ASCII hexadecimal code. This is supported by RFCs 4514, but may cause errors with older LDAP servers and Microsoft AD.


Example

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;

NOOP Function

Return p_string unchanged. Use this function to silence automatic injection detection tests, similar to dbms_assert.noop for SQL injection.

Syntax

APEX_ESCAPE.NOOP (
    p_string IN VARCHAR2)
    return VARCHAR2 deterministic;

Parameters

Table 9-9 describes the parameters available in the NOOP function.

Table 9-9 APEX_ESCAPE.NOOP Function Parameters

Parameter Description

p_string

The input text string.


Example

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;

SET_HTML_ESCAPING_MODE Procedure

The SET_HTML_ESCAPING_MODE procedure configures HTML escaping mode for wwv_flow_escape.html.

Syntax

APEX_ESCAPE.SET_HTML_ESCAPING_MODE (
    p_mode IN VARCHAR2);

Parameters

Table 9-10 describes the parameters available in the SET_HTML_ESCAPING_MODE procedure.

Table 9-10 APEX_ESCAPE.SET_HTML_ESCAPING_MODE Procedure Parameters

Parameter Description

p_mode

If equal to B, then do basic escaping, like sys.htf.escape_sc. If equal to E, then do extended escaping.


Example

For an example, see "HTML Function".