access-control, acl — Kernun proxies access control system


Access control in the Kernun firewall is driven by so-called Access Control Lists (ACLs) defined in the configuration. In terms of Kernun configuration(7), an ACL is a repeatable section consisting of subsections and items. A set of ACLs for every particular proxy is defined in the firewall configuration (see kernun.cml(5)) and by the cml(8) tool; it is written to the particular proxy configuration file.

Kernun ACLs form a multilayer structure, in order to fit several phases of decisions made by the particular proxy when serving client requests. For example, tcp-proxy has only one layer, because it makes access decisions only once after accepting a TCP connection. On the contrary, ftp-proxy implements three layers of ACLs: session-acl, command-acl, and doc-acl. First, session-acl is consulted when receiving a connection from a client. Then, command-acl is consulted for each command received from the client. Finally, doc-acl is consulted for each transferred file.

At each layer, multiple ACLs can be defined. They present a ruleset for proxy decisions. In an ACL there are configuration directives of two basic functions:

entry conditions

define whether or not the particular ACL matches the current situation;


define proxy operation continuation.

Every ACL definition in each proxy/layer is derived from the general prototype called acl. Each proxy/layer ACL changes the general model by

  • defining a new name of the configuration section (e.g. doc-acl instead of just acl);

  • renaming subsections/items;

  • excluding subsections/items (they become unknown in the new ACL);

  • adding new subsections/items specific for the proxied protocol;

  • changing default values of item elements (attributes);

  • changing/adding/removing integrity constraints.

The ACLs used by individual proxies are described in the proxy-specific manual pages (section 5 and section 8). This manual page desribes the general model of ACLs.

Layering model

As we have stated above, if the proxy needs to make an access control decision in several phases, it uses a multilayer ACL model. The current Kernun proxies use up to three layers of ACLs.

  1. The first layer (which is present in all proxies) is called session-acl. It is derived from a specialized prototype acl-1 (see acl(5) for details) and represents the crucial proxy decision: whether or not the client is to be served. This decision is made at the very beginning of the communication and therefore uses only data from the lower OSI layers — connection/request source (item from) and destination (item to) physical address etc. Specifically, this means that it uses no protocol dependent data.

    For these reasons, this layer plays a very important role and is therefore handled specially in the CML. The phase 1 ACLs (named acl) are defined at the system level (rather than within a particular proxy definition). Thus, the administrator can express the global access control policy at the single point by defining which clients may connect to which servers, which protocols they may use and at which time.

    A proxy can add proxy-specific actions to a particular acl by listing them in a session-acl section within its configuration section with the name identical to the system-level one.

  2. The second layer of ACL (derived from the acl-2 prototype, see acl(5) for details) comes into effect when the connection or request has been accepted, the proxy has read some data from the protocol and makes some protocol-dependent decisions. That is why:

    • different proxies use different names for the ACL (e.g. request-acl for HTTP or DNS, but delivery-acl for SMTP);

    • ACL entry conditions use protocol-dependent data (e.g. URI for HTTP, SERVICE for SQL*Net etc.); the to item (physical target) is mostly changed to the server item (logical target);

    • ACL actions can define protocol-specific responses (e.g. special reply code and text).

  3. The third layer of ACL is specific only for proxies that work with documents (i.e. HTTP, FTP and mail handling protocols). It therefore includes document-specific entry conditions and actions (e.g. mime-type or html-filter, see acl-3 prototype definition in acl(5) for details).

    One of the tasks that can be performed by the third-layer ACL is antivirus check. There is a fundamental difference between proxies using the store-and-forward model (such as SMTP) and those using the pass-thru model (such as HTTP). The former have the whole document available before making a decision, so they can use the antivirus result as an entry condition. The latter must decide on-the-flow: they define antivirus check as an action and, together with it, they define also ex-post reactions.

ACL Selection

If multiple ACLs of the same layer are present in the configuration, the proxy must select a single one that will control its further operation. ACL matching is performed according to the entry conditions used in the particular ACL. The individual ACL sections are evaluated in the order in which they occur in the configuration, and the first matching ACL is selected. If no ACL matches, the service is denied.

The following data items are defined in the general acl prototype and can be used to select the proper ACL (unless the proxy definition excludes them from a proxy-specific ACL):

from addrs

This condition matches if the client address is a member of the addrs  host-set. The algorithm used for address and host-name matching is described in host-matching(7).

to mode addrs [port ports]

This condition tests the destination address of the connection or request. In the non-transparent mode case, the destination address is one of addresses of the firewall itself. In the transparent mode case, the destination address is the address of the target server (see also transparency(7)). It is also possible to match the target port number.

server addrs

This condition matches if the (logical) target server of the connection/request is a member of the addrs  host-set. The server may (but need not) be the same as the host matched by the to item. In HTTP, for example, the to item checks the IP destination address of a connection from a client, whereas the server item checks the server name specified in the request URL or Host HTTP request header.

user none

This condition matches if the user authentication data is not present.

user users [group groups]

This condition is true if the user has been successfully authenticated and her/his username is a member of the users  str-set. It is also possible to match groups a user belongs to.

time time-spec

The condition matches if the current time matches time-spec. The matching algorithm is described in the time-matching(7) manual page.

parent-acl acl-names

This condition can be used only in a multilayer ACL set. It is true if the name of the ACL chosen in the previous layer is a member of the acl-names  str-set.

Within one ACL section, the entry conditions of the same type are combined using logical OR (matches if any one is true). Entry conditions of different types are combined using logical AND (matches if all of them are true). Unused conditions are not checked.

For example, the ACL

  command-acl transparent-for-joe-or-mary {
    user joe;
    from [];
    user mary;

matches if the following logical formula is true:

  (user=joe OR user=mary) AND from=

ACL Actions

A set of actions can be specified for each ACL using configuration items or subsections within the ACL. The specified actions are performed if the ACL is selected (matched). Each proxy declares its own set of proxy-specific actions. For actions available in individual proxies, consult the proxy-specific manual pages (section 5). The following list presents the set of common actions that have the same meaning in all proxies, in which they are supported. Each ACL must contain exactly one action from the pair {accept|deny}.


This item specifies that any connection/request satisfying this ACL is accepted. Various parameters from this ACL and other parts of the configuration control further handling of the connection/request.


This item specifies that any connection/request satisfying this ACL is denied. Typically, no other actions are neither applicable nor performed, although some proxies may, in some cases, allow special actions that fine-tune the kind of negative reaction to be be used.

auth method [param]

This item specifies that proxy authentication is required and the authentication method to be used. For more information, see auth(7).

source-address {client|addr}

The specified source address is to be used for connection to the server. If client is specified, the client's address will be used. The addr element is of the host type.

plug-to server

The connection or request is to be forwarded to server regardless of the IP destination address and target server specified by the user. The server element is of sock type.

See Also

acl(5), auth(7), configuration(7), host-matching(7), time-matching(7), transparency(7)


This man page is a part of Kernun Firewall.
Copyright © 2000–2023 Trusted Network Solutions, a. s.
All rights reserved.