Home | History | Annotate | only in /external/wpa_supplicant_8/hostapd
Up to higher level directory
NameDateSize
android.config25-Jul-20135.5K
Android.mk25-Jul-201318.2K
ChangeLog25-Jul-201343.4K
config_file.c25-Jul-201382.9K
config_file.h25-Jul-2013469
ctrl_iface.c25-Jul-201336K
ctrl_iface.h25-Jul-2013998
defconfig25-Jul-20138.9K
dump_state.c25-Jul-20134.8K
dump_state.h25-Jul-2013330
eap_register.c25-Jul-20132.9K
eap_register.h25-Jul-2013309
eap_testing.txt25-Jul-20132.5K
hlr_auc_gw.c25-Jul-201322K
hlr_auc_gw.milenage_db25-Jul-2013734
hlr_auc_gw.txt25-Jul-20133.2K
hostapd.825-Jul-20131.5K
hostapd.accept25-Jul-2013276
hostapd.conf25-Jul-201361.9K
hostapd.deny25-Jul-2013144
hostapd.eap_user25-Jul-20134K
hostapd.eap_user_sqlite25-Jul-2013506
hostapd.radius_clients25-Jul-2013142
hostapd.sim_db25-Jul-2013409
hostapd.vlan25-Jul-2013282
hostapd.wpa_psk25-Jul-2013549
hostapd_cli.125-Jul-20131.8K
hostapd_cli.c25-Jul-201326.8K
logwatch/25-Jul-2013
main.c25-Jul-201315.6K
Makefile25-Jul-201318.7K
nt_password_hash.c25-Jul-2013922
README25-Jul-201316.6K
README-WPS25-Jul-201314.1K
src/25-Jul-2013
wired.conf25-Jul-20131.1K
wps-ap-nfc.py25-Jul-20136.9K

