[Previous: Issues with FTP] [Contents] [Next: Example #1: Firewall for Home or Small Office]

PF: Authpf: User Shell for Authenticating Gateways

Introduction
Configuration
Seeing Who is Logged In
More Information
Example

Introduction

Authpf(8) is a user shell for authenticating gateways. An authenticating gateway is just like a regular network gateway (a.k.a. a router) except that users must first authenticate themselves to the gateway before it will allow traffic to pass through it. When a user's shell is set to /usr/sbin/authpf (i.e., instead of setting a user's shell to ksh(1), csh(1), etc) and the user logs in using SSH, authpf will make the necessary changes to the active pf(4) ruleset so that the user's traffic is passed through the filter and/or translated using Network Address Translation or redirection. Once the user logs out or their session is disconnected, authpf will remove any rules loaded for the user and kill any stateful connections the user has open. Because of this, the ability of the user to pass traffic through the gateway only exists while the user keeps their SSH session open.

Authpf alters the pf(4) ruleset by adding rules to a named ruleset attached to an anchor point. Each time a user authenticates, authpf creates a new named ruleset and loads the preconfigured filter, nat, binat, and rdr rules into it. The rules that authpf loads can be configured on a per-user or global basis.

Example uses of authpf include:

Requiring users to authenticate before allowing Internet access.
Granting certain users -- such as administrators -- access to restricted parts of the network.
Allowing only known users to access the rest of the network or Internet from a wireless network segment.
Allowing workers from home, on the road, etc., access to resources on the company network. Users outside the office can not only open access to the company network, but can also be redirected to particular resources (e.g., their own desktop) based on the username they authenticate with.
In a setting such as a library or other place with public Internet terminals, PF may be configured to allow limited Internet access to guest users. Authpf can then be used to provide registered users with complete access.

Authpf logs the username and IP address of each user who authenticates successfully as well as the start and end times of their login session via syslogd(8). By using this information, an administrator can determine who was logged in when and also make users accountable for their network traffic.

Configuration

The basic steps needed to configure authpf are outlined here. For a complete description of authpf configuration, please refer to the authpf man page.

Linking Authpf into the Main Ruleset

Authpf is linked into the main ruleset by using anchor rules:

nat-anchor authpf rdr-anchor authpf binat-anchor authpf anchor authpf

Wherever the anchor rules are placed within the ruleset is where PF will branch off from the main ruleset to evaluate the authpf rules. It's not necessary for all four anchor rules to be present; for example, if authpf hasn't been setup to load any nat rules, the nat-anchor rule can be omitted.

Configuring Loaded Rules

Authpf loads its rules from one of two files:

/etc/authpf/users/$USER/authpf.rules
/etc/authpf/authpf.rules

