Network Traffic Interceptor

Peter V. Radatti
CyberSoft, Inc.
radatti@cyber.com
June 10, 2002

Introduction

The CyberSoft Network Traffic Intercepter (NTI) is the component of the VFind Security Toolkit (VSTK) that intercepts data on Unix TCP connections and arranges for them to be validated using the virus scanning tools uad and Vfind. This enables scanning of connections both into and out of a computer and is independent of and transparent to the applications and server daemons that communicate using the supported protocols.

The NTI currently works in a Unix STREAMS environment under Sun Solaris and Hewlett-Packard HP-UX.

User Documentation Index

Overview: Feature list, overview, and theory of operation.

Install: Installation instructions.

User_doc: Description of NTI operation from a user's perspective.

conf_example: Default configuration file walkthrough.

conf_file: Protocol Daemon Configuration File Format. Also documents command-line options.

smime: Description of S/MIME processing.

cert_verify_api: SSL Certificate Verifier API specification.

mail_reprocess: Description of the function and interface of the mail reprocessing application.

tpicept_tpi.h: tpicept kernel interface header file.

CyberSoft Network Traffic Intercepter

Features

STREAMS kernel module which efficiently and seamlessly selects and intercepts TCP network connections.
Protocol processor which can interpret HTTP, FTP, POP3, and SMTP and will delineate files or messages for virus scanning or other validation. Files/messages can be substituted if necessary.
Fully configurable via simple text configuration file and command-line options.
Protocols can be selected to be intercepted on any TCP ports or port ranges, both client (outgoing) or server (incoming) connections, or direction of file/message transfer.
MIME types can be selected for interception via a flexible include/exclude list with wildcards.
Interception and scanning of SSL-wrapped protocols (such as HTTPS and POP3s) and SSL-enabled sessions (SMTP and POP3 with the STARTTLS command) by creating an SSL proxy.
Debug/trace mode of the protocol processor is useful as an analysis tool for higher level protocols, especially if encrypted.
Kernel TCP interception API can be utilized for other protocol processing applications.
Content validation (scanning) is fully configurable and can be easily tied in to external software subsystems. The default configuration is virus scanning using the CyberSoft uad and vfind software components.
Offending files/messages are logged and held for administrative review.
Scanning of S/MIME encrypted mail messages. This is performed using an internal validation step that decrypts the message and passes it on for further decomposition and virus scanning. Private keys are retrieved from the Netscape key database.
Certificate authority verification mostly duplicating Netscape's functionality and reading Netscape's certificate database.
Stand-alone validation using the protocol daemon as a filter for files and messages (such as email being deposited into local mailboxes).

Overview

The Network Traffic Intercepter (NTI) subsystem consists of three main components:

tpicept: A kernel component which allows TCP traffic between applications and the external network to be routed through another application. The effect of this can range from total transparency to blocking and replacement of data. It is implemented as a tightly-coupled STREAMS module and driver.

The tpicept module is normally configured to be automatically attached to every TCP connection by configuring the STREAMS autopush facility (see autopush(1M)) to add tpicept to the list of modules pushed onto every open of the /dev/tcp device. These opens may be explicit or implicit via kernel or library code, for example the SYS_so_socket system call. At this layer the STREAMS messages are the TPI (Transport Provider Interface) protocol. The module is configured to selectively route these messages through the tpicept driver to a user-space application, normally the NTI protocol daemon.

The tpicept driver is accessible via the /dev/tpicept pseudo-device. This interface is used by the NTI protocol daemon to configure the interception conditions of the tpicept module and process network data from intercepted TCP streams.

nti_protocold: A daemon which manages interception, interprets application protocols, and coordinates scanning of files and messages.

The protocol daemon is driven by a configuration file that determines which TCP ports to intercept and which application protocols to expect on them. The protocol daemon can interpret FTP, SMTP, POP3, and HTTP protocols and isolates files and messages for validation that meet specified constraints.

The configuration file also specifies how content validation is performed.

VFind Toolkit: A set of applications which analyzes suspect files and scans them for viruses or performs other content filtering. Files and messages are received from the protocol daemon and the vfind applications decompose, decode, test, and then return the desired result action back to the protocol daemon.

Theory of Operation

nti_protocold opens a pair of tpicept driver instances and associates them as a pair in order to wait for a connection to be attached. These file descriptors are the means by which the application in user space sends and receives kernel network data and the means by which the kernel operation is configured and controlled.
The user application opens a connection to the networking subsystem, either to make an outgoing connection or receive incoming connections. The tpicept kernel module is inserted into this STREAM through the autopush mechanism. This allows the connection to be intercepted automatically, unconditionally, and transparently to the application.
Unless and until the proper conditions are met the tpicept kernel module shunts messages directly to/from their intended destination. This mechanism allows the TPI subsystem to have minimal impact on the performance of the computer and networking connections unless a connection using the appropriate protocol is detected.
When an appropriate incoming connection is received or an outgoing connection is established, a waiting pair of tpicept driver instances is "attached" by the tpicept module. This establishes the relationship between a stream of network data flowing in the kernel and the nti_protocold application which performs protocol analysis and content selection.
Both directions of protocol and user data flow to/from nti_protocold, which interprets both TPI (a kernel protocol used to manage network connections at the network/session layer) and application protocols. nti_protocold interprets application-layer protocol commands and other elements and delineates and captures user data files or messages. These file or message units are each subject to content selection such as scanning for viruses.
Files/messages are sent to other applications uad and vfind which analyze and validate the data and return a result to nti_protocold.
nti_protocold either forwards the data along to its intended destination through the tpicept connection or constructs appropriate substitute messages indicating a virus scanning failure. In this way the undesirable data is prevented from entering or leaving the computer over the network and a useful diagnostic message may be shown to the human user.
The user application closes the connection to the networking subsystem causing the STREAM to be dismantled. The attachment to the tpicept kernel drivers is broken and they then wait for the next attachment.

Notes

Instances of nti_protocold and tpicept driver pairs are created dynamically as needed to support the current load.

In addition to TPI protocol and user data, special messages are sent between nti_protocold and the tpicept driver instances for control and housekeeping of the connection.

CyberSoft Network Traffic Intercepter Installation

Supported platforms

SunOS 5.5.1 (Solaris 2.5.1) SPARC or Intel
SunOS 5.6 (Solaris 2.6) SPARC or Intel
SunOS 5.7 (Solaris 2.7 or 7) SPARC or Intel
SunOS 5.8 (Solaris 8) SPARC or Intel
SunOS 5.9 (Solaris 9) SPARC or Intel
HP-UX 11.0 (32-bit)

Required Operating System Patches

For Solaris 2.5.1, 2.6, 7, or 8 there are not any particular patches required for proper operation of the NTI software. However it is prudent for maximum reliability to install any current recommended patches.

Installation

NTI is installed on a Solaris system by changing directory to the mounted distribution media or extracted archive location and running the install script install.sh as the root user.

Step-by-step

Insert the CD-ROM into your CD-ROM drive.
If you do not have an "auto-mounting" daemon, then use the mount command to mount the cd. (please see mount(1) in your Unix system manual) for example:
```
mount -t iso9660 /dev/cdrom /mnt/cdrom
```
Once the CD is mounted, use the cd command to change your current directory to that of the cdrom at it's top level. for example:
```
cd /mnt/cdrom
```
Read the file noarch/legal.txt. This is a copy of your right to use license.
Proceeding with this step means that you agree to the terms in noarch/legal.txt. Making sure that you are in the root directory of the CD-ROM run the install.sh script:
```
./install.sh
```
Follow the instructions in the install script.
Now you must setup a valid usage license or demo license.
Change directory to the VSTKP base installation directory that you specified during the install process. In it, you will find an example license in a file called LICENSE. This is an example only. You may *NOT* edit this or *ANY* license file or it will not work. If you were supplied with a Permanent Activation Key, or a Demo Key, then replace the example license file with the supplied key. Please double and triple check your license file if you entered it by hand. If you want to inquire about a Demo Key or a Permanent Activation Key then contact the CyberSoft Sales Support Center.

During the installation process, files are copied to appropriate places. A default nti_protocold configuration file is installed. The system startup is amended to autopush the tpicept module and start running nti_protocold.

CyberSoft Network Traffic Intercepter

User-visible effect

The main noticeable user-visible effect will be that files and messages transferred from or to the network will not appear to be transferred gradually but rather will appear "all at once" after the delay required to actually transfer the file. This effect is similar to that seen with certain proxies or network-level content filters. For small files, non-interactive operations (such as SMTP) or fast networks this effect should be barely noticeable. Otherwise you may notice:

The application may not report that the operation has started until the very end.
Progress indicators will not show any progress until the very end.
Estimates of transfer rate and time remaining may be grossly inaccurate.
In rare cases the application may time out the operation before it is completed. Fortunately most applications that may do this allow you to adjust the amount of time before timeout.

Because of the additional steps required and the rerouting of data between the kernel and the daemons, overall performance may be affected somewhat, especially under heavy load.

SSL Connections

Intercepted SSL connections made using the HTTPS protocol will behave somewhat differently from non-intercepted connections. The NTI works as an SSL proxy and actually manages two separate SSL protocol connections, one with the client application and one with the remote server. From the client's point of view (usually this is a Web browser) all connections will look like they are being made to a single remote site with a single server certificate.

From the remote server's point of view things might work slightly differently because the SSL protocol engine is based on OpenSSL rather than the browser (which may have a different cipher set, options, etc.). This means that configuration of options related to the remote SSL connection such as protocol versions, available ciphers, and certificate verification must be done through the NTI rather than with the browser's configuration. However NTI is able to read the user's private Netscape certificate database which allows certificates to be managed through the browser interface. The NTI however can not change this database directly so if an untrusted site is contacted the NTI (if configured appropriately) will pop up it's own dialog requesting confirmation. If the user indicates that the certificate should be stored permanently then the NTI will store it in its own (global) database. For certificate authorities the user should then import this certificate into the Netscape database using links provided on the authority's site for this purpose.

