1214503Srpaulohostapd and Wi-Fi Protected Setup (WPS) 2214503Srpaulo======================================= 3214503Srpaulo 4214503SrpauloThis document describes how the WPS implementation in hostapd can be 5214503Srpauloconfigured and how an external component on an AP (e.g., web UI) is 6214503Srpauloused to enable enrollment of client devices. 7214503Srpaulo 8214503Srpaulo 9214503SrpauloIntroduction to WPS 10214503Srpaulo------------------- 11214503Srpaulo 12214503SrpauloWi-Fi Protected Setup (WPS) is a mechanism for easy configuration of a 13214503Srpaulowireless network. It allows automated generation of random keys (WPA 14214503Srpaulopassphrase/PSK) and configuration of an access point and client 15214503Srpaulodevices. WPS includes number of methods for setting up connections 16214503Srpaulowith PIN method and push-button configuration (PBC) being the most 17214503Srpaulocommonly deployed options. 18214503Srpaulo 19214503SrpauloWhile WPS can enable more home networks to use encryption in the 20214503Srpaulowireless network, it should be noted that the use of the PIN and 21214503Srpauloespecially PBC mechanisms for authenticating the initial key setup is 22214503Srpaulonot very secure. As such, use of WPS may not be suitable for 23214503Srpauloenvironments that require secure network access without chance for 24214503Srpauloallowing outsiders to gain access during the setup phase. 25214503Srpaulo 26214503SrpauloWPS uses following terms to describe the entities participating in the 27214503Srpaulonetwork setup: 28214503Srpaulo- access point: the WLAN access point 29214503Srpaulo- Registrar: a device that control a network and can authorize 30214503Srpaulo addition of new devices); this may be either in the AP ("internal 31214503Srpaulo Registrar") or in an external device, e.g., a laptop, ("external 32214503Srpaulo Registrar") 33214503Srpaulo- Enrollee: a device that is being authorized to use the network 34214503Srpaulo 35214503SrpauloIt should also be noted that the AP and a client device may change 36214503Srpauloroles (i.e., AP acts as an Enrollee and client device as a Registrar) 37214503Srpaulowhen WPS is used to configure the access point. 38214503Srpaulo 39214503Srpaulo 40214503SrpauloMore information about WPS is available from Wi-Fi Alliance: 41214503Srpaulohttp://www.wi-fi.org/wifi-protected-setup 42214503Srpaulo 43214503Srpaulo 44214503Srpaulohostapd implementation 45214503Srpaulo---------------------- 46214503Srpaulo 47214503Srpaulohostapd includes an optional WPS component that can be used as an 48214503Srpaulointernal WPS Registrar to manage addition of new WPS enabled clients 49214503Srpauloto the network. In addition, WPS Enrollee functionality in hostapd can 50214503Srpaulobe used to allow external WPS Registrars to configure the access 51214503Srpaulopoint, e.g., for initial network setup. In addition, hostapd can proxy a 52214503SrpauloWPS registration between a wireless Enrollee and an external Registrar 53214503Srpaulo(e.g., Microsoft Vista or Atheros JumpStart) with UPnP. 54214503Srpaulo 55214503Srpaulo 56214503Srpaulohostapd configuration 57214503Srpaulo--------------------- 58214503Srpaulo 59214503SrpauloWPS is an optional component that needs to be enabled in hostapd build 60214503Srpauloconfiguration (.config). Here is an example configuration that 61214503Srpauloincludes WPS support and uses madwifi driver interface: 62214503Srpaulo 63214503SrpauloCONFIG_DRIVER_MADWIFI=y 64214503SrpauloCFLAGS += -I/usr/src/madwifi-0.9.3 65214503SrpauloCONFIG_WPS=y 66252726SrpauloCONFIG_WPS2=y 67214503SrpauloCONFIG_WPS_UPNP=y 68214503Srpaulo 69252726SrpauloFollowing parameter can be used to enable support for NFC config method: 70214503Srpaulo 71252726SrpauloCONFIG_WPS_NFC=y 72252726Srpaulo 73252726Srpaulo 74214503SrpauloFollowing section shows an example runtime configuration 75214503Srpaulo(hostapd.conf) that enables WPS: 76214503Srpaulo 77214503Srpaulo# Configure the driver and network interface 78214503Srpaulodriver=madwifi 79214503Srpaulointerface=ath0 80214503Srpaulo 81214503Srpaulo# WPA2-Personal configuration for the AP 82214503Srpaulossid=wps-test 83214503Srpaulowpa=2 84214503Srpaulowpa_key_mgmt=WPA-PSK 85214503Srpaulowpa_pairwise=CCMP 86214503Srpaulo# Default WPA passphrase for legacy (non-WPS) clients 87214503Srpaulowpa_passphrase=12345678 88214503Srpaulo# Enable random per-device PSK generation for WPS clients 89214503Srpaulo# Please note that the file has to exists for hostapd to start (i.e., create an 90214503Srpaulo# empty file as a starting point). 91214503Srpaulowpa_psk_file=/etc/hostapd.psk 92214503Srpaulo 93214503Srpaulo# Enable control interface for PBC/PIN entry 94214503Srpauloctrl_interface=/var/run/hostapd 95214503Srpaulo 96214503Srpaulo# Enable internal EAP server for EAP-WSC (part of Wi-Fi Protected Setup) 97214503Srpauloeap_server=1 98214503Srpaulo 99214503Srpaulo# WPS configuration (AP configured, do not allow external WPS Registrars) 100214503Srpaulowps_state=2 101214503Srpauloap_setup_locked=1 102214503Srpaulo# If UUID is not configured, it will be generated based on local MAC address. 103214503Srpaulouuid=87654321-9abc-def0-1234-56789abc0000 104214503Srpaulowps_pin_requests=/var/run/hostapd.pin-req 105214503Srpaulodevice_name=Wireless AP 106214503Srpaulomanufacturer=Company 107214503Srpaulomodel_name=WAP 108214503Srpaulomodel_number=123 109214503Srpauloserial_number=12345 110214503Srpaulodevice_type=6-0050F204-1 111214503Srpauloos_version=01020300 112214503Srpauloconfig_methods=label display push_button keypad 113214503Srpaulo 114214503Srpaulo# if external Registrars are allowed, UPnP support could be added: 115214503Srpaulo#upnp_iface=br0 116214503Srpaulo#friendly_name=WPS Access Point 117214503Srpaulo 118214503Srpaulo 119214503SrpauloExternal operations 120214503Srpaulo------------------- 121214503Srpaulo 122214503SrpauloWPS requires either a device PIN code (usually, 8-digit number) or a 123214503Srpaulopushbutton event (for PBC) to allow a new WPS Enrollee to join the 124214503Srpaulonetwork. hostapd uses the control interface as an input channel for 125214503Srpaulothese events. 126214503Srpaulo 127252726SrpauloThe PIN value used in the commands must be processed by an UI to 128252726Srpauloremove non-digit characters and potentially, to verify the checksum 129252726Srpaulodigit. "hostapd_cli wps_check_pin <PIN>" can be used to do such 130252726Srpauloprocessing. It returns FAIL if the PIN is invalid, or FAIL-CHECKSUM if 131252726Srpaulothe checksum digit is incorrect, or the processed PIN (non-digit 132252726Srpaulocharacters removed) if the PIN is valid. 133252726Srpaulo 134214503SrpauloWhen a client device (WPS Enrollee) connects to hostapd (WPS 135214503SrpauloRegistrar) in order to start PIN mode negotiation for WPS, an 136214503Srpauloidentifier (Enrollee UUID) is sent. hostapd will need to be configured 137214503Srpaulowith a device password (PIN) for this Enrollee. This is an operation 138214503Srpaulothat requires user interaction (assuming there are no pre-configured 139214503SrpauloPINs on the AP for a set of Enrollee). 140214503Srpaulo 141214503SrpauloThe PIN request with information about the device is appended to the 142214503Srpaulowps_pin_requests file (/var/run/hostapd.pin-req in this example). In 143214503Srpauloaddition, hostapd control interface event is sent as a notification of 144214503Srpauloa new device. The AP could use, e.g., a web UI for showing active 145214503SrpauloEnrollees to the user and request a PIN for an Enrollee. 146214503Srpaulo 147214503SrpauloThe PIN request file has one line for every Enrollee that connected to 148214503Srpaulothe AP, but for which there was no PIN. Following information is 149214503Srpauloprovided for each Enrollee (separated with tabulators): 150214503Srpaulo- timestamp (seconds from 1970-01-01) 151214503Srpaulo- Enrollee UUID 152214503Srpaulo- MAC address 153214503Srpaulo- Device name 154214503Srpaulo- Manufacturer 155214503Srpaulo- Model Name 156214503Srpaulo- Model Number 157214503Srpaulo- Serial Number 158214503Srpaulo- Device category 159214503Srpaulo 160214503SrpauloExample line in the /var/run/hostapd.pin-req file: 161214503Srpaulo1200188391 53b63a98-d29e-4457-a2ed-094d7e6a669c Intel(R) Centrino(R) Intel Corporation Intel(R) Centrino(R) - - 1-0050F204-1 162214503Srpaulo 163214503SrpauloControl interface data: 164214503SrpauloWPS-PIN-NEEDED [UUID-E|MAC Address|Device Name|Manufacturer|Model Name|Model Number|Serial Number|Device Category] 165214503SrpauloFor example: 166214503Srpaulo<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] 167214503Srpaulo 168214503SrpauloWhen the user enters a PIN for a pending Enrollee, e.g., on the web 169214503SrpauloUI), hostapd needs to be notified of the new PIN over the control 170214503Srpaulointerface. This can be done either by using the UNIX domain socket 171214503Srpaulo-based control interface directly (src/common/wpa_ctrl.c provides 172214503Srpaulohelper functions for using the interface) or by calling hostapd_cli. 173214503Srpaulo 174214503SrpauloExample command to add a PIN (12345670) for an Enrollee: 175214503Srpaulo 176214503Srpaulohostapd_cli wps_pin 53b63a98-d29e-4457-a2ed-094d7e6a669c 12345670 177214503Srpaulo 178214503SrpauloIf the UUID-E is not available (e.g., Enrollee waits for the Registrar 179214503Srpauloto be selected before connecting), wildcard UUID may be used to allow 180214503Srpaulothe PIN to be used once with any UUID: 181214503Srpaulo 182214503Srpaulohostapd_cli wps_pin any 12345670 183214503Srpaulo 184214503SrpauloTo reduce likelihood of PIN being used with other devices or of 185214503Srpauloforgetting an active PIN available for potential attackers, expiration 186252726Srpaulotime in seconds can be set for the new PIN (value 0 indicates no 187252726Srpauloexpiration): 188214503Srpaulo 189214503Srpaulohostapd_cli wps_pin any 12345670 300 190214503Srpaulo 191252726SrpauloIf the MAC address of the enrollee is known, it should be configured 192252726Srpauloto allow the AP to advertise list of authorized enrollees: 193214503Srpaulo 194252726Srpaulohostapd_cli wps_pin 53b63a98-d29e-4457-a2ed-094d7e6a669c \ 195252726Srpaulo 12345670 300 00:11:22:33:44:55 196252726Srpaulo 197252726Srpaulo 198214503SrpauloAfter this, the Enrollee can connect to the AP again and complete WPS 199214503Srpaulonegotiation. At that point, a new, random WPA PSK is generated for the 200214503Srpauloclient device and the client can then use that key to connect to the 201214503SrpauloAP to access the network. 202214503Srpaulo 203214503Srpaulo 204214503SrpauloIf the AP includes a pushbutton, WPS PBC mode can be used. It is 205214503Srpauloenabled by pushing a button on both the AP and the client at about the 206214503Srpaulosame time (2 minute window). hostapd needs to be notified about the AP 207214503Srpaulobutton pushed event over the control interface, e.g., by calling 208214503Srpaulohostapd_cli: 209214503Srpaulo 210214503Srpaulohostapd_cli wps_pbc 211214503Srpaulo 212214503SrpauloAt this point, the client has two minutes to complete WPS negotiation 213214503Srpaulowhich will generate a new WPA PSK in the same way as the PIN method 214214503Srpaulodescribed above. 215214503Srpaulo 216214503Srpaulo 217214503SrpauloWhen an external Registrar is used, the AP can act as an Enrollee and 218214503Srpaulouse its AP PIN. A static AP PIN (e.g., one one a label in the AP 219214503Srpaulodevice) can be configured in hostapd.conf (ap_pin parameter). A more 220214503Srpaulosecure option is to use hostapd_cli wps_ap_pin command to enable the 221214503SrpauloAP PIN only based on user action (and even better security by using a 222214503Srpaulorandom AP PIN for each session, i.e., by using "wps_ap_pin random" 223214503Srpaulocommand with a timeout value). Following commands are available for 224214503Srpaulomanaging the dynamic AP PIN operations: 225214503Srpaulo 226214503Srpaulohostapd_cli wps_ap_pin disable 227214503Srpaulo- disable AP PIN (i.e., do not allow external Registrars to use it to 228214503Srpaulo learn the current AP settings or to reconfigure the AP) 229214503Srpaulo 230214503Srpaulohostapd_cli wps_ap_pin random [timeout] 231214503Srpaulo- generate a random AP PIN and enable it 232214503Srpaulo- if the optional timeout parameter is given, the AP PIN will be enabled 233214503Srpaulo for the specified number of seconds 234214503Srpaulo 235214503Srpaulohostapd_cli wps_ap_pin get 236214503Srpaulo- fetch the current AP PIN 237214503Srpaulo 238214503Srpaulohostapd_cli wps_ap_pin set <PIN> [timeout] 239214503Srpaulo- set the AP PIN and enable it 240214503Srpaulo- if the optional timeout parameter is given, the AP PIN will be enabled 241214503Srpaulo for the specified number of seconds 242214503Srpaulo 243252726Srpaulohostapd_cli get_config 244252726Srpaulo- display the current configuration 245214503Srpaulo 246252726Srpaulohostapd_cli wps_config <new SSID> <auth> <encr> <new key> 247252726Srpauloexamples: 248252726Srpaulo hostapd_cli wps_config testing WPA2PSK CCMP 12345678 249252726Srpaulo hostapd_cli wps_config "no security" OPEN NONE "" 250252726Srpaulo 251252726Srpaulo<auth> must be one of the following: OPEN WPAPSK WPA2PSK 252252726Srpaulo<encr> must be one of the following: NONE WEP TKIP CCMP 253252726Srpaulo 254252726Srpaulo 255214503SrpauloCredential generation and configuration changes 256214503Srpaulo----------------------------------------------- 257214503Srpaulo 258214503SrpauloBy default, hostapd generates credentials for Enrollees and processing 259214503SrpauloAP configuration updates internally. However, it is possible to 260214503Srpaulocontrol these operations from external programs, if desired. 261214503Srpaulo 262214503SrpauloThe internal credential generation can be disabled with 263214503Srpauloskip_cred_build=1 option in the configuration. extra_cred option will 264214503Srpaulothen need to be used to provide pre-configured Credential attribute(s) 265214503Srpaulofor hostapd to use. The exact data from this binary file will be sent, 266214503Srpauloi.e., it will have to include valid WPS attributes. extra_cred can 267214503Srpauloalso be used to add additional networks if the Registrar is used to 268214503Srpauloconfigure credentials for multiple networks. 269214503Srpaulo 270214503SrpauloProcessing of received configuration updates can be disabled with 271214503Srpaulowps_cred_processing=1 option. When this is used, an external program 272214503Srpaulois responsible for creating hostapd configuration files and processing 273214503Srpauloconfiguration updates based on messages received from hostapd over 274214503Srpaulocontrol interface. This will also include the initial configuration on 275214503Srpaulofirst successful registration if the AP is initially set in 276214503Srpaulounconfigured state. 277214503Srpaulo 278214503SrpauloFollowing control interface messages are sent out for external programs: 279214503Srpaulo 280214503SrpauloWPS-REG-SUCCESS <Enrollee MAC address <UUID-E> 281214503SrpauloFor example: 282214503Srpaulo<2>WPS-REG-SUCCESS 02:66:a0:ee:17:27 2b7093f1-d6fb-5108-adbb-bea66bb87333 283214503Srpaulo 284252726SrpauloThis can be used to trigger change from unconfigured to configured 285214503Srpaulostate (random configuration based on the first successful WPS 286214503Srpauloregistration). In addition, this can be used to update AP UI about the 287214503Srpaulostatus of WPS registration progress. 288214503Srpaulo 289214503Srpaulo 290214503SrpauloWPS-NEW-AP-SETTINGS <hexdump of AP Setup attributes> 291214503SrpauloFor example: 292214503Srpaulo<2>WPS-NEW-AP-SETTINGS 10260001011045000c6a6b6d2d7770732d74657374100300020020100f00020008102700403065346230343536633236366665306433396164313535346131663462663731323433376163666462376633393965353466316631623032306164343438623510200006024231cede15101e000844 293214503Srpaulo 294214503SrpauloThis can be used to update the externally stored AP configuration and 295214503Srpaulothen update hostapd configuration (followed by restarting of hostapd). 296252726Srpaulo 297252726Srpaulo 298252726SrpauloWPS with NFC 299252726Srpaulo------------ 300252726Srpaulo 301252726SrpauloWPS can be used with NFC-based configuration method. An NFC tag 302252726Srpaulocontaining a password token from the Enrollee can be used to 303252726Srpauloauthenticate the connection instead of the PIN. In addition, an NFC tag 304252726Srpaulowith a configuration token can be used to transfer AP settings without 305252726Srpaulogoing through the WPS protocol. 306252726Srpaulo 307252726SrpauloWhen the AP acts as an Enrollee, a local NFC tag with a password token 308252726Srpaulocan be used by touching the NFC interface of an external Registrar. The 309252726Srpaulowps_nfc_token command is used to manage use of the NFC password token 310252726Srpaulofrom the AP. "wps_nfc_token enable" enables the use of the AP's NFC 311252726Srpaulopassword token (in place of AP PIN) and "wps_nfc_token disable" disables 312252726Srpaulothe NFC password token. 313252726Srpaulo 314252726SrpauloThe NFC password token that is either pre-configured in the 315252726Srpauloconfiguration file (wps_nfc_dev_pw_id, wps_nfc_dh_pubkey, 316252726Srpaulowps_nfc_dh_privkey, wps_nfc_dev_pw) or generated dynamically with 317252726Srpaulo"wps_nfc_token <WPS|NDEF>" command. The nfc_pw_token tool from 318252726Srpaulowpa_supplicant can be used to generate NFC password tokens during 319252726Srpaulomanufacturing (each AP needs to have its own random keys). 320252726Srpaulo 321252726SrpauloThe "wps_nfc_config_token <WPS/NDEF>" command can be used to build an 322252726SrpauloNFC configuration token. The output value from this command is a hexdump 323252726Srpauloof the current AP configuration (WPS parameter requests this to include 324252726Srpauloonly the WPS attributes; NDEF parameter requests additional NDEF 325252726Srpauloencapsulation to be included). This data needs to be written to an NFC 326252726Srpaulotag with an external program. Once written, the NFC configuration token 327252726Srpaulocan be used to touch an NFC interface on a station to provision the 328252726Srpaulocredentials needed to access the network. 329252726Srpaulo 330252726SrpauloWhen the NFC device on the AP reads an NFC tag with a MIME media type 331252726Srpaulo"application/vnd.wfa.wsc", the NDEF message payload (with or without 332252726SrpauloNDEF encapsulation) can be delivered to hostapd using the 333252726Srpaulofollowing hostapd_cli command: 334252726Srpaulo 335252726Srpaulowps_nfc_tag_read <hexdump of payload> 336252726Srpaulo 337252726SrpauloIf the NFC tag contains a password token, the token is added to the 338252726Srpaulointernal Registrar. This allows station Enrollee from which the password 339252726Srpaulotoken was received to run through WPS protocol to provision the 340252726Srpaulocredential. 341