Host AP driver for Intersil Prism2/2.5/3	(DEVELOPMENT VERSION!)
========================================

Copyright (c) 2001-2002, SSH Communications Security Corp and Jouni Malinen
Author: 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.


Note!
This development version is mainly for research use; it has not
been thoroughly tested and may contain various bugs. This is not for
production use and use of this driver may require thorough knowledge
of IEEE 802.11, pcmcia-cs, Linux, etc.

Any comments, reports on success/failure, ideas for further
improvement, feature requests, etc. are welcome at jkmaline@cc.hut.fi.
Please note, that I may not always have time for replying emails
quickly, but I'll try to go through my mail when ever time permits.
There is also a mailing list for Host AP related messages. Since this
list has a broader audience, you might even get an answer.. Anyway,
this list is recommended for general questions about Host AP driver
and its development. In addition, I will send release notes to it
whenever a new version is available.

The mailing list information and web archive is at
http://lists.shmoo.com/mailman/listinfo/hostap. Messages to
hostap@shmoo.com will be delivered to the subscribers. Please note, that
due to large number of spam and virus messages sent to the list address,
the list is configured to automatically accept messages only from
subscribed addresses.<p>


Introduction
============

This is a Linux driver for wireless LAN cards based on Intersil's
Prism2/2.5 chipset. The driver supports a so called Host AP mode, i.e.,
it takes care of IEEE 802.11 management functions in the host computer
and acts as an access point. This does not require any special
firmware for the wireless LAN card. In addition to this, it has some
support for normal station operations in BSS and possible also in
IBSS. However, the orinoco_cs driver in current 2.4 kernel tree or
pcmcia-cs package or linux-wlan-ng is probably better supported
solution for cases that do not use Host AP mode.

Intersil's station firmware for Prism2/2.5 chipset supports a so called
Host AP mode in which the firmware takes care of time critical tasks
like beacon sending and frame acknowledging, but leaves other
management tasks to host computer driver. This driver implements basic
functionality needed to initialize and configure Prism2/2.5-based cards,
to send and receive frames, and to gather statistics. In addition, it
includes an implementation of following IEEE 802.11 functions:
authentication (and deauthentication), association (reassociation, and
disassociation), data transmission between two wireless stations,
power saving (PS) mode signaling and frame buffering for PS
stations. The driver has also various features for development
debugging and for researching IEEE 802.11 environments like access to
hardware configuration records, I/O registers, and frames with 802.11
headers.


Supported environment
=====================

Hardware
--------

The driver supports IEEE 802.11 wireless LAN PC Cards that are based
on Intersil's Prism2 or Prism2.5 chipsets (especially, MAC processors
HFA3841 or HFA3842 for Prism2 and ISL3874 for Prism2.5). Native PCI
cards using Prism2.5 are also supported, but USB cards based on
Prism2.5 chipset are not supported in this version.

This version has been successfully tested with number of different
models, e.g., Compaq WL100 and WL200, D-Link DWL-650, and Linksys
WPC11, but there may still be issues with some models.

If you happen to have a wireless LAN card that is based on Prism2, but
does not seem to work with this driver, please let me know the model
and I can try to come up with a solution for any problems. This will
be easier if I have access to the non-functioning card model, but I
might also be able to solve some cases based on debug logs and other
easily collectible information.

In addition to Intersil's Prism2/2.5 chipsets, this driver may partly
support other chipsets. As far as I know, other chipsets do not have
Host AP mode, so this is not supported, but managed mode (i.e., being
a station in a BSS) seems to work with Prism1 (e.g., Intel, 3Com, and
Symbol cards) and Lucent WaveLAN. I would like to add support for AP
functionality also with these cards, but I'm not sure whether it can
be done without special firmware. Please let me know, if you have
further information about this.

The driver should be portable to different host CPUs. I have tested it
on ix86 and PowerPC platforms. In addition, I have received reports of
it working on Alpha and Arm.

Software
--------