There are some situations when the user may receive multiple pop-ups to verify the same certificate, or when the "for this session only" does not seem to persist the entire life of the browser's session. This is due to the implementation of multiple connections through the NTI and the fact that the NTI can have no direct knowledge of the span of a user's session.

At present it is not possible for the NTI to automatically verify certificates which are only for a specific site rather than ones which are issued by a known certificate authority. This is an inherent limitation of the verification mechanism in the OpenSSL library package used to implement SSL in the NTI.

Ports and Protocols

The NTI subsystem is configured to intercept traffic on specific TCP ports. It may intercept both incoming and outgoing connections. It presumes that traffic on particular ports will always be a certain protocol, for instance SMTP for port 25 or HTTP for port 80. If a different protocol is used on these ports, or new or experimental features of a protocol are used, it is possible that nti_protocold may get confused and log error messages, hang the connection, or even cause some kind of protocol inconsistency or error in the application on either end.

TCP ports which have not been configured for interception by the NTI subsystem will pass traffic transparently. This may be undesirable in some cases when non-standard ports are used for well-known protocols (HTTP is the most common example of this).

Rejected files

Files and messages which have failed the virus-scanning tests (meaning that an actual virus was detected) or have had other problems in the validation process are "embargoed" in a directory (default /var/tmp) for later manual analysis. This directory should be checked and cleaned up periodically.

Reject text describing the failure in an appropriate format is substituted for the actual file or message transferred as follows:

FTP: The description file is simply substituted.

SMTP, POP3: A message header "Virus-Scan-Status: reason" is added. The reason may be "rejected", "quarantined", or "exception" depending on the results of validation.

HTTP GET: An HTTP error is returned. Depending on the results of validation the error may be "471 Virus-infected File Rejected", "472 Possible Virus-infected File Quarantined", or "473 Content validation subsystem failed".

HTTP PUT, POST: The request contains the header "If-Match: "Virus-infected-file"" which should cause the operation to fail with a "412 Precondition Failed" error.

Stopping the Protocol Daemon

The protocol daemon may be stopped by sending a SIGHUP, SIGINT, or SIGTERM signal to the top-level process. This will cause the kernel module to stop intercepting new connections and will direct each subprocess to clean up its connection and detach from the interception. A message will be logged to syslog when this is complete. All connections will pass messages transparently after the daemon exits.

Stopping the daemon cleanly is most easily accomplished through the -k option of nti_protocold or the /etc/init.d/nti_protocold_init script.

Known Problems

On HP-UX if the kernel components are reinstalled multiple times without rebooting eventually the installation will fail until after the next reboot. The exact number is system-dependent but is usually around 15-20. This issue should only arise during development or testing when multiple installs are performed. It relates to the dynamic allocation of device major number by the dynamic loading subsystem. HP is aware of this problem and may fix it in a future release or patch.

Netscape Communicator may pop up a message the first time an HTTPS site is contacted indicating a "name mismatch" of the server's certificate. This is because NTI's certificate does not match the name of the server. It is harmless and should always be approved by the user.

CyberSoft Network Traffic Intercepter Default Configuration File Walkthrough

Here we describe the default NTI configuration file nti_protocold.conf.

# $Id$  Copyright (c) 1998-2002 CyberSoft, Inc.

# An example configuration used for scanning

# Global options and directory definitions
global:

After some initial comments, the global section is introduced. Items in this section affect the program as a whole.

do_fork

do_fork mode is always specified for production use so that the program can intercept multiple connections and manage process start and timeout.

dir=/opt/vstk/nti

The program changes into this directory so that pathnames elsewhere in the configuration can be specified relative to this. This makes for fewer paths to modify if the location changes.

reject_dir=reject
	quarantine_dir=quarantine
	exception_dir=exception

These specify directories where files or messages go when they are rejected (due to a virus, for example), quarantined (because an S/MIME decryption key is not known), or validation fails in some other way (the VFind license expired, for example). Note that these directories are relative to /opt/vstk/nti as specified above.

# Extra environment variables passed to validation steps and helper applications
env:

In this section, instead of the keyword=value form setting specific predefined options, it allows arbitrary environment variables to be defined. These add to or replace the environment received upon invocation of the program. They are most useful for passing additional information to validation applications.

PATH=/opt/vstk/nti/bin:/opt/vstk/bin

Setting of PATH is mostly useful to allow simple relative paths to be used when specifying validation steps and helper applications.

VSTK_HOME=/opt/vstk

This is required so that the VFind applications know where to find their additional files.

# Scan specification sections, one per protocol to be intercepted

scan: proto=ftp	#FTP control stream. Type of interception is specified here.

This introduces a scan section. There may be several scan sections, each handling a different protocol. The first item here specifies that this section is for intercepting the FTP (File Transfer Protocol) control channel.

port=21

21 is the standard control channel port for FTP, and is almost always the only one used except when testing. The port keyword specifies interception of both incoming (server) and outgoing (client) connections. The program examines the control protocol to determine which ports will be used to transfer files, and sets up interception of these ports. Note that since no file data flows on the control port, validation-related options are not specified here.

scan=both

We want to scan (validate) files moving in either direction on either type of connection (incoming or outgoing).

scan: proto=ftpdata 
#FTP data stream. Replacement file definitions are specified here.

This scan section is used to control validation of files transferred via the FTP protocol.

port=20 
# not used for matching if control stream is intercepted

Normally this port specification is ignored, as FTP data ports to intercept are determined automatically and dynamically by examining the control protocol. It remains here in case the scan section for ftp is removed, in which case port 20 will be intercepted. This would only intercept certain types of FTP data connections.

reject_file=messages/reject_file_msg.txt
	exception_file=messages/exception_file_msg.txt

These specify file templates used when an FTP file transfer is rejected or incurs an exception during validation. Since files sent via FTP have no specific structure such as MIME the only replacement message we can use is simple plain text. For the same reason FTP files can never be quarantined since they are never considered as S/MIME messages.

scan: proto=smtp # Mail transport

This scan section is used to control validation of messages sent via SMTP (Simple Mail Transfer Protocol) to an MTA (Mail Transport Agent) such as sendmail from another MTA or from an MUA (Mail User Agent) such as Netscape or Eudora.

port=25  #Intercept both directions
# port_client=25 
#When using replacement /bin/mail only intercept outgoing to avoid double-scanning

25 is the standard protocol port for SMTP, and is almost always the only one used except when testing.

There are two options shown here. The default is to only intercept network mail, in which case we intercept both incoming and outgoing connections. The second option is to replace /bin/mail with a script that uses NTI in standalone mode to validate mail sent to local mailboxes. This script intercepts all local-delivery mail including mail from the network, so we specify here to only intercept outgoing (client) connections to avoid double-validation of incoming mail. An added advantage of this option is that mail that is relayed through this machine is not double-validated as it would be with the first option.

allow_starttls

This allows use of the STARTTLS SMTP command to switch to encrypted SSL mode. This method differs from HTTPS (HTTP over SSL) in which a different TCP port is used to indicate an SSL connection and SSL is negotiated before starting the HTTP protocol. An equivalent method for SMTP has never been widely implemented (because the STARTTLS method is preferred) but is supported by NTI if you specify a port using an ssl_port* keyword.

scan=both  # both client and server smtp
# scan_client=send_class2  # S/MIME mail scanning

With SMTP mail messages only flow from client to server, but this first line simply covers all cases when it is desired to validate all mail. It could have been specified as scan_client=send scan_server=receive to not include the unused cases of server to client flow.

The second line restricts validation to outgoing messages and specifies a non-default validation class when it is desired to decrypt and validate S/MIME mail. This option only makes sense when used with the /bin/mail replacement script.

# This section defines fancy messages with MIME log attachments
reject_file=messages/reject_mail_msg.multipart  # w/o original embedded
# reject_file=messages/reject_mail_msg_embed.multipart  # w/ original embedded
reject_file_type=multipart/mixed
quarantine_file=messages/quarantine_mail_msg.multipart
quarantine_file_type=multipart/mixed
# exception_file=messages/exception_mail_msg.multipart  # w/o original embedded
exception_file=messages/exception_mail_msg_embed.multipart # w/ original embedded
exception_file_type=multipart/mixed

These specify replacement message templates that include the error logs for the various components as MIME attachments. The default version throws away messages that failed validation, but you may also choose a version that includes the rejected message as a MIME attachment.

# This section defines simple messages with inline logs
# reject_file=messages/reject_mail_msg.txt
# quarantine_file=messages/quarantine_mail_msg.txt
# exception_file=messages/exception_mail_msg.txt

If you're using an MUA that only handles plain text or you just don't like MIME attachments you can choose these plain text versions. Note that the file type is not specified and defaults to a Content-Type of text/plain.

scan:	proto=pop3	# Mailbox access

This scan section is used to control validation of messages sent via POP3 (Post Office Protocol, version 3). The server is a POP3 server and the client is typically an MUA (Mail User Agent) such as Netscape or Eudora.

	port_client=110 ssl_port_client=995
	allow_starttls

110 is the standard protocol port for plain POP3, and is almost always the only one used except when testing. 995 is the standard port used for POP3 over SSL, in which SSL is negotiated before starting the POP3 protocol. We also support the method using the STLS command on a plain channel. Either of these methods are used by various POP3 implementations.

We only validate client (outgoing) connections. Incoming POP3 connections are retrieving local mail messages that have been deposited via /bin/mail or SMTP and therefore have already been validated by NTI.

	scan=both
#	scan_client=receive_class1	# S/MIME mail scanning

Similarly to SMTP the default scan types cover all cases even though mail only flows from server to client in POP3. The second version specifies a non-default validation class for decrypting S/MIME mail.

