[Top] | [Contents] | [Index] | [ ? ] |
This document applies to Oasis version 1.0rc8.
1. The basics Basic concepts 2. The configuration services Configuration services 2.4 The oasis implementation The access server 2.5 The firewall control daemon 3. Step-by-step installation instructions
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
StockholmOpen.Net is an authentication mechanism for a public access network. Internet access is provided by different operators, and users are able to dynamically choose which operator to use, ie, the access network is operator neutral.
Users are required to authenticate to the network in order to gain access. This is done on a secure web page where the user fills in username and password. Before authentication, users are redirected to the login page if the user tries to access another webpage. When the user disconnects from the network, access is again denied. This means that users are required to login each time they want to access the network.
The network consists of two types of services: public services common to the whole network, and provider specific services. The common services are what "holds everything together". They provide configuration to requesting clients and act as a relay to the provider specific services. The provider specific services are what do the actual authentication, and includes the access server.
The access server is responsible for opening and closing rules in a firewall and thus allowing users to reach the services provided by the provider. These services will typically be access to the global Internet.
The common services in the public network are:
This service registers new MAC addresses with a chosen operator and relays DHCP requests to the operators DHCP server based on the choice made by the user. When a new user (with a previously unregistered network card) connects to the registration webpage, he is presented with a choice of upstream providers and the choice is stored in a database. This database is used in following connections to relay DHCP requests.
The common services should be located in the same machine. For each provider, the following services must exist:
This is an ordinary DHCP server. The policy of IP address allocation is not enforced by the system. Either automatic, dynamic or manual allocation could be used. For simplicity, dynamic allocation is recommended.
The DHCP server must be placed outside the open network, in the providers own network, unreachable from unauthenticated users. Otherwise, the functionality of the common relay agent will be disturbed.
This service is where users sends his/her credentials in order to login to the network. The user is presented with a web frontend, which is assumed to be secured via an https connection, although this is not a requirement of the system.
Upon successful authentication, the access server communicates with the dynamic firewall to open up a rule, allowing the user access to the upstream network.
The actual authentication need not be performed in the access server. The access server could include a client module that speaks to an authentication server, for example RADIUS or Kerberos.
The acces server would then send the user credentials to the authentication server for verification. The authentication server could be common to other services that the operator provides and be located inside the ISPs own network.
The dynamic firewall in the current system is a standard PC running Linux and iptables. The firewall could also be a dedicated router that can be remotely controlled.
The firewall should be configured to drop all packets from a yet unauthenticated user (based on MAC and IP address). If there are certain services that are required for unauthenticated users, such as DNS, there can be static rules that open those services.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The configuration services provides configuration to requesting clients and maintains the registration between user and selected provider.
2.1 Design of the relay agent 2.2 The registration services 2.3 Setting up the MAC database
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The BOOTP relay agent is a modified version of ISCs dhcrelay version 3.0. The relay agent has been modified to instead of sending a recieved DHCP message to one or more servers it now sends the DHCP message to only one server based on the MAC address of the requesting client. This is achieved by looking up the MAC address in a database consisting of mappings between MAC addresses and providers. The database is a PostgreSQL and is accessed trough libpq.
The database has the following definitions:
@verbatim CREATE TABLE T_provider ( provider_id SERIAL, provider_name text, provider_dhcp inet, provider_auth_url text, provider_net inet, provider_netmask inet, primary key (provider_id));
CREATE TABLE T_macbind ( mac_addr macaddr, provider_id bigint, mac_reg_date timestamp, primary key (mac_addr));
CREATE VIEW V_mapping AS SELECT M.mac_addr, P.provider_dhcp, P.provider_net, P.provider_netmask, P.provider_auth_url FROM T_macbind AS M,T_provider AS P WHERE M.provider_id = P.provider_id;
GRANT ALL ON T_provider TO macbind; GRANT ALL ON T_macbind TO macbind; GRANT ALL ON V_mapping TO macbind;
In the table T_provider:
In T_provider there has to exist one entry with `provider_name' = "default" to be used as default when a (MAC address, provider) binding is not available.
In the table T_macbind:
The view V_mapping is just a way to ease up the queries to the database so that the client only has to make one query to get the (MAC address, provider) binding.
2.1.1 Compiling the relay agent
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Unpack the DHCP sources and apply the patch:
tar zxf dhcp-3.0.tar.gz cd dhcp-3.0 patch -p0 < ../dhcp.patch |
Now configure and make DHCP:
./configure make make install |
The relay agent does not need any configuration. All neccessary information is retrieved from the MAC database.
For more instructions, see the included documentation in the original ISC DHCP sources.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The registration service lets users choose the provider to use. It is a web page that records the users choice in the MAC database.
When the user wants to authenticate to the network, he enters the registration page. This page looks up the MAC address of the requesting client in the MAC database and redirects the user to the real authentication webpage of the chosen ISP. The registration page also makes it possible for the user to change ISP.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
PostgreSQL is used for the MAC database.
PostgreSQL is available as convenient packages for many GNU/Linux distributions, including RedHat (+ clones) and Debian.
Alternatively, one can download and compile PostgreSQL from source. The sources are available from http://www.postgresql.org/. Instructions for compiling PostgreSQL are included in the sources.
createdb macbind |
createuser -P macbind |
macbind_qwerty
into the access and DHCP relay
sources. This really has to be fixed.
psql -U macbind -f init-macbind.sql macbind |
Edit the PostgreSQL access configuration file to allow connections to
the macbind database with a password. Add the following line to
/etc/postgresql/pg_hba.conf
:
local macbind password |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This chapter describes the oasis
implementation.
2.4.1 How oasis is designed How it works 2.4.2 Format of the requests 2.4.3 Compiling oasis Compiling the sources 2.4.4 Configuring oasis 2.4.5 Starting Oasis Starting oasis 2.4.6 PAM 2.4.7 The firewall control program Controlling the firewall
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
oasis
is designed as a multi-threaded application. The main
thread listens on a UNIX socket for requests. Each request is
processed in order, one at a time. When a login request is received,
the user is authenticated via PAM (see 2.4.6 PAM) and, if successful,
the configured firewall control program is run to open up a rule for
that user (identified by MAC and IP address) in the corresponding
firewall.
The requests will typically be sent by the web frontend. In the www subdirectory of the source distribution there are PHP scripts that prompts for username and password, retrieves the IP and MAC addresses and sends a request to the access server.
oasis
uses PAM (Pluggable Authentication Modules) as
authentication mechanism. PAM is a highly configurable system, in
which one can plug in any authentication module. This system is used
on many UN*X systems and there exists many modules, including
Kerberos, Radius, plain passwd files and LDAP.
To prevent malicious users from using a valid user authenticated
connection after he has disconnected from the network, the rule in the
firewall must be closed when a user disconnects. oasis
has
two modes of operation to detect the presence of a user:
oasis
uses a plugin
system. Currently, there exists plugins for ARP ping and ICMP
ping. The probe plugin to use is configurable per domain.
If the user fails to answer a certain number of such "probes" the user is considered disconnected and the firewall is closed.
Each probe is run in a separate thread to simultaneously probe a (configurable) number of users. It is important to configure the number of simultaneous probes and the maximum number of users allowed in a good way. If too many users are probed simultanously this could create a flood ping. On the other hand, if too few users are probed, it will take a long time before a user is logged out.
fwcd
, the firewall
control daemon. When a user authenticates to the access server, a
request is sent to fwcd
(running on the firewall) to open up
the rule. The connection is secured using SSL. The firewall control
daemon then starts to listen on the traffic passed through it. If
packets arrive from the users MAC/IP address, he is active and no
active action is necessary. When the user is inactive (but still
connected) the firewall then starts to probe the user as described in
the previous mode until the user starts to send packets again.
This mode eases the load on the network by reducing the amount of "useless" traffic, but also requires that the firewall is able to run the daemon. This is not the case with dedicated routers.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The request is formatted as a string of ascii characters, terminated
with a linefeed - carriage return pair (\r\n). The first keyword is
the name of the command requested. Each keyword must be separated by
space. After the command keyword the arguments follow. An argument is
formatted as OPTION=VALUE
, each argument separated with a
linefeed character (\r
).
LOGIN USER=username\rPASS=password\rDOMAIN=domain\rIP=ip-address\rMAC=mac-address\r\n
LOGOUT\rUSER=username\rDOMAIN=domain\r\n
STATS\r\n
sends information about all logged in users.
STATS\rDOMAIN=domain\r\n
sends information about all logged in
users in the specified domain.
STATS\rDOMAIN=domain\rUSER=username\r\n
sends information about
the specified user in that domain.
After a request is processed, a reply is sent back. The reply is
formatted as RETURN-CODE ERROR-MESSAGE\r\n
. The return code can
be either 0 (successful) or 1 (failed). The ERROR-MESSAGE is a string
specifying the reason for failure.
See the test clients included in the source package for a more practical example of how requests are sent to the server.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
oasis
is distributed as a gzipped tarball. Type tar
zxf oasis-x.x.tar.gz
to unpack the sources (replace x.x with the
version number). This will create a directory `oasis-x.x'.
oasis
uses a configure script to adapt the sources to
different platforms. To configure the sources, simply run
./configure
in the top level directory of the source tree. The
script accepts some arguments, use ./configure --help
to see
them.
To build successfully, pthreads, libpcap and libnet are required (and their development headers). If you use a recent distribution, look for the packages libpthreads-dev[el], libpcap-dev[el] or libnet-dev[el].
The default install prefix is `/usr/local', but this can be
changed by passing the --prefix=PATH
argument to configure.
After the configuration step, simple type make
to compile the
sources. To install, type make install
as root.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The configuration file is by default installed as `/usr/local/etc/oasis.conf'. There is a template in the etc subdirectory of the source distribution that you can modify to your needs. The syntax is simple: each directive consists of a keyword, an equal sign and the argument, as in:
keyword = argument
Comments begin with #
or //
and extends to the end of
the line. Block comments can be written in C syntax, beginning with
/*
and ending in */
.
Valid global directives are:
probe-interval
probe-max-users
probes.
probe-max-users
max-missed-probes
probe-timeout
probe-interval
.
socket-path
/tmp/oasis
.
socket-owner
root.nobody
.
socket-mode
chmod
(1), as in "u=rw,g=wx,o=wr"
and octal mode can be
used. If octal mode is used, you must surround it in double quotes, as
in "0644"
.
log-facility
LOG_AUTHPRIV, LOG_DAEMON, LOG_LOCAL0, LOG_LOCAL1, LOG_LOCAL2, LOG_LOCAL3, LOG_LOCAL4, LOG_LOCAL5, LOG_LOCAL6, LOG_LOCAL7, LOG_USER
firewall-soft-timeout
firewall-hard-timeout
backlog
To define a new domain, use the following syntax:
domain NAME { DIRECTIVES }
NAME
is used in the DOMAIN keyword sent in the request.
Recognized DIRECTIVES
in a domain definition are:
max-users
max-same-users
max-users
limit
above).
firewall-program
To open up a rule: <open> <IP> <MAC>
To close a rule: <close> <IP> <MAC>
To reset the firewall: <reset>
IP is a string in dotted-decimal form (xxx.xxx.xxx.xxx) and MAC is a colon-separated string of hex numbers (00:01:60:12:a7:bd).
This directive is mutually exclusive with the fwcd-host
directive.
fwcd-host
fwcd
, the firewall control
daemon).
fwcd-port
firewall-host
option above). The default port is 1717.
port
certificate-file
key-file
fwcd-certificate-file
pam-service
probe-library
probe-interface
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Options are specified by the usual GNU command line syntax, with long
options starting with two dashes (--
).
Usage: oasis [options]
Options:
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
A complete description of PAM (Pluggable Authentication Modules) is outside the scope of this document. More information can be found at http://www.kernel.org/pub/linux/libs/pam/.
PAM is used to do the actual authentication of a user. PAM is a general framework for authentication, accounting and password management. Only the authentication part is used in the access server. The framework uses a plug-in system where modules can be written to extend the system to support almost any kind of authentication mechanism. Today there exists modules for Kerberos, Radius, LDAP, password files and more.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
If your domain is configured with firewall-program
, this option
specifies a program (a simple shell script) to be executed when
controlling the firewall. In the scripts subdirectory of the source
distribution the is a template to begin with.
The script is passed different parameters depending on what it should do. The first parameter is the action string which can be "open", "close" or "reset". The two first actions takes two more parameters, the IP and MAC address, as strings.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
fwcd is a daemon that runs on the firewall. This requires that the firewall is an ordinary computer and not a dedicated router (such as a Cisco router). It communicates with Oasis, who sends requests to fwcd to login a user. The firewall control daemon will then start to listen on the traffic to decide if the user is logged in or not. When the user is inactive (but still connected), fwcd starts to ping the user until he is active again.
This solves the problem of too much probing, since the firewall doesn't need to actively probe all the time.
2.5.1 Starting fwcd 2.5.2 Configuring fwcd
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Options are specified by the usual GNU command line syntax, with long
options starting with two dashes (--
).
Usage: fwcd [options]
Options:
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The configuration file is by default installed as `/usr/local/etc/fwcd.conf'. There is a template in the `etc' subdirectory of the source distribution that you can modify to your needs. The syntax is simple: each directive consists of a keyword, an equal sign and an argument, as in:
keyword = argument
Comments begin with #
or //
and extends to the end of
the line. Block comments can be written in C syntax, beginning with
/*
and ending in */
.
Valid directives are:
probe-interval
log-facility
LOG_AUTHPRIV, LOG_DAEMON, LOG_LOCAL0, LOG_LOCAL1, LOG_LOCAL2, LOG_LOCAL3, LOG_LOCAL4, LOG_LOCAL5, LOG_LOCAL6, LOG_LOCAL7, LOG_USER
max-missed-probes
firewall-soft-timeout
firewall-hard-timeout
firewall-program
To open up a rule: <open> <IP> <MAC>
To close a rule: <close> <IP> <MAC>
To reset the firewall: <reset>
IP is a string in dotted-decimal form (xxx.xxx.xxx.xxx) and MAC is a colon-separated string of hex numbers (00:01:60:12:a7:bd).
port
probe-interface
oasis-host
oasis-port
probe-library
certificate-file
key-file
oasis-certificate-file
network
promiscuous
promiscuous
to 0
is a better
choice since the firewall only needs to listen on traffic to be routed
through that machine.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This is a step-by-step guide for installing the StockholmOpen.Net system. It is assumed that the reader has knowledge of Un*x administration in general and Un*x networking in particular. Installation of the StockholmOpen.Net system is more of "plug-and-pray" than "plug-and-play" right now.
Choose what machines should run the configuration services (BOOTP relay agent, MAC database and registration). Choose if the access server and firewall should be colocated in the same machine. A tip is to start with one machine for access server and firewall if you're not sure you will need them separated (perhaps you're using a Ciso router?). They can easily be separated later.
The relay agent machine needs one additional interface for each operator
present in order for the DHCP server to accept the request as
authoritative. These interfaces should be aliases and assigned an IP
address belonging to the operators subnet. In Linux aliased interfaces
can be created with ifconfig eth0:0 10.0.0.1
(the first alias,
starting with 0, for interface eth0).
/usr/local/sbin/oasis-firewall-sample
. If the firewall is
colocated with the access server (ie, local access to the firewall), the
sample script will probably work fine (assuming you use iptables),
otherwise use your imagination (SSH could be used to securely control a
remote PC-based firewall, in which case you must set up public keys
appropriately for automatic root access).
In the reset section you might want to include static rules for access to an upstream DNS and other services that should be provided before authentication.
The default firewall script includes redirection to a local webserver for unauthenticated users. If you decided to separate oasis and the firewall this will not work directly. Install a simple webserver on the firewall that issues a http redirect to the oasis web server.
client
program. It's
available in the src
subdirectory in the source distribution.
/usr/local/var/www
) and tailor it to your taste. They are quite
minimal in order to make it easier to modify the design/layout.
/lib/security
) and
create a PAM configuration file for oasis.
Assuming you name your PAM service "gazonk", create the file
/etc/pam.d/gazonk
with the following contents for a Kerberos
service (a Kerberos 4 PAM module is available at
http://software.stockholmopen.net/):
auth required pam_krb4.so MY.REALM
Then point oasis to this PAM service by setting pam-service
in
the oasis configuration file to "gazonk". Now oasis will use the PAM
rules in /etc/pam.d/gazonk
when authenticating users for that
domain. You can have different authentication mechanisms for different
domains.
PAM is very flexible. For example to use an existing Kerberos database but only allow a subset of the users in the Kerberos database, one can use the following in the PAM configuration file:
@verbatim auth required pam_listfile.so onerr=fail sense=allow item=user file=/etc/userlist auth required pam_krb4.so
[Top] | [Contents] | [Index] | [ ? ] |
[Top] | [Contents] | [Index] | [ ? ] |
1. The basics
2. The configuration services
3. Step-by-step installation instructions
[Top] | [Contents] | [Index] | [ ? ] |
Button | Name | Go to | From 1.2.3 go to |
---|---|---|---|
[ < ] | Back | previous section in reading order | 1.2.2 |
[ > ] | Forward | next section in reading order | 1.2.4 |
[ << ] | FastBack | previous or up-and-previous section | 1.1 |
[ Up ] | Up | up section | 1.2 |
[ >> ] | FastForward | next or up-and-next section | 1.3 |
[Top] | Top | cover (top) of document | |
[Contents] | Contents | table of contents | |
[Index] | Index | concept index | |
[ ? ] | About | this page |