The first file contains rules that are only loaded when the user $USER (which is replaced with the user's username) logs in. The per-user rule configuration is used when a specific user -- such as an administrator -- requires a set of rules that is different than the default set. The second file contains the default rules which are loaded for any user that doesn't have their own authpf.rules file. If the user-specific file exists, it will override the default file. At least one of the files must exist or authpf will not run.

Filter and translation rules have the same syntax as in any other PF ruleset with one exception: Authpf allows for the use of two predefined macros:

$user_ip - the IP address of the logged in user
$user_id - the username of the logged in user

It's recommended practice to use the $user_ip macro to only permit traffic through the gateway from the authenticated user's computer.

Access Control Lists

Users can be prevented from using authpf by creating a file in the /etc/authpf/banned/ directory and naming it after the username that is to be denied access. The contents of the file will be displayed to the user before authpf disconnects them. This provides a handy way to notify the user of why they're disallowed access and who to contact to have their access restored.

Conversely, it's also possible to allow only specific users access by placing usernames in the /etc/authpf/authpf.allow file. If the /etc/authpf/authpf.allow file does not exist or "*" is entered into the file, then authpf will permit access to any user who successfully logs in via SSH as long as they are not explicitly banned.

If authpf is unable to determine if a username is allowed or denied, it will print a brief message and then disconnect the user. An entry in /etc/authpf/banned/ always overrides an entry in /etc/authpf/authpf.allow.

Assigning Authpf as a User's Shell

In order for authpf to work it must be assigned as the user's login shell. When the user successfully authenticates to sshd(8), authpf will be executed as the user's shell. It will then check if the user is allowed to use authpf, load the rules from the appropriate file, etc.

There are a couple ways of assigning authpf as a user's shell:

Manually for each user using chsh(1), vipw(8), useradd(8), usermod(8), etc.
By assigning users to a login class and changing the class's shell option in /etc/login.conf.

Seeing Who is Logged In

Once a user has successfully logged in and authpf has adjusted the PF rules, authpf changes its process title to indicate the username and IP address of the logged in user:

    # ps -ax | grep authpf
    23664 p0  Is+     0:00.11 -authpf: charlie@192.168.1.3 (authpf)

Here the user charlie is logged in from the machine 192.168.1.3. By sending a SIGTERM signal to the authpf process, the user can be forcefully logged out. Authpf will also remove any rules loaded for the user and kill any stateful connections the user has open.

    # kill -TERM 23664

More Information

For a complete description of authpf operation, please refer to the authpf man page.

Example

Authpf is being used on an OpenBSD gateway to authenticate users on a wireless network which is part of a larger campus network. Once a user has authenticated, assuming they're not on the banned list, they will be permitted to SSH out and to browse the web (including secure web sites) in addition to accessing either of the campus DNS servers.

The /etc/authpf/authpf.rules file contains the following rules:

wifi_if = "wi0" dns_servers = "{ 10.0.1.56, 10.0.2.56 }" pass in quick on $wifi_if proto udp from $user_ip to $dns_servers \ port domain keep state pass in quick on $wifi_if proto tcp from $user_ip to port { ssh, http, \ https } flags S/SA keep state

The administrative user charlie needs to be able to access the campus SMTP and POP3 servers in addition to surfing the web and using SSH. The following rules are setup in /etc/authpf/users/charlie/authpf.rules:

wifi_if = "wi0" smtp_server = "10.0.1.50" pop3_server = "10.0.1.51" dns_servers = "{ 10.0.1.56, 10.0.2.56 }" pass in quick on $wifi_if proto udp from $user_ip to $dns_servers \ port domain keep state pass in quick on $wifi_if proto tcp from $user_ip to $smtp_server \ port smtp flags S/SA keep state pass in quick on $wifi_if proto tcp from $user_ip to $pop3_server \ port pop3 flags S/SA keep state pass in quick on $wifi_if proto tcp from $user_ip to port { ssh, http, \ https } flags S/SA keep state

The main ruleset -- located in /etc/pf.conf -- is setup as follows:

# macros wifi_if = "wi0" ext_if = "fxp0" scrub in all # filter block drop all pass out quick on $ext_if proto tcp from $wifi_if:network flags S/SA \ modulate state pass out quick on $ext_if proto { udp, icmp } from $wifi_if:network \ keep state pass in quick on $wifi_if proto tcp from $wifi_if:network to $wifi_if \ port ssh flags S/SA keep state anchor authpf in on $wifi_if

The ruleset is very simple and does the following:

Block everything (default deny).
Pass outgoing TCP, UDP, and ICMP traffic on the external interface from the wireless network.
Pass incoming SSH traffic from the wireless network destined for the gateway itself. This rule is necessary to permit users to log in.
Create the anchor point "authpf" for incoming traffic on the wireless interface.

The idea behind the main ruleset is to block everything and allow the least amount of traffic through as possible. Traffic is free to flow out on the external interface but is blocked from entering the wireless interface by the default deny policy. Once a user authenticates, their traffic is permitted to pass in on the wireless interface and to then flow through the gateway into the rest of the network. The quick keyword is used throughout so that PF doesn't have to evaluate each named ruleset when a new connection passes through the gateway.