diff options
authorJouni Malinen <j@w1.fi>2008-11-30 15:42:58 (GMT)
committerJouni Malinen <j@w1.fi>2008-11-30 15:42:58 (GMT)
commitbd034191abfdca60e2ee4c82f840c3e681856afc (patch)
parenta8d05fca5f14fc3b89cc408a58c47fad7470364e (diff)
WPS: Added initial documentation on using WPS with wpa_supplicant
1 files changed, 130 insertions, 0 deletions
diff --git a/wpa_supplicant/README-WPS b/wpa_supplicant/README-WPS
new file mode 100644
index 0000000..85c8960
--- /dev/null
+++ b/wpa_supplicant/README-WPS
@@ -0,0 +1,130 @@
+wpa_supplicant and Wi-Fi Protected Setup (WPS)
+This document describes how the WPS implementation in wpa_supplicant
+can be configured and how an external component on the client (e.g.,
+management GUI) is used to enable WPS enrollment and registrar
+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:
+wpa_supplicant implementation
+wpa_supplicant includes an optional WPS component that can be used as
+an Enrollee to enroll new network credential or as a Registrar to
+configure an AP. The current version of wpa_supplicant does not
+support operation as an external WLAN Management Registrar for adding
+new client devices or configuring the AP over UPnP.
+wpa_supplicant configuration
+WPS is an optional component that needs to be enabled in
+wpa_supplicant build configuration (.config). Here is an example
+configuration that includes WPS support and Linux wireless extensions
+-based driver interface:
+WPS needs the Universally Unique IDentifier (UUID; see RFC 4122) for
+the device. This is configured in the runtime configuration for
+# example UUID for WPS
+The network configuration blocks needed for WPS are added
+automatically based on control interface commands, so they do not need
+to be added explicitly in the configuration file.
+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. wpa_supplicant uses the control interface as an input channel
+for these events.
+If the client device has a display, a random PIN has to be generated
+for each WPS registration session. wpa_supplicant can do this with a
+control interface request, e.g., by calling wpa_cli:
+wpa_cli wps_pin any
+This will return the generated 8-digit PIN which will then need to be
+entered at the Registrar to complete WPS registration. At that point,
+the client will be enrolled with credentials needed to connect to the
+AP to access the network.
+If the client device does not have a display that could show the
+random PIN, a hardcoded PIN that is printed on a label can be
+used. wpa_supplicant is notified this with a control interface
+request, e.g., by calling wpa_cli:
+wpa_cli wps_pin any 12345670
+This starts the WPS negotiation in the same way as above with the
+generated PIN.
+If the client design wants to support optional WPS PBC mode, this can
+be enabled by either a physical button in the client device or a
+virtual button in the user interface. The PBC operation requires that
+a button is also pressed at the AP/Registrar at about the same time (2
+minute window). wpa_supplicant is notified of the local button event
+over the control interface, e.g., by calling wpa_cli:
+wpa_cli wps_pbc
+At this point, the AP/Registrar has two minutes to complete WPS
+negotiation which will generate a new WPA PSK in the same way as the
+PIN method described above.
+If the client wants to operation in the Registrar role to configure an
+AP, wpa_supplicant is notified over the control interface, e.g., with
+wpa_cli wps_reg <AP BSSID> <AP PIN>
+(example: wpa_cli wps_reg 02:34:56:78:9a:bc 12345670)