README

      1 hostapd - user space IEEE 802.11 AP and IEEE 802.1X/WPA/WPA2/EAP
      2 	  Authenticator and RADIUS authentication server
      3 ================================================================
      4 
      5 Copyright (c) 2002-2013, Jouni Malinen <j (a] w1.fi> and contributors
      6 All Rights Reserved.
      7 
      8 This program is licensed under the BSD license (the one with
      9 advertisement clause removed).
     10 
     11 If you are submitting changes to the project, please see CONTRIBUTIONS
     12 file for more instructions.
     13 
     14 
     15 
     16 License
     17 -------
     18 
     19 This software may be distributed, used, and modified under the terms of
     20 BSD license:
     21 
     22 Redistribution and use in source and binary forms, with or without
     23 modification, are permitted provided that the following conditions are
     24 met:
     25 
     26 1. Redistributions of source code must retain the above copyright
     27    notice, this list of conditions and the following disclaimer.
     28 
     29 2. Redistributions in binary form must reproduce the above copyright
     30    notice, this list of conditions and the following disclaimer in the
     31    documentation and/or other materials provided with the distribution.
     32 
     33 3. Neither the name(s) of the above-listed copyright holder(s) nor the
     34    names of its contributors may be used to endorse or promote products
     35    derived from this software without specific prior written permission.
     36 
     37 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
     38 "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
     39 LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
     40 A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
     41 OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
     42 SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
     43 LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
     44 DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
     45 THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
     46 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
     47 OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
     48 
     49 
     50 
     51 Introduction
     52 ============
     53 
     54 Originally, hostapd was an optional user space component for Host AP
     55 driver. It adds more features to the basic IEEE 802.11 management
     56 included in the kernel driver: using external RADIUS authentication
     57 server for MAC address based access control, IEEE 802.1X Authenticator
     58 and dynamic WEP keying, RADIUS accounting, WPA/WPA2 (IEEE 802.11i/RSN)
     59 Authenticator and dynamic TKIP/CCMP keying.
     60 
     61 The current version includes support for other drivers, an integrated
     62 EAP server (i.e., allow full authentication without requiring
     63 an external RADIUS authentication server), and RADIUS authentication
     64 server for EAP authentication.
     65 
     66 
     67 Requirements
     68 ------------
     69 
     70 Current hardware/software requirements:
     71 - drivers:
     72 	Host AP driver for Prism2/2.5/3.
     73 	(http://hostap.epitest.fi/)
     74 	Please note that station firmware version needs to be 1.7.0 or newer
     75 	to work in WPA mode.
     76 
     77 	madwifi driver for cards based on Atheros chip set (ar521x)
     78 	(http://sourceforge.net/projects/madwifi/)
     79 	Please note that you will need to add the correct path for
     80 	madwifi driver root directory in .config (see defconfig file for
     81 	an example: CFLAGS += -I<path>)
     82 
     83 	mac80211-based drivers that support AP mode (with driver=nl80211).
     84 	This includes drivers for Atheros (ath9k) and Broadcom (b43)
     85 	chipsets.
     86 
     87 	Any wired Ethernet driver for wired IEEE 802.1X authentication
     88 	(experimental code)
     89 
     90 	FreeBSD -current (with some kernel mods that have not yet been
     91 	committed when hostapd v0.3.0 was released)
     92 	BSD net80211 layer (e.g., Atheros driver)
     93 
     94 
     95 Build configuration
     96 -------------------
     97 
     98 In order to be able to build hostapd, you will need to create a build
     99 time configuration file, .config that selects which optional
    100 components are included. See defconfig file for example configuration
    101 and list of available options.
    102 
    103 
    104 
    105 IEEE 802.1X
    106 ===========
    107 
    108 IEEE Std 802.1X-2001 is a standard for port-based network access
    109 control. In case of IEEE 802.11 networks, a "virtual port" is used
    110 between each associated station and the AP. IEEE 802.11 specifies
    111 minimal authentication mechanism for stations, whereas IEEE 802.1X
    112 introduces a extensible mechanism for authenticating and authorizing
    113 users.
    114 
    115 IEEE 802.1X uses elements called Supplicant, Authenticator, Port
    116 Access Entity, and Authentication Server. Supplicant is a component in
    117 a station and it performs the authentication with the Authentication
    118 Server. An access point includes an Authenticator that relays the packets
    119 between a Supplicant and an Authentication Server. In addition, it has a
    120 Port Access Entity (PAE) with Authenticator functionality for
    121 controlling the virtual port authorization, i.e., whether to accept
    122 packets from or to the station.
    123 
    124 IEEE 802.1X uses Extensible Authentication Protocol (EAP). The frames
    125 between a Supplicant and an Authenticator are sent using EAP over LAN
    126 (EAPOL) and the Authenticator relays these frames to the Authentication
    127 Server (and similarly, relays the messages from the Authentication
    128 Server to the Supplicant). The Authentication Server can be colocated with the
    129 Authenticator, in which case there is no need for additional protocol
    130 for EAP frame transmission. However, a more common configuration is to
    131 use an external Authentication Server and encapsulate EAP frame in the
    132 frames used by that server. RADIUS is suitable for this, but IEEE
    133 802.1X would also allow other mechanisms.
    134 
    135 Host AP driver includes PAE functionality in the kernel driver. It
    136 is a relatively simple mechanism for denying normal frames going to
    137 or coming from an unauthorized port. PAE allows IEEE 802.1X related
    138 frames to be passed between the Supplicant and the Authenticator even
    139 on an unauthorized port.
    140 
    141 User space daemon, hostapd, includes Authenticator functionality. It
    142 receives 802.1X (EAPOL) frames from the Supplicant using the wlan#ap
    143 device that is also used with IEEE 802.11 management frames. The
    144 frames to the Supplicant are sent using the same device.
    145 
    146 The normal configuration of the Authenticator would use an external
    147 Authentication Server. hostapd supports RADIUS encapsulation of EAP
    148 packets, so the Authentication Server should be a RADIUS server, like
    149 FreeRADIUS (http://www.freeradius.org/). The Authenticator in hostapd
    150 relays the frames between the Supplicant and the Authentication
    151 Server. It also controls the PAE functionality in the kernel driver by
    152 controlling virtual port authorization, i.e., station-AP
    153 connection, based on the IEEE 802.1X state.
    154 
    155 When a station would like to use the services of an access point, it
    156 will first perform IEEE 802.11 authentication. This is normally done
    157 with open systems authentication, so there is no security. After
    158 this, IEEE 802.11 association is performed. If IEEE 802.1X is
    159 configured to be used, the virtual port for the station is set in
    160 Unauthorized state and only IEEE 802.1X frames are accepted at this
    161 point. The Authenticator will then ask the Supplicant to authenticate
    162 with the Authentication Server. After this is completed successfully,
    163 the virtual port is set to Authorized state and frames from and to the
    164 station are accepted.
    165 
    166 Host AP configuration for IEEE 802.1X
    167 -------------------------------------
    168 
    169 The user space daemon has its own configuration file that can be used to
    170 define AP options. Distribution package contains an example
    171 configuration file (hostapd/hostapd.conf) that can be used as a basis
    172 for configuration. It includes examples of all supported configuration
    173 options and short description of each option. hostapd should be started
    174 with full path to the configuration file as the command line argument,
    175 e.g., './hostapd /etc/hostapd.conf'. If you have more that one wireless
    176 LAN card, you can use one hostapd process for multiple interfaces by
    177 giving a list of configuration files (one per interface) in the command
    178 line.
    179 
    180 hostapd includes a minimal co-located IEEE 802.1X server which can be
    181 used to test IEEE 802.1X authentication. However, it should not be
    182 used in normal use since it does not provide any security. This can be
    183 configured by setting ieee8021x and minimal_eap options in the
    184 configuration file.
    185 
    186 An external Authentication Server (RADIUS) is configured with
    187 auth_server_{addr,port,shared_secret} options. In addition,
    188 ieee8021x and own_ip_addr must be set for this mode. With such
    189 configuration, the co-located Authentication Server is not used and EAP
    190 frames will be relayed using EAPOL between the Supplicant and the
    191 Authenticator and RADIUS encapsulation between the Authenticator and
    192 the Authentication Server. Other than this, the functionality is similar
    193 to the case with the co-located Authentication Server.
    194 
    195 Authentication Server and Supplicant
    196 ------------------------------------
    197 
    198 Any RADIUS server supporting EAP should be usable as an IEEE 802.1X
    199 Authentication Server with hostapd Authenticator. FreeRADIUS
    200 (http://www.freeradius.org/) has been successfully tested with hostapd
    201 Authenticator and both Xsupplicant (http://www.open1x.org) and Windows
    202 XP Supplicants. EAP/TLS was used with Xsupplicant and
    203 EAP/MD5-Challenge with Windows XP.
    204 
    205 http://www.missl.cs.umd.edu/wireless/eaptls/ has useful information
    206 about using EAP/TLS with FreeRADIUS and Xsupplicant (just replace
    207 Cisco access point with Host AP driver, hostapd daemon, and a Prism2
    208 card ;-). http://www.freeradius.org/doc/EAP-MD5.html has information
    209 about using EAP/MD5 with FreeRADIUS, including instructions for WinXP
    210 configuration. http://www.denobula.com/EAPTLS.pdf has a HOWTO on
    211 EAP/TLS use with WinXP Supplicant.
    212 
    213 Automatic WEP key configuration
    214 -------------------------------
    215 
    216 EAP/TLS generates a session key that can be used to send WEP keys from
    217 an AP to authenticated stations. The Authenticator in hostapd can be
    218 configured to automatically select a random default/broadcast key
    219 (shared by all authenticated stations) with wep_key_len_broadcast
    220 option (5 for 40-bit WEP or 13 for 104-bit WEP). In addition,
    221 wep_key_len_unicast option can be used to configure individual unicast
    222 keys for stations. This requires support for individual keys in the
    223 station driver.
    224 
    225 WEP keys can be automatically updated by configuring rekeying. This
    226 will improve security of the network since same WEP key will only be
    227 used for a limited period of time. wep_rekey_period option sets the
    228 interval for rekeying in seconds.
    229 
    230 
    231 WPA/WPA2
    232 ========
    233 
    234 Features
    235 --------
    236 
    237 Supported WPA/IEEE 802.11i features:
    238 - WPA-PSK ("WPA-Personal")
    239 - WPA with EAP (e.g., with RADIUS authentication server) ("WPA-Enterprise")
    240 - key management for CCMP, TKIP, WEP104, WEP40
    241 - RSN/WPA2 (IEEE 802.11i), including PMKSA caching and pre-authentication
    242 
    243 WPA
    244 ---
    245 
    246 The original security mechanism of IEEE 802.11 standard was not
    247 designed to be strong and has proved to be insufficient for most
    248 networks that require some kind of security. Task group I (Security)
    249 of IEEE 802.11 working group (http://www.ieee802.org/11/) has worked
    250 to address the flaws of the base standard and has in practice
    251 completed its work in May 2004. The IEEE 802.11i amendment to the IEEE
    252 802.11 standard was approved in June 2004 and this amendment is likely
    253 to be published in July 2004.
    254 
    255 Wi-Fi Alliance (http://www.wi-fi.org/) used a draft version of the
    256 IEEE 802.11i work (draft 3.0) to define a subset of the security
    257 enhancements that can be implemented with existing wlan hardware. This
    258 is called Wi-Fi Protected Access<TM> (WPA). This has now become a
    259 mandatory component of interoperability testing and certification done
    260 by Wi-Fi Alliance. Wi-Fi provides information about WPA at its web
    261 site (http://www.wi-fi.org/OpenSection/protected_access.asp).
    262 
    263 IEEE 802.11 standard defined wired equivalent privacy (WEP) algorithm
    264 for protecting wireless networks. WEP uses RC4 with 40-bit keys,
    265 24-bit initialization vector (IV), and CRC32 to protect against packet
    266 forgery. All these choices have proven to be insufficient: key space is
    267 too small against current attacks, RC4 key scheduling is insufficient
    268 (beginning of the pseudorandom stream should be skipped), IV space is
    269 too small and IV reuse makes attacks easier, there is no replay
    270 protection, and non-keyed authentication does not protect against bit
    271 flipping packet data.
    272 
    273 WPA is an intermediate solution for the security issues. It uses
    274 Temporal Key Integrity Protocol (TKIP) to replace WEP. TKIP is a
    275 compromise on strong security and possibility to use existing
    276 hardware. It still uses RC4 for the encryption like WEP, but with
    277 per-packet RC4 keys. In addition, it implements replay protection,
    278 keyed packet authentication mechanism (Michael MIC).
    279 
    280 Keys can be managed using two different mechanisms. WPA can either use
    281 an external authentication server (e.g., RADIUS) and EAP just like
    282 IEEE 802.1X is using or pre-shared keys without need for additional
    283 servers. Wi-Fi calls these "WPA-Enterprise" and "WPA-Personal",
    284 respectively. Both mechanisms will generate a master session key for
    285 the Authenticator (AP) and Supplicant (client station).
    286 
    287 WPA implements a new key handshake (4-Way Handshake and Group Key
    288 Handshake) for generating and exchanging data encryption keys between
    289 the Authenticator and Supplicant. This handshake is also used to
    290 verify that both Authenticator and Supplicant know the master session
    291 key. These handshakes are identical regardless of the selected key
    292 management mechanism (only the method for generating master session
    293 key changes).
    294 
    295 
    296 IEEE 802.11i / WPA2
    297 -------------------
    298 
    299 The design for parts of IEEE 802.11i that were not included in WPA has
    300 finished (May 2004) and this amendment to IEEE 802.11 was approved in
    301 June 2004. Wi-Fi Alliance is using the final IEEE 802.11i as a new
    302 version of WPA called WPA2. This includes, e.g., support for more
    303 robust encryption algorithm (CCMP: AES in Counter mode with CBC-MAC)
    304 to replace TKIP and optimizations for handoff (reduced number of
    305 messages in initial key handshake, pre-authentication, and PMKSA caching).
    306 
    307 Some wireless LAN vendors are already providing support for CCMP in
    308 their WPA products. There is no "official" interoperability
    309 certification for CCMP and/or mixed modes using both TKIP and CCMP, so
    310 some interoperability issues can be expected even though many
    311 combinations seem to be working with equipment from different vendors.
    312 Testing for WPA2 is likely to start during the second half of 2004.
    313 
    314 hostapd configuration for WPA/WPA2
    315 ----------------------------------
    316 
    317 TODO
    318 
    319 # Enable WPA. Setting this variable configures the AP to require WPA (either
    320 # WPA-PSK or WPA-RADIUS/EAP based on other configuration). For WPA-PSK, either
    321 # wpa_psk or wpa_passphrase must be set and wpa_key_mgmt must include WPA-PSK.
    322 # For WPA-RADIUS/EAP, ieee8021x must be set (but without dynamic WEP keys),
    323 # RADIUS authentication server must be configured, and WPA-EAP must be included
    324 # in wpa_key_mgmt.
    325 # This field is a bit field that can be used to enable WPA (IEEE 802.11i/D3.0)
    326 # and/or WPA2 (full IEEE 802.11i/RSN):
    327 # bit0 = WPA
    328 # bit1 = IEEE 802.11i/RSN (WPA2)
    329 #wpa=1
    330 
    331 # WPA pre-shared keys for WPA-PSK. This can be either entered as a 256-bit
    332 # secret in hex format (64 hex digits), wpa_psk, or as an ASCII passphrase
    333 # (8..63 characters) that will be converted to PSK. This conversion uses SSID
    334 # so the PSK changes when ASCII passphrase is used and the SSID is changed.
    335 #wpa_psk=0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
    336 #wpa_passphrase=secret passphrase
    337 
    338 # Set of accepted key management algorithms (WPA-PSK, WPA-EAP, or both). The
    339 # entries are separated with a space.
    340 #wpa_key_mgmt=WPA-PSK WPA-EAP
    341 
    342 # Set of accepted cipher suites (encryption algorithms) for pairwise keys
    343 # (unicast packets). This is a space separated list of algorithms:
    344 # CCMP = AES in Counter mode with CBC-MAC [RFC 3610, IEEE 802.11i]
    345 # TKIP = Temporal Key Integrity Protocol [IEEE 802.11i]
    346 # Group cipher suite (encryption algorithm for broadcast and multicast frames)
    347 # is automatically selected based on this configuration. If only CCMP is
    348 # allowed as the pairwise cipher, group cipher will also be CCMP. Otherwise,
    349 # TKIP will be used as the group cipher.
    350 #wpa_pairwise=TKIP CCMP
    351 
    352 # Time interval for rekeying GTK (broadcast/multicast encryption keys) in
    353 # seconds.
    354 #wpa_group_rekey=600
    355 
    356 # Time interval for rekeying GMK (master key used internally to generate GTKs
    357 # (in seconds).
    358 #wpa_gmk_rekey=86400
    359 
    360 # Enable IEEE 802.11i/RSN/WPA2 pre-authentication. This is used to speed up
    361 # roaming be pre-authenticating IEEE 802.1X/EAP part of the full RSN
    362 # authentication and key handshake before actually associating with a new AP.
    363 #rsn_preauth=1
    364 #
    365 # Space separated list of interfaces from which pre-authentication frames are
    366 # accepted (e.g., 'eth0' or 'eth0 wlan0wds0'. This list should include all
    367 # interface that are used for connections to other APs. This could include
    368 # wired interfaces and WDS links. The normal wireless data interface towards
    369 # associated stations (e.g., wlan0) should not be added, since
    370 # pre-authentication is only used with APs other than the currently associated
    371 # one.
    372 #rsn_preauth_interfaces=eth0
    373 

README-WPS

      1 hostapd and Wi-Fi Protected Setup (WPS)
      2 =======================================
      3 
      4 This document describes how the WPS implementation in hostapd can be
      5 configured and how an external component on an AP (e.g., web UI) is
      6 used to enable enrollment of client devices.
      7 
      8 
      9 Introduction to WPS
     10 -------------------
     11 
     12 Wi-Fi Protected Setup (WPS) is a mechanism for easy configuration of a
     13 wireless network. It allows automated generation of random keys (WPA
     14 passphrase/PSK) and configuration of an access point and client
     15 devices. WPS includes number of methods for setting up connections
     16 with PIN method and push-button configuration (PBC) being the most
     17 commonly deployed options.
     18 
     19 While WPS can enable more home networks to use encryption in the
     20 wireless network, it should be noted that the use of the PIN and
     21 especially PBC mechanisms for authenticating the initial key setup is
     22 not very secure. As such, use of WPS may not be suitable for
     23 environments that require secure network access without chance for
     24 allowing outsiders to gain access during the setup phase.
     25 
     26 WPS uses following terms to describe the entities participating in the
     27 network setup:
     28 - access point: the WLAN access point
     29 - Registrar: a device that control a network and can authorize
     30   addition of new devices); this may be either in the AP ("internal
     31   Registrar") or in an external device, e.g., a laptop, ("external
     32   Registrar")
     33 - Enrollee: a device that is being authorized to use the network
     34 
     35 It should also be noted that the AP and a client device may change
     36 roles (i.e., AP acts as an Enrollee and client device as a Registrar)
     37 when WPS is used to configure the access point.
     38 
     39 
     40 More information about WPS is available from Wi-Fi Alliance:
     41 http://www.wi-fi.org/wifi-protected-setup
     42 
     43 
     44 hostapd implementation
     45 ----------------------
     46 
     47 hostapd includes an optional WPS component that can be used as an
     48 internal WPS Registrar to manage addition of new WPS enabled clients
     49 to the network. In addition, WPS Enrollee functionality in hostapd can
     50 be used to allow external WPS Registrars to configure the access
     51 point, e.g., for initial network setup. In addition, hostapd can proxy a
     52 WPS registration between a wireless Enrollee and an external Registrar
     53 (e.g., Microsoft Vista or Atheros JumpStart) with UPnP.
     54 
     55 
     56 hostapd configuration
     57 ---------------------
     58 
     59 WPS is an optional component that needs to be enabled in hostapd build
     60 configuration (.config). Here is an example configuration that
     61 includes WPS support and uses madwifi driver interface:
     62 
     63 CONFIG_DRIVER_MADWIFI=y
     64 CFLAGS += -I/usr/src/madwifi-0.9.3
     65 CONFIG_WPS=y
     66 CONFIG_WPS2=y
     67 CONFIG_WPS_UPNP=y
     68 
     69 Following parameter can be used to enable support for NFC config method:
     70 
     71 CONFIG_WPS_NFC=y
     72 
     73 
     74 Following section shows an example runtime configuration
     75 (hostapd.conf) that enables WPS:
     76 
     77 # Configure the driver and network interface
     78 driver=madwifi
     79 interface=ath0
     80 
     81 # WPA2-Personal configuration for the AP
     82 ssid=wps-test
     83 wpa=2
     84 wpa_key_mgmt=WPA-PSK
     85 wpa_pairwise=CCMP
     86 # Default WPA passphrase for legacy (non-WPS) clients
     87 wpa_passphrase=12345678
     88 # Enable random per-device PSK generation for WPS clients
     89 # Please note that the file has to exists for hostapd to start (i.e., create an
     90 # empty file as a starting point).
     91 wpa_psk_file=/etc/hostapd.psk
     92 
     93 # Enable control interface for PBC/PIN entry
     94 ctrl_interface=/var/run/hostapd
     95 
     96 # Enable internal EAP server for EAP-WSC (part of Wi-Fi Protected Setup)
     97 eap_server=1
     98 
     99 # WPS configuration (AP configured, do not allow external WPS Registrars)
    100 wps_state=2
    101 ap_setup_locked=1
    102 # If UUID is not configured, it will be generated based on local MAC address.
    103 uuid=87654321-9abc-def0-1234-56789abc0000
    104 wps_pin_requests=/var/run/hostapd.pin-req
    105 device_name=Wireless AP
    106 manufacturer=Company
    107 model_name=WAP
    108 model_number=123
    109 serial_number=12345
    110 device_type=6-0050F204-1
    111 os_version=01020300
    112 config_methods=label display push_button keypad
    113 
    114 # if external Registrars are allowed, UPnP support could be added:
    115 #upnp_iface=br0
    116 #friendly_name=WPS Access Point
    117 
    118 
    119 External operations
    120 -------------------
    121 
    122 WPS requires either a device PIN code (usually, 8-digit number) or a
    123 pushbutton event (for PBC) to allow a new WPS Enrollee to join the
    124 network. hostapd uses the control interface as an input channel for
    125 these events.
    126 
    127 The PIN value used in the commands must be processed by an UI to
    128 remove non-digit characters and potentially, to verify the checksum
    129 digit. "hostapd_cli wps_check_pin <PIN>" can be used to do such
    130 processing. It returns FAIL if the PIN is invalid, or FAIL-CHECKSUM if
    131 the checksum digit is incorrect, or the processed PIN (non-digit
    132 characters removed) if the PIN is valid.
    133 
    134 When a client device (WPS Enrollee) connects to hostapd (WPS
    135 Registrar) in order to start PIN mode negotiation for WPS, an
    136 identifier (Enrollee UUID) is sent. hostapd will need to be configured
    137 with a device password (PIN) for this Enrollee. This is an operation
    138 that requires user interaction (assuming there are no pre-configured
    139 PINs on the AP for a set of Enrollee).
    140 
    141 The PIN request with information about the device is appended to the
    142 wps_pin_requests file (/var/run/hostapd.pin-req in this example). In
    143 addition, hostapd control interface event is sent as a notification of
    144 a new device. The AP could use, e.g., a web UI for showing active
    145 Enrollees to the user and request a PIN for an Enrollee.
    146 
    147 The PIN request file has one line for every Enrollee that connected to
    148 the AP, but for which there was no PIN. Following information is
    149 provided for each Enrollee (separated with tabulators):
    150 - timestamp (seconds from 1970-01-01)
    151 - Enrollee UUID
    152 - MAC address
    153 - Device name
    154 - Manufacturer
    155 - Model Name
    156 - Model Number
    157 - Serial Number
    158 - Device category
    159 
    160 Example line in the /var/run/hostapd.pin-req file:
    161 1200188391	53b63a98-d29e-4457-a2ed-094d7e6a669c	Intel(R) Centrino(R)	Intel Corporation	Intel(R) Centrino(R)	-	-	1-0050F204-1
    162 
    163 Control interface data:
    164 WPS-PIN-NEEDED [UUID-E|MAC Address|Device Name|Manufacturer|Model Name|Model Number|Serial Number|Device Category]
    165 For example:
    166 <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]
    167 
    168 When the user enters a PIN for a pending Enrollee, e.g., on the web
    169 UI), hostapd needs to be notified of the new PIN over the control
    170 interface. This can be done either by using the UNIX domain socket
    171 -based control interface directly (src/common/wpa_ctrl.c provides
    172 helper functions for using the interface) or by calling hostapd_cli.
    173 
    174 Example command to add a PIN (12345670) for an Enrollee:
    175 
    176 hostapd_cli wps_pin 53b63a98-d29e-4457-a2ed-094d7e6a669c 12345670
    177 
    178 If the UUID-E is not available (e.g., Enrollee waits for the Registrar
    179 to be selected before connecting), wildcard UUID may be used to allow
    180 the PIN to be used once with any UUID:
    181 
    182 hostapd_cli wps_pin any 12345670
    183 
    184 To reduce likelihood of PIN being used with other devices or of
    185 forgetting an active PIN available for potential attackers, expiration
    186 time in seconds can be set for the new PIN (value 0 indicates no
    187 expiration):
    188 
    189 hostapd_cli wps_pin any 12345670 300
    190 
    191 If the MAC address of the enrollee is known, it should be configured
    192 to allow the AP to advertise list of authorized enrollees:
    193 
    194 hostapd_cli wps_pin 53b63a98-d29e-4457-a2ed-094d7e6a669c \
    195 	12345670 300 00:11:22:33:44:55
    196 
    197 
    198 After this, the Enrollee can connect to the AP again and complete WPS
    199 negotiation. At that point, a new, random WPA PSK is generated for the
    200 client device and the client can then use that key to connect to the
    201 AP to access the network.
    202 
    203 
    204 If the AP includes a pushbutton, WPS PBC mode can be used. It is
    205 enabled by pushing a button on both the AP and the client at about the
    206 same time (2 minute window). hostapd needs to be notified about the AP
    207 button pushed event over the control interface, e.g., by calling
    208 hostapd_cli:
    209 
    210 hostapd_cli wps_pbc
    211 
    212 At this point, the client has two minutes to complete WPS negotiation
    213 which will generate a new WPA PSK in the same way as the PIN method
    214 described above.
    215 
    216 
    217 When an external Registrar is used, the AP can act as an Enrollee and
    218 use its AP PIN. A static AP PIN (e.g., one one a label in the AP
    219 device) can be configured in hostapd.conf (ap_pin parameter). A more
    220 secure option is to use hostapd_cli wps_ap_pin command to enable the
    221 AP PIN only based on user action (and even better security by using a
    222 random AP PIN for each session, i.e., by using "wps_ap_pin random"
    223 command with a timeout value). Following commands are available for
    224 managing the dynamic AP PIN operations:
    225 
    226 hostapd_cli wps_ap_pin disable
    227 - disable AP PIN (i.e., do not allow external Registrars to use it to
    228   learn the current AP settings or to reconfigure the AP)
    229 
    230 hostapd_cli wps_ap_pin random [timeout]
    231 - generate a random AP PIN and enable it
    232 - if the optional timeout parameter is given, the AP PIN will be enabled
    233   for the specified number of seconds
    234 
    235 hostapd_cli wps_ap_pin get
    236 - fetch the current AP PIN
    237 
    238 hostapd_cli wps_ap_pin set <PIN> [timeout]
    239 - set the AP PIN and enable it
    240 - if the optional timeout parameter is given, the AP PIN will be enabled
    241   for the specified number of seconds
    242 
    243 hostapd_cli get_config
    244 - display the current configuration
    245 
    246 hostapd_cli wps_config <new SSID> <auth> <encr> <new key>
    247 examples:
    248   hostapd_cli wps_config testing WPA2PSK CCMP 12345678
    249   hostapd_cli wps_config "no security" OPEN NONE ""
    250 
    251 <auth> must be one of the following: OPEN WPAPSK WPA2PSK
    252 <encr> must be one of the following: NONE WEP TKIP CCMP
    253 
    254 
    255 Credential generation and configuration changes
    256 -----------------------------------------------
    257 
    258 By default, hostapd generates credentials for Enrollees and processing
    259 AP configuration updates internally. However, it is possible to
    260 control these operations from external programs, if desired.
    261 
    262 The internal credential generation can be disabled with
    263 skip_cred_build=1 option in the configuration. extra_cred option will
    264 then need to be used to provide pre-configured Credential attribute(s)
    265 for hostapd to use. The exact data from this binary file will be sent,
    266 i.e., it will have to include valid WPS attributes. extra_cred can
    267 also be used to add additional networks if the Registrar is used to
    268 configure credentials for multiple networks.
    269 
    270 Processing of received configuration updates can be disabled with
    271 wps_cred_processing=1 option. When this is used, an external program
    272 is responsible for creating hostapd configuration files and processing
    273 configuration updates based on messages received from hostapd over
    274 control interface. This will also include the initial configuration on
    275 first successful registration if the AP is initially set in
    276 unconfigured state.
    277 
    278 Following control interface messages are sent out for external programs:
    279 
    280 WPS-REG-SUCCESS <Enrollee MAC address <UUID-E>
    281 For example:
    282 <2>WPS-REG-SUCCESS 02:66:a0:ee:17:27 2b7093f1-d6fb-5108-adbb-bea66bb87333
    283 
    284 This can be used to trigger change from unconfigured to configured
    285 state (random configuration based on the first successful WPS
    286 registration). In addition, this can be used to update AP UI about the
    287 status of WPS registration progress.
    288 
    289 
    290 WPS-NEW-AP-SETTINGS <hexdump of AP Setup attributes>
    291 For example:
    292 <2>WPS-NEW-AP-SETTINGS 10260001011045000c6a6b6d2d7770732d74657374100300020020100f00020008102700403065346230343536633236366665306433396164313535346131663462663731323433376163666462376633393965353466316631623032306164343438623510200006024231cede15101e000844
    293 
    294 This can be used to update the externally stored AP configuration and
    295 then update hostapd configuration (followed by restarting of hostapd).
    296 
    297 
    298 WPS with NFC
    299 ------------
    300 
    301 WPS can be used with NFC-based configuration method. An NFC tag
    302 containing a password token from the Enrollee can be used to
    303 authenticate the connection instead of the PIN. In addition, an NFC tag
    304 with a configuration token can be used to transfer AP settings without
    305 going through the WPS protocol.
    306 
    307 When the AP acts as an Enrollee, a local NFC tag with a password token
    308 can be used by touching the NFC interface of an external Registrar. The
    309 wps_nfc_token command is used to manage use of the NFC password token
    310 from the AP. "wps_nfc_token enable" enables the use of the AP's NFC
    311 password token (in place of AP PIN) and "wps_nfc_token disable" disables
    312 the NFC password token.
    313 
    314 The NFC password token that is either pre-configured in the
    315 configuration file (wps_nfc_dev_pw_id, wps_nfc_dh_pubkey,
    316 wps_nfc_dh_privkey, wps_nfc_dev_pw) or generated dynamically with
    317 "wps_nfc_token <WPS|NDEF>" command. The nfc_pw_token tool from
    318 wpa_supplicant can be used to generate NFC password tokens during
    319 manufacturing (each AP needs to have its own random keys).
    320 
    321 The "wps_nfc_config_token <WPS/NDEF>" command can be used to build an
    322 NFC configuration token. The output value from this command is a hexdump
    323 of the current AP configuration (WPS parameter requests this to include
    324 only the WPS attributes; NDEF parameter requests additional NDEF
    325 encapsulation to be included). This data needs to be written to an NFC
    326 tag with an external program. Once written, the NFC configuration token
    327 can be used to touch an NFC interface on a station to provision the
    328 credentials needed to access the network.
    329 
    330 When the NFC device on the AP reads an NFC tag with a MIME media type
    331 "application/vnd.wfa.wsc", the NDEF message payload (with or without
    332 NDEF encapsulation) can be delivered to hostapd using the
    333 following hostapd_cli command:
    334 
    335 wps_nfc_tag_read <hexdump of payload>
    336 
    337 If the NFC tag contains a password token, the token is added to the
    338 internal Registrar. This allows station Enrollee from which the password
    339 token was received to run through WPS protocol to provision the
    340 credential.
    341 
    342 "nfc_get_handover_sel <NDEF> <WPS>" command can be used to build the
    343 contents of a Handover Select Message for connection handover when this
    344 does not depend on the contents of the Handover Request Message. The
    345 first argument selects the format of the output data and the second
    346 argument selects which type of connection handover is requested (WPS =
    347 Wi-Fi handover as specified in WSC 2.0).
    348 
    349 "nfc_report_handover <INIT/RESP> WPS <carrier from handover request>
    350 <carrier from handover select>" is used to report completed NFC
    351 connection handover. The first parameter indicates whether the local
    352 device initiated or responded to the connection handover and the carrier
    353 records are the selected carrier from the handover request and select
    354 messages as a hexdump.
    355