Access Control

Imap4-proxy uses three-phase ACLs, see access-control(7). The first phase, session-acl is checked once for each client connection. It permits or denies client access and sets some connection parameters. The second phase, command-acl is also checked once for each connection, but it can be selected according to the client certificate in case of SSL/TLS enabled by session-acl. Various parameters can be set in command-acl, e.g., permitted sets of IMAP4 commands and capabilities, timeouts, SSL/TLS on the server connection. The third phase ACLs are used only if mail processing is enabled in command-acl.

There are two types of them. Mail-acl is checked once for each transferred mail. It defines rules for accepting or rejecting the mail according to its content and antivirus/antispam test results. Doc-acl is checked once for each document (MIME part) of a mail. It defines document processing, e.g., filtration or replacement by a fixed file. See mod-mail-doc(5) for more details.

Connection Establishment

When a connection from a IMAP4 client arrives, the configuration is searched for a matching session-acl. If the ACL says that the connection should be denied or there is no matching ACL, the proxy does not communicate with the client and closes the connection immediately. In addition to the generic ACL conditions and actions described in access-control(7), some Imap4-proxy-specific conditions and parameters can be set. It is possible to set language of protocol response messages generated by the proxy.

Item client-ssl-params switches on SSL/TLS on the client connection and sets various SSL/TLS parameters. If the connection from the client uses SSL/TLS then item client-cert-match defines the acceptable client certificates. If the client certificate does not pass the test, SSL/TLS connection establishment fails and the connection is closed. SSL/TLS handshake must complete until idle-timeout expires, otherwise the proxy closes the connection.

If the client connection is transparent (arriving to a transparent listening port), the original destination address is detected by the proxy and used as the server address for the server connection. Otherwise, the server must be specified by item plug-to. It is also possible to override a transparent destination address by plug-to.

Firewall administrator can choose the out-of-band method described in auth(7) for authenticating users on the proxy.

In the next step, the configuration is searched for a matching command-acl. It is possible to use values from a client certificate as a search condition. There are many options settable in command-acl. Language of protocol response messages generated by the proxy can be changed by language. This item overrides language setting from session-acl.

It is possible to turn on SSL/TLS on the server connection by server-ssl-params and to set requirements for the server certificate by server-cert-match. SSL/TLS can be used independently on the client and the server connection, hence the proxy may provide translation between unencrypted and encrypted communication.

Many limits can be set for a session. If any of the limits is exceeded, the proxy terminates the session. Total number of bytes transferred during a session is limited separately for client-to-server (max-bytes-out) and server-to-client (max-bytes-in) directions. No single mail may be larger than max-mail-in (server-to-client) or max-mail-out (client-to-server) bytes. Total time of the session is bounded by max-time. The session is terminated if it is idle longer than idle-timeout.

When a matching command-acl is found and it does not deny the session, the proxy connects to the server.

Protocol Processing

The proxy passes IMAP4 communication between the client and the server. It performs basic checks of the protocol. It is possible to permit only a subset of command by command-acl.commands. A forbidden command is not sent to the server and the proxy returns an error response. Item command-acl.capabilities selects an allowed subset of capabilities (returned by server in response to CAPABILITY command). A forbidden capability is discarded by the proxy and not sent to the client. IMAP4 command LOGOUT or connection close by either the client or the server terminates the session.

Mail can be transferred to the client or to the server in one of two modes. In the first mode, the mail is first stored by the proxy, processed, and the result is sent to the client/server. In the second mode, turned on by item no-mail-scanning in command-acl, the mail is not processed by the proxy and data from the server are immediately passed to the client and vice versa. In the second mode without mail processing, antivirus and antispam checking is not performed. No conditions on mail contents and no mail modification options in mail-acl and doc-acl work, because mail-acl and doc-acl are not consulted at all (they can be even missing).

Mail Processing

Mail processing is controlled separately for mail transferred from the client to the server (section command-acl.upload) and for mail transferred from the server to the client (section command-acl.download). Mail processing is performed for each mail if the active command-acl does not contain no-mail-scanning. Mail processing options can be set by mail-filter which contains options specifying corrections of mails violating RFCs. In command-acl, there are also settings for antivirus and antispam checks (items use-antivirus and use-antispam, respectively). After a mail is read and stored by the proxy, it is checked by antivirus and antispam and its structure is analyzed.

Mail-acl (only one) and doc-acl (one for every MIME part of the mail) are found according to the conditions like direction of mail transfer (download or upload), results returned by the antispam and the antivirus, size, or MIME type. If any of the selected ACLs contains item deny, the mail is discarded and an error response is returned to the client. According to doc-acl, each document (MIME part) may be left unchanged, passed to the HTML filter, or replaced by a file. Actions defined by mail-acl for the whole mail include adding text to the subject and replacing the mail body by content of a file. See mod-mail-doc(5) for more details.

Logging

As all other Kernun proxies, imap4-proxy generates many log messages during its operation. Meaning of the messages may be found in section 6 of the manual pages. Details about Kernun logging can be found in logging(7).

The proxy logs statistical messages about each client connection and each request. When a connection arrives, SESSION-START is logged. Then ACL messages inform about the session and command ACLs selected for this connection. If mail processing is enabled, ACL messages are logged for each mail and doc ACL. Finally, SESSION-END is logged when the session is terminated.

Common Kernun Features

Imap4-proxy uses common Kernun mechanisms for listening on its sockets, accepting client connections, and managing its processes. It can also run in a chrooted environment and change its user identity upon startup. See also application(5), tcpserver(5), and tcpserver(7).

The proxy uses a common Kernun mechanism for network input/output. The configuration allows to specify several parameters like buffer sizes and timeouts, both for client and server connections. The parameters are set in configuration sections client-conn and server-conn. See netio(7) for details.

The proxy uses common Kernun mechanism for name resolving (see resolving(7) manual page).

Imap4-proxy uses common Kernun mechanism for runtime monitoring. For more detailed information, see monitoring(7).

Imap4-proxy uses common Kernun mechanism for traffic shaping. For more detailed information, see traffic-shaping(7).

The proxy uses common Kernun mechanism for document type identification (see doctype-identification(7) manual page).