Expressions

Overview

EZproxy has the ability to perform complex string and math manipulations to allow advanced authorization decisions. The following information explains the constant, variables and functions that are available to create complex expressions.

The EZproxy administration page provides a Test user.txt configuration option, which can be used to experiment with variables and functions.

From the Test user.txt configuration page, you can check the Force Debug option and then enter a test like this:

::Common 
If login:user eq "test"; Msg user is test 
If login:user =~ "/^(.)(.)(.)(.)$/" { 
Set rev = re:4 . re:3 . re:2 . re:1 
Msg 4-letter username reversed and stored in rev 
} 
/Common 

If you paste in this example, try entering the 4-letter usernames test and TEST, noting that only the lower-case test triggers the message "user is test" to appear since eq is case-sensitive.

Conventions

aggvar

The base name of a variable that can have one or more value, such as the base name of an array or the name of an auth: variable that returns multiple values; when used with an aggregate test, EZproxy will also include any non-array variable of the specified name in the test (e.g., abc, abc[1], and abc["xyz"] are all considered when performing an aggregate test for the variable abc).

bool, bool1, bool2

For Boolean values, empty strings and 0 are considered to be false, all other values are considered true.
The result of a Boolean operation is 0 if the value is false or 1 if the value is true.

dt

A numeric value representing a date/time as the number of seconds that have elapsed since midnight, January 1, 1970.

int, int1, int2

An integer numeric value (any decimal portion is ignored).

num, num1, num2

A numeric value that can include decimal points.

str, str1, str2

A string value.

re

A string containing a regular expression; the string must starts with a non-alpha, non-digit character, a pattern, the same non-alpha, non-digit character, and may optionally be followed by i for a case-insensitive comparison and/or g to indicate a global replace.

wild

A wildcard comparison string which is compared using a case-insensitive comparison and in which ? matches to any single character and * matches 0 or more characters.

Constants

Numeric constants are formed from digits and an optional decimal point.