This driver is developed in Linux 2.4.x environment, but it may also
work with Linux 2.2.x kernels (I have tested it few times with 2.2.x
kernel successfully, but I'm not really used those kernel versions
anymore so there may be some compatibility problems). Linux 2.5.x
should also work, but all versions might not be tested with it.

PCI (hostap_pci.o) and PLX9052 (hostap_plx.o) versions require at
least Linux kernel version 2.4.x for their PCI initialization
routines.


Installation and configuration
==============================

See README file for driver compilation and installation instructions
(PC Card systems using kernel tree PCMCIA modules or external pcmcia-cs
package, PC Cards in PLX9052-based adapters, and Prism2.5 PCI cards).

If you are using hostap_cs.o version, pcmcia-cs needs to know which
driver to use for each PC Card. This driver has its own file
(/etc/pcmcia/hostap_cs.conf) that lists few PC Cards that are
supported. It does not include every Prism2/2.5-based card, so you may
need to add your model to hostap_cs.conf in order to get the driver
started. If you add new model information to the configuration file
and the card works with this driver, please send me the output of
'cardctl ident' and the lines you added so that I can include them
in the next release.

If you are using hostap_plx.o version, prism2_plx_known_manfids table
in driver/modules/hostap_plx.c needs to have an entry for the PC Card
you are using. Module parametered 'ignore_cis' can used to skip manfid
verifications for testing any card (please note, that this will try to
initialize any PC Card in PLX adapter as Prism2). If you have a card
that works with the driver after adding its manfid to the table,
please let me know the card manufacturer, model, and the manfid
numbers so that I can include them in the next release of the driver.

