aboutsummaryrefslogtreecommitdiffstats
path: root/README
blob: 59a269b0d5733855113a7c12e81fa0a6aa3105d5 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
Host AP driver for Intersil Prism2/2.5/3	(DEVELOPMENT VERSION!)
========================================

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


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.

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
===================

PC Cards (not in PLX9052 adapter)	hostap_cs.o
---------------------------------

Systems using kernel tree PCMCIA modules:

'Makefile' includes commands for compiling and installing Host AP
driver for systems using kernel tree PCMCIA support (i.e., kernel
modules are not compiled with external pcmcia-cs package). Edit
KERNEL_PATH in Makefile to match your system. Run 'make pccard' (this
compiles the sources; this step can be run as non-root user). After
the compilation has finished, you can install hostap_cs.o by running
'make install_pccard' (as root). You will then need to restart cardmgr
to load new configuration from /etc/pcmcia/hostap_cs.conf.


Systems using external pcmcia-cs modules:

There are two options for building and installing:

1) just like the steps for kernel tree, but also configure PCMCIA_PATH in
   Makefile (i.e., compile and install pcmcia-cs separately)

2)
Copy everything except driver/modules/Makefile from 'driver' subdirectory on
top of root pcmcia-cs directory, i.e., so that driver/modules/hostap.c ends up
in pcmcia-cs's 'modules' directory, like so:

	# make sure that Makefile does not overwrite old Makefile in pcmcia-cs
	mv driver/modules/Makefile driver/modules/Makefile-not-used
	cp -a driver/* /usr/src/pcmcia-cs-3.1.31

After this you should be able to build and install pcmcia-cs with this
driver (hostap_cs.o) using normal commands ('make config', 'make all',
and 'make install').

PC Cards in PLX9052 adapter	hostap_plx.o
---------------------------

'Makefile' includes commands for compiling and installing Host AP
driver for systems using PLX9052-based PCI adapters for PC Cards.
These cards do not use pcmcia-cs package and hostap_plx.o is used to
also initialize the PCI parts of such setup. Edit KERNEL_PATH in
Makefile to match your system. Run 'make plx' (this compiles the
sources; this step can be run as non-root user). After the compilation
has finished, you can install hostap_plx.o by running 'make
install_plx' (as root). You can probe PCI bus for PLX9052 adapters and
initialize the devices by loading the module ('modprobe hostap_plx.o').

PCI cards based on Prism2.5	hostap_pci.o
---------------------------

'Makefile' includes commands for compiling and installing Host AP
driver for systems using Prism2.5-based PCI cards. These cards do not
use pcmcia-cs package. Edit KERNEL_PATH in Makefile to match your
system. Run 'make pci' (this compiles the sources; this step can be
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.