[Previous: Issues with FTP] [Contents] [Next: Firewall Redundancy with CARP and pfsync]

PF: Authpf: User Shell for Authenticating Gateways

Introduction
Configuration
Creating an authpf Login Class
Seeing Who is Logged In
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 loads a user's filter/NAT rules into a unique anchor point. The anchor is named by combining the user's UNIX username and the authpf process-id into the format "username(PID)". Each users' anchor is stored within the authpf anchor which is in turn anchored to the main ruleset. The "fully qualified anchor path" then becomes:

main_ruleset/authpf/username(PID)

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.

Enabling Authpf

Authpf will not run if the config file /etc/authpf/authpf.conf is not present. Even if the file is empty (zero size), it must still be present or authpf will exit immediately after a user authenticates successfully.

The following configuration directives can be placed in authpf.conf:

anchor=name - Use the specified anchor name instead of "authpf".
table=name - Use the specified table name instead of "authpf_users".

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.

In addition to the $user_ip macro, authpf will make use of the authpf_users table (if it exists) for storing the IP addresses of all authenticated users. Be sure to define the table before using it:

table <authpf_users> persist pass in on $ext_if proto tcp from <authpf_users> \ to port smtp flags S/SA keep state

This table should only be used in rules that are meant to apply to all authenticated users.

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.

Displaying a Login Message

Whenever a user successfully authenticates to authpf, a greeting is printed that indicates that the user is authenticated.

Hello charlie. You are authenticated from host "64.59.56.140"

This message can be supplemented by putting a custom message in /etc/authpf/authpf.message. The contents of this file will be displayed after the default welcome message.

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.

Creating an authpf Login Class

When using authpf on a system that has regular user accounts and authpf user accounts, it can be beneficial to use a separate login class for the authpf users. This allows for certain changes to those accounts to be made on a global basis and also allows different policies to be placed on regular accounts and authpf accounts. Some examples of what policies can be set:

shell - Specify a user's login shell. This can be used to force a user's shell to authpf regardless of the entry in the passwd(5) database.
welcome - Specify which motd(5) file to display when a user logs in. This is useful for displaying messages that are relevant only to authpf users.

authpf:\ :welcome=/etc/motd.authpf:\ :shell=/usr/sbin/authpf:\ :tc=default:

Users are assigned to a login class by editing the class field of the user's passwd(5) database entry. One way to do this is with the chsh(1) command.

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

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"

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"

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"
dns_servers = "{ 10.0.1.56, 10.0.2.56 }"

table <authpf_users> persist

scrub in all

# filter
block drop all

pass out quick on $ext_if inet proto tcp from \
   { $wifi_if:network, $ext_if } flags S/SA modulate state
pass out quick on $ext_if inet proto { udp, icmp } from \
   { $wifi_if:network, $ext_if } keep state

pass in quick on $wifi_if inet proto tcp from $wifi_if:network to $wifi_if \
   port ssh flags S/SA keep state

pass in quick on $wifi_if inet proto { tcp, udp } from <authpf_users> \
   to $dns_servers port domain 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 and from the gateway itself.
Pass incoming SSH traffic from the wireless network destined for the gateway itself. This rule is necessary to permit users to log in.
Pass incoming DNS requests from all authenticated authpf users to the campus DNS servers.
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.