Updated usage, deprecated -S

README.md

@@ -1,6 +1,6 @@
 # Overview [![License](https://img.shields.io/badge/License-GPL%20v3%2B-blue.svg?style=flat-square)](https://github.com/wiire/pixiewps/blob/master/LICENSE.md)
 
-**Pixiewps** is a tool written in C used to **bruteforce offline** the WPS PIN exploiting the low or non-existing entropy of some Access Points, the so-called "pixie dust attack" discovered by Dominique Bongard in summer 2014. It is meant for educational purposes only.
+**Pixiewps** is a tool written in C used to **bruteforce offline** the WPS PIN exploiting the low or non-existing entropy of some Access Points, the so-called "pixie-dust attack" discovered by Dominique Bongard in summer 2014. It is meant for educational purposes only.
 
 As opposed to the traditional online brute-force attack, implemented in tools like Reaver or Bully which aim to recover the pin in a few hours, this method can get the PIN in only a matter of **milliseconds** to **minutes**, depending on the target, **if vulnerable**.
 
@@ -68,9 +68,7 @@ Optional arguments:
 
   -m, --r-nonce     : Registrar nonce
   -b, --e-bssid     : Enrollee BSSID
-  -S, --dh-small    : Small Diffie-Hellman keys (PKr not needed)  [No]
-  -f, --force       : Brute-force timestamp seed
-  -l, --length      : Brute-force entire pin length (experimental)
+  -l, --length      : Bruteforce entire pin length (experimental)
   -v, --verbosity   : Verbosity level 1-3, 1 is quietest           [3]
   -o, --output      : Write output to file
   -j, --jobs        : Number of parallel threads to use         [Auto]
@@ -80,8 +78,9 @@ Optional arguments:
   -V, --version     : Display version
 
   --mode N[,... N]  : Mode selection, comma separated           [Auto]
-  --start [mm/]yyyy : Starting date (only mode 3)             [+1 day]
-  --end   [mm/]yyyy : Ending date   (only mode 3)             [-1 day]
+  --start [mm/]yyyy : Starting date             (only mode 3) [+1 day]
+  --end   [mm/]yyyy : Ending date               (only mode 3) [-1 day]
+  -f, --force       : Bruteforce full range     (only mode 3)
 
 Miscellaneous arguments:
 
@@ -102,15 +101,18 @@ which requires a modified version of Reaver or Bully which prints the *Authentic
 The program has also a man page and a verbose help screen (`--help`) with more examples.
 
 ## -S, --dh-small
-This feature was introduced back in Reaver 1.4. It works by choosing the private key = 1, thus resulting in having the public key `--pkr` = 2. This speeds up the cracking process since the AP must do less computations to calculate the Diffie-Hellman shared secret, which is later used to derive the session keys that encrypt the current transaction. Pixiewps can exploit this feature so that the user doesn't have to input `--pkr` (it's always 2) and optionally compute the session keys, like `--authkey`, if additional arguments, `--r-nonce` and `--bssid`, are specified.
+This feature was introduced back in Reaver 1.3. It works by choosing the private key = 1, thus resulting in having the public key `--pkr` = 2. This speeds up the cracking process since the AP must do less computations to calculate the Diffie-Hellman shared secret, which is later used to derive the session keys that encrypt the current transaction. Pixiewps can exploit this feature so that the user doesn't have to input `--pkr` (it's always 2) and optionally compute the session keys, like `--authkey`, if additional arguments, `--r-nonce` and `--bssid`, are specified.
 
-It turns out some routers are buggy and do not function correctly with this feature. Some won't even be able to validate the correct PIN and the transaction will fail after M4. For this reason this feature should **never be used** in Reaver.
+It turns out some routers are buggy and do not function correctly with this feature. Some won't even be able to validate the correct PIN and the transaction will fail after M4. For this reason this feature is **deprecated** and should **never be used** in Reaver.
 
 ## -7, --m7-enc
 This option requires the attribute *encrypted settings* found in M7 when the Registrar proved knowledge of the PIN, and the Access Points, the Enrollee, sends its current network configuration.
 
 This feature can be used to crack the WPA-PSK (and WPS PIN) from a passive packet capture (e.g. sniffing a PBC session).
 
