Jason's Web Thingy: Rocking on with HostAP 2002-10-12

Items of Interest

Installing and Setting up basic HostAP box

In my second wireless article, I discussed setting up both linux-wlan-ng and Prism2 Host AP. It's now been about three months and things have changed dramatically since the May release of HostAP, so it's time to renew my discussion of installation and configuration.

First, A Brief Word On Compatible 802.11b Cards

HostAP only works with Intersil's Prism{2,2.5,3} chipset for PCI, PLX, and PC Card interfaces. So, which cards come with the Prism chipset? That's a pretty good question. Due to the economics of production, what card has what chipset changes occasionally. As of this writing D-Link plans on switching to the Atmel chipset for their DWL-650 (non plus) card and LinkSys has already switched its WMP11 PCI card to a BroadCom chipset. Neither chipsets are supported by HostAP. (I know of no Linux support as of this writing for BroadCom's WiFi chipset, but if you're using a card that ships with the Atmel chipset, you might be in luck. I refer you to this page for more information.)

You can find information on various wireless cards and which chipsets they ship with at PersonalTelco's Prism2Card page or Seattle Wireless' Hardware Comparison. Keep in mind the actual chipset being used is subject to change at the vendor's discretion and it may not be obvious until after you install the card and find out it isn't a Prism card.

One last thing might aid you in your search. It's the FCC's Office of Engineering and Technology search page, where you can search through vendor's documentation and test submissions to the Federal Communications Commission (U.S.). The only catch is you need your vendor's FCC ID.

For products sold in the U.S., it will be on the device itself, but that won't help you if you don't already own one. Another solution is to search for your vendor's name under Grantee Search Report. Use the Grantee Code given in the search results to look up your vendor. From there, you'll need to identify the product that interests you by going through each entry sequentially or finding a familiar string in the FCC IDs listed in the results. The documents are all in PDF format, and may or may not contain any information about the chipset on the card. You will find other interesting things like card output power and antenna connector type, if applicable.

Things You'll Need Before Starting With 2002-10-12

First, you'll need to acquire these things:

Linux Kernel v2.4.20
Host AP driver driver v2002-10-12
Linux Wireless Extensions Tools v25 (or apt-get install wireless-tools under Debian GNU/Linux)
Wireless Extensions v15 patch
Wireless Extensions v16 patch (optional, but useful if you want to run more recent HostAP CVS)
Optionally you can install any other Wireless Extensions patches you may need, but most of these are already in 2.4.20-pre2 and above.

You'll need to apply the wireless extension v15 patch (or the other wireless extension patches of your choice in order first, then finally the v15 patch) to your shiny new 2.4.20 kernel.

On my x86 box, at least, 2.4.19 and 2.4.20 perform very poorly. Poorly in the sense that the machine frequently pauses and mouse and keyboard input aren't possible. As this appears to be a known issue with 2.4.19 and 2.4.20, I am recommending people that have problems with 2.4.20 to use 2.4.18 instead. You will need both the WEv13 and WEv14 patchs, which you must apply in order before WEv15 linked above, if you choose to use 2.4.18.

When you patch your kernel with WEv15, you may receive the following error:

Hunk #9 succeeded at 678 (offset -2 lines).
Hunk #10 succeeded at 697 (offset -2 lines).
Hunk #11 succeeded at 963 (offset -2 lines).
1 out of 11 hunks FAILED --
    saving rejects to file net/core/wireless.c.rej

You can safely ignore the reject error -- That hunk contains comments only. There is no code in that hunk.

When you build your new kernel, make sure you enable the Wireless Extensions! Optionally if you want to bridge a wired and wireless network, enable 802.1d Ethernet Bridging (Kernel Ethernet Bridging) in your kernel configuration.

If you are running a recent RedHat distribution, compiling HostAP may not be necessary. Aaron Baer has assembled RPMs for i386 and i686 systems with a kernel (and HostAP as a module) ready to go. The source RPM is also available for your customization needs.

A (Not So) Brief Firmware Discussion