# This section defines fancy messages with MIME log attachments
reject_file=messages/reject_mail_msg.multipart # w/o original embedded
# reject_file=messages/reject_mail_msg_embed.multipart # w/ original embedded
reject_file_type=multipart/mixed
quarantine_file=messages/quarantine_mail_msg.multipart
quarantine_file_type=multipart/mixed
# exception_file=messages/exception_mail_msg.multipart # w/o original embedded
exception_file=messages/exception_mail_msg_embed.multipart # w/ original embedded
exception_file_type=multipart/mixed

# This section defines simple messages with inline logs
# reject_file=messages/reject_mail_msg.txt
# quarantine_file=messages/quarantine_mail_msg.txt
# exception_file=messages/exception_mail_msg.txt

These replacement messages are identical to those for mail transported via SMTP.

scan:	proto=http	# Web service

This scan section is used to control validation of files sent via HTTP (HyperText Transfer Protocol). The server is a Web server such as Apache and the client is typically a Web browser such as Netscape.

	port_client=80-81,3128,8000,8080,8800 ssl_port_client=443

80 is the standard protocol port for plain HTTP. Some other commonly-used web server ports are also intercepted, as well as 3128 for the Squid web proxy. 443 is the standard port used for HTTP over SSL, in which SSL is negotiated before starting the HTTP protocol. HTTP does not support a method of starting SSL from a plain connection.

We only intercept client (outgoing) connections because incoming connections are accessing local content that should not require validation, and validation would cause a big performance reduction for a local web server.

	scan_outgoing=receive

Only incoming files (received via HTTP commands such as GET) are validated since outgoing files (e.g. using POST) generally do not contain whole files that might be a threat.

	include_types=text/plain,application/msword,application/octet-stream,
		application/x-tar,application/x-gtar,application/x-ustar,
		application/x-cpio,application/x-bcpio,application/x-sv4cpio,
		application/x-sv4crc,application/x-shar,application/x-stuffit,
		application/mac-binhex40,application/zip,
		application/x-zip-compressed,application/x-compress,
		application/x-gzip,application/x-sh,application/x-csh,
		application/x-javascript

Only files with these MIME types will be validated. The list contains known types of files that may contain viruses. text/plain is included since this type is often associated with unknown file types. Conspicuously absent is text/html since it cannot contain viruses. If your content validation is not a virus scanner then you may need to change this list.

	reject_file=messages/reject_file_msg.html
	reject_file_type=text/html
	exception_file=messages/exception_file_msg.html
	exception_file_type=text/html

These specify replacement message templates that include the error logs for the various components formatted with HTML. Unfortunately there is no way with HTML to include content of linked sections in a single file, so the presentation must be inline. Note that HTML special characters (angle brackets and ampersands) contained in the error logs are not escaped and may confuse the output.

# Validation steps, specified in pipeline order
# Steps not in the default class (0) are not included
unless referenced in the scan spec
validate: args="uad -ssw --stdin -z"
	capture_stderr=1

First we process the file or message through UAD, the Universal Atomic Disintegrator, to recursively de-encapsulate components. -ssw causes the output to be written in a structured stream format (SmartScan) understood by vfind and the internal S/MIME decryption module. The standard error output is captured and may be referenced in replacement files using marker number 01.

validate: smartscan_smime_decrypt capture_stderr=3 class=1
validate: smartscan_smime_decrypt capture_stderr=3 class=2 exclude_users=root,daemon

One of these steps is used only when the scan spec references one of the classes specified here. Class 1 is used for POP3 messages and always processes the message. Class 2 is used for SMTP messages and is skipped if one of the excluded users is processing the message. Since sendmail generally only runs as root or daemon when acting as a daemon, this behavior prevents relayed mail from requiring decryption since it is unlikely the decryption keys would be found locally.

