diff options
author | Dmitry Shmidt <dimitrysh@google.com> | 2011-05-09 14:06:53 -0700 |
---|---|---|
committer | Dmitry Shmidt <dimitrysh@google.com> | 2011-05-09 14:24:08 -0700 |
commit | 8d520ff1dc2da35cdca849e982051b86468016d8 (patch) | |
tree | 3e33700a20ffe9064c3de3e9efa3a9dfcebb7b03 /hostapd/README-WPS | |
parent | 7acd11a82b3521a1ec0ef3976af4786b02642e7e (diff) | |
download | android_external_wpa_supplicant_8-8d520ff1dc2da35cdca849e982051b86468016d8.tar.gz android_external_wpa_supplicant_8-8d520ff1dc2da35cdca849e982051b86468016d8.tar.bz2 android_external_wpa_supplicant_8-8d520ff1dc2da35cdca849e982051b86468016d8.zip |
wpa_supplicant: Initial Revision 0.8.X
Based on:
commit 0725cc7b7efc434910e89865c42eda7ce61bbf08
Author: Jouni Malinen <j@w1.fi>
Date: Thu Apr 21 20:41:01 2011 +0300
Enable CONFIG_DRIVER_NL80211=y in the default configuration
nl80211 should be preferred over WEXT with any recent Linux
kernel version.
Change-Id: I26aec5afbbd4f4a1f5fd900912545b6f5050de64
Signed-off-by: Dmitry Shmidt <dimitrysh@google.com>
Diffstat (limited to 'hostapd/README-WPS')
-rw-r--r-- | hostapd/README-WPS | 291 |
1 files changed, 291 insertions, 0 deletions
diff --git a/hostapd/README-WPS b/hostapd/README-WPS new file mode 100644 index 00000000..17988d47 --- /dev/null +++ b/hostapd/README-WPS @@ -0,0 +1,291 @@ +hostapd and Wi-Fi Protected Setup (WPS) +======================================= + +This document describes how the WPS implementation in hostapd can be +configured and how an external component on an AP (e.g., web UI) is +used to enable enrollment of client devices. + + +Introduction to WPS +------------------- + +Wi-Fi Protected Setup (WPS) is a mechanism for easy configuration of a +wireless network. It allows automated generation of random keys (WPA +passphrase/PSK) and configuration of an access point and client +devices. WPS includes number of methods for setting up connections +with PIN method and push-button configuration (PBC) being the most +commonly deployed options. + +While WPS can enable more home networks to use encryption in the +wireless network, it should be noted that the use of the PIN and +especially PBC mechanisms for authenticating the initial key setup is +not very secure. As such, use of WPS may not be suitable for +environments that require secure network access without chance for +allowing outsiders to gain access during the setup phase. + +WPS uses following terms to describe the entities participating in the +network setup: +- access point: the WLAN access point +- Registrar: a device that control a network and can authorize + addition of new devices); this may be either in the AP ("internal + Registrar") or in an external device, e.g., a laptop, ("external + Registrar") +- Enrollee: a device that is being authorized to use the network + +It should also be noted that the AP and a client device may change +roles (i.e., AP acts as an Enrollee and client device as a Registrar) +when WPS is used to configure the access point. + + +More information about WPS is available from Wi-Fi Alliance: +http://www.wi-fi.org/wifi-protected-setup + + +hostapd implementation +---------------------- + +hostapd includes an optional WPS component that can be used as an +internal WPS Registrar to manage addition of new WPS enabled clients +to the network. In addition, WPS Enrollee functionality in hostapd can +be used to allow external WPS Registrars to configure the access +point, e.g., for initial network setup. In addition, hostapd can proxy a +WPS registration between a wireless Enrollee and an external Registrar +(e.g., Microsoft Vista or Atheros JumpStart) with UPnP. + + +hostapd configuration +--------------------- + +WPS is an optional component that needs to be enabled in hostapd build +configuration (.config). Here is an example configuration that +includes WPS support and uses madwifi driver interface: + +CONFIG_DRIVER_MADWIFI=y +CFLAGS += -I/usr/src/madwifi-0.9.3 +CONFIG_WPS=y +CONFIG_WPS2=y +CONFIG_WPS_UPNP=y + + +Following section shows an example runtime configuration +(hostapd.conf) that enables WPS: + +# Configure the driver and network interface +driver=madwifi +interface=ath0 + +# WPA2-Personal configuration for the AP +ssid=wps-test +wpa=2 +wpa_key_mgmt=WPA-PSK +wpa_pairwise=CCMP +# Default WPA passphrase for legacy (non-WPS) clients +wpa_passphrase=12345678 +# Enable random per-device PSK generation for WPS clients +# Please note that the file has to exists for hostapd to start (i.e., create an +# empty file as a starting point). +wpa_psk_file=/etc/hostapd.psk + +# Enable control interface for PBC/PIN entry +ctrl_interface=/var/run/hostapd + +# Enable internal EAP server for EAP-WSC (part of Wi-Fi Protected Setup) +eap_server=1 + +# WPS configuration (AP configured, do not allow external WPS Registrars) +wps_state=2 +ap_setup_locked=1 +# If UUID is not configured, it will be generated based on local MAC address. +uuid=87654321-9abc-def0-1234-56789abc0000 +wps_pin_requests=/var/run/hostapd.pin-req +device_name=Wireless AP +manufacturer=Company +model_name=WAP +model_number=123 +serial_number=12345 +device_type=6-0050F204-1 +os_version=01020300 +config_methods=label display push_button keypad + +# if external Registrars are allowed, UPnP support could be added: +#upnp_iface=br0 +#friendly_name=WPS Access Point + + +External operations +------------------- + +WPS requires either a device PIN code (usually, 8-digit number) or a +pushbutton event (for PBC) to allow a new WPS Enrollee to join the +network. hostapd uses the control interface as an input channel for +these events. + +The PIN value used in the commands must be processed by an UI to +remove non-digit characters and potentially, to verify the checksum +digit. "hostapd_cli wps_check_pin <PIN>" can be used to do such +processing. It returns FAIL if the PIN is invalid, or FAIL-CHECKSUM if +the checksum digit is incorrect, or the processed PIN (non-digit +characters removed) if the PIN is valid. + +When a client device (WPS Enrollee) connects to hostapd (WPS +Registrar) in order to start PIN mode negotiation for WPS, an +identifier (Enrollee UUID) is sent. hostapd will need to be configured +with a device password (PIN) for this Enrollee. This is an operation +that requires user interaction (assuming there are no pre-configured +PINs on the AP for a set of Enrollee). + +The PIN request with information about the device is appended to the +wps_pin_requests file (/var/run/hostapd.pin-req in this example). In +addition, hostapd control interface event is sent as a notification of +a new device. The AP could use, e.g., a web UI for showing active +Enrollees to the user and request a PIN for an Enrollee. + +The PIN request file has one line for every Enrollee that connected to +the AP, but for which there was no PIN. Following information is +provided for each Enrollee (separated with tabulators): +- timestamp (seconds from 1970-01-01) +- Enrollee UUID +- MAC address +- Device name +- Manufacturer +- Model Name +- Model Number +- Serial Number +- Device category + +Example line in the /var/run/hostapd.pin-req file: +1200188391 53b63a98-d29e-4457-a2ed-094d7e6a669c Intel(R) Centrino(R) Intel Corporation Intel(R) Centrino(R) - - 1-0050F204-1 + +Control interface data: +WPS-PIN-NEEDED [UUID-E|MAC Address|Device Name|Manufacturer|Model Name|Model Number|Serial Number|Device Category] +For example: +<2>WPS-PIN-NEEDED [53b63a98-d29e-4457-a2ed-094d7e6a669c|02:12:34:56:78:9a|Device|Manuf|Model|Model Number|Serial Number|1-0050F204-1] + +When the user enters a PIN for a pending Enrollee, e.g., on the web +UI), hostapd needs to be notified of the new PIN over the control +interface. This can be done either by using the UNIX domain socket +-based control interface directly (src/common/wpa_ctrl.c provides +helper functions for using the interface) or by calling hostapd_cli. + +Example command to add a PIN (12345670) for an Enrollee: + +hostapd_cli wps_pin 53b63a98-d29e-4457-a2ed-094d7e6a669c 12345670 + +If the UUID-E is not available (e.g., Enrollee waits for the Registrar +to be selected before connecting), wildcard UUID may be used to allow +the PIN to be used once with any UUID: + +hostapd_cli wps_pin any 12345670 + +To reduce likelihood of PIN being used with other devices or of +forgetting an active PIN available for potential attackers, expiration +time in seconds can be set for the new PIN (value 0 indicates no +expiration): + +hostapd_cli wps_pin any 12345670 300 + +If the MAC address of the enrollee is known, it should be configured +to allow the AP to advertise list of authorized enrollees: + +hostapd_cli wps_pin 53b63a98-d29e-4457-a2ed-094d7e6a669c \ + 12345670 300 00:11:22:33:44:55 + + +After this, the Enrollee can connect to the AP again and complete WPS +negotiation. At that point, a new, random WPA PSK is generated for the +client device and the client can then use that key to connect to the +AP to access the network. + + +If the AP includes a pushbutton, WPS PBC mode can be used. It is +enabled by pushing a button on both the AP and the client at about the +same time (2 minute window). hostapd needs to be notified about the AP +button pushed event over the control interface, e.g., by calling +hostapd_cli: + +hostapd_cli wps_pbc + +At this point, the client has two minutes to complete WPS negotiation +which will generate a new WPA PSK in the same way as the PIN method +described above. + + +When an external Registrar is used, the AP can act as an Enrollee and +use its AP PIN. A static AP PIN (e.g., one one a label in the AP +device) can be configured in hostapd.conf (ap_pin parameter). A more +secure option is to use hostapd_cli wps_ap_pin command to enable the +AP PIN only based on user action (and even better security by using a +random AP PIN for each session, i.e., by using "wps_ap_pin random" +command with a timeout value). Following commands are available for +managing the dynamic AP PIN operations: + +hostapd_cli wps_ap_pin disable +- disable AP PIN (i.e., do not allow external Registrars to use it to + learn the current AP settings or to reconfigure the AP) + +hostapd_cli wps_ap_pin random [timeout] +- generate a random AP PIN and enable it +- if the optional timeout parameter is given, the AP PIN will be enabled + for the specified number of seconds + +hostapd_cli wps_ap_pin get +- fetch the current AP PIN + +hostapd_cli wps_ap_pin set <PIN> [timeout] +- set the AP PIN and enable it +- if the optional timeout parameter is given, the AP PIN will be enabled + for the specified number of seconds + +hostapd_cli get_config +- display the current configuration + +hostapd_cli wps_config <new SSID> <auth> <encr> <new key> +examples: + hostapd_cli wps_config testing WPA2PSK CCMP 12345678 + hostapd_cli wps_config "no security" OPEN NONE "" + +<auth> must be one of the following: OPEN WPAPSK WPA2PSK +<encr> must be one of the following: NONE WEP TKIP CCMP + + +Credential generation and configuration changes +----------------------------------------------- + +By default, hostapd generates credentials for Enrollees and processing +AP configuration updates internally. However, it is possible to +control these operations from external programs, if desired. + +The internal credential generation can be disabled with +skip_cred_build=1 option in the configuration. extra_cred option will +then need to be used to provide pre-configured Credential attribute(s) +for hostapd to use. The exact data from this binary file will be sent, +i.e., it will have to include valid WPS attributes. extra_cred can +also be used to add additional networks if the Registrar is used to +configure credentials for multiple networks. + +Processing of received configuration updates can be disabled with +wps_cred_processing=1 option. When this is used, an external program +is responsible for creating hostapd configuration files and processing +configuration updates based on messages received from hostapd over +control interface. This will also include the initial configuration on +first successful registration if the AP is initially set in +unconfigured state. + +Following control interface messages are sent out for external programs: + +WPS-REG-SUCCESS <Enrollee MAC address <UUID-E> +For example: +<2>WPS-REG-SUCCESS 02:66:a0:ee:17:27 2b7093f1-d6fb-5108-adbb-bea66bb87333 + +This can be used to trigger change from unconfigured to configured +state (random configuration based on the first successful WPS +registration). In addition, this can be used to update AP UI about the +status of WPS registration progress. + + +WPS-NEW-AP-SETTINGS <hexdump of AP Setup attributes> +For example: +<2>WPS-NEW-AP-SETTINGS 10260001011045000c6a6b6d2d7770732d74657374100300020020100f00020008102700403065346230343536633236366665306433396164313535346131663462663731323433376163666462376633393965353466316631623032306164343438623510200006024231cede15101e000844 + +This can be used to update the externally stored AP configuration and +then update hostapd configuration (followed by restarting of hostapd). |