The driver supports Linux Wireless Extensions and certain configuration
items can be viewed and changed with iwconfig(8) and iwpriv(8) from
wireless utilities, e.g., mode (AP/station; iwconfig's 'mode'),
channel (iwconfig's 'freq' or 'channel'), WEP (encryption; iwconfig's
'key').

TODO: list example iwconfig commands and explain what they do

Current driver supports following iwpriv commands:

iwpriv wlan0 monitor <val>		[DEPRECATED]
	see 'IEEE 802.11 monitoring' below

iwpriv wlan0 prism2_param <param> <val>
	see prism2_param wrapper below

iwpriv wlan0 readmif <2*CR>
iwpriv wlan0 writemif <2*CR> <val>
	testing commands that allow low-level access to baseband processor
	configuration registers; do *NOT* use these, unless you are sure what
	you are doing; these do not have error checking and it may be
	possible to cause physical damage to your equipment by setting invalid
	values

iwpriv wlan0 reset <val>
	0: perform soft reset of the card
	1: perform COR sreset (almost hardreset ;-)
	2: perform port reset (disable and enable port 0)

iwpriv wlan0 inquire <val>
	use inquire command; debugging only

iwpriv wlan0 wds_add <mac addr>
iwpriv wlan0 wds_del <mac addr>
	add/remove WDS links (see WDS below)

iwpriv wlan0 set_rid_word <rid> <value>
	debug command for setting RIDs

iwpriv wlan0 maccmd <val>
	0: open policy for ACL (default)
	1: allow policy for ACL
	2: deny policy for ACL
	3: flush MAC access control list
	4: kick all authenticated stations

iwpriv wlan0 addmac <mac addr>
	add mac addr into access control list

iwpriv wlan0 delmac <mac addr>
	remove mac addr from access control list

iwpriv wlan0 kickmac <mac addr>
	kick authenticated station from AP

The distribution package includes a wrapper for 'iwpriv wlan0
prism2_param <param> <val>' command. This wrapper is a shell script,
utils/prism2_param, that translates parameter names from text format
into a integer value used in the real iwpriv command.

Usage: prism2_param <interface> <parameter> [value]

Wrapper for setting hostap_{cs,plx,pci}.o parameters using iwpriv and
prism2_param ioctl. This wrapper converts the given text parameter
(see list below) to corresponding prism2_param ioctl() value and uses
iwpriv to set the given value.

If value argument is not given, the current value is shown (if available).

interface:
	interface name for the wireless LAN device to be used (e.g., wlan0)

parameter:
	txratectrl:
		0 = use host driver based TX rate control (default),
		1 = use f/w based TX rate control
	beacon_int: beacon interval (1 = 1024 usec)
	dtim_period: DTIM period, i.e., number of beacon intervals between
		successive delivery traffic identification maps (DTIMs),
		used for power saving and multicast/broadcast delivery
	pseudo_ibss:
		0 = use IEEE 802.11 IBSS mode (default),
		1 = use pseudo adhoc mode (no management frames)
	other_ap_policy:
		0 = skip all beacons
		1 = accept beacons with our SSID
		2 = accept beacons from all APs
		3 = accept all beacons (even from IBSS)
	dump: set RX/TX/TXEXC debug dump header bitfield
		0 = do not dump frame headers
		1 = dump RX frame headers
		2 = dump TX frame headers
		4 = dump TX error frame headers
		(these values can be bitwise ORed; e.g. 3 = both RX and TX)
	ap_max_inactivity: Time (in seconds) after which inactive stations
		can be removed from AP's station list
	ap_bridge_packets:
		0 = do not bridge packets between associated stations, i.e.,
			just pass them to upper layers for handling
		1 = bridge packets directly between associated stations, i.e.,
			upper layers do not even see these packets
	ap_nullfunc_ack:
		0 = let station firmware take care of data::nullfunc ACKs
		1 = send "extra" ACKs for data::nullfunc frames to workaround
			problems with stations using PS mode
		(default 1 if STA f/w version is 0.8.0, otherwise 0)
	max_wds: maximum number of allowed WDS connections (default 16)
	autom_ap_wds:
		0 = add WDS connections manually
		1 = add WDS connections automatically to all recorded APs
			(based on other_ap_policy)
	ap_auth_algs: allowed authentication algorithms
		0 = none (no authentication will succeed)
		1 = only open
		2 = only shared key
		3 = open or shared key (default)
	monitor_allow_fcserr:
		0 = drop frames with FCS errors in monitor mode
		1 = pass also frames with FCS errors
	host_encrypt:
		0 = do not use host encryption unless in Host AP mode
		1 = use host encryption in all modes
	host_decrypt:
		0 = use WLAN card firmware to decrypt frames
		1 = use host driver to decrypt frames
	bus_master_threshold_rx:
		packet length threshold for using PCI bus master on RX
		(only used with hostap_pci.o and if PRISM2_BUS_MASTER is set)
	bus_master_threshold_tx:
		packet length threshold for using PCI bus master on TX
		(only used with hostap_pci.o and if PRISM2_BUS_MASTER is set)
	host_roaming:
		0 = use station firmware for roaming decision (default)
		1 = use host driver roaming decision
	bcrx_sta_key:
		0 = use station specific key (WEP key mapping) to override
		    default keys only for RX frames sent to unicast address
		    ("individual RA") (default)
		1 = use station specific key also with broadcast RX frames
		    (this is against IEEE 802.11, but makes it easier to use
		    different keys with stations that do not support WEP key
		    mapping)
	ieee_802_1x:
		0 = do not use IEEE 802.1X specific functionality (default)
		1 = use IEEE 802.1X: require 802.1X auth, filter EAPOL packets
	antsel_tx:
		0 = do not touch TX AntSel, i.e., use card default (default)
		1 = use antenna diversity
		2 = force TX AntSel pin low
		3 = force TX AntSel pin high
	antsel_rx:
		0 = do not touch RX AntSel, i.e., use card default (default)
		1 = use antenna diversity
		2 = force RX AntSel pin low
		3 = force RX AntSel pin high
	monitor_type:
		0 = IEEE 802.11 headers (ARPHRD_IEEE80211)
		1 = Prism2 + IEEE 802.11 headers (ARPHRD_IEEE80211_PRISM)
	wds_type: WDS type bitfield
		0 = options disabled (default)
		1 = use broadcast RA (WDS frame destination) for broadcast and
			multicast frames
		2 = use AP client mode in 'Managed mode'

	Following parameters are for debug use only;
	do not use unless you are sure what you are doing!

	ptype: port type
	alc: 0=disabled ALC, 1=enable ALC
	txpower: TX power (normally, 'iwconfig wlan# txpower <arg>' is used)


Bridging between wireless and wired networks
============================================

Prism2/2.5 AP driver controls a wireless device (wlan#), but does not
take care of bridging between wireless and wired networks. If this AP
feature is required, it has to be implemented using an external
software.

Linux kernels support Ethernet bridging (code already present in 2.4.x
kernels and also as a separate patch for 2.2.x kernels). This can be
used to easily build an AP between the wired and wireless
networks. Below is an example of a simple setup in which the AP has
one Ethernet interface and one wireless interface. If needed, see
http://bridge.sourceforge.net/ for more information on Linux kernel's
Ethernet bridging.

Example:

(after loading Prism2/2.5 AP driver)

brctl addbr br0
brctl addif br0 eth0
brctl addif br0 wlan0
ifconfig eth0 0.0.0.0
ifconfig wlan0 0.0.0.0
ifconfig br0 192.168.100.200 up

(the AP bridges packets between Ethernet and wireless LAN and can be
reached with IP address 192.168.100.200 from either network; stations
associated to this AP can then communicate with other wireless LAN
stations and with the hosts in the wired network)


Wireless distribution system (WDS)
==================================

IEEE 802.11 specifies a method for using wireless connection as a
distribution system. A special data frame with four addresses is
defined for this. This allows layer 2 bridging of packets (two
addresses, the immediate sender and receiver, are required for 802.11
frame acknowledgement; the other two addresses are the original
sending and receiver of the frame).

There is a bug in station firmware code used in Prism2/2.5 cards that
prevents standard-compliant 4-address frames being sent in Host AP
mode. To overcome this problem, the current version of the driver uses
a non-standard frame format, in which the 802.11 header has first
three addresses and the fourth address (which is usually also in the
header) is sent after the frame payload.

Note!
-----

Due to this non-standard frame format, this version of the driver does
not interoperate with standard-compliant AP devices as far as WDS
connections are concerned. The driver includes commented out code for
sending standard-compliant frames, should a fixed station firmware
become available for Prism2/2.5 cards.

The non-standard frame format should be identical to the one used in
OpenAP project (http://opensource.instant802.com/), so APs using their
code should interoperate (although this has not yet been tested).


Example WDS configuration:

- bridging between two wired network using a wireless link
- additional wireless net included in the bridge setup

Note! It should be needless to say, but this kind of bridging of wired
networks introduces serious security problems due to open nature of
the wireless network. This is just a simple example of what could be
done with bridging code and WDS links. Connections should be encrypted
in real networks, e.g., with IPSec, to prevent packets from being
captured of injected into the network.


Network 192.168.1.0/24  (same address space in each network)

<wired net A>--eth0 : AP-A : wlan0 -- <wireless net A>
                               |
                              WDS
                               |
                             wlan0 : AP-B : eth0--<wired net B>

Each AP has eth0 as the wired network device and Host AP driver loaded
and wlan0 as the wireless device.

AP-A: wireless LAN card with hwaddr 00:11:11:11:11:11, IP addr 192.168.1.1
AP-B: wireless LAN card with hwaddr 00:22:22:22:22:22, IP addr 192.168.1.2


AP-A configuration:

iwpriv wlan0 wds_add 00:22:22:22:22:22
brctl addbr br0
brctl addif br0 eth0
brctl addif br0 wlan0
brctl addif br0 wlan0wds0
ifconfig eth0 0.0.0.0
ifconfig wlan0 0.0.0.0
ifconfig wlan0wds0 0.0.0.0
ifconfig br0 192.168.1.1 up

AP-B configuration:

iwpriv wlan0 wds_add 00:11:11:11:11:11
brctl addbr br0
brctl addif br0 eth0
brctl addif br0 wlan0wds0
ifconfig eth0 0.0.0.0
ifconfig wlan0wds0 0.0.0.0
ifconfig br0 192.168.1.2 up

(AP-B's wlan0 interface is not used in this example; all wireless
traffic goes through WDS link to AP-A using wlan0wds0)


'brctl show' should show br0 bridge with the added interfaces and STP
enabled.

'brctl showstp br0' should show more statistics about each bridge
port. 'state' should first be few seconds 'learning' and then change
to 'forwarding'.

'brctl showmacs br0' can be used to check behind which bridge port
each known mac addr is currently.

With this example configuration, the users of the network can be in
any of the three listed network. They can even move their computer to
another network and the bridging code will eventually (it seemed to
take about 30 seconds in my test; this can probably be adjusted with
bridge parameters) learn about the move. The bridging is performed on
layer 2, so other hosts in the 192.168.1.0/24 network look like they
were in the same physical network, no matter in which part of the
bridged network (wired net A, wired net B, wireless net A) they are.


Monitoring other APs
====================

Host AP driver can be instructed to monitor beacon frames from other
APs (other_ap_policy parameter). In addition, WDS code can be setup to
automatically add new WDS links to all detected APs to ease bridge
setup with STP.

prism2_param wlan0 autom_ap_wds 1
prism2_param wlan0 other_ap_policy 1

WDS connections can be added with 'iwpriv wlan# wds_add <other end
hwaddr>' and removed with similar wds_del command. hwaddr
00:00:00:00:00:00 can be used as a special address to pre-allocate
netdevices. These entries are used when adding the real WDS link,
e.g., when a new AP is detected. Pre-allocated devices can be included
in a bridging configuration and set into UP state before knowing the
real AP address.

In other words, you would need to run 'iwpriv wlan0 wds_add
00:00:00:00:00:00' N times after loading the driver and then add
interfaces wlan0wds0 to wlan0wds<N-1> into bridge configuration. When
new APs are detected after this, they will be assigned a pre-allocated
interface that is already part of the bridge setup.

Another option would be to make an external program for monitoring new
WDS links (e.g., from /proc/net/hostap/wlan#/wds) and automatically
add them to the bridge setup with brctl.


Driver status and debug information
===================================

/proc/net/hostap/wlan#
	##:##:##:##:##:## for each authenticated station
		STA/AP information, TX/RX statistics, etc.

	ap_control
		Access control list for station authentication

	ap_debug
		AP debugging information (wireless bridging statistics)

	debug
		driver debugging information (TX queue)

	registers
		Prism2/2.5 MAC register contents (for development use)

	rids
		Prism2/2.5 MAC configuration/statistics registers
		(mainly for development use)

	stats
		TX/RX statistics

	unknown_rids
		Unidentified Prism2/2.5 MAC configuration/statistics
		registers (mainly for development use)

	wds
		List of configured WDS links (netdevice, remote hwaddr)


kernel messages (dmesg/syslog)
	The driver send debugging information to kernel log. The last
	entries from the kernel ring buffer can be viewed with
	dmesg(8) and the log entries can also be recorded with
	syslogd(8).


IEEE 802.11 monitoring
======================

Prism2/2.5/3 cards have a test mode that can be used for monitoring wireless
networks. In this mode the driver receives all raw IEEE 802.11 frames
(including management frames).

Monitor mode is enabled with 'iwconfig wlan0 mode monitor'. Monitor
mode was added to wireless tools version 25. With later versions, you
cannot use iwconfig, so please either upgrade wireless tools or use
old iwpriv monitor method described below.

'prism2_param wlan0 monitor_type <val>' can be used to select which
headers are included in the monitored frames (0: IEEE 802.11,
1: Prism2 + IEEE 802.11).

Previously, monitoring mode was started using iwpriv(8). This is now
deprecated and it is currently implemented as a backward compatibility
wrapper for iwconfig mode command. It may be removed in the future
versions of the driver.

iwpriv wlan0 monitor 2
	start monitor mode and send received frames (including 802.11 header)
	to user space using normal netdevice. This changes the device type
	to ARPHRD_IEEE80211 so that user space programs know how to handle
	different header type.
iwpriv wlan0 monitor 3
	start monitor mode and send received frames (including Prism2 RX data
	and 802.11 header) to user space using normal netdevice. This changes
	the device type to ARPHRD_IEEE80211_PRISM so that user space programs
	know how to handle different header type.

iwpriv wlan0 monitor 0
	disable monitor mode and return to Host AP mode


Example program in 'sniff', wlansniff.c, is a simple 802.11 frame
parser that shows both the Prism2/2.5-specific data from the RX frame
and parsed contents of the 802.11 frame.

Latest versions of libpcap and Ethereal support ARPHRD_IEEE80211 and
ARPHRD_IEEE80211_PRISM, so monitor modes 2 and 3 can be used with them
for real time IEEE 802.11 network monitoring.


Access control list (ACL) for stations
======================================

Default configuration of the AP allows any station to authenticate and
associate (open policy). This behavior can be changed with ACL
configuration.

ACL is based on MAC address of the station. New addresses can be added with
'addmac' command (iwpriv) and policy can be changed with 'maccmd'.

Examples:

# allow policy
iwpriv wlan0 maccmd 1
iwpriv wlan0 addmac 00:11:22:33:44:55
iwpriv wlan0 addmac 00:12:34:56:78:9a

Allow only stations 00:11:22:33:44:55 and 00:12:34:56:78:9a to
authenticate with the AP.


# deny policy
iwpriv wlan0 maccmd 2
iwpriv wlan0 addmac 00:11:22:33:44:55
iwpriv wlan0 addmac 00:12:34:56:78:9a

Deny authentication from stations 00:11:22:33:44:55 and
00:12:34:56:78:9a, but allow every other station to authenticate.


# open policy
iwpriv wlan0 maccmd 0

Allow any station to authenticate (regardless of ACL contents).


Encryption
==========

Host AP driver supports both firmware and host driver based encryption.
Firmware based encryption has some limitations--it has a bug in Host AP mode
that breaks TX frames when using WEP, it does not support other encryption
algorithms than WEP, it does not yet support WEP key mappings with individual
keys for different stations. These limitations can be overcome by using host
based encryption.

Host AP driver uses modularized encryption implementation that allows
the encryption code be shared by different hardware versions of the
driver (hostap_{cs,plx,pci}.o). In addition, this design allows one to
load new algorithms dynamically if needed. WEP implementation
(driver/modules/hostap_crypt_wep.c) can be used as an example
implementation when adding support for other algorithms.

Generic encryption algorithm handler module, hostap_crypt.o, will be
automatically loaded when driver is loaded (assuming module
dependencies are set with depmod; otherwise, it will need to be loaded
manually). WEP implementation, hostap_crypt_wep.o, is not loaded
automatically during initialization, but driver tries to load it with
kmod when WEP is configured. If this does not work, the module needs
to be loaded either with modprobe/insmod after having loaded driver
module or by configuring /etc/modules.conf or pcmcia-cs configuration
to load it when using Host AP driver.

When using WEP, default encryption keys can be set using 'key' command
of iwconfig(8) from Wireless Tools. All other setups (key mapping with
individual keys or other algorithms) must use separate tool,
utils/hostap_crypt_conf (that can be compiled by running 'make' in
'util' subdirectory). hostap_crypt_conf takes following options:

Usage: hostap_crypt_conf [-1]..[-9] [-t] [-p] <device> <addr> <alg> [key]
Options:
  -1 .. -9   key index (for WEP); only one index per command
  -t         set TX key index (given with -1 .. -9)
  -p         permanent station configuration (do not expire data)
  device     wlan#
  addr       station hwaddr or ff:ff:ff:ff:ff:ff for default/broadcast key
  alg        crypt algorithm (WEP, NULL, none)
  key        key data (in hex, e.g. '0011223344', or s:string)

Algorithms:
  WEP        40 or 104 bit WEP
  NULL       NULL encryption (i.e., do not encrypt/decrypt);
             used to configure no encryption for given
             station when using default encryption
  none       disable encryption


IEEE 802.11 (Chap. 8.3.2) specifies that dot11WEPKeyMappings uses only
one key per station address (whereas dot11WEDefaultKeys has four), but
Host AP uses a more general implementation that allows four keys even
with individual keys. However, to remain compliant with the standard,
it is recommended to use only the first key with station-specific key
mapping. In addition, it might be useful to configure default TX key
to be something else than the first key to allow individual keys to be
used even with stations that not explicitly support WEP key mapping.

Examples:

AP configuration
----------------

# use station specific key also with broadcast RX frames to support
# different keys with stations that do not use WEP key mapping;
# if the stations allow configuration of separate key for broadcast/multicast
# bcrx_sta_key should be left to 0 (default)

prism2_param wlan0 bcrx_sta_key 1

# set key2 as the default key (used with broadcast/multicast frames
# and with stations for which there is no individual key mapping)
hostap_crypt_conf -2t wlan0 ff:ff:ff:ff:ff:ff WEP s:abcde

# or with iwconfig:
iwconfig wlan0 key s:abcde [2]
iwconfig wlan0 key [2]

# set a permanent key mapping for STA2 (hwaddr=00:11:22:33:44:55)
hostap_crypt_conf -p wlan0 00:11:22:33:44:55 WEP s:qwert

STA1 configuration
------------------

# use only the default key (i.e., no key mapping)
iwconfig wlan0 key s:abcde [2]
iwconfig wlan0 key [2]

STA2 configuration (hwaddr=00:11:22:33:44:55)
------------------

# configure default key (idx 2) so that the station knows how to
# decrypt broadcast/multicast frames
iwconfig wlan0 key s:abcde [2]

# configure individual key (idx 1) that will be used to decrypt unicast
# frames from the AP and to encrypt all frames to the AP
iwconfig wlan0 key s:qwert [1]
iwconfig wlan0 key [1]


IEEE 802.1X
===========

IEEE Std 802.1X-2001 is a standard for port-based network access
control. In case of IEEE 802.11 networks, a "virtual port" is used
between each associated station and the AP. IEEE 802.11 specifies
minimal authentication mechanism for stations, whereas IEEE 802.1X
introduces a extensible mechanism for authenticating and authorizing
users.

IEEE 802.1X uses elements called Supplicant, Authenticator, Port
Access Entity, and Authentication Server. Supplicant is a component in
a station and it performs the authentication with the Authentication
Server. An access point includes Authenticator that relies the packets
between Supplicant and Authentication Server. In addition, it has a
Port Access Entity (PAE) with Authenticator functionality for
controlling the virtual port authorization, i.e., whether to accept
packets from or to the station.

IEEE 802.1X uses Extensible Authentication Protocol (EAP). The frames
between Supplicant and Authenticator are sent using EAP over LAN
(EAPOL) and Authenticator relays these frames to the Authenticatation
Server (and similarily, relayes the messages from Authentication
Server to the Supplicant). Authention Server can be colocated with the
Authenticator, in which case there is no need for additional protocol
for EAP frame transmission. However, more common configuration is to
use an external Authentication Server and encapsulate EAP frame in the
frames used by that server. RADIUS is suitable for this, but IEEE
802.1X would allow also other mechanisms.

Host AP driver includes a PAE functionality in the kernel driver. It
is a relatively simple mechanism for denying normal frames going to
are coming from an unauthorized port. PAE allows IEEE 802.1X related
frames to be passed between the Supplicant and the Authenticator even
on an unauthorized port.

User space daemon, hostapd, includes Authenticator functionality. It
receives 802.1X (EAPOL) frames from the Supplicant using the wlan#ap
device that is also used with IEEE 802.11 management frames. The
frames to the Supplicant are sent using the same device.

hostapd includes a minimal colocated Authentication Server for testing
purposes. It only requests the identity of the Supplicant and
authorizes any host that is able to send valid EAP Response
frame. This can be used for quick testing since it does not require an
external Authentication Server, but it should not be used for any real
authentication purposes since no keys are required and anyone can
authenticate.

The normal configuration of the Authenticator would use an external
Authentication Server. hostapd supports RADIUS encapsulation of EAP
packets, so the Authention Server should be a RADIUS server, like
FreeRADIUS (http://www.freeradius.org/). The Authenticator in hostapd
relays the frames between the Supplicant and the Authentication
Server. It also controls the PAE functionality in the kernel driver by
authorizing and unauthorizing virtual ports, i.e., station-AP
connection, based on the IEEE 802.1X state.

When a station would like to use the services of an access point, it
will first perform IEEE 802.11 authentication. This is normally done
with open systems authentication, so there is it provides no
security. After this, IEEE 802.11 association is performed. If IEEE
802.1X is configured to be used, the virtual port for the station is
set in Unauthorized state and only IEEE 802.1X frames are accepted at
this point. The Authenticator will then ask the Supplicant to
authenticate with the Authentication Server. After this is completed
successfully, the virtual port is set to Authorized state and frames
from and to the station are accepted.

Host AP configuration for IEEE 802.1X
-------------------------------------

Host AP driver includes and Authenticator implementation in the user
space daemon. When using this Authenticator, the driver needs to be
compiled for user space management functionality, i.e., with
PRISM2_HOSTAPD defined. This is not the default option, so an
additional configuration is needed. This can be added by editing
driver/modules/hostap_config.h, or more easily by using EXTRA_CFLAGS
definition:

make pccard EXTRA_CFLAGS="-DPRISM2_HOSTAPD"

After this, the kernel driver should be installed and the kernel
modules loaded to initialize the wireless LAN card. In addition, the
user space daemon needs to be build:

cd hostapd
make

Assuming that the kernel driver used wlan0 as the device name, the
user space daemon can be started with './hostapd wlan0' for
functionality _without_ IEEE 802.1X, i.e., only to perform IEEE 802.11
authentication and association. IEEE 802.1X with the co-located
minimal authentication server can be tested with './hostapd -xm
wlan0'.

With IEEE 802.1X, any station supporting IEEE 802.1X Supplicant should
be able to authenticate using the co-located authentication server. In
other words, stations that do not support IEEE 802.1X should not be
able to send data frames through this AP, even though they can perform
IEEE 802.11 authentication and association whereas stations with IEEE
802.1X Supplicant cab get the virtual port authorized and after this
exchange data frames with the AP.

An external Authentication Server (RADIUS) is configured with
following command line options './hostapd -x -o<AP IP addr> -a<RADIUS
server IP addr> -s<shared secret AP-auth.serv.> wlan0'. In this case,
the co-located Authentication Server is not used and the EAP frames
are relayed using EAPOL between the Supplicant and the Authenticator
and RADIUS encapsulation between the Authenticator and the
Authentication Server. Other than this, the functionality is similar
to the case with the co-located Authentication Server.

Authentication Server and Supplicant
------------------------------------

Any RADIUS server supporting EAP should be usable as an IEEE 802.1X
Authentication Server with hostapd Authenticator. FreeRADIUS
(http://www.freeradius.org/) has been successfully tested with hostapd
Authenticator and both Xsupplicant (http://www.open1x.org) and Windows
XP Supplicants. EAP/TLS was used with Xsupplicant and
EAP/MD5-Challenge with Windows XP.

http://www.missl.cs.umd.edu/wireless/eaptls/ has useful information
about using EAP/TLS with FreeRADIUS and Xsupplicant (just replace
Cisco access point with Host AP driver, hostapd daemon, and a Prism2
card ;-). http://www.freeradius.org/doc/EAP-MD5.html has information
about using EAP/MD5 with FreeRADIUS, including instructions for WinXP
configuration. http://www.denobula.com/EAPTLS.pdf has a HOWTO on
EAP/TLS use with WinXP Supplicant.

Automatic WEP key configuration
-------------------------------

EAP/TLS generates a session key that can be used to send WEP keys from
an AP to authenticated stations. The Authenticator in hostapd can be
configured to automatically select a random default/broadcast key
(shared by all authenticated stations) with -b5 (40-bit WEP) or -b13
(104-bit WEP). In addition, -i5 or -i13 option can be used to
configure individual unicast keys for stations. This requires support
for individual keys in the station driver.
