CFI AND CFI SCRIPT

Communication between client and DeleGate or between DeleGate and server can be filtered or translated by user defined filter programs attached to DeleGate using a simple scheme named CFI (Common Filter Interface). Existing filter programs, from standard input to standard output, can be used as a CFI program without modification. The usage of CFI is controlled by parameters like following:

filterName="filterSpec"
CMAP="filterSpec":filterName:connMap

  filterName  ==  FCL | FTOCL | FFROMCL |
                  FSV | FTOSV | FFROMSV |
                  FMD | FTOMD | FFROMMD 
  filterSpec  ==  filterCommand | CFIscriptName
                  | tcprelay://host:port

filterName is named as FXX, FTOXX and FFROMXX where XX is one of CL (client), SV (server) and MD (MASTER-DeleGate). Filter commands for FXX are bidirectional filter given file descriptor 0 bound for the client, and file descriptor 1 bound for the DeleGate. Filters commands for FTOXX and FFROMXX getting input from standard input and put output to standard output which is bound for XX. A unidirectional filter at a remote host can be used by connecting it on TCP by "tcprelay://host:port"

A filter can be applied conditionally based on circuit level information, using CMAP parameter like follows:

CMAP=filterSpec:filterName:ProtoList:dstHostList:srcHostList
For example, CMAP="sslway:FSV:telnet:hostA:*" means applying SSLway filter only when connecting to the Telnet server at hostA.

For FTOXX and FFROMXX filters, CFI script enables selecting an appropriate filter to be applied to each data depending on the type of data. Instead of direct usage of a filter program like FTOCL=filterCommand, specify FTOCL=filter.cfi where filter.cfi is a file in the CFI script format. Or a CFI script can be loaded from remote host like FTOCL=URL via HTTP or FTP. When the file name of CFI scripts or a filter command referred in the script is specified in relative path name, it is searched in LIBPATH.

CFI script

The CFI script is a simple script to select an appropriate filter to be applied to a message data relayed on DeleGate, depending on the type of data, the server name, the type of client, and so on. A CFI script is text data which starts with a magic string "#!cfi" and contains more than one filter specifications which are separated by "--" with each other.

  CFI script   == "!#cfi" NL filterUnit [ "--" NL filterUnit ]*
  filterUnit   == filterRule [ filterRule ]*
  filterRule   == matchingRule | rewriteRule | filterSpec
  matchingRule == matchingName ":" ruleBody
  matchingName == MIMEheader | X-header | CGIENV
  MIMEheader   == "Content-Type" | "User-Agent" | ...
  X-header     == "X-Status-Ver" | "X-Status-Code"
                | "X-Request-Method" | "X-Request-Ver"| "X-Request-URL" | ...
  CGIENV       == "REQUEST_METHOD" | "SERVER_PROTOCOL" | "SERVER_NAME"
                | "PATH_INFO" | "PATH_TRANSLATED" | "HTTP_USER_AGENT" | ...
  rewriteRule  == Action "/" MIMEheader : ruleBody
  Action       == "Output" | "Remove"
  filterSpec   == filterType ":" ruleBody
  filterType   == "Body-Filter" | "CGI" | "Header-Filter"
                | "MIME-Filter" | "Message-Filter"
  ruleBody     == string NL [ SP  string NL ]*

Input Format:
The input data to CFI script is a message of application protocol in MIME format preceded with a request or a response status line of the application protocol (HTTP, SMTP, POP, NNTP). A MIME message is composed with a header and a body separated with an empty line.

  CFIinputMessage == statusLine MIMEheader NL MIMEbody

Example: a simple HTTP response message

HTTP/1.0 200 OK           ... response status line
Content-Type: text/html   ... header
Content-Length: 20        ... header
                          ... header/body separator
body of the message       ... body

Matching Rule:
A matchingRule indicates matching the ruleName:ruleBody to the input header. It matches when the input message has a ruleName header with a field body matches with ruleBody. If at least one of matching rules turns to be true, then the filterUnit is adopted. If no matching rule is included in a filterUnit then the filterUnit is adopted unconditionally. Currently, only a limited set of MIME headers (in request or response message) can be used for the matching. Also, some extended headers can be used to match with information not included in the original header (ex. "X-Status-Code" which means status code in response message). Matching with CGI environment variables.

Example: a matching rule

#!cfi
HTTP_USER_AGENT: MSIE
SERVER_HOST: www1.dom1
SERVER_HOST: www2.dom2
X-Status-Code: 200
Content-Type: text/html
Content-Type: text/plain
Body-Filter: ...


Rewriting Rule:
A rewriteRule with a prefix "Action/" to a ruleName:ruleBody specifies some simple rewriting using ruleBody data for relevant ruleName field. "Output/ruleName:ruleBody" indicates appending (or replacing) a ruleName:ruleBody field into the header. "Remove/ruleName:ruleBody" indicates removing header fields with name ruleName and body matches to ruleBody.

Filter Specification:
A filterSpec specifies a filter to be applied to the input data. The whole or a part of input message will be passed to the standard input of the filter program, then the output from the standard output of it will be forwarded to the destination (client or server) instead of the original input message.

  Body-Filter:    filter for MIMEbody
  CGI:            filter for MIMEbody
  Header-Filter:  filter for MIMEheader
  MIME-Filter:    filter for MIMEheader + MIMEbody
  Message-Filter: filter for statusLine + MIMEheader + MIMEbody

For filters of any type, the set of CGI environment variables is passed. In addition, CFI origin environments variables are passed including "SERVER_HOST" (the name of the destination server), "REQUEST_URL" (the URL of the request).

For filters of "Body-Filter" or "CGI", the "Content-Length" header in the forwarded message will be adjusted to indicate the size of the body part after the filtering. The output of "CGI" filter must preceded with the status header of CGI output.

For filters of "Header-Filter", the header part of a message will be passed to and from the filter. The start-line in the HTTP message (Request-Line or Status-Line) will be passed as a header field prefixed with "Request-Line:" or "Status-Line:".

For filters of "MIME-Filter", the whole of the MIME message consists of a header and a body is passed to and from the filter.

For filters of "Message-Filter", the whole message of the application protocol is passed to and from the filter where each message consists of a MIME message prefixed with a line representing request or response status in the application protocol.

Example: rewriting HTTP response messages

SERVER=http FTOCL=test.cfi

[content of test.cfi]
#!cfi
Content-Type: text/html
Body-Filter: sed 's/string1/string2/'
--
Content-Type: image/gif
Output/Content-Type: image/jpeg
Body-Filter: gif2jpeg


Example: dump available headers and environment variables

#!cfi
Header-Filter: -tee-n-v /dev/tty
Body-Filter: env|sort > /dev/tty; cat