+## -f, --force
+This option is used only for mode 3. When used pixiewps will start bruteforcing from the current time and go back all the way to 0. It is conceptually identical to using `--end 01/1970` only (or `--start 01/1970` since they're interchangeable).
+
 ## Empty PIN
 The empty PIN, denoted with `<empty>` can be tested with `-p ""` in Reaver [1.6.1](https://github.com/t6x/reaver-wps-fork-t6x/releases/tag/v1.6.1) and later. It comes from a misconfiguration of the WPS pin method on some Access Points which have the pin variable set to `NULL` (or empty string).
 

pixiewps.1

@@ -4,7 +4,7 @@
 .SH DESCRIPTION
 .IP
 Pixiewps is a tool written in C used to bruteforce offline the WPS PIN method exploiting
-the low or non-existing entropy of some Access Points, the so-called "pixie dust attack".
+the low or non-existing entropy of some Access Points, the so-called "pixie-dust attack".
 .IP
 It is meant for educational purposes only.
 .IP

src/pixiewps.h

@@ -118,8 +118,8 @@ struct global {
 
 char usage[] =
 	"\n"
-	" Pixiewps %s WPS pixie dust attack tool\n"
-	" Copyright (c) 2015-2016, wiire <wi7ire@gmail.com>\n"
+	" Pixiewps %s WPS pixie-dust attack tool\n"
+	" Copyright (c) 2015-2017, wiire <wi7ire@gmail.com>\n"
 	"\n"
 	" Usage: %s <arguments>\n"
 	"\n"
@@ -136,106 +136,114 @@ char usage[] =
 	"\n"
 	"   -m, --r-nonce     : Registrar nonce\n"
 	"   -b, --e-bssid     : Enrollee BSSID\n"
-	"   -S, --dh-small    : Small Diffie-Hellman keys (PKr not needed)  [No]\n"
-	"   -f, --force       : Brute-force timestamp seed\n"
-	"   -l, --length      : Brute-force entire pin length (experimental)\n"
+//	"   -S, --dh-small    : Small Diffie-Hellman keys (PKr not needed)  [No]\n"
+	"   -l, --length      : Bruteforce entire pin length (experimental)\n"
 	"   -v, --verbosity   : Verbosity level 1-3, 1 is quietest           [3]\n"
 	"   -o, --output      : Write output to file\n"
 	"   -j, --jobs        : Number of parallel threads to use         [Auto]\n"
 	"\n"
 	"   -h                : Display this usage screen\n"
 	"   --help            : Verbose help and more usage examples\n"
-	"   -V, --version     : Displays version\n"
+	"   -V, --version     : Display version\n"
 	"\n"
 	"   --mode N[,... N]  : Mode selection, comma separated           [Auto]\n"
-	"   --start [mm/]yyyy : Starting date (only mode 3)             [+1 day]\n"
-	"   --end   [mm/]yyyy : Ending date   (only mode 3)             [-1 day]\n"
+	"   --start [mm/]yyyy : Starting date             (only mode 3) [+1 day]\n"
+	"   --end   [mm/]yyyy : Ending date               (only mode 3) [-1 day]\n"
+	"   -f, --force       : Bruteforce full range     (only mode 3)\n"
 	"\n"
 	" Miscellaneous arguments:\n"
 	"\n"
 	"   -7, --m7-enc      : Recover encrypted settings from M7 (only mode 3)\n"
 	"   -5, --m5-enc      : Recover secret nonce from M5       (only mode 3)\n"
 	"\n"
-	" Example:\n"
+	" Example (use --help for more):\n"
 	"\n"
 	" pixiewps -e <pke> -r <pkr> -s <e-hash1> -z <e-hash2> -a <authkey> -n <e-nonce>\n"
 	"%s";
 
 char v_usage[] =
 	"\n"
-	" Pixiewps %s WPS pixie dust attack tool\n"
-	" Copyright (c) 2015-2016, wiire <wi7ire@gmail.com>\n"
+	" Pixiewps %s WPS pixie-dust attack tool\n"
+	" Copyright (c) 2015-2017, wiire <wi7ire@gmail.com>\n"
 	"\n"
 	" Description of arguments:\n"
 	"\n"
 	" -e, --pke\n"
 	"\n"
-	"    Enrollee DH public key, found in M1.\n"
+	"     Enrollee's DH public key, found in M1.\n"
 	"\n"
 	" -r, --pkr\n"
 	"\n"
-	"    Registrar DH public key, found in M2. It can be avoided by specifying "
-	"--dh-small in both Reaver and Pixiewps.\n"
-	"\n"
-	"  [?] pixiewps -e <pke> -s <e-hash1> -z <e-hash2> -a <authkey> -n <e-nonce> -S\n"
+	"     Registrar's DH public key, found in M2.\n"
 	"\n"
 	" -s, --e-hash1\n"
 	"\n"
-	"    Enrollee hash-1, found in M3.\n"
+	"     Enrollee hash-1, found in M3. It's the hash of the first half of the PIN.\n"
 	"\n"
 	" -z, --e-hash2\n"
 	"\n"
-	"    Enrollee hash-2, found in M3.\n"
+	"     Enrollee hash-2, found in M3. It's the hash of the second half of the PIN.\n"
 	"\n"
 	" -a, --authkey\n"
 	"\n"
-	"    Authentication session key. Although for this parameter a modified version of "
+	"     Authentication session key. Although for this parameter a modified version of "
 	"Reaver or Bully is needed, it can be avoided by specifying small Diffie-Hellman "
 	"keys in both Reaver and Pixiewps and supplying --e-nonce, --r-nonce and --e-bssid.\n"
 	"\n"
-	"  [?] pixiewps -e <pke> -s <e-hash1> -z <e-hash2> -S -n <e-nonce> -m <r-nonce> -b <e-bssid>\n"
+	" [?] pixiewps -e <pke> -s <e-hash1> -z <e-hash2> -S -n <e-nonce> -m <r-nonce> -b <e-bssid>\n"
 	"\n"
 	" -n, --e-nonce\n"
 	"\n"
-	"    Enrollee's nonce, found in M1.\n"
+	"     Enrollee's nonce, found in M1.\n"
 	"\n"
 	" -m, --r-nonce\n"
 	"\n"
-	"    Registrar's nonce, found in M2.\n"
+	"     Registrar's nonce, found in M2. Used with other parameters to compute the session keys.\n"
 	"\n"
 	" -b, --e-bssid\n"
 	"\n"
-	"    Enrollee's BSSID.\n"
+	"     Enrollee's BSSID. Used with other parameters to compute the session keys.\n"
 	"\n"
-	" -S, --dh-small\n"
+	" -S, --dh-small (deprecated)\n"
 	"\n"
-	"    Small Diffie-Hellman keys. The same option MUST be specified in Reaver "
-	"(1.3 or later versions) too. This option DOES NOT WORK (currently) with mode 3.\n"
+	"     Small Diffie-Hellman keys. The same option must be specified in Reaver too. "
+	"Some Access Points seem to be buggy and don't behave correctly with this option. "
+	"Avoid using it with Reaver when possible\n"
 	"\n"
 	" --mode N[,... N]\n"
 	"\n"
-	"    Select modes, comma separated (experimental modes are not used unless specified):\n"
+	"     Select modes, comma separated (experimental modes are not used unless specified):\n"
 	"\n"
-	"      1 (%s)\n"
-	"      2 (%s)\n"
-	"      3 (%s)\n"
-	"      4 (%s) [Experimental]\n"
-	"      5 (%s)    [Experimental]\n"
+	"         1 (%s)\n"
+	"         2 (%s)\n"
+	"         3 (%s)\n"
+	"         4 (%s) [Experimental]\n"
+	"         5 (%s)    [Experimental]\n"
 	"\n"
 	" --start [mm/]yyyy\n"
 	" --end   [mm/]yyyy\n"
 	"\n"
-	"    Starting and ending dates for mode 3. They are interchangeable. "
-	"If only one is specified, the machine current time will be used for the other. "
-	"The earliest possible date is 01/1970 corresponding to 0 (Epoch time).\n"
+	"     Starting and ending dates for mode 3. They are interchangeable. "
+	"If only one is specified, the current time will be used for the other. "
+	"The earliest possible date is 01/1970, corresponding to 0 (Unix epoch time), "
+	"the latest is 02/2038, corresponding to 0x7FFFFFFF. If --force is used then "
+	"pixiewps will start from the current time and go back all the way to 0.\n"
+	"\n"
+	" -7, --m7-enc\n"
+	"\n"
+	"     Encrypted settings, found in M7. Recover Enrollee's WPA-PSK and secret nonce 2. "
+	"This feature only works on some Access Points vulnerable to mode 3.\n"
+	"\n"
+	" [?] pixiewps -e <pke> -r <pkr> -n <e-nonce> -m <r-nonce> -b <e-bssid> -7 <enc7> --mode 3\n"
 	"\n"
-	" -7, --m7-enc      : Recover encrypted settings from M7 (only mode 3)\n"
+	" -5, --m5-enc\n"
 	"\n"
-	"    Recover encrypted settings. It's the attribute in M7 that contains the current "
-	"configuration of the Access Point (enrollee). This option WORKS (currently) only with mode 3 "
-	"with a limited number of models and requires --pke, --pkr, --e-nonce, --r-nonce and --e-bssid\n"
+	"     Encrypted settings, found in M5. Recover Enrollee's secret nonce 1. "
+	"This option must be used in conjunction with --m7-enc. If --e-hash1 and "
+	"--e-hash2 are also specified, pixiewps will also recover the WPS PIN.\n"
 	"\n"
-	"  [?] pixiewps -7 <enc> -e <pke> -r <pkr> -n <e-nonce> -m <r-nonce> -b <e-bssid> --mode 3\n"
+	" [?] pixiewps -e <pke> -r <pkr> -n <e-nonce> -m <r-nonce> -b <e-bssid> -7 <enc7> -5 <enc5> --mode 3\n"
+	" [?] pixiewps -e <pke> -r <pkr> -n <e-nonce> -m <r-nonce> -b <e-bssid> -7 <enc7> -5 <enc5> -s <e-hash1> -z <e-hash2> --mode 3\n"
 	"\n";
 
 /* One digit comma separated number parsing */