Supplemental Information about profiles
Following is supplemental information about particular aspects of Web App Firewall profiles. This information explains how to include special characters in a security check rule or relaxation, and how to use variables when configuring profiles.
Configuration variable support
Instead of using static values, to configure the Web App Firewall’s security checks and settings, you can now use standard Citrix ADC named variables. By creating variables, you can more easily export and then import configurations to new Citrix ADC appliances, or update existing Citrix ADC appliances from a single set of configuration files. This simplifies updates when you use a test bed setup to develop a complex Web App Firewall configuration that is tuned for your local network and servers and then transfer that configuration to your production Citrix ADC appliances.
You create Web App Firewall configuration variables in the same manner as you do any other Citrix ADC named variables, following standard Citrix ADC conventions. You can create a named expression variable using the Citrix ADC command line or Citrix GUI.
The following URLs and expressions can be configured with variables instead of static values:
- Start URL (-starturl)
- Deny URL ( -denyurl)
- Form Action URL for Form Field Consistency Check (-fieldconsistency)
- Action URL for XML SQL Injection Check (-xmlSQLInjection)
- Action URL for XML Cross-Site Scripting Check (-xmlcross-site scripting)
- Form Action URL for HTML SQL Injection Check (-sqlInjection)
- Form Action URL for Field Format Check (-fieldFormat)
- Form Origin URL and Form Action URL for Cross-Site Request Forgery (CSRF) Check (-csrfTag)
- Form Action URL for HTML Cross-Site Scripting Check (-crossSiteScripting)
- Safe Object (-safeObject)
- Action URL for XML Denial-of-Service (XDoS) check (-XMLDoS)
- URL for Web Services Interoperability check (-XMLWSIURL)
- <URL for XML Validation check (-XMLValidationURL)
- URL for XML Attachment check (-XMLAttachmentURL)
For more information, see Policies and Expressions.
To use a variable in the configuration, you enclose the variable name between two at (@) symbols and then use it exactly as you would the static value that it replaces. For example, if you are configuring the Deny URL check by using the GUI and want to add the named expression variable myDenyURL to the configuration, you would type @myDenyURL@ into the Add Deny URL dialog box, Deny URL text area. To do the same task by using the Citrix ADC command line, you would type add appfw profile <name> -denyURLAction @myDenyURL@.
PCRE character encoding format
The Citrix ADC operating system supports direct entry of characters in the printable ASCII character set only—characters with hexadecimal codes between HEX 20 (ASCII 32) and HEX 7E (ASCII 127). To include a character with a code outside that range in your Web App Firewall configuration, you must enter its UTF-8 hexadecimal code as a PCRE regular expression.
A number of character types require encoding using a PCRE regular expression if you include them in your Web App Firewall configuration as a URL, form field name, or Safe Object expression. They include:
-
Upper-ASCII characters. Characters with encodings from HEX 7F (ASCII 128) to HEX FF (ASCII 255). Depending on the character map used, these encodings can refer to control codes, ASCII characters with accents or other modifications, non-Latin alphabet characters, and symbols not included in the basic ASCII set. These characters can appear in URLs, form field names, and safe object expressions.
-
Double-Byte characters. Characters with encodings that use two 8-byte words. Double-byte characters are used primarily for representing Chinese, Japanese, and Korean text in electronic format. These characters can appear in URLs, form field names, and safe object expressions.
-
ASCII control characters. Non-printable characters used to send commands to a printer. All ASCII characters with hexadecimal codes less than HEX 20 (ASCII 32) fall into this category. These characters must never appear in a URL or form field name, however, and would rarely if ever appear in a safe object expression.
The Citrix ADC appliance does not support the entire UTF-8 character set, but only the characters found in the following eight charsets:
-
English US (ISO-8859-1). Although the label reads, “English US,” the Web App Firewall supports all characters in the ISO-8859-1 character set, also called the Latin-1 character set. This character set fully represents most modern western European languages and represents all but a few uncommon characters in the rest.
-
Chinese Traditional (Big5). The Web App Firewall supports all characters in the BIG5 character set, which includes all of the Traditional Chinese characters (ideographs) commonly used in modern Chinese as spoken and written in Hong Kong, Macau, Taiwan, and by many people of Chinese ethnic heritage who live outside of mainland China.
-
Chinese Simplified (GB2312). The Web App Firewall supports all characters in the GB2312 character set, which includes all of the Simplified Chinese characters (ideographs) commonly used in modern Chinese as spoken and written in mainland China.
-
Japanese (SJIS). The Web App Firewall supports all characters in the Shift-JIS (SJIS) character set, which includes most characters (ideographs) commonly used in modern Japanese.
-
Japanese (EUC-JP). The Web App Firewall supports all characters in the EUC-JP character set, which includes all characters (ideographs) commonly used in modern Japanese.
-
Korean (EUC-KR). The Web App Firewall supports all characters in the EUC-KR character set, which includes all characters (ideographs) commonly used in modern Korean.
-
Turkish (ISO-8859-9). The Web App Firewall supports all characters in the ISO-8859-9 character set, which includes all letters used in modern Turkish.
-
Unicode (UTF-8). The Web App Firewall supports certain additional characters in the UTF-8 character set, including those used in modern Russian.
When configuring the Web App Firewall, you enter all non-ASCII characters as PCRE-format regular expressions using the hexadecimal code assigned to that character in the UTF-8 specification. Symbols and characters within the normal ASCII character set, which are assigned single, two-digit codes in that character set, are assigned the same codes in the UTF-8 character set. For example, the exclamation point (!), which is assigned hex code 21 in the ASCII character set, is also hex 21 in the UTF-8 character set. Symbols and characters from another supported character set have a paired set of hexadecimal codes assigned to them in the UTF-8 character set. For example, the letter a with an acute accent (á) is assigned UTF-8 code C3 A1.
The syntax you use to represent these UTF-8 codes in the Web App Firewall configuration is “xNN” for ASCII characters; “\xNN\xNN” for non-ASCII characters used in English, Russian, and Turkish; and “\xNN\xNN\xNN” for characters used in Chinese, Japanese, and Korean. For example, if you want to represent a ! in an Web App Firewall regular expression as a UTF-8 character, you would type \x21. If you want to include an á, you would type \xC3\xA1.
Note:
Normally you do not need to represent ASCII characters in UTF-8 format, but when those characters might confuse a web browser or an underlying operating system, you can use the character’s UTF-8 representation to avoid this confusion. For example, if a URL contains a space, you might want to encode the space as x20 to avoid confusing certain browsers and web server software.
Below are examples of URLs, form field names, and safe object expressions that contain non-ASCII characters that must be entered as PCRE-format regular expressions to be included in the Web App Firewall configuration. Each example shows the actual URL, field name, or expression string first, followed by a PCRE-format regular expression for it.
-
A URL containing extended ASCII characters.
Actual URL:
http://www.josénuñez.comEncoded URL:
^http://www\[.\]jos\xC3\xA9nu\xC3\xB1ez\[.\]com$ -
Another URL containing extended ASCII characters.
Actual URL:
http://www.example.de/trömso.htmlEncoded URL:
^http://www[.]example\[.]de/tr\xC3\xB6mso[.]html$ -
A form field name containing extended ASCII characters.
Actual Name: nome_do_usuárioEncoded Name:
^nome_do_usu\xC3\xA1rio$ -
A safe object expression containing extended ASCII characters.
Unencoded Expression
[A-Z]{3,6}¥[1-9][0-9]{6,6}Encoded Expression:
[A-Z]{3,6}\xC2\xA5[1-9][0-9]{6,6}
You can find a number of tables that include the entire Unicode character set and matching UTF-8 encodings on the Internet. A useful website that contains this information is located at the following URL:
http://www.utf8-chartable.de/unicode-utf8-table.pl
For the characters in the table on this website to display correctly, you must have an appropriate Unicode font installed on your computer. If you do not, the visual display of the character may be in error. Even if you do not have an appropriate font installed to display a character, however, the description and the UTF-8 and UTF-16 codes on this set of web pages will be correct.
Inverted PCRE Expressions
In addition to matching content that contains a pattern, you can match content that does not contain a pattern by using an inverted PCRE expression. To invert an expression, you simply include an exclamation point (!) followed by white space as the first character in the expression.
Note: If an expression consists only of an exclamation point with nothing following, the exclamation point is treated as a literal character, not syntax indicating an inverted expression.
The following Web App Firewall commands support inverted PCRE expressions:
- Start URL (URL)
- Deny URL (URL)
- Form Field Consistency (form action URL)
- Cookie Consistency (form action URL)
- Cross Site Request Forgery (CSRF) (form action URL)
- HTML Cross-site Scripting (form action URL)
- Field Format (form action URL)
- Field Type (type)
- Confidential Field (URL)
Note: If the security check contains an isRegex flag or check box, it must be set to YES or checked to enable regular expressions in the field. Otherwise the contents of that field are treated as literal and no regular expressions (inverted or not) are parsed.
Disallowed Names for Web App Firewall Profiles
The following names are assigned to built-in actions and profiles on the Citrix ADC appliance, and cannot be used as names for a user-created Web App Firewall profile.
- AGRESSIVE
- ALLOW
- BASIC
- CLIENTAUTH
- COMPRESS
- CSSMINIFY
- DEFLATE
- DENY
- DNS-NOP
- DROP
- GZIP
- HTMLMINIFY
- IMGOPTIMIZE
- JSMINIFY
- MODERATE
- NOCLIENTAUTH
- NOCOMPRESS
- NONE
- NOOP
- NOREWRITE
- RESET
- SETASLEARNNSLOG_ACT
- SETNSLOGPARAMS_ACT
- SETSYSLOGPARAMS_ACT
- SETTMSESSPARAMS_ACT
- SETVPNPARAMS_ACT
- SET_PREAUTHPARAMS_ACT
- default_DNS64_action
- dns_default_act_Cachebypass
- dns_default_act_Drop
- nshttp_default_profile
- nshttp_default_strict_validation
- nstcp_default_Mobile_profile
- nstcp_default_XA_XD_profile
- nstcp_default_profile
- nstcp_default_tcp_interactive_stream
- nstcp_default_tcp_lan
- nstcp_default_tcp_lan_thin_stream
- nstcp_default_tcp_lfp
- nstcp_default_tcp_lfp_thin_stream
- nstcp_default_tcp_lnp
- nstcp_default_tcp_lnp_thin_stream
- nstcp_internal_apps