String constants must be surrounded by either a single quote (') or a double quote (") characters. The use of a single quote (') or double quote character (") has identical meaning to EZproxy. Within a string, the backslash (\) can be used to escape the string quoting character (e.g. O'Grady can be specified as 'O\'Grady' or "O'Grady"). Since backslash acts as an escape character, two backlashes (\\) must be used within a string to specify a single backslash (\) character.

Variables

Standard variables are case-sensitive and must start with a letter which can be followed by any combination of letters, digits, underscores (_), and at signs (@). Variables may also be followed by an opening square bracket, an expression that forms an associate index, and a closing square bracket to store values in an associative array.

There are several namespace prefixes that are used to access special variable sets. The standard namespace prefixes are auth:, db:, login:, re:, and session:.

The auth: namespace is used to access variables from an authentication source. Examples of support authentication methods include CAS, HIP, III, LDAP, Shibboleth, SIP, and TLC. The auth: variables are only available during the processing of user.txt, so any value that needs to be retained should be stored in a session: variable. See the example below. If an authentication source can return more than one value for the same variable, access the first value by include [0] at the end of the variable names, [1], for the second, etc. When using auth:, the variable names can include any of these additional special characters: ! # $ % & * + - . / ^ | ~

The db: prefix provides access to database definition information within the ^B/^E loop of menu.htm. The variables available include db:title, db:description, and db:url.

The env: prefix provides access to operating system environment variables.

The login: prefix provides access to key variables that come from login.htm and loginbu.htm during login, including login:auth, login:pass, login:pin, login:url, and login:user. If a value is assigned to login:loguser during login process, the assigned value is used as the username for the user. A value may be assigned to login:user to override the username that is tested by authentication methods.

The re: namespace provides access to the last values that matches during a regular expression comparison, with re:0 holding the last value matched, and re:1 through re:9 holding any values captured by parentheses.

The session: namespace can be used to store values in variables that survive across the entire user session. These variables can be used in files such as menu.htm using the syntax ^{expression}. The special variable session:admin returns 1 if the logged in user is an administrator, 0 if not. The special variable session:user provides the current username if some function has activated username tracking (e.g., if auditing is enabled).

Expressions

Expressions are formed by mixing constants and variables using any appropriate combination of the following comparisons, operations, and functions.

The most common uses for expressions occur in user.txt with an authentication method block using the If or Set directives. For example:

::SIP
Host sip.yourlib.org
SIP2
IfUnauthenticated; Stop
If auth:BV >= 10 || auth:AT > 5; Deny delinquent.htm
Set session:fullname = auth:AE
/SIP 

can be used to deny access if someone's outstanding fines (BV in SIP) are $10 or higher, or if the user has five or more items overdue (AT in SIP), and to store away the person's name (AE in SIP) in a session variable called fullname that can then be referenced in menu.htm with ^{session:fullname}.

Numeric operations

num1 + num2

Add num1 to num2

num1 - num2

Subtract num2 from num1

num1 * num2

Multiply num1 by num2

num1 / num2

Divide num1 by num2

int1 % int2

Integer modulus of int1 and int2 (the integer remainder of the division of int1 and int2)

int1 & int2

Bitwise and of int1 and int2

int1 | int2

Bitwise or of int1 and int2

String operation

str1 . str2

Concatenate str1 and str2 together into a single string

Boolean operations

For Boolean operations, empty strings and 0 are considered to be false, all other values are considered true. The result of a Boolean operation is 1 if the value is true or 0 if the value is false.

! bool

1 if bool is considered false, 0 otherwise (not operator)

bool1 && bool2

1 if bool1 and bool2 are considered true, 0 otherwise (and operation)

bool1 || bool2

1 if bool1 or bool2 are considered true, 0 otherwise (or operation)

bool ? val1 : val2

val1 if bool is considered true, val2 otherwise (ternary operation); this expression now evaluates to be equivalent to var = (bool ? val1 : val2)

Miscellaneous operations

var = val

Used to assign a value to variable

expression1, expression2

Multiple expressions be combined with a comma, which is most often used to perform multiple variable assignments in a single expression (e.g., a = 1, b = 2, c = 3).

Numeric comparisons

These comparisons are based on the numeric values of the values being compared (e.g., 2 is less than 10).

num1 < num2

1 if num1 is less than num2, 0 if not

num1<= num2

1 if num1 is less than or equal to num2, 0 if not

num1 == num2

Note: this symbol is two equal signs and not just a single equal sign
1 if num1 equals num2, 0 if not

num1 != num2

1 if num1 is not equal to num2, 0 if not

num1 >= num2

1 if num1 is greater than or equal to num2, 0 if not

num1 > num2

1 if num1 is greater than num2, 0 if not

String comparisons

Unless otherwise noted, these comparisons are case-sensitive based on the sequences of characters in the string values being compared (e.g., "10" is less than "2" since the character "1" comes before the character "2", and "B" is less than "a" since internally "B" comes before the character "a"). To perform a case-insensitive comparison, use either the Upper or Lower function (e.g., Upper("B") is greater than Upper("a") since "B" is comes after "A", and likewise Lower("B") is greater than Lower("a") since "b" comes after "a").

str1 lt str2

1 if str1 is less than str2, 0 if not

str1 le str2

1 if str1 is less than or equal to str2, 0 if not

str1 eq str2

1 if str1 is equal to str2, 0 if not

str1 ne str2

1 if str1 is not equal to str2, 0 if not

str1 ge str2

1 if str1 is greater than or equal to str2, 0 if not

str1 gt str2

1 if str1 is greater than str2, 0 if not

str =* wild

1 if str is wildcard equal to wild, 0 if not

str =~ re

1 if str matches the regular expression re and set local variable re:0 to the match string and re:1 through re:9 to anything capture by parentheses, 0 if not.

str !~ re

0 if str matches the regular expression, 1 if not and set local variable re:0 to the match string and re:1 through re:9 to anything capture by parentheses

Functions

If CompareIP("192.168.1.1", "192.168.001.001") eq "0"; Msg "Addresses match"

# Example 1: name in surname, forename middleName, nameSuffix format
# store results to surname, title, forename, middleName, nameSuffix
Set ParseName(name, "S,TFM,X", "")
# Example 2: name in title forename middleName surname nameSuffix
# store results to session:title, session:forename, session:middleName,
# session:surname, session:nameSuffix,
Set ParseName(name, "TFMSX", "session")

SSOUsername ssotest PPID("sts")

^{UserFile("greeting.txt"), greeting}

::Common
Set now = DateTime()
Set hour = FormatDateTime("%H", now)
Set timeOfDay = "afternoon"
If hour < 12; Set timeOfDay = "morning"
If hour >= 18; Set timeOfDay = "evening"
Set greeting = "Good " . timeOfDay
/Common

GeoLite data

This product includes GeoLite data created by MaxMind, available from www.maxmind.com .