This internal validation step attempts to decrypt the MIME mail message. If successful it feeds its output back through the top of validation so that the nested content can be decomposed and/or decrypted (there's a large helping of specialized magic here that makes this only likely to work using the supplied tools).

The standard error output is captured and may be referenced in replacement files using marker number 03.

validate: args="vfind -ssr -vexit -quiet=2" reject_codes=23
	capture_stderr=2

This step performs virus scanning of its input which comes in the form of the SmartScan protocol from uad and smartscan_smime_decrypt.

The standard error output is captured and may be referenced in replacement files using marker number 02.

# Type name definitions for user command virus scanning
standalone: name=file proto=ftpdata
standalone: name=mail proto=pop3
standalone: name=encmail proto=pop3 class=1
standalone: name=http proto=http

This section names protocol and class combinations used for standalone validation. Currently this is only used by the /bin/mail script to validate locally-delivered mail.

# Configuration of the SSL and S/MIME subsystem
ssl:

	cert_file=ssl/certs/nti_server.pem

	server_opt=netscape_challenge_bug

#	client_cipher_list=NULL-MD5,EXP-RC4-MD5,RC4-MD5
#	server_cipher_list=RC4-MD5

	ca_path=ssl/newcerts:nti/ssl/certs

	ns_cert_db=~/.netscape/cert7.db
	ns_key_db=~/.netscape/key3.db

	cert_confirm_app=cvgui

See the configuration file guide for details on the ssl section.

# Kernel filter specs for protocol daemon content validation
filter:	seq=initial pass=all redirect=r_bind_spec,r_oconn_spec,r_iconn_spec
filter:	seq=0 pass=addr,info,misc redirect=data,r_bind,r_oconn,r_iconn,dconn

This configures the NTI kernel module in the appropriate way for content validation. See nti_snoop.conf for an example of another configuration for a different purpose.

CyberSoft Protocol Daemon Configuration File Format and Command Line Options

The CyberSoft protocol daemon configuration is specified using a free-format keyword/value type definition file. Whitespace (spaces, tabs, newlines, etc.) is used to delimit keywords and values when no other delimiter is specified in the description. Any amount may be used as a delimiter or added between delimiters, keywords, values, or list elements. Values which may be quoted strings may be delimited by single quotes ('), double quotes ("), or a pair of left and right angle brackets (<>). Quoting preserves all contained whitespace or other delimiters including types of quotes other than the ones chosen. There is no other escape mechanism available (such as backslash) besides quoted strings except in special cases described below. Comments begin with the # character and extend to the end of the line. They are only legal when a keyword would be; they may not be placed between keywords and values or between values in a list. Keyword-matching is case-insensitive. Values generally are case-insensitive also for reasons due to their usage inside the program (such as header labels) except for values such as pathnames which are case sensitive.

The configuration file is divided into sections each preceded by a section specifier which is a keyword followed by a colon. Each section type allows certain other keywords/values to be specified in a keyword=value format. Lists of values are delimited with commas (e.g. keyword=value1,value2,value3) or optionally with colons.

Alternate keywords shown may be used instead of the primary (preferred) keywords. When abbreviations of subwords are shown it is implied that any permutation of abbreviations may be used. In addition a dash character (-) may be used to separate subwords instead of an underscore(_). For example the keyword exception_directory may also be specified as exception_dir, exc_dir, exc_directory, exception-directory, exception-dir, exc-dir, or exc-directory.

Certain keywords may also be specified instead as command-line options. Some of these are historical, but mostly they are intended to provide a convenient mechanism for testing and debugging rather than as a replacement for the configuration file. Command-line options override specifications in the configuration file.

This daemon is normally run as the root user. For testing and evaluation purposes it may be run as another user which will restrict intercepted traffic to network connections completed by processes running as that same user.

There are two additional command-line options which are parsed before the configuration file is read and do not have equivalent configuration file keywords:

-c path: This specifies the location of the configuration file. If -c is not used the default configuration file path for the Unix platform is /etc/nti_protocold.conf.

-k signal [STREAMS only]: This does not run the program normally but instead causes the top-level control process of a currently running protocol daemon to be sent a signal. No other options may be specified with -k, and the configuration file is not read. signal must be specified numerically. Useful values are 15 (SIGTERM), which causes the daemon to perform a clean shutdown, and 0 (no signal) which simply tests for the existence of a running daemon.

The exit code after running with this option can be used to determine what happened. 0 indicates success, 2 (ENOENT) indicates that the daemon is not running, and 1 (EPERM) indicates that this user does not have permission to send a signal to the daemon. The daemon produces no output except for serious errors.

Arguments on the command line after any options are only legal in standalone mode and specify a list of usernames to use for looking up S/MIME decryption keys.

global section

This section specifies options and parameters global to the program.

do_fork (command line -f) [STREAMS only]: Fork as necessary to accommodate new simultaneous attachments. Trace output (if enabled) is tagged with process IDs. If not specified the program will handle one connection only and multiple instances must be running to handle more. do_fork should always be specified in production use as the non-forking mode is only useful for certain types of testing and debugging.

do_trace (command line -t) do_trace=n: Turn on trace mode. Multiple instances enable more verbose output (currently there are three levels of verbosity including 0). The verbosity level may also be specified numerically. A trace message is sent for each TPI message or protocol command processed as well as other events. Trace output is normally sent to standard output, but in standalone validation mode trace output is instead sent to standard error. See below for the output format.

debug=x (command line -d) [STREAMS only]\: Specifies (in hexadecimal) debug flags for the tpicept kernel driver. This causes it to spew various messages to the console log which may be useful for debugging.

directory=p [alt: dir]: Changes the directory that other specified pathnames are relative to. p may be a quoted string.

reject_directory=p [alt: reject_dir]: Changes the work directory (default /var/tmp) for files to scan. Rejected files remain "embargoed" here. p may be a quoted string.

quarantine_directory=p [alt: quar_dir]: Changes the directory (default /var/tmp/quarantine) into which files are moved when they have been quarantined pending further information or processing (such as S/MIME decryption). This directory need not be specified or exist unless a validate specification indicates the possibility of quarantine. On Unix this directory must be on the same filesystem as the reject_directory. Other systems may impose the same restriction or may incur significant copying overhead if the directories are on different filesystems. p may be a quoted string.

exception_directory=p [alt: exc_dir]: Changes the directory (default is to leave files in the reject_directory) into which files are moved when an exceptional condition occurs during validation. On Unix this directory must be on the same filesystem as the reject_directory. Other systems may impose the same restriction or may incur significant copying overhead if the directories are on different filesystems. p may be a quoted string.

ns_prefs_file=p [alt: netscape_preferences_file]: This is the path to the user's preferences file for Netscape Communicator which is used when storing files in the quarantine area to look up the user's email address. p may be a quoted string. This pathname may contain platform-specific coding which may specify a variable path. On Unix an initial "~" (tilde) character will be expanded to the home directory of the real user ID of the connected process. The default value on Unix is ~/.netscape/preferences.js which should suit most purposes.

standalone_type=s [alt: sa_type] (command line -v): When this keyword or command-line option is specified the protocol daemon will not run in normal protocol processing mode but will instead validate one file or message received from standard input and will output the result (either the original data or a substitute file) to standard output. In this mode any trace output is sent to standard error. The specified name s refers to a specification in the standalone section.

The program exit code will be:

0: Validation was successful or was not necessary.

21: An exception occurred during validation. The exception_msg has been sent to the output.

22: Validation completed with a quarantine status. The quarantine_msg has been sent to the output.

23: Validation completed with a reject status. The reject_msg has been sent to the output.

other: A specification or system error occurred during standalone processing. The exact output is indeterminate.

timeout=n [alt: listen_timeout] [STREAMS only]: Changes the time in seconds (default 60) after which idle daemon subprocesses will exit. 0 means that subprocesses will never timeout.

min_listeners=n [STREAMS only]: Changes the minimum number of subprocesses (default 1) which the daemon will attempt to keep ready waiting for intercepted connections. Increasing this will reduce delay of intercepted connections due to daemon subprocess startup, but only when load levels tend to increase rapidly. The default value should be optimum for most environments.

syslog_facility=f [alt: log_facility] [STREAMS only]: Changes the facility indicator (default daemon) used to send messages to the system log. Facility names are as listed in syslog(3) and may be specified without the LOG_ prefix. The facility may also be specified numerically.

environment section [alt: env, environ]

Any keyword=value specified in this section is used to set an environment variable. The value may be a quoted string. Environment variables are not used directly by the program but may be used by subprograms that perform content validation or certificate confirmation.

scan section

Each instance of this section specifies a protocol type to scan on a set of TCP ports. There may be multiple scan sections specifying the same protocol and different ports if it is desired to use a different set of options when scanning different ports.

proto=k: The protocol name. Must be ftp, ftpdata, smtp, pop3, or http. If ftp is specified then there must also be a scan specification for ftpdata with corresponding ports (control port - 1) and no scan type (e.g. scan=) specifications. In this case the ftpdata spec is not used directly for port matching but data connections are intercepted by direction of the FTP control protocol interpreter. This is the preferred method. If only ftpdata and not ftp is specified then FTP data connections are port matched directly and subject to the scan specification. In either case any alternate files (e.g. reject_file) are always specified with ftpdata.

port=l

port_client=l [alt: port_c, port_o, port_out, port_outgoing]

port_server=l [alt: port_s, port_i, port_in, port_incoming]: The TCP ports which will be intercepted for this protocol. port_client and port_server will intercept only client or server connections respectively (relative to this host), while port will intercept both. The port list is a comma-separated list of decimal port numbers or port ranges (n-m). These keywords may be repeated for clarity or to specify different port sets for client, server, and both. For most protocols the port matched is the server port since the connection is generally made between an anonymous client port and a known server port. FTP is different in that the data connection (in PORT mode) is made from a known port on the server host (acting as a client) to an anonymous (but known to the protocol) port on the client host (acting as a server). The daemon knows to match the client port instead of the server port for FTP but the configuration still must take into account the reversed client/server connections.

ssl_port=l

ssl_port_client=l [alt: sport_c, sport_o, sport_out, ssl_port_outgoing]

ssl_port_server=l [alt: sport_s, sport_i, sport_in, ssl_port_incoming]: These TCP ports will be intercepted as with port, port_client and port_server except that SSL will be used as the outer (wrapper) protocol around the application protocol. This is commonly used for HTTP (becoming HTTPS) and sometimes for POP3. SMTP, however, does not commonly use this method but instead uses the STARTTLS command (see the allow_starttls option).

These keywords may only be specified if the protocol daemon has been compiled to support SSL encrypted connections. You will also need to specify parameters in the ssl section to properly configure SSL.

allow_starttls [alt: allow_stls]: This allows use of the STARTTLS (SMTP) or STLS (POP3) protocol command to start the SSL protocol on a connection initiated as plaintext. Without this keyword an error is always returned to a client that issues this protocol command. This keyword has no effect for other protocols (FTP, HTTP) which do not have an equivalent command. (A similar mechanism has been defined for HTTP in RFC 2817 but this has not been implemented in the protocol engine.)

Note that it is legal and reasonable to specify both secure ports for complete SSL protocol wrapping using the ssl_port* keywords and to allow use of STARTTLS/STLS to initiate SSL on plaintext ports.

This keyword may only be specified if the protocol daemon has been compiled to support SSL encrypted connections. You will also need to specify parameters in the ssl section to properly configure SSL.

scan=l

scan_client=l [alt: scan_c, scan_o, scan_out, scan_outgoing]

scan_server=l [alt: scan_s, scan_i, scan_in, scan_incoming]: Message connection types and directions which will be scanned. scan_client and scan_server will only scan messages on this connection type, while scan will scan messages on either connection type. These keywords may be repeated. The list specifies message directions to scan and the validation classes which should be applied. A validate spec which specifies one or more classes will only be used for scan specs which include one of those classes.

none [alt: n]: Does nothing, useful for clarity.

write [alt: w, s, send] : From local host to remote host. Specifies class 0.

write_classn [alt: write_cn, writen, wn, etc.]: From local host to remote host. Specifies class n (0-7).

read [alt: r, receive]: From remote host to local host. Specifies class 0.

read_classn [alt: read_cn, readn, rn, etc.]: From remote host to local host. Specifies class n (0-7).

both [alt: b]: Both directions. Specifies class 0.

both_classn [alt: both_cn, bothn, bn]: Both directions. Specifies class n (0-7).

[Note: directions would have made more sense to have been specified relative to the client or server rather than the local host.]

include_types=l (command line -i): This keyword only has effect in conjunction with the HTTP, SMTP, or POP3 protocols. It specifies a list of Content-Types which will be scanned. This keyword may be repeated. If no include_types are specified then all types are scanned subject to the exclude list. Each specified Content-Type may be one part, which will match a major type (for example audio will match audio/basic or audio/x-wav) or may fully specify a subtype. Individual list elements may be quoted, but the entire list may not be quoted (this is different than most other lists used in the configuration file).

exclude_types=l (command line -x): This keyword only has effect in conjunction with the HTTP, SMTP, or POP3 protocols. It is a list of Content-Types to exclude from scanning. Types not matched by the exclude list must match the include list, if specified, in order to be scanned. A special type unknown may be specified to exclude scanning of files or messages which don't contain a Content-Type header. This includes most simple email as well as pre-1.0 HTTP responses. Unknown types are otherwise scanned by default. Individual list elements may be quoted, but the entire list may not be quoted (this is different than most other lists used in the configuration file).

reject_file=p

quarantine_file=p (alt: quar_file)

exception_file=p (alt: exc_file):A path to a file containing a template for a file or message substituted for the actual file or message when validation does not complete with all "good" status. p may be a quoted string. reject_file is used when any of the validation steps return codes in the reject_codes list. quarantine_file is used if there were no matching reject_codes but there is a match in the quarantine_codes list. exception_file is used when there were no matching reject_codes or quarantine_codes and there were one or more codes not in the good_codes list. If a file is not specified then a simple default internally-generated text will be used.

It is important that substitution files contain line terminators (i.e. LF or CR/LF) appropriate for the platform.

Each file may contain markers which will be expanded into actual output generated during validation. A marker consists of a tilde (~) followed by two digits on a line by itself. The marker number refers to the numeric parameter of the capture_stdout, capture_stderr, and capture_fdf keywords in the validate section. If any validation steps have directed output from file descriptors to this marker then the marker (and it's following newline) in the substitution template will be replaced by this output, otherwise the marker will simply be deleted from the output. Certain marker numbers are reserved and will always be substituted as follows:

00 A log of any process creation errors, execution errors, signals, or process exit codes considered exceptional (i.e. not reject, quarantine, or good).

97 A MIME multipart boundary delimiter line. This is only useful if the Content-Type has been defined as a multipart type (see below). Keep in mind that the preceding line terminator is part of the delimiter; therefore the preceding line should be empty if you intend for the previous part to end with a line terminator.

98 A MIME multipart boundary final delimiter line. This is a regular delimiter line with an extra two dashes at the end.

99 The original file or message (that failed validation). For the SMTP and POP3 protocols, the message including all of its original headers (but not a UUCP-style "From " banner, if present) is inserted. This is the correct format to embed in a multipart message as a part with a Content-Type of message/rfc822. For FTP and HTTP the file is inserted raw (without any HTTP server-supplied headers). FTP transfers have no mechanism to encapsulate parts, so original file embedding should not be used. HTTP does not appear to provide usable encapsulation semantics which work properly with current browsers, so original file embedding should not be used with HTTP. A useful protocol engine implementation of embedding original HTTP files would also require a method to embed the Content-* headers.

reject_file_type=s

quarantine_file_type=s (alt: quar_file_type)

exception_file_type=s (alt: exc_file_type): This specifies the Content-Type of the files specified with reject_file, quarantine_file, and exception_file. s may be a quoted string. The default Content-Type is text/plain. text/html is recommended for HTTP/HTTPS and could also be used for mail (SMTP and POP3). Some protocols (e.g. FTP) do not have a concept of Content-Type in which case the specified type will be ignored. A plain text file should be used in this case for maximum readability.

If the top-level type specified is multipart than a boundary parameter specifying a unique multipart boundary delimiter string will be automatically appended to the Content-Type header that is output. The corresponding boundary delimiter lines may be output using special markers in substitution templates. See RFC 2046 for details on the proper format of multipart messages.

validate section

Each instance of this section specifies an external program (or special internal filter) to potentially run in order to validate whether files or messages should be passed through transparently or whether they should be replaced with an error message. Typically this is used for virus scanning or other type of content validation.

The set of programs to run in order to validate a particular file or message is determined by the class matching logic described below. The programs are set up in a pipeline with the first program receiving the file or message as standard input and its standard output directed to the next program's standard input. Each program's output to standard error or other designated file descriptors may be captured and used as part of the substituted message if validation fails. The standard output of the last program in the pipeline is sent to the same place as its standard error. The ordering of the steps in the pipeline corresponds to the ordering of the validate sections in the configuration file.

cmd=p [alt: command]: A path to an external program to run. p may be a quoted string. If not specified the first argument of args will be used. If neither cmd nor args is specified and an internal filter is not specified then this validate section will be ignored. If the command path does not contain a slash character then the PATH environment variable (either specified in the environment section or before execution of the protocol daemon) will be used to search for the program.

args=a [alt: arg, argument, arguments]: This is the argument list passed to the program. The first argument in the list is the program name. a will generally be a quoted string since this is the only way to protect whitespace in the value as a whole. Within the value string unprotected white space is used to separate arguments in the list. The ending quote chosen to protect the entire value may not appear in the value string, but single (') or double (") quotes which do not violate this may be used to protect whitespace characters from being argument separators. The backslash character (\) may also be used (outside of quotes) to protect individual characters.

If the args keyword is not specified then the cmd (if specified) will be used as the single argument.

class=l [alt: classes]: This is a list of classes, 0-7, to which this validation step belongs. If desired this keyword may be repeated to specify additional class lists. If no classes are specified then this validation step will be used in all cases when validation occurs. If any classes are specified then this validation step will only be used when the scan type and direction list in the scan section specifies one of these classes. Since the scan class of scan value keywords in the scan section without explicit class suffixes is 0 it is somewhat counterintuitive to list class 0 in a validate spec since the obvious intent is for this scan spec to only include default (i.e. unclassed) validation steps.

sleep=n:The integer n is the number of seconds for the validation subprocess to pause after forking and before execing or performing its function. This is only useful for debugging when it is necessary to have time to attach a debugger to the subprocess.

capture_fdf=n: Output written to file descriptor f of this validation step is captured for use in substitution files or messages when validation doesn't complete as "good".

File descriptor 0 may not be captured since this is standard input.

An attempt to capture file descriptor 1 for any step other than the last step of a validation pipeline will log a warning and have no effect since in all but the last step it is used to pipe data to the next step. If file descriptor 1 is not explicitly captured for the last step then it will automatically become a duplicate of file descriptor 2.

If file descriptor 2 is not explicitly captured then data sent to it by the validation application will be discarded.

For internal validation steps (such as smime_decrypt) only file descriptor 2 may be captured. An attempt to capture any other file descriptor is an error.

File descriptors 0, 1, and 2 have special behavior as noted above. Other file descriptor numbers require an explicit capture spec in order to exist initially in the validation application.

The integer n is the marker number by which this text is referenced, and must be in the range 1-96. See the description above of reject_file, etc. for a discussion of markers. Capture specs in the same validation run (in the same or other validate specs) that reference the same marker number will all refer to the same output file. This will most likely not result in a meaningful interspersion of output unless the programs specifically write meaningful blocks to the file descriptors atomically, therefore this behavior is probably only useful for the special version marker (see below).

capture_fdf=version [alt: capture_fdf=v]

Output written to file descriptor f of this validation step is captured similarly to a marker and causes output of a Virus-Scan-Version header (for POP3, SMTP, or HTTP) containing the text written to this file descriptor. Empty lines are omitted and each line after the first is preceded by a tab for conformance with RFC 822 header continuation line syntax.

This feature is best used by having all validation steps capture version output from a certain file descriptor (such as 3) and for each validation application to write a single line (atomically) to this file descriptor identifying its name and version.

Output sent to the designated file descriptor by nested validation steps is automatically discarded to avoid duplicate version strings in the header.

capture_stdout=n [alt: capture_out, capture_output, capture_stdoutput]: These keywords are completely equivalent to capture_fd1 and exist for clarity to capture the standard output from file descriptor 1.

capture_stderr=n [alt: capture_err, capture_error, capture_stderror]: These keywords are completely equivalent to capture_fd2 and exist for clarity and backward compatibility to capture the standard error output from file descriptor 2.

exclude_users=l [STREAMS only]: This is a list of numerical user IDs or names which are exempt from this scanning step. For example a "system" user might use a certain protocol in a way for which it is not desired to include this step. The step could be included in a separate class, with this list specified, and only referenced by that protocol.

good_codes=l [alt: good_code, good_exit_codes]

reject_codes=l [alt: reject_code, reject_exit_codes]

quarantine_codes=l [alt: quarantine_code, quar_codes, quarantine_exit_codes]: After the validation program's exit code is masked with the appropriate mask value these lists are searched for the masked exit code. The results of these searches determines the outcome of the validation as either good, reject, quarantine, or exception. See reject_file above for a description of the logic. The list may contain integers in C format: digits without a leading zero are a decimal number, digits with a leading zero are an octal number, and hexadecimal numbers are preceded by 0x. These keywords should not be repeated since the lists are not cumulative (the last one of each type specified has effect).

If good_codes is not specified the default list contains only the value 0. reject_codes and quarantine_codes default to an empty list for steps specifying an external program. Internal validation types may have other defaults. It is useful for testing to set the list of good_codes for some step to a single value that will never be returned, forcing an exception and allowing the stderr logs to be examined in the substitute message.

good_mask=n

reject_mask=n

quarantine_mask=n: If specified the validation program's exit code is masked (logical ANDed) with these mask values before searching the exit code lists. This allows easy matching with only some bits of the exit code without having to specify long lists of codes for each bit combination for which the result is the same. The mask is specified as a C format integer.

smime_decrypt [alt: ss_smime_decrypt, smartscan_smime_decrypt]: This validation step does not run an external program but rather uses internal code which performs the function. It is not necessary to specify a cmd or args or to define any return codes.

The CyberSoft SmartScan protocol is decoded and components which are S/MIME (PKCS #7) encrypted messages are processed; all other component types are passed through. Using logic documented elsewhere the encryption key is located and used to decrypt the message. If the encryption key can not be determined or located then this module will return an exit code indicating that the entire original file or message should be kept in quarantine. The specification of this quarantine_code is implicit.

If decryption is successful the plaintext message is used as input to a nested set of validation steps which consists of all steps up to and including another instance of the smime_decrypt filter. Nesting may continue to any level. The aggregate output of all nested validation chains is passed on (with proper SmartScan sequencing) to any steps after the smime_decrypt filter. Banners delimiting output generated by nested runs of validation steps are automatically output to all captured file descriptors except 1 (stdout) or ones collecting output for the version marker.

This module is most useful when placed between the CyberSoft uad and vfind programs when processing incoming mail messages.

standalone section

Each instance of this section creates an association used for standalone validation (see standalone_type in the global section).

name=s: This specifies the name used by the standalone_type keyword or the -v command-line option to refer to this association.

proto=k: This specifies that the last scan section matching this protocol type will be used for relevant parameters. The actual protocol conversation itself does not occur, but the file or message received is processed and validated similarly to files or messages received using the specified protocol. The supported protocol types are:

ftpdata: The input will be treated as a raw file without headers or other structure.

smtp, pop3: The input will be treated as a message (RFC 822-style) with headers. Certain headers may be changed or omitted if validation fails. The content will always be validated.

http, https: The input will be treated as the result of an HTTP GET command (without the status line) which is similar to an RFC 822-style message. Certain headers may be changed or omitted. The content will be validated subject to matching of the Content-Type header with the include_types and exclude_types. Specifying https does not actually involve using the SSL protocol and in fact is synonymous for matching purposes with http.

class=l [alt: classes]: This is a list of classes, 0-7, which specifies the classes of validation steps which will be used to validate the standalone data. The default (if unspecified) is to only use steps which do not specify any class(es). If desired this keyword may be repeated to specify additional class lists.

filter section [STREAMS only]

This section specifies the low-level filtering and redirection logic used by the kernel driver and module. Proper specification is critical for the correct operation of the protocol daemon and the integrity of all intercepted connections so it is recommended that you use only the supplied configurations unless you really know the full implications of changing them. Full documentation of the filtering mechanism is in the tpicept_tpi.h header file; this section only documents the keyword syntax.

sequence=initial [alt: seq] (implied by command line -P, -R, -H): This section will specify the initial filter used before (and to cause) attachment.

sequence=n [alt: seq] (implied by command line -p, -r, -h): This section will specify filter number used after attachment. The daemon only supports specifying one filter, number 0.

pass=l [alt: p] (command line -P or -p): The list of message classes to pass through the kernel module to their intended destination. (default: all)

redirect=l [alt: r] (command line -R or -r): The list of message classes to redirect to the daemon. The daemon will forward (subject to scanning of data) messages which have been redirected but not also passed. (default: all)

hold=l [alt: h] (command line -H or -h): The list of message classes to hold in the module queue pending release. This should not be used as the daemon currently has no support for this mechanism. (default: none)

trigger=l [alt: t]: The list of message classes which will cause a switch to the next filter. Since the daemon only supports one filter this keyword should not be used.

The message class keywords are listed below along with their corresponding TPICEPT_FILTER_* constant equivalents:

Keyword	TPICEPT_FILTER_* constant
r_data	R_DATA
w_data	W_DATA
data	R_DATA \| W_DATA
r_data_lim	R_DATA_LIM
w_data_lim	W_DATA_LIM
data_lim	R_DATA_LIM \| W_DATA_LIM
r_bind	R_BIND
w_bind	W_BIND
bind	R_BIND \| W_BIND
r_bind_spec	R_BIND_SPEC
bind_spec	R_BIND_SPEC
r_aconn	R_ACONN
w_aconn	W_ACONN
aconn	R_ACONN \| W_ACONN
r_aconn_spec	R_ACONN_SPEC
aconn_spec	R_ACONN_SPEC
r_oconn	R_OCONN
w_oconn	W_OCONN
oconn	R_OCONN \| W_OCONN
r_oconn_spec	R_OCONN_SPEC
oconn_spec	R_OCONN_SPEC
r_iconn	R_ICONN
iconn	R_ICONN
r_iconn_spec	R_ICONN_SPEC
iconn_spec	R_ICONN_SPEC
r_dconn	R_DCONN
w_dconn	W_DCONN
dconn	R_DCONN \| W_DCONN
r_info	R_INFO
w_info	W_INFO
info	R_INFO \| W_INFO
r_misc	R_MISC
w_misc	W_MISC
misc	R_MISC \| W_MISC
none	(none, used as placeholder)
all	R_DATA \| R_BIND \| R_ACONN \| R_OCONN \| R_ICONN \| R_DCONN \| R_INFO \| R_MISC \| W_DATA \| W_BIND \| W_ACONN \| W_OCONN \| W_DCONN \| W_INFO \| W_MISC
addr	R_BIND \| R_ACONN \| R_OCONN \| R_ICONN \| W_BIND \| W_ACONN \| W_OCONN

ssl section

This section specifies options and parameters which configure the Secure Sockets Layer subsystem and the S/MIME decryption filter. The configuration is common to all protocols which support SSL encapsulation.

client_cipher_list=l: l is a list of ciphers allowed when accepting an SSL connection from the client program. l may be a quoted string. Unlike other lists this list may not include whitespace around the list separators. List elements are cipher names and shortcut names such as all defined by the SSLeay/OpenSSL software package. The default list should suit most purposes. It may be desirable to limit client connections to a faster (and possibly weaker) cipher to maximize speed.

server_cipher_list=l: l is a list of ciphers allowed when initiating an SSL connection to a remote server. l may be a quoted string. Unlike other lists this list may not include whitespace around the list separators. List elements are cipher names and shortcut names such as all defined by the SSLeay/OpenSSL software package. The default list should suit most purposes. This specification replaces the client program's own configuration of a cipher list when SSL connections are being intercepted.

cert_file=p [alt: certificate_file]: A path to a PEM-encoded file containing a server certificate to be used by the server SSL when authenticating to the client software. This specification is required. p may be a quoted string. It will be necessary to accept this certificate into the database of your browser (or other client) to avoid warning messages.

key_file=p [alt: privatekey_file]: A path to a PEM-encoded file containing a private key to be used by the server SSL when authenticating to the client software. p may be a quoted string. Typically this is not specified causing the key to be searched for in the same file as the server certificate.

ca_file=p [alt: certificate_authority_file, cert_auth_file]: A path to a PEM-encoded file containing certificates of certificate authorities recognized by the client SSL for authenticating remote SSL servers. p may be a quoted string. This may be used to supplement or replace the browser's database of recognized authorities.

ca_path=p [alt: certificate_authority_path, cert_auth_path]: A list of paths to directories containing hash-named PEM-encoded files each containing a certificate of a certificate authority recognized by the client SSL for authenticating remote SSL servers. p may be a quoted string. This may be used to supplement or replace the browser's database of recognized authorities. The first path in this list will be used to store new certificates which are confirmed by user prompting.

ns_cert_db=p [alt: netscape_certificate_db]: A path to a Netscape Communicator 4 format certificate database file usually named cert7.db. p may be a quoted string. If specified this database will be searched for certificates of certificate authorities for authenticating remote SSL servers. This pathname may contain platform-specific coding which may specify a variable path. On Unix an initial "~" (tilde) character will be expanded to the home directory of the real user ID of the connected process. This is typically specified on Unix as ~/.netscape/cert7.db.

ns_key_db=p [alt: netscape_private_key_db]: A path to a Netscape Communicator 4 format private key database file usually named key3.db. p may be a quoted string. This database will be searched for private keys needed to decrypt encrypted S/MIME messages. This pathname may contain platform-specific coding which may specify a variable path. On Unix an initial "~" (tilde) character will be expanded to the home directory of the real user ID of the connected process. The default value on Unix is ~/.netscape/key3.db which should suit most purposes.

cert_confirm_app=c [alt: certificate_confirm_application]: A shell command line which invokes an application used to verify unknown server certificates. c may be a quoted string. The application must conform to the CyberSoft Certificate Verifier API. It typically will pop up a dialog box asking the user to confirm storage or use of the unknown certificate. If this parameter is not specified then all server certificates will be accepted without confirmation.

ssl_trace (command line -s)

ssl_trace=n: Turn on SSL trace mode. Multiple instances enable more verbose output (currently there are three levels of verbosity including 0). The verbosity level may also be specified numerically. At level 1 a trace message is sent to standard output for each SSL warning or error. At level 2 SSL states are also traced.

options=l [alt: bugs]

client_options=l [alt: client_bugs]

server_options=l [alt: server_bugs]: These parameters specify SSL protocol options or bug workarounds which may be necessary in certain cases. The list may name one or more of the following options. options sets options for both SSL connections. client_options only affects the connection to the client application. server_options only affects the connection to the remote server. Check the SSLeay/OpenSSL package for details on these options.

Keyword	Description
no_ssl2, no_sslv2	Don't attempt to negotiate SSL version 2
no_ssl3, no_sslv3	Don't attempt to negotiate SSL version 3
no_tls1, no_tlsv1	Don't attempt to negotiate TLS version 1
microsoft_sess_id	Work around this issue
netscape_challenge	Work around this issue
netscape_reuse_cipher_change	Work around this issue
sslref2_reuse_cert_type	Work around this issue
microsoft_big_sslv3_buffer	Work around this issue
msie_sslv2_rsa_padding	Work around this issue
ssleay_080_client_dh	Work around this issue
tls_d5	Work around this issue
tls_block_padding	Work around this issue
tls_rollback	Work around this issue
single_dh_use	Only use tmp_dh parameters once
ephemeral_rsa	Also use the tmp_rsa key when doing RSA operations
pkcs1_check_1	Checking for PKCS#1 attack
pkcs1_check_2	Checking for PKCS#1 attack
netscape_ca_dn	Work around this issue
non_export_first	Rearranges ordering default ciphers
netscape_demo_cipher_change_bug	Work around this issue
all	Work around all bug-related issues

ssl2 [alt: sslv2]

ssl3 [alt: sslv3]

tls1 [alt: tlsv1]

client_ssl2 [alt: client_sslv2]

client_ssl3 [alt: client_sslv3]

client_tls1 [alt: client_tlsv1]

server_ssl2 [alt: server_sslv2]

server_ssl3 [alt: server_sslv3]

server_tls1 [alt: server_tlsv1]: These parameters specify that only a certain protocol will be used, either SSL version 2, SSL version 3 or TLS version 1. These differ from the options above to disallow certain protocols in that a protocol-specific initial handshake is used instead of a compatible one. ssl2/ssl3/tls1 sets options for both SSL connections. client_ssl2/client_ssl3/client_tls1 only affects the connection to the client application. server_ssl2/server_ssl3/server_tls1 only affects the connection to the remote server.

Trace output

Each line of trace output is prefixed with:

Pid of subprocess doing this (in do_fork mode), or blank for the top-level process.

Direction/type of message:

c	control, received by top-level process
d	debug, generated by program
i	informational, generated by program
r	read (upstream) message, not forwarded by app
w	write (downstream) message, not forwarded by app
s	ssl, generated by program
R	read message, to be forwarded by app (but could be deleted by scan)
W	write message, to be forwarded by app (but could be deleted by scan)

Priority:

:	Band 0 (or priority not applicable)
+	Band 1. On the module stream this was a high-priority (M_PCPROTO) message.
*	Band 2. Used for urgent indications by the driver.
!	high-priority (M_PCPROTO). Used for acknowledgement of TPICEPT requests.

CyberSoft Protocol Daemon Configuration File Format and Command Line Options

There are two additional command-line options which are parsed before the configuration file is read and do not have equivalent configuration file keywords:

-c path: This specifies the location of the configuration file. If -c is not used the default configuration file path for the Unix platform is /etc/nti_protocold.conf.

Arguments on the command line after any options are only legal in standalone mode and specify a list of usernames to use for looking up S/MIME decryption keys.

global section

This section specifies options and parameters global to the program.

do_trace (command line -t)

do_trace=n: Turn on trace mode. Multiple instances enable more verbose output (currently there are three levels of verbosity including 0). The verbosity level may also be specified numerically. A trace message is sent for each TPI message or protocol command processed as well as other events. Trace output is normally sent to standard output, but in standalone validation mode trace output is instead sent to standard error. See below for the output format.

debug=x (command line -d) [STREAMS only]: Specifies (in hexadecimal) debug flags for the tpicept kernel driver. This causes it to spew various messages to the console log which may be useful for debugging.

directory=p [alt: dir]: Changes the directory that other specified pathnames are relative to. p may be a quoted string.

reject_directory=p [alt: reject_dir]: Changes the work directory (default /var/tmp) for files to scan. Rejected files remain "embargoed" here. p may be a quoted string.

The program exit code will be:

0 Validation was successful or was not necessary.

21 An exception occurred during validation. The exception_msg has been sent to the output.

22 Validation completed with a quarantine status. The quarantine_msg has been sent to the output.

23 Validation completed with a reject status. The reject_msg has been sent to the output.

other A specification or system error occurred during standalone processing. The exact output is indeterminate.

timeout=n [alt: listen_timeout] [STREAMS only]: Changes the time in seconds (default 60) after which idle daemon subprocesses will exit. 0 means that subprocesses will never timeout.

environment section [alt: env, environ]

scan section

port=l

port_client=l [alt: port_c, port_o, port_out, port_outgoing]

For most protocols the port matched is the server port since the connection is generally made between an anonymous client port and a known server port. FTP is different in that the data connection (in PORT mode) is made from a known port on the server host (acting as a client) to an anonymous (but known to the protocol) port on the client host (acting as a server). The daemon knows to match the client port instead of the server port for FTP but the configuration still must take into account the reversed client/server connections.

ssl_port=l

ssl_port_client=l [alt: sport_c, sport_o, sport_out, ssl_port_outgoing]

Note that it is legal and reasonable to specify both secure ports for complete SSL protocol wrapping using the ssl_port* keywords and to allow use of STARTTLS/STLS to initiate SSL on plaintext ports.

scan=l

scan_client=l [alt: scan_c, scan_o, scan_out, scan_outgoing]

none [alt: n]: Does nothing, useful for clarity.

write [alt: w, s, send]: From local host to remote host. Specifies class 0.

write_classn [alt: write_cn, writen, wn, etc.]: From local host to remote host. Specifies class n (0-7).

read [alt: r, receive]: From remote host to local host. Specifies class 0.

read_classn [alt: read_cn, readn, rn, etc.]: From remote host to local host. Specifies class n (0-7).

both [alt: b]: Both directions. Specifies class 0.

both_classn [alt: both_cn, bothn, bn]: Both directions. Specifies class n (0-7).

[Note: directions would have made more sense to have been specified relative to the client or server rather than the local host.]

reject_file=p

quarantine_file=p (alt: quar_file)

exception_file=p (alt: exc_file): A path to a file containing a template for a file or message substituted for the actual file or message when validation does not complete with all "good" status. p may be a quoted string. reject_file is used when any of the validation steps return codes in the reject_codes list. quarantine_file is used if there were no matching reject_codes but there is a match in the quarantine_codes list. exception_file is used when there were no matching reject_codes or quarantine_codes and there were one or more codes not in the good_codes list. If a file is not specified then a simple default internally-generated text will be used.

It is important that substitution files contain line terminators (i.e. LF or CR/LF) appropriate for the platform.

00 A log of any process creation errors, execution errors, signals, or process exit codes considered exceptional (i.e. not reject, quarantine, or good).

98 A MIME multipart boundary final delimiter line. This is a regular delimiter line with an extra two dashes at the end.

reject_file_type=s

quarantine_file_type=s (alt: quar_file_type)

validate section

If the args keyword is not specified then the cmd (if specified) will be used as the single argument.

sleep=n: The integer n is the number of seconds for the validation subprocess to pause after forking and before execing or performing its function. This is only useful for debugging when it is necessary to have time to attach a debugger to the subprocess.

capture_fdf=n: Output written to file descriptor f of this validation step is captured for use in substitution files or messages when validation doesn't complete as "good".

File descriptor 0 may not be captured since this is standard input.

If file descriptor 2 is not explicitly captured then data sent to it by the validation application will be discarded.

For internal validation steps (such as smime_decrypt) only file descriptor 2 may be captured. An attempt to capture any other file descriptor is an error.

File descriptors 0, 1, and 2 have special behavior as noted above. Other file descriptor numbers require an explicit capture spec in order to exist initially in the validation application.

capture_fdf=version [alt: capture_fdf=v]: Output written to file descriptor f of this validation step is captured similarly to a marker and causes output of a Virus-Scan-Version header (for POP3, SMTP, or HTTP) containing the text written to this file descriptor. Empty lines are omitted and each line after the first is preceded by a tab for conformance with RFC 822 header continuation line syntax.

Output sent to the designated file descriptor by nested validation steps is automatically discarded to avoid duplicate version strings in the header.

good_codes=l [alt: good_code, good_exit_codes]

reject_codes=l [alt: reject_code, reject_exit_codes]

quarantine_codes=l [alt: quarantine_code, quar_codes, quarantine_exit_codes]:After the validation program's exit code is masked with the appropriate mask value these lists are searched for the masked exit code. The results of these searches determines the outcome of the validation as either good, reject, quarantine, or exception. See reject_file above for a description of the logic. The list may contain integers in C format: digits without a leading zero are a decimal number, digits with a leading zero are an octal number, and hexadecimal numbers are preceded by 0x. These keywords should not be repeated since the lists are not cumulative (the last one of each type specified has effect).

good_mask=n

reject_mask=n

This module is most useful when placed between the CyberSoft uad and vfind programs when processing incoming mail messages.

standalone section

Each instance of this section creates an association used for standalone validation (see standalone_type in the global section).

name=s: This specifies the name used by the standalone_type keyword or the -v command-line option to refer to this association.

ftpdata: The input will be treated as a raw file without headers or other structure.

smtp, pop3: The input will be treated as a message (RFC 822-style) with headers. Certain headers may be changed or omitted if validation fails. The content will always be validated.

filter section [STREAMS only]

sequence=initial [alt: seq] (implied by command line -P, -R, -H)

This section will specify the initial filter used before (and to cause) attachment. sequence=n [alt: seq] (implied by command line -p, -r, -h)

This section will specify filter number used after attachment. The daemon only supports specifying one filter, number 0. pass=l [alt: p] (command line -P or -p)

The list of message classes to pass through the kernel module to their intended destination. (default: all) redirect=l [alt: r] (command line -R or -r)

The list of message classes to redirect to the daemon. The daemon will forward (subject to scanning of data) messages which have been redirected but not also passed. (default: all) hold=l [alt: h] (command line -H or -h)

The list of message classes to hold in the module queue pending release. This should not be used as the daemon currently has no support for this mechanism. (default: none) trigger=l [alt: t]

The list of message classes which will cause a switch to the next filter. Since the daemon only supports one filter this keyword should not be used.

The message class keywords are listed below along with their corresponding TPICEPT_FILTER_* constant equivalents:

Keyword	TPICEPT_FILTER_* constant
r_data	R_DATA
w_data	W_DATA
data	R_DATA \| W_DATA
r_data_lim	R_DATA_LIM
w_data_lim	W_DATA_LIM
data_lim	R_DATA_LIM \| W_DATA_LIM
r_bind	R_BIND
w_bind	W_BIND
bind	_BIND \| W_BIND
r_bind_spec	R_BIND_SPEC
bind_spec	R_BIND_SPEC
r_aconn	R_ACONN
w_aconn	W_ACONN
aconn	R_ACONN \| W_ACONN
r_aconn_spec	R_ACONN_SPEC
aconn_spec	R_ACONN_SPEC
r_oconn	R_OCONN
w_oconn	W_OCONN
oconn	R_OCONN \| W_OCONN
r_oconn_spec	R_OCONN_SPEC
oconn_spec	R_OCONN_SPEC
r_iconn	R_ICONN
iconn	R_ICONN
r_iconn_spec	R_ICONN_SPEC
iconn_spec	R_ICONN_SPEC
r_dconn	R_DCONN
w_dconn	W_DCONN
dconn	R_DCONN \| W_DCONN
r_info	R_INFO
w_info	W_INFO
info	R_INFO \| W_INFO
r_misc	R_MISC
w_misc	W_MISC
misc	R_MISC \| W_MISC
none	(none, used as placeholder)
all	R_DATA \| R_BIND \| R_ACONN \| R_OCONN \| R_ICONN \| R_DCONN \| R_INFO \| R_MISC \| W_DATA \| W_BIND \| W_ACONN \| W_OCONN \| W_DCONN \| W_INFO \| W_MISC
addr	R_BIND \| R_ACONN \| R_OCONN \| R_ICONN \| W_BIND \| W_ACONN \| W_OCONN

ssl section

ns_key_db_pass=s [alt: netscape_private_key_db_password]: This specifies the password used to decrypt private keys in the Netscape key database. s may be a quoted string. By default no password (actually a zero-length password) is used. Currently the key databases for all users must share the same password. cert_confirm_app=c [alt: certificate_confirm_application]: A shell command line which invokes an application used to verify unknown server certificates. c may be a quoted string. The application must conform to the CyberSoft Certificate Verifier API. It typically will pop up a dialog box asking the user to confirm storage or use of the unknown certificate. If this parameter is not specified then all server certificates will be accepted without confirmation.

ssl_trace (command line -s)

client_options=l [alt: client_bugs]

Keyword	Description
no_ssl2, no_sslv2	Don't attempt to negotiate SSL version 2
no_ssl3, no_sslv3	Don't attempt to negotiate SSL version 3
no_tls1, no_tlsv1	Don't attempt to negotiate TLS version 1
microsoft_sess_id	Work around this issue
netscape_challenge	Work around this issue
netscape_reuse_cipher_change	Work around this issue
sslref2_reuse_cert_type	Work around this issue
microsoft_big_sslv3_buffer	Work around this issue
msie_sslv2_rsa_padding	Work around this issue
ssleay_080_client_dh	Work around this issue
tls_d5	Work around this issue
tls_block_padding	Work around this issue
tls_rollback	Work around this issue
single_dh_use	Only use tmp_dh parameters once
ephemeral_rsa	Also use the tmp_rsa key when doing RSA operations
pkcs1_check_1	Checking for PKCS#1 attack
pkcs1_check_2	Checking for PKCS#1 attack
netscape_ca_dn	Work around this issue
non_export_first	Rearranges ordering default ciphers
netscape_demo_cipher_change_bug	Work around this issue
all	Work around all bug-related issues

ssl2 [alt: sslv2]

ssl3 [alt: sslv3]

tls1 [alt: tlsv1]

client_ssl2 [alt: client_sslv2]

client_ssl3 [alt: client_sslv3]

client_tls1 [alt: client_tlsv1]

server_ssl2 [alt: server_sslv2]

server_ssl3 [alt: server_sslv3]

Trace output

Each line of trace output is prefixed with:

Pid of subprocess doing this (in do_fork mode), or blank for the top-level process.

Direction/type of message:

c	control, received by top-level process
d	debug, generated by program
i	informational, generated by program
r	read (upstream) message, not forwarded by app
w	write (downstream) message, not forwarded by app
s	ssl, generated by program
R	read message, to be forwarded by app (but could be deleted by scan)
W	write message, to be forwarded by app (but could be deleted by scan)

Priority:

:	Band 0 (or priority not applicable)
+	Band 1. On the module stream this was a high-priority (M_PCPROTO) message.
*	Band 2. Used for urgent indications by the driver.
!	high-priority (M_PCPROTO). Used for acknowledgement of TPICEPT requests.

CyberSoft Protocol Daemon S/MIME Processing

In order to decrypt and virus scan S/MIME encrypted mail we need to find the private key of the recipient of the mail. If this fails we may "quarantine" the mail until the certificate can be found, and then we need a way to try sending to the mailbox again. These are non-trivial problems. With two intercepted protocols, POP3 and SMTP, there are four situations since either can be a client or server. There is also the case of local mail.

If mail is quarantined then the user must perform some other action (such as adding the key to their local Netscape key database) which allows the protocol engine to find the private key. Then the original message must be re-sent to the user and the email address to send to must be determined.

Note that there is little useful information in the mail header as neither sender nor recipient addresses reliably reflect the actual source and destinations involved.

POP3 client (incoming mail)

The MUA (mail user agent) is presumed to be Netscape Communicator which will attempt to download the mail from a remote POP3 server. The location of the user's Netscape certificate and private key databases can be determined from the user ID making the connection (this works similarly to SSL connections). If this fails then a message is substituted telling of the problem. The mail must then be sent back to the user by sending it to an email address which will cause it to be re-deposited into the POP3 mailbox. To do this there needs to be an association between user IDs and email addresses. Since Netscape only stores one email address per user this should be unambiguous enough to use and can be easily retrieved from the Netscape preferences file.

Alternately there could be an association list from POP3 server and user names to email addresses stored in some other manner. This is not currently implemented.

POP3 server (outgoing mailbox access)

The server stores mail most likely arriving from remote users and then being served back out to remote users, so it is unlikely that any of the encryption keys will be available. Therefore this type of connection should not be intercepted. However if the incoming mail arrived through SMTP then it would be intercepted at that point.

SMTP client (outgoing mail)

If this connection originates from a Netscape browser then the same method can be used to look up the key as is used for a POP3 client. Encrypted mail can generally be decrypted by the sender (that way a user can look at his own sent mail) so the sender's key should be available. Otherwise the mail will be quarantined and a substitute message will be sent. When the mail is re-sent the user ID who originated the connection can be used to determine the originating mailbox (this is similar to the POP3 client). The mail is then returned to the originator who can then correct the situation before re-sending it.

Note that when the mail is quarantined the originator will have no direct indication that this has occurred, and must either wait for the recipient(s) to complain or check the quarantine area manually. However this situation should not occur in normal usage as it is very difficult to send an encrypted message from Netscape Communicator without possessing the private key. It more likely indicates a misconfiguration which has made the protocol engine unable to use the key database (such as a wrong database password).

If this type of connection originates from a sendmail process (or other type of MTA) then it is probably forwarded mail and should not be intercepted. The user ID here is generally 0 (root) or other system user ID and this can be used to distinguish the two cases.

SMTP server (incoming mail)

The destination user (and whether local or remote) in this case is the least clear of all the cases. Local aliases, mailing lists, and alternate hostnames can all confuse this determination. Normally this is determined by the local MTA such as sendmail. An association list could be used which would map e-mail addresses to user IDs. Mail which fits a certain pattern (such as a destination to known local host names) could require decryption while other mail (which is probably destined elsewhere) could be passed through without requiring decryption. If it is known that the MTA does not forward at all then all mail could require decryption.

The difficulty of determining the mail destination from information in the SMTP protocol makes it preferable to not intercept incoming SMTP traffic but instead intercept local mail delivery through other means.

Local Mail

This may be mail that is sent from an local MUA to a local MTA (through direct program invocation) and then deposited in a local mailbox. It is also the final delivery for mail arriving via SMTP, UUCP, or other transports.

Why this case is interesting is that if mail is intercepted before it gets deposited into the local mailbox this would replace the need to intercept incoming SMTP and figure out the true local mailbox name (and therefore the user ID which is used to look up the encryption key). An easy way to intercept mail in this way is to replace the local delivery agent (typically /bin/mail) with a virus scanning version. This uses the protocol daemon in standalone validation mode.

CyberSoft Certificate Verifier API

The certificate verifier GUI application accepts parameters from standard input in a MIME-inspired format. Data is specified either as a single line:

Field-Type: this is the data

or as multi-line:

Field-Type:
	these are multiple lines of data
	here is the second line

Each line of data begins with a tab which is not part of the data and is terminated by an empty line (without a tab), another field type header, or the end of input. Field types are:

Cert-Type: [single]: This is either "Site" to verify a site certificate or "Authority" to verify a certificate authority.

Cert-Subject-Name: [single]: The simple name of the certificate owner.

Cert-Issuer-Name: [single] The simple name of the certificate signer.

Cert-Subject-Info: [multi]: Lines of description (name, address, etc.) about the owner.

Cert-Issuer-Info: [multi]: Lines of description (name, address, etc.) about the signer.

Cert-Serial: [single]: The certificate serial number.

Cert-Validity-Notbefore: [single]: The date the certificate is valid from (free-format).

Cert-Validity-Notafter: [single]: The date the certificate is valid through (free-format).

Cert-Fingerprint: [single]: The fingerprint string (usually an ASCII sequence of hex bytes).

Cert-Encryption: [single]: Description of encryption. Whether this will be a standard name (e.g. RC2-CBC-MD5) or a text string is TBD.

These fields may not all be present, there may be additional unspecified fields, and the fields may be specified in any order.

The application should display various dialogs to the user asking to verify the certificate. Netscape should probably be used as a model. To see an example site verification try connecting here. To see an example CA verification try here. Note that if you accept these certificates you will have to delete them using Netscape's security window if you wish to go through the verification process again.

The program may send response data to standard output in the same format:

Cert-Nickname: [single]: For CAs, this is used to tag the entry in the certificate database. If not specified then Cert-Subject-Name will be used.

The program's exit code should be constructed as follows:

Bit 0: Warn before connecting to sites certified by this CA

Bit 1: Certificate declined for network sites

Bit 2: Certificate declined for e-mail (Authority only)

Bit 3: Certificate declined for software developers (Authority only)

Bit 4: Permanent storage of certificate declined (makes no sense for Authority)

Bit 6: a program error of some kind has occurred. Bits 0-5 define the error and are presently unspecified. Errors should probably include:

Input parse error

Failure to contact the X server

CyberSoft Mail Reprocess Application

As S/MIME encrypted mail is encountered by the NTI protocol engine there is a module in place which attempts to decrypt it by looking up the destination user's private key. If this fails then the mail is stored in a special "quarantine" directory. Instead of the original mail the user will receive a message describing the problem. The user then does what is necessary so that the decryption routine can find the private key (usually this involves making sure the certificate and private key are in his Netscape databases). After this the mail may be reprocessed (hopefully) with more success. This document describes an application which allows the user to trigger the reprocessing of this quarantined mail.

Input Data

The application must know the directory into which the quarantined messages have been deposited. This directory will contain pairs of files, one of each pair ending in a ".info" suffix and the other having the same name but without the ".info" suffix. The second file in each pair will contain the actual mail message. This may be parsed for RFC822 headers if desired which may provide interesting information for display (e.g. Sender/From, Subject, and Date) but the contents of this file are otherwise only intended to be used for reprocessing. The first file in each pair (with the ".info" suffix) will consist of header lines in RFC822 form which provide the following information:

To: This is a (space-separated) list of email addresses to which mail should be sent for reprocessing. It is often a user's external POP3 mailbox or simple names for local mailbox delivery. This header will not be present if this information can not be determined (such as when a user does not have a Netscape preferences file from which to determine a POP3 mailbox address).

Username: This is (space-separated) list of simple usernames. These are the local users who are the final recipient of the mail. It is either the user who initiated the receipt of POP3 mail into his mailbox or the local destination users of SMTP mail delivery.

Protocol: This is the protocol which was intercepted to receive this message. It is normally "SMTP" or "POP3" but "HTTP" and "FTP" are possible for certain configurations. If the message was intercepted in standalone mode then this string will be of the form "standalone/name" where name is the name of the standalone spec.

Direction: This is the direction of message flow and will appear in the form "Direction: dir/role". dir is either incoming or outgoing. role is either client or server. This header will not be present if the message was intercepted in standalone mode.

Application Modes

A typical application might run in two modes depending of whether the invoking user was privileged. In the non-privileged mode the application would display information about messages for which one of the Usernames matches the invoking user. Each message (or all messages) could be marked for reprocessing.

In the privileged mode the application would display information about all messages and allow messages to be marked for reprocessing or optionally marked for reprocessing without further virus scanning or the requirement to decrypt encrypted content. It might also be desirable to allow the administrator to change the email destination to which the mail is sent for reprocessing.

Mail Reprocessing

Mail is best reprocessed by handing it to the /bin/mail program. A command line such as "/bin/mail recipient" with the mail file as standard input is appropriate. The recipient is the contents of the To header in the .info file.

Mail Reprocessing Without Further Virus Scanning

This is only slightly more complicated than the regular case. /bin/mail is invoked but handed data which consists of the header line "Virus-Scan-Status: ignored" followed by the contents of the mail file. This will direct the protocol engine to pass through the message without the content validation step. Note that if a virus were encountered in any non-encrypted parts of the message that it would have already been rejected on the first pass.

File Handling and Locking

The application should find file pairs in the quarantine directory by searching for files with an ".info" suffix and then deriving the message file name from the .info file name. The protocol engine will ensure that any .info files present are complete and have a corresponding complete message file.

After successfully sending a message for reprocessing the application should first delete the corresponding .info file and then the message file.

Other than the file deletion there is no locking protocol necessary with the protocol engine since it simply adds new files with unique names to the quarantine directory. The application itself, however, should employ some sort of locking protocol for multiple instances of itself. This will prevent program errors and duplicate mail. It is safe to use the quarantine directory for lock files.