aboutsummaryrefslogtreecommitdiffstats
path: root/README
diff options
context:
space:
mode:
authorJouni Malinen <j@w1.fi>2003-05-19 03:02:13 (GMT)
committerJouni Malinen <j@w1.fi>2003-05-19 03:02:13 (GMT)
commit15373557432ac422d45d1deee261a898c03dafba (patch)
treeca6033774a5ae00497d5017ef86b709bf754b41e /README
parentae839be2204d3b92dc4ed517f3b9e88582ca1092 (diff)
downloadhostap-history-15373557432ac422d45d1deee261a898c03dafba.zip
hostap-history-15373557432ac422d45d1deee261a898c03dafba.tar.gz
hostap-history-15373557432ac422d45d1deee261a898c03dafba.tar.bz2
Combined README and README.prism2.
Diffstat (limited to 'README')
-rw-r--r--README863
1 files changed, 859 insertions, 4 deletions
diff --git a/README b/README
index abfdbeb..59a269b 100644
--- a/README
+++ b/README
@@ -11,11 +11,101 @@ published by the Free Software Foundation. See COPYING for more
details.
-Released versions of the driver and CVS repository for latest testing
-versions is available at http://hostap.epitest.fi/.
+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 whenever 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.
-Please read README.prism2 for further information about the Host AP
-driver.
+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.
+
+
+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.
Driver installation
@@ -80,3 +170,768 @@ run as non-root user). After the compilation has finished, you can
install hostap_pci.o by running 'make install_pci' (as root). You can
probe PCI bus for Prism2.5 PCI cards and initialize the devices by loading
the module ('modprobe hostap_pci.o').
+
+
+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)
+ 3: disable port 0
+ 4: 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 that are two bytes long; you may need
+ to specify RID and value in decimal format (i.e. 64512, not 0xFC00)
+
+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)
+ 2 = AVS monitor header + 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'
+ 4 = use standard compliant WDS (4 addr) frame also in Host AP
+ mode (Note! This requires STA f/w ver 1.5.x or newer)
+ hostscan: perform non-destructive AP scanning (i.e., maintain current
+ association state); this requires STA f/w ver 1.3.1 or newer
+ 1 = send Probe Request at 1 Mbps
+ 2 = send Probe Request at 2 Mbps
+ 3 = send Probe Request at 5.5 Mbps
+ 4 = send Probe Request at 11 Mbps
+ ap_scan: interval (in seconds) between passive AP scans on different
+ channels, 0 = disabled (default)
+ enh_sec: "enhanced security" bitfield
+ 0 = options disabled (default)
+ 1 = hide SSID in beacon frames
+ 2 = ignore clients configured with "ANY" (broadcast) SSID
+ (3 = both options)
+ Note! This requires STA f/w ver 1.6.3 or newer
+ basic_rates: basic transmit rate bitmap
+ bit 0: 1 M, bit 1: 2 M, bit 2: 5.5 M, bit 3: 11 M
+ (default 3: 1 and 2 Mbps)
+ oper_rates: operational transmit rate bitmap
+ bit 0: 1 M, bit 1: 2 M, bit 2: 5.5 M, bit 3: 11 M
+ (default 15: 1, 2, 5.5, and 11 Mbps)
+ Note! This changes the same value as iwconfig rate command, but
+ as a bitfield.
+ hostapd: hostapd mode configuration
+ 0 = use kernel driver for IEEE 802.11 management
+ 1 = use user space daemon, hostapd, for IEEE 802.11 management
+
+
+ Following parameters are for debug use only;
+ do not use unless you are sure what you are doing!
+
+ ptype: port type (0=IBSS, 1=BSS, 2=WDS, 3=PseudoIBSS, 6=HostAP)
+ alc: 0=disabled ALC, 1=enable ALC (automatic level control)
+ 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.
+
+Due to this non-standard frame format, the driver with a card using
+station firmware older than v1.5.0 does not interoperate with
+standard-compliant AP devices as far as WDS connections are concerned.
+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.
+
+Note!
+-----
+
+The latest firmware versions (STA firmware version 1.5.0 or newer)
+have fixed this bug. The driver can use standard-compliant 4-address
+frames with these firmware versions. Please upgrade your card firmware
+if you want to use IEEE 802.11 compliant WDS frames with the
+driver. Current driver code selects automatically which format to use
+based on the firmware version on the card.
+
+
+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. This can be build with following commands:
+
+cd hostapd
+make
+
+The user space daemon has its own configuration file that can be used to
+define AP options. Distribution package contains an example
+configuration file (hostapd/hostapd.conf) that can be used as a basis
+for configuration. It includes examples of all supported configuration
+options and short description of each option. hostapd should be started
+with full path to the configuration file as the command line argument,
+e.g., './hostapd /etc/hostapd.conf'.
+
+hostapd includes a minimal co-located IEEE 802.1X server which can be
+used to test IEEE 802.1X authentication. However, it should not be
+used in normal use since it does not provide any security. This can be
+configured by setting ieee8021x and minimal_eap options in the
+configuration file.
+
+An external Authentication Server (RADIUS) is configured with
+auth_server_{addr,port,shared_secret} options. In addition,
+ieee8021x and own_ip_addr must be set for this mode. With such
+configuration, the co-located Authentication Server is not used and EAP
+frames will be 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 wep_key_len_broadcast
+option (5 for 40-bit WEP or 13 for 104-bit WEP). In addition,
+wep_key_len_unicast option can be used to configure individual unicast
+keys for stations. This requires support for individual keys in the
+station driver.
+
+WEP keys can be automatically updated by configuring rekeying. This
+will improve security of the network since same WEP key will only be
+used for a limited period of time. wep_rekey_period option sets the
+interval for rekeying in seconds.