RTDOT1XD - user space IEEE 802.1X Authenticator
for RT_WIFI linux 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 - rtdot1xd, which comes with RT_WIFI linux driver.
This README explains the relationship between the linux 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 linux driver or 802.1x daemon,
This README has also mentions below.
I. Introduction
=================================================================
rtdot1xd is an optional user space component for RT_WIFI linux driver.
It adds 802.1x Authenticator feature using external RADIUS Authentication
Server(AS).
II. IEEE 802.1X features in rtdot1xd
=================================================================
IEEE Std 802.1X-2001 is a standard for port-based network access
control. It introduces a extensible mechanism for authenticating
and authorizing users.
rtdot1xd 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 rtdot1xd.
And those key management is included in RT_WIFI linux driver.
rtdot1xd relays the frames between the Supplicant and the AS.
Not until either one timeout or Success or Fail frame
indicated does rtdot1xd finish the authentication process.
The port control entity is implemented in linux driver for RT_WIFI.
III. How to start rtdot1xd
=================================================================
1. First we need to compile the source code using 'make' command
2. The command synopsis as below,
rtdot1xd [-d debug_level] [-i card_number]
-d debug_level
Allow user to set debug level. This debug_level
parameter must be 0~4.
0 : RT_DEBUG_OFF
1 : RT_DEBUG_ERROR
2 : RT_DEBUG_WARN
3 : RT_DEBUG_TRACE
4 : RT_DEBUG_INFO
-i card_number
Only work for multiple card function of RT_WIFI linux
driver. This command provides users to assign the
corresponding wireless card.
p.s.
The card_number set 1, it mean that the daemon works with the 1st card(ra00-x).
The card_number set 2, it mean that the daemon works with the 2nd card(ra01-x).
....
3. Manually start rtdot1xd, default type $rtdot1xd
IV. rtdot1xd configuration for IEEE 802.1X
=================================================================
When rtdot1xd starts, it reads the configuraion file to derive parameters.
For any changes to make, one need to first edit the configuration file, then
restart rtdot1xd. Noted that manually restarting rtdot1xd is unnecessary,
because setting linux driver's SSID with command 'iwpriv' will automatically restart rtdot1xd.
In a word, edit the configuraion file and then set its SSID is all to do to change
any settings related to 802.1x authenticaion.
This common configuraion file is RT2860AP.dat, located in /etc/Wireless/RT2860AP/.
The format of configuraion file is "Paramater = Value". Each line contains one parameter setting.
The following describes how to achieve :
1.) How to configure RT_WIFI 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 and 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 rtdot1xd.
The optional variables as below,
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.
EAPifname is assigned as the binding interface for EAP negotiation.
Its default value is "br0". But if the wireless interface doesn't attach to bridge interface
or the bridge interface name isn't "br0", please modify it.
for example,
EAPifname=br0
PreAuthifname is assigned as the binding interface for WPA2 Pre-authentication.
Its default value is "br0". But if the ethernet interface doesn't attach to bridge interface
or the bridge interface name isn't "br0", please modify it.
for example,
PreAuthifname=br0
V. How to add other interfaces to this linux driver and 802.1x daemon?
=================================================================
For programmers who want to add interface for 802.1x daemon and linux driver,
edit the configuration file and reset its SSID via linux IOCTL.
Detailed linux IOCTL informtaion is in the interface.txt come with 802.1x daemon.
Please refer to that.
VI. Multiple RADIUS Server supporting
=================================================================
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 "RT2860AP.dat" to co-operate with 802.1x.
We extend some variables to support individual RADIUS server IP address, port and secret key for MBSS.
For example :
RADIUS_Server=192.168.2.1;192.168.2.2;192.168.2.3;192.168.2.4
RADIUS_Port=1811;1812;1813;1814
RADIUS_Key=ralink_1;ralink_2;ralink_3;ralink_4
or
RADIUS_Key1=ralink_1
RADIUS_Key2=ralink_2
RADIUS_Key3=ralink_3
RADIUS_Key4=ralink_4
For backward compatible, driver would parse "RADIUS_Key" or "RADIUS_KeyX"(X=1~4) for radius key usage.
But the paramter "RADIUS_Key" has the first priority.
p.s. This implies the RADIUS server IP of ra0 is 192.168.2.1, its port is 1811 and its secret key is ralink_1.
The RADIUS server IP of ra1 is 192.168.2.2, its port is 1812 and its secret key is ralink_2.
The RADIUS server IP of ra2 is 192.168.2.3, its port is 1813 and its secret key is ralink_3.
The RADIUS server IP of ra3 is 192.168.2.4, its port is 1814 and its secret key is ralink_4.
VII. 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 RT2860AP.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 RT2860AP.dat to decide whether the broadcast key is generated
randomly or not, so please update the RT2860AP.dat and restart rtdot1xd if those correlative parameters are changed.
