LSDK-WLAN-9.2.0.31_b.gz

apps/wpa2 software -- Main documentation file Original Author: Ted Merrill 2007-2008 =========================================================================== Overview =========================================================================== The apps/wpa2 source directory provides a solution for authentication software support for Atheros access point hardware in both access point and station modes, including WPS support. However, the software is quite general and can be used on any linux-based device with Atheros WLAN hardware. The "hostap" free software written by Jouni (hostapd, wpa_supplicant) is quite good and complete but (as of this writing) does not include WPS support. This is thus a clone which includes WPS support; the clone including WPS support was developed by Sony, and then further modified by Atheros, particularly to make UPnP support more economical. Additionally, Atheros has made changes to the configuration file format in the hope that this will make it easier to use. Note that this software relies intimately upon Atheros "madwifi" drivers that have the proper WPS extensions. Features: -- Complete(?) WiFi authentication support as provided by hostapd and wpa_supplicant -- Complete(?) WiFi-based WPS support -- UPnP WPS support (currently for hostapd only, see notes below) -- Atheros WPS extensions support Latent Features: -- UPnP support from wpa_supplicant requires either bringing back libupnp (ugh!) or writing a "tiny upnp" code for it (as was done for hostapd). -- Sony code provides near field control (NFC) but we have never disabled this and it won't work without some effort at fixing bit rot. The following document attempts to give a definitive list of supported and unsupported features, plus configuration methods: Atheros_WPS_Extensions_Specification.doc ============================================================================ Running the software ============================================================================ The configuration file system for hostapd has been greatly changed by Atheros. Please read configuration.txt in detail. The central configuration file is a "topology file", see examples/topology.conf . Normally, both wpa_supplicant and hostapd will be run with a single topology file as an argument and will read the configuration files listed therein. The program "apstart" also sets up the network devices according to the content of the topology file. The topology file refers to other files. A common problem is that the path to the other files is incorrect. There are examples of all files in the examples directory; these examples can be used as-is for simple cases. The examples are self-documenting (contain lots of comments); these comments should be removed (to save space) from a product. Prior to running the authentication programs, the network devices and bridge devices must be set up. (The drivers need to be loaded first, but that is outside of the scope of this document). One way to do that is to run: apstart /etc/wpa2/topology.conf hostapd is invoked as: hostapd [-d] [-B] /etc/wpa2/topology.conf & where: -d turns on debug messages (-dd for even more) ... omit if not needed -B daemonizes wpa_supplicant is invoked in the same way. Communication with the wpa_supplicant and hostapd programs is via socket files that are normally resident in the /var/run/wpa_supplicant and /var/run/hostapd directories (respectively). The wpatalk program serves an example of how to talk via these socket files. The protocol involves sending a command line and receiving an acknowledgement; for more complicated operations, it may be necessary to wait for asyncronous acknowledgement. Once running, you can use wpatalk to send commands to the running programs, or more exactly to the context within the program that handles a particular network device (e.g. ath0, ath1 etc.). wpatalk is invoked as: wpatalk ath<n> 'command arg arg' (you can give multiple commands, BUT don't forget to quote any command that has arguments, even if you have only one command!) or just wpatalk ath<n> for interactive, in which case you enter no more than one command per input line. Commands whose names are capitalized ("raw commands") are passed through to the appropriate program unmodified. Commands whose names are lower case receive handling within wpatalk before being (possibly) passed through (wpatalk detects if it is talking to a wpa_supplicant or hostapd). See hcmd.txt for a list of raw commands for hostapd. See wcmd.txt for a list of raw commands for wpa_supplicant. ============================================================================ Configuring hostapd ============================================================================ Refer to the comments in the example configuration files for details. The topology file defines (in a "radio" section) how the underlying network interface (e.g. "wifi0") is configured with "virtual APs" which become the active wireless network interface, e.g. "ath0". The topology file must define a bridge section that connects an active wireless interface such as "ath0" (defined in a radio section) with a wired interface such as "eth0". Any (?) number of interfaces can be bridged together. The general parameters for an AP radio are defined in a config file referenced from the radio/ap subsection, e.g. config install/etc/wpa2/ap_example_80211g.conf This file is rarely if ever changed once set up for a particular access point. The per-BSS (per active network interface, such as "ath0") parameters are more frequently changed. Note that the fields "interface" and "bridge" are present for historical reasons but actually ignored. The field "ctrl_interface" must be "/var/run/hostapd" in order to work with the default setting for wpatalk. In order for WPS to work, regardless of the authentication mode, the following fields must always be set: eap_server=1 To configure the AP to be totally open and unencrypted you need the following values: ieee8021x=0 auth_algs=1 wpa=0 wpa_key_mgmt= (or equivalently, the field "wpa_key_mgmt" may be commented out). (and you need to comment out wep key info?). To configure the AP to use WEP-PSK ("WEP-open"): ieee8021x=0 wpa=0 wpa_key_mgmt= auth_algs=1 wep_default_key=0 (wep_default_key can be 0, 1, 2 or 3 but 0 is most common) wep_key0="abcde" (Use appropropriate wep key! Use wep_key<n> for wep_default_key=<n>). (Wep keys must be quoted strings of 5 or 13 chars, or hex numerals of 10 or 26 characters; other wep key sizes are NOT supported). To configure the AP to use WPA-TKIP-PSK: ieee8021x=1 auth_algs=1 wpa=1 wpa_key_mgmt=WPA-PSK wpa_pairwise=TKIP and also set wpa_psk or wpa_passphrase (may need to remove wep key info?). To configure the AP to use WPA2-CCMP-PSK: ieee8021x=1 auth_algs=1 wpa=2 wpa_key_mgmt=WPA-PSK wpa_pairwise=CCMP and also set wpa_psk or wpa_passphrase (may need to remove wep key info?). There are many other combinations supported by hostapd... ============================================================================ Using Wifi Protected Setup (WPS) ============================================================================ See above for configuration requirements for hostapd. Note that wps_disabled=0 is required (and wps_upnp_disabled=0 to allow UPnP sessions). The magical and very confusing AP (hostapd) parameter "wps_configured" --------------------------------------------------------------------------- The "wps_configured" hostapd parameter is mandated by the WPS specification. It's factory default may be 0 or 1 (false or true) but as a practical matter it is expected (by WPS test suites) that it will be 0. It is normally set to zero only on a "set factor