Firmware comes up a lot with regard to host based AP mode. There are quite a few different kinds of firmware available for your card. (In some cases availability is at the discretion of your WiFi card vendor.) Firmware drives the Media Access Controller, or MAC. ( But don't confuse it with the mac address, which is a unique 48 bit number given to network interface cards to identify your card on the network and closely related to the MAC itself; Hence "mac address".)

There are at least four kinds of firmware surrounding Intersil Prism cards, including the initial, primary, secondary, and tertiary firmware. The initial firmware is bootstrap code and is used only when initially programming the adapter. The primary firmware deals with network interface card stuff, like interfacing with the system bus. It also enables you to load or upgrade other kinds of firmware. The secondary firmware deals with the Prism radio. Intersil's Prism chipset secondary firmware (often called the station firmware) is unique in that it deals with time sensitive tasks like frame acknowledgement and beacon transmission. The tertiary firmware deals with access point specific things.

The primary and secondary firmware are the most important, especially the secondary, because its handling of time sensitive tasks makes host computer based access points possible. It's also the firmware revision that will cause you the most grief if your card has a known broken secondary (or primary) firmware revision.

He's a list of secondary firmware revisions that are in the wild:

0.7.5: Known to generate INFDROP events under high load
0.8.0: Same as above
0.8.3: Known good
1.3.4: Jouni Malinen writes, "However, one should note that PRI 1.0.5 and STA 1.3.4 have some PCI bus related bugs that cause packet corruption."
1.3.5: Known good
1.3.6: Known good
1.4.2: Jouni Malinen explains, "The bug in 1.4.2 causes the card to not reply Probe Request frames in Host AP mode. However, beacon frames are sent correctly."
1.4.9: Known good -- Only version up to this point to support firmware based WEP encryption properly
1.5.6: Exists; Works and WDS mode can send standards compliant WDS frames with this STA firmware
1.6.3: Internal Intersil; Unavailable publicly to my knowledge (It is reported to work with CVS > 2003-02-01, though)
1.7.2: Unavailable, but I believe it exists.

If you use 0.8.3, 1.3.{5,6}, or 1.4.9 you should be in good shape. Intersil has secondary firmware revision 1.5.x out now, but I don't know of any cards that ship with that revision yet. If you have known bad firmware, check with your vendor to see if there's a new firmware revision available for you to flash your card with.

If your vendor can't help, you can try these as a last resort. Avishai Wool has made available a Windows LinkSys utility patched to flash LinkSys cards to revision 1.4.9. As his page says, use this at your own risk. I have not used it personally, so you're on your own. If you have one of the many other brands of cards shipping with the Prism chipset, you might try these firmware hex images hosted by NetGate. Each file includes two PDFs explaining which hex file is compatible with which card variants. The RAM based images can be loaded with a HostAP utility we'll discuss later.

Installing The Prism2 Host AP driver

Here, I will walk through installation of a PCI based Prism2 card. PLX style cards are installed in a similiar fashion, but you'll want to substitute plx for pci in the commands and output below.

First, dump the hostap-2002-10-12.tar.gz file in your favorite source directory and untar it.

Next, edit the Makefile:

# Edit this path to match with your system
# (it should point to the root
# directory of the Linux kernel source)
KERNEL_PATH=/usr/src/linux

Ensure that the KERNEL_PATH variable points to your kernel source tree.

Now, run make pci and look on as HostAP builds. After a moment that will finish and you can either run make install, or be a purist like me and copy all the *.o files from driver/modules/ to /lib/modules/`uname -r`/kernel/drivers/net. In either case, your module set ought to be these for a PCI card installation:

nebula:/usr/src/hostap-2002-10-12# ls driver/modules/*.o

driver/modules/hostap_crypt.o      driver/modules/hostap.o
driver/modules/hostap_crypt_wep.o  driver/modules/hostap_pci.o

Next, you'll need to edit your /etc/modules.conf (or /etc/modutils/aliases on Debian GNU/Linux and then run update-modules) file and add the following:

alias wlan0 hostap_pci

Lastly, run depmod -a to update your module dependancies.

The driver should produce output similar to this, when it's loaded, in your syslog:

hostap_crypt: registered algorithm 'NULL'
hostap_pci: hostap_pci.c 0.0.0 2002-10-12
  (SSH Communications Security Corp, Jouni Malinen)
hostap_pci: (c) Jouni Malinen 
PCI: Found IRQ 12 for device 00:0b.0
hostap_pci: Registered netdevice wlan0
prism2_hw_init()
prism2_hw_config: initialized in 17775 iterations
wlan0: NIC: id=0x8013 v1.0.0
wlan0: PRI: id=0x15 v1.0.7
wlan0: STA: id=0x1f v1.3.5
wlan0: defaulting to host-based encryption as a workaround for
  firmware bug in Host AP mode WEP
wlan0: LinkStatus=2 (Disconnected)
wlan0: Intersil Prism2.5 PCI: mem=0xe7000000, irq=12
wlan0: prism2_open
wlan0: LinkStatus=2 (Disconnected)

You might note the reference to host-based encryption. This applies to all firmware revisions before v1.4.9 as noted above in the firmware discussion.

Using HostAP With The Linux Wireless Extensions

The most important tool is iwconfig and its similarity with ifconfig is telling of its purpose. You'll use iwconfig to set your card's mode, channel, and essid. You'll still need to set an IP address for you card using the traditional ifconfig, though.

To get your card up and running in AP (or Master) mode, issue the following commands:

# ifconfig wlan0 192.168.0.1
# iwconfig wlan0 essid vortex
# iwconfig wlan0 channel 1
# iwconfig wlan0 mode Master

Then, take a gander at your new software based access point:

rebecca:~# iwconfig wlan0

wlan0     IEEE 802.11-b  ESSID:"vortex"
Mode:Master  Frequency:2.412GHz  Access Point: 00:06:25:A7:BB:DA
Bit Rate:11Mb/s   Tx-Power:-11 dBm   Sensitivity=1/3
Retry min limit:8   RTS thr:off   Fragment thr:off
Encryption key:off
Power Management:off
Link Quality:0  Signal level:0  Noise level:0
Rx invalid nwid:0  Rx invalid crypt:0  Rx invalid frag:0
Tx excessive retries:0  Invalid misc:0   Missed beacon:0

Most of the items are self explanatory. Link quality, signal, and noise won't show up when in Master mode.

You can also use the HostAP driver in Ad-Hoc and Managed (Infrastructure) modes, and it also excels in these modes. Here's an example Ad-Hoc command sequence and output:

# ipconfig wlan0 192.168.1.12
# iwconfig wlan0 mode Ad-Hoc
# iwconfig wlan0 essid vortex
# iwconfig wlan0 channel 11

rebecca:~# iwconfig wlan0

wlan0     IEEE 802.11-b  ESSID:"vortex"
Mode:Ad-Hoc  Frequency:2.462GHz  Cell: 02:06:07:E7:F7:DA
Bit Rate:11Mb/s   Tx-Power:-8 dBm   Sensitivity=1/3
Retry min limit:8   RTS thr:off   Fragment thr:off
Encryption key:off
Power Management:off
Link Quality:92/92  Signal level:-40 dBm  Noise level:-100 dBm
Rx invalid nwid:0  Rx invalid crypt:0  Rx invalid frag:0
Tx excessive retries:0  Invalid misc:0   Missed beacon:0

Unfortunately, I cannot discuss setting up a wireless distribution system (WDS) using Repeater mode because I don't have another Prism card I can test it with. Please read the README.prism2 file, included with your hostap tarball, for detailed information about setting up a WDS.

Enabling Basic WEP Under HostAP

Discussion of why WEP is not that secure could be the topic for an entire article. Nevertheless, WEP is another layer of protection and depending on your level of risk aversion you might be perfectly happy with the level of security it provides. That said, enabling WEP for HostAP is extremely easy and works in Ad-Hoc and Managed mode the same way as in Master mode. Stations without the correct WEP key will be able to associate, but not authenticate with the base station.

The iwconfig command with the key option is the gateway to encryption. To enable WEP, you first need to set at least one key. You can enter a key in hexadecimal of length ten for 40-bit WEP keys, or a key of length twenty-six with a dash after each four hexadecimal numbers for 104-bit WEP. For example:

# iwconfig wlan0 key 1234567890
# iwconfig wlan0 key 1234-1234-5678-5678-1234-1234-99

The above will set the specified key as the new current key. It will also enable encryption if it was previously disabled and set the encryption mode to Restricted. Refer to the output below with a 40-bit WEP key set (with the irrelevant portions removed):

rebecca:# iwconfig wlan0
wlan0     IEEE 802.11-b  ESSID:"vortex"
Mode:Master  Frequency:2.412GHz  Access Point: 00:06:25:A7:BB:DA
Encryption key:1234-5678-90   Encryption mode:restricted

If you want to add additional keys (up to a maximum of four, or the original plus three more) without altering the current key, prepend or append a numerical index ([4]) to the argument, like so:

# iwconfig wlan0 key [2] 1234-1234-5678-5678-1234-1234-12

If you want to change the current active key, specify only the key's index.

# iwconfig wlan0 key [1]

Lastly, you can enter the key as an ASCII string instead by prefixing it with "s:", as demonstrated below:

# iwconfig wlan0 key s:jasonb

40-bit WEP keys entered as strings should be five characters. 104-bit WEP keys as strings should be thirteen characters. (And when I speak of 40-bit and 104-bit I'm referring to 64-bit and 128-bit WEP respectively.) It's important to note that using strings generally gives you less entropy than using hexadecimals.

# iwconfig wlan0 key off

And, the above will disable WEP entirely.

For a nice list of current WEP options, including which of the four keys is currently being used, how many bits each key is, and the current encryption mode, we're going to call upon iwlist. Example output after setting four 104-bit WEP keys and selecting the third key as the active key is the following:

rebecca:# iwlist wlan0 key
wlan0     2 key sizes : 40, 104bits
4 keys available :
  [1]: 6161-6161-6161-6161-6161-6161-61 (104 bits)
  [2]: 6161-6161-6161-6161-6161-6161-61 (104 bits)
  [3]: 6161-6161-6161-6161-6161-6161-61 (104 bits)
  [4]: 6161-6161-6161-6161-6161-6161-61 (104 bits)
 Current Transmit Key: [3]
 Encryption mode:restricted

If you'd like access to additional WEP keying options beyond the scope of basic WEP, you'll want to play with the options hostap_crypt_conf offers, which is located in the utils/ subdirectory of your hostap directory.

Configuring Your Card To Load On Boot

Getting your card to load on start up is distribution specific. In the interest of not spreading false information, I'm only going to discuss setup for Debian Woody and beyond and not guess about the correct proceedure for RedHat. (But if someone would like to contribute, it would be educational for me and appropriate credit would be attributed if I reproduce some of it here.)

The best place for information on getting your card up at boot is to read the DISTRIBUTIONS.txt file which comes with the wireless tools package. It explains setup for RH{7,8}, Debian {2.2,3}, and others. Usage of wireless.opts is now generally depreciated on most distributions for PC Cards. My description of Debian below does not utilize The Debian Way of setting up a wireless card on boot. Again, review DISTRIBUTIONS.txt for that until I update this section accordingly.

On Debian, you will want to edit the file /etc/network/interfaces to bring your card up on start up. Assuming you made the appropriate entry in your /etc/modules.conf file earlier, the following should bring your card up at boot.

auto wlan0
iface wlan0 inet static
        address 192.168.1.1
        netmask 255.255.255.0
        up /sbin/iwconfig wlan0 essid debian && \
        /sbin/iwconfig wlan0 channel 1

The up directive will run any arguments following it. The backslash allows commands to run beyond a single line. It's essentially shell, and you can && and || stuff as you please. There is also the pre-up directive, if you want the card to have things set before the actual interface comes up.

Enabling Ethernet Bridging

You can use the Linux kernel's 802.1d Ethernet Bridging option to perform the functions of a hardware bridge using your Linux box and any interfaces that are currently configured on it. Bridging your HostAP wlan0 interface with your internal wired network, say eth0, will provide you with the same benefits (and pitfalls) as using a store bought Wireless Access Point. Devices on both interfaces will share the same subnet. You'll need the Linux Ethernet Bridging Utilities (or apt-get install bridge-utils under Debian GNU/Linux) that work with the kernel bridging functionality.

You you need to remove any existing IP addresses on your chosen interfaces, first (assuming wlan0 is the wireless interface and eth0 is the wired interface):

ifconfig wlan0 0.0.0.0
ifconfig eth0 0.0.0.0

Then, you'll need to enable bridging, with the brctl utility, by adding a bridged interface, br0, assigning physical interfaces wlan0 and eth0 to it, and finally using ifconfig to assign the new virtual bridged interface an IP address:

brctl addbr br0
brctl addif br0 eth0
brctl addif br0 wlan0
ifconfig br0 192.168.1.1 up

Now, if you're on Debian then you're in luck, as you can easily edit /etc/network/interfaces to load your bridged interfaces on start up! You'll want to read bridge-utils/README.Debian.gz for full details, but here's my basic configuration that I've used (RedHat 7.x/8.x configuration submissions welcome!):

auto br0
iface br0 inet static
       address 192.168.1.1
       network 192.168.1.0
       netmask 255.255.255.0
       broadcast 192.168.1.255
       bridge_ports wlan0 eth0
       up \
       /sbin/iwconfig wlan0 essid trekweb && \
       /sbin/iwconfig wlan0 channel 4 && \
       /sbin/iwconfig wlan0 mode Master

Now your Wired and Wireless network are bridged, as one.

Uploading A New Secondary (Station) Firmware Image

First, go back and recompile HostAP with PRISM2_DOWNLOAD_SUPPORT by running make pci EXTRA_CFLAGS="-DPRISM2_DOWNLOAD_SUPPORT" after doing a make clean. Optionally you can set this directly in driver/modules/hostap_config.h, which has some other interesting experimental options you can review, but should save for later.

Don't forget to make install or copy the *.o files over manually to where you put them last time and run depmod -a again.

Next, you need to go back to your hostap source directory and enter the utils subdirectory. Once there, if you haven't already, type make to compile the utilities. Now, turn your attention to the prism2_srec file, which ought to give you this output when run:

rebecca:# ./prism2_srec
Usage: prism2_srec [-vvrfd]  
Options:
  -v   verbose (add another for more verbosity
  -r   download SREC file into RAM (volatile)
  -f   download SREC file into flash (non-volatile)
  -d   dump SREC image into prism2_srec.dump

Options -r and -f cannot be used together.
If -r or -f is not specified, image summary is shown and
compatibility with WLAN card is verified without downloading
anything.

HostAP does not yet support "download SREC file into flash (non-volatile)" (-f). You'll need to "download SREC file into RAM (volatile)" (-r) instead, and this will be necessary each time the card is reset.

Now, you just need a new secondary firmware image file (*.hex) to download onto your card. I linked to them earlier at NetGate's Web site. The PDF files include a list of compatible hardware along with their board IDs in hexadecimal. You can either match this up with the information you get in your syslog when you initialize the HostAP driver, or you can use the nifty hostap_diag utility which you just compiled above.

rebecca:# ./hostap_diag wlan0
Host AP driver diagnostics information for 'wlan0'

NICID: id=0x8013 v1.0.0
  (PRISM II (2.5) Mini-PCI (SST parallel flash))
PRIID: id=0x0015 v1.0.7
STAID: id=0x001f v1.3.5 (station firmware)

From the output above you will want to refer to the NICID hex value to determine which HEX file is right for you. Make sure the image you choose is stated to be a "RAM-download" Secondary firmware.

Now, it's magic time. Running prism2_srec should get you output like this:

rebecca:# ./prism2_srec -r wlan0 /path/to/firmware/RF010409.HEX

srec summary for RF010409.HEX
... Card Information ...
Downloading to volatile memory (RAM).
OK.

Rerunning hostap_diag should show your card using it's new station firmware:

rebecca:# ./hostap_diag wlan0
Host AP driver diagnostics information for 'wlan0'

NICID: id=0x8013 v1.0.0
  (PRISM II (2.5) Mini-PCI (SST parallel flash))
PRIID: id=0x0015 v1.0.7
STAID: id=0x001f v1.4.9 (station firmware)

This proceedure may not work for downloading new primary firmware onto all cards, more specifically Prism2.5 chipset cards.

Very Frequently Asked Questions Regarding HostAP Driver

Does HostAP support my ... USB wireless card?

No, HostAP has no support of any kind for your USB wireless card. If you don't care about taking advantage of the HostAP stuff, you can get away with using the wlan-ng driver which does support USB Prism2 cards.

Does HostAP support my [some brand] wireless card?

Maybe. Check the compatibility section at the beginning of this article and search the FCC's database. Maybe you'll get lucky.

How do I turn off beacon frames completely?

You can't. You can reduce their frequency (which increases performance) by using the prism2_param script in the utils/ directory and running it like:
prism2_param [interface] beacon_int 1000
(where each unit is 1024 usec)

When my card initialized, I got this weird error: CMDCODE_ACCESS_WRITE failed

If this happens after extended usage, you're probably using a very old verison of HostAP (don't do that) which used to throw that under odd circumstances. If this happens as soon as the driver attempts to initialize your card, it's very likely your card does not have a Prism2 chipset. If large version numbers are mentioned during the initialize attempt, this is further evidence that it isn't a Prism2 card.

I want to use four Prism cards, two local, two remote, for improved performance. Can I do that?

Possibly. You might research these two threads. 4 cards in full duplex mode. 4 cards for a full duplex link... possible?. No promises.

Links and Useful Resources

Jean Tourrilhes' extensive list of wireless cards and their support status under Linux
Linux and Prism2-based wireless cards
Host Based AP Mailing List Archives (Old)
Host Based AP Mailing List Archives (New)
Personal Telco's list of Prism2.x chipset cards
Gentoo Linux HostAP Setup Guide which references this document a few times and has some additional information that's useful
O'Reilly's excellent book 802.11 Wireless Networks: The Definitive Guide which I highly recommend

Thanks and Credits

Thanks to Aaron Baer for providing RPMs for RedHat distributions.

Thanks to Gerald Britton for helping me understand the various firmware types that exist for Prism cards and for his section topic suggestions.

Thanks to Jacques Caron for the heads up on LinkSys moving the WMP11 to the BroadCom chipset and his photos of the card I posted in another article.

Thanks to Jerritt Collord for setting me straight on WEP keys and PLX cards.

Thanks to Michael Smith for his feedback on 40 bit WEP keys.

Thanks to NetGate for hosting STA firmware revisions 1.3.4, 1.3.6, and 1.4.9.

Thanks to Jean Tourrilhes for pointing me to his DISTRIBUTIONS.txt file for bringing wireless cards up on boot.

Copyright and Revision Information

10-13-02 - Initial Draft

10-16-02 - Added setup, WEP, and firmware download sections

10-18-02 - Added compatibility discussion

10-20-02 - Copied bridging discussion from wireless2 with a few changes

10-24-02 - Made some corrections to WEP, configuration, and bringing the card up on boot

12-08-02 - Added notice about possible problems with 2.4.20 and a workaround; Changed link for WEv15 to point to the version for 2.4.x series kernels. I apologize if this has caused anyone grief; Added link to optional WEv16 for 2.4.x kernels

12-11-02 - Changed recommended kernel version to 2.4.20 since you need not prepatch 2.4.19 up to 2.4.20-rcX anymore

12-13-02 - Added link to RedHat RPMs of a ready to go kernel with HostAP as a module

02-14-03 - Added two new firmware revisions believed to exist; Status known

03-30-03 - Slight update to the STA firmware list