Merge branch 'moonshot' of ssh://moonshot.suchdamage.org:822/srv/git/libeap into...

[libeap.git] / hostapd / README-WPS

diff --git a/hostapd/README-WPS b/hostapd/README-WPS
index b46d767..c052df6 100644 (file)
--- a/hostapd/README-WPS
+++ b/hostapd/README-WPS
@@ -62,8 +62,8 @@ includes WPS support and uses madwifi driver interface:
 
 CONFIG_DRIVER_MADWIFI=y
 CFLAGS += -I/usr/src/madwifi-0.9.3
-CONFIG_EAP=y
 CONFIG_WPS=y
+CONFIG_WPS2=y
 CONFIG_WPS_UPNP=y
 
 
@@ -120,6 +120,13 @@ 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
@@ -165,10 +172,24 @@ 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:
+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
@@ -189,6 +210,36 @@ 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
+
+
 Credential generation and configuration changes
 -----------------------------------------------