RT61apd - user space IEEE 802.1X Authenticator
          for RT61 a/b/g SoftAP driver, Ralink Tech Corp.
=================================================================
Copyright (c) 2002-2003, Jouni Malinen <jkmaline@cc.hut.fi>

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License version 2 as
published by the Free Software Foundation. See COPYING for more
details.

=================================================================

This is the README file for the 802.1x daemon - rt61apd, which comes with RT61 SoftAP driver.
This README explains the relationship between the SoftAP driver and 802.1x daemon.
In addtiion, this will teach you how to use this 802.1x daemon.
For programmers who want to add other interfaces for SoftAP driver or 802.1x daemon,
This README has also mentions below.

I.  Introduction
=================================================================
rt61apd is an optional user space component for RT61 SoftAP driver. 
It adds 802.1x Authenticator feature using external RADIUS Authentication
Server(AS).
 

II.  IEEE 802.1X features in rt61apd
=================================================================
IEEE Std 802.1X-2001 is a standard for port-based network access
control. It introduces a extensible mechanism for authenticating 
and authorizing users.

rt61apd implements partial IEEE 802.1x features that helps AS authenrizing
Supplicant and in the mean time proves itself a valid Authenticator for AS.
Noticed that Key management state machine is not included in rt61apd. 
And those key management is included in RT61 SoftAp driver.

rt61apd relays the frames between the Supplicant and the AS.
Not until either one timeout or Success or Fail frame
indicated does rt61apd finish the authentication process.
The port control entity is implemented in SoftAp driver for RT61.


III.  How to start rt61apd
=================================================================
1. First we need to compile the source code using 'make' command
2 Manually start rt61apd, type $rt61apd


IV.  rt61apd configuration for IEEE 802.1X
=================================================================
When rt61apd starts, it reads the configuraion file to derive parameters.
For any changes to make, one need to first edit the configuration file, then
restart rt61apd. Noted that manually restarting rt61apd is unnecessary,
because setting SoftAP driver's SSID with command 'iwpriv' will automatically restart rt61apd.
In a word, edit the configuraion file and then set SoftAp's SSID is all to do to change
any settings related to 802.1x authenticaion.

This common configuraion file is RT61AP.dat, located in /etc/Wireless/RT61AP/.
The format of configuraion file is "Paramater = Value". Each line contains one parameter setting.
The following describes how to achieve :

1.) How to configure SoftAp driver?
========================================
Add correct values for AuthMode and EncrypType parameters.
If you edit like this, 
AuthMode=WPA
EncrypType=TKIP
you would like the AP to use WPA with TKIP to encrypt the data packets.

To change SSID, you can type $iwpriv ra0 set SSID=yourssid


2.) How to configure 802.1x daemon?
========================================
4 essential paramters for 802.1x authenticaion are RADIUS_Server,RADIUS_Port,RADIUS_Key,own_ip_addr.
for example,
RADIUS_Server=192.168.2.3
RADIUS_Port=1812
RADIUS_Key=password
own_ip_addr=192.168.1.123
This implies the RADIUS Server' IP is 192.168.2.3. Port 1812 is used for 802.1x authenticaion.
The RADIUS secret between AP(RADIUS client) and RADIUS server is password. AP's IP is 192.168.1.123.
For any changes to make, edit the configuraion file, and set the AP's SSID again to restart rt61apd.

session_timeout_interval is for 802.1x reauthentication setting.
set zero to disable 802.1x reauthentication service for each session.
session_timeout_interval unit is second and must be larger than 60.
for example,
session_timeout_interval = 120
will reauthenticate each session every 2 minutes.
session_timeout_interval = 0
will disable reauthenticate service.


V.  How to add other interfaces to this SoftAp driver and 802.1x daemon?
=================================================================
For programmers who want to add interface for 802.1x daemon and SoftAp driver,
edit the configuration file and reset SoftAP's SSID via linux IOCTL. 
Detailed linux IOCTL informtaion is in the interface.txt come with 802.1x daemon.
Please refer to that.


VI.  rt61apd configuration for WPA2
=================================================================
All Same as (IV), but if the binding ethernet interface is not eth0, you need to 
modify "eth%d" as "xxx%d" in Apd_init_sockets() in rt61apd.c


VII. Multiple RADIUS Server supporting
=================================================================
1.)	We use complier option to turn on/off the multiple RADIUS servers for 802.1x. 
	If you want to enable the feature, make sure that "MULTIPLE_RADIUS" is defined in Makefile.
	Default is disabled. Besides, you must modify the file "RT61AP.dat" to co-operate with 802.1x.
	We add some variables to configure individual RADIUS server IP address, port and secret key per wireless interface. 

	For example :
	RADIUS_Server_ra0=<ip_arrdess>
	RADIUS_Port_ra0=<port_number>
	RADIUS_Key_ra0=<secret_key>
	RADIUS_Server_ra1=<ip_arrdess>
	RADIUS_Port_ra1=<port_number>
	RADIUS_Key_ra1=<secret_key>
	......
	......
	RADIUS_Server_raN=<ip_arrdess>
	RADIUS_Port_raN=<port_number>
	RADIUS_Key_raN=<secret_key>

	If your wireless interface prefix is not "ra", please modify these variables.
	ex: If the wireless interface name is "wlan0", then 
		RADIUS_Server_wlan0=<ip_arrdess>
		RADIUS_Port_wlan0=<port_number>
		RADIUS_Key_wlan0=<secret_key>
	
 
2.)	Then we can start to run 802.1x. The setting command is
	"rt61apd <wireless_if_name>"  -  <wireless_if_name> is wireless interface name.(ex. ra0, ra1,.....)
	ex. "rt61apd ra0"
    	"rt61apd ra1"  
	After per task is started successfully, we record its Process ID in /var/run/auth_raN.pid. (N is integer)
	If "ra" is not the wireless interface prefix, please modify it in rt61apd.c.

VIII. Enhance dynamic wep keying
=================================================================
In OPEN-WEP with 802.1x mode, the authentication process generates broadcast and unicast key.
The unicast key is unique for every individual client so it is always generated randomly by 
802.1x daemon. 
But the broadcast key is shared for all associated clients, it can be pre-set manually by users or 
generated randomly by 802.1x daemon.

Through the parameter "DefaultKeyID" and its corresponding parameter "KeyXStr"(i.e. X = the value of DefaultKeyID)
in RT61Ap.dat, the 802.1x daemon would use it as the broadcast key material. But if the corresponding parameter "KeyXStr" is
empty or unsuitable, the broadcast key would be generated randomly by the 802.1x daemon.

The 802.1x daemon need to read RT61AP.dat to decide whether the broadcast key is generated
randomly or not, so please update the RT61AP.dat and restart rt61apd if those correlative parameters are changed.