auth — client authentication on proxy


The auth library handles the authentication of client users to proxies. The firewall administrator can restrict access to a proxy by requiring authentication of users. If this is the case, a user must not only connect to the proxy from an allowed host, but also prove his or her identity in order to be granted access.

The proxy authentication library currently supports the following authentication methods: none, password file, RADIUS, LDAP, and out of band authentication. Not all the methods are supported by all proxies.

None Authentication

The none authentication mode means in fact "no authentication is required". Any user is granted access without a requirement to provide their identity.

Password File Authentication

In the password authentication mode, each user is required to provide a valid user name and password. These are compared against a password file stored on the firewall. The file has a simple line structure: each line contains information about one user. It includes two fields delimited by a colon: the first one is the user name and the second one the encrypted password. Optionally, there can be the third colon-delimited field containing a comma-separated list of groups the user belongs to.

The fwpasswd utility can be used to manipulate the password file. See also fwpasswd(1).

RADIUS Authentication

The RADIUS Authentication mode also requires valid information to be received from the user. The user identity is verified by sending an authentication request to a RADIUS (Remote Authentication Dial In User Service) server. The RADIUS server checks the information from the user and tells the proxy whether the user has been authenticated successfully. The RADIUS authentication mode supports a simple name/password scheme as well as a securer challenge/response scheme.

If the name/password authentication is used, the user presents his/her name along with a password, which remains always the same. This represents a potential security hole, because the password could be sniffed while being transferred over the network.

The challenge/response scheme offers better security. The user enters his/her name, the RADIUS server sends back a challenge, which is changed after each (successful) authentication attempt of the user. The user performs some calculation on their local machine and obtains a response based on their password and the challenge received. He/she then sends the proxy only the response, but not the password itself. The RADIUS server verifies the response and notifies the proxy whether or not the user should be considered authenticated. An example of a widely available challenge/response scheme is OPIE (One-time Passwords In Everything). However, the Kernun authentication library offers generic support of challenge/response protocols, which does not depend on a particular challenge/response scheme implemented by a RADIUS server.

LDAP Authentication

LDAP Authentication is somewhat similar to the preceding authentication methods; the difference is that the information about users is stored on an LDAP server.

The user presents his/her username and password in order to prove his/her identity. The firewall first checks the username/password with the information stored on the LDAP server. If the provided information is valid, the firewall obtains the list of groups the user is member of.

External Tool Authentication

The authentication can be managed also by your own tool, instead of LDAP or RADIUS servers.

The tool (with a pathname given in the configuration) is called whenever the user submits data. The data is supplied to the tool in the following environment variables:


User name.


User password or response.


Any data supplied by the previous call of the tool.

The tool responds by writing one status and zero or more data lines to the standard output. The status line has following format:

status data-length

The status must be a 3-digit status code, the first digit defines authentication result (2 – OK, 3 – another response needed, 4+5 – error). The data-length is the total length of all subsequent lines (including the LF characters). Every data line starts with the type character follwed by the colon and the text. There are following types of data lines:


The message text to be displayed to the user.


The internal data to be supplied in the subsequent tool invocation.


The (comma separated) list of groups the user belongs to.


The session timeout (in seconds).

The M data has the following meaning, according to the response codes:

2xx response

The (HTML) message contains additional info concerning the session.

3xx response

The (plain) message that needs to be displayed to the client in order for the authentication to be completed successfuly. It should be the challenge text in challenge response, an error message if the tool gives the user another chance to reenter response etc.

4xx/5xx response

The (plain) message containing the reason of a nonrecoverable authentication error.

Out of Band Authentication

The out of band (OOB) authentication mode is special. All other authentication methods obtain authentication data (a user name, a password, or a response to a challenge) from the user via the proxied application protocol. They are thus usable only in proxies for protocols that support passing of authentication data, such as HTTP or FTP. OOB authentication first authenticates a user to the firewall as a whole. The user may enter the authentication data into an HTML form, or some other mechanism can be used to provide a list of authenticated users. Out of the box, Kernun contains tools for obtaining user list from a Samba server. The use of other sources of authentication data requires only modification of a single script. The authenticated user is associated to an IP address. All connections from this IP address are considered to be from this user. As the source IP address is available in all protocols, OOB authentication can be used in (almost) any proxy. Even the generic tcp-proxy and udp-proxy support OOB authentication.

OOB authentication is managed by an OOB authentication server, which is a specially configured http-proxy(8). The ooba-samba(1) script is used to read of the list of users from Samba.

NTLM Authentication

The NTLM authentication mode is specific to http-proxy. It allows a Web browser on a Microsoft Windows client operating system to be authenticated without user interaction, provided that the user is authenticated in an Active Directory domain. If the proxy requests NTLM authentication from a browser, several messages are exchanged among the browser, the proxy, the NTLM authentication support part of the Kernun system, and the Active Directory domain controller. In this process, the browser uses the user credentials acquired during the user login to the Active Directory domain. See the manpage for http-proxy(8) details about the NTLM authentication.

See Also

Kernun: fwpasswd(1), ooba-samba(1), auth(5), radius(5), http-proxy(8)

FreeBSD: opiekey(1), opiepasswd(1)


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