Bug#382314: [pkg-wpa-devel] Bug#382314: Need to scramble wpa-psk?
Apparently yes, but not obvious
Eduard Bloch
edi at gmx.de
Sat Aug 12 12:40:59 UTC 2006
#include <hallo.h>
* Kel Modderman [Sat, Aug 12 2006, 07:39:31PM]:
> Hi Eduard,
> > Then I decided to play with the tools mentioned in README.modes.gz, I
> > used wpa_passphrase, passed my essid and the old psk to it and it threw
> > me some new key inside of a "config section". When I added this new key
> > as wpa-psk in the interfaces file, it worked.
>
> Your key is a plaintext passphrase; did you wrap it in quotes like:
>
> wpa-psk "passphrase"
I have not used quotes since there we nothing but ascii letters/numbers.
And even then, README.notes explcitely says "without quotes".
> or use the special wpa-passphrase option:
>
> wpa-passphrase passphrase
Oh, yes, that is the option I needed in fact. Why have I not discovered
it before? Simply because the first example in README.notes does not
contain it and the difference is not obvious. I guess this is not
obvious from your point of view, but you know all the details but a NEW
USER does not.
So, I suggest that wpasupplicant warns if the psk does not look like a
hexadezimal string! This is a simple method to catch such cases. And
that an error message appears, aka becomes _visible_ in the output,
saying what happened, something like:
PSK KEY CHECK FAILED (psk with non-hexadecimal chars, confused with passhrase?)
CIPHER NEGOTIATION FAILED (missing cipher driver)
And at least Debian's documentation clearly distinguishes between the
key and the key (err, psk used for psk mode vs. passphrase).
> > I can only ASSUME that the programers decided to switch from a plaintext
> > pass phrase to a scrambled form. But in this case, DOCUMENT THE CHANGE
> > ON VISIBLE PLACES. Sorry, that's the minimum requirement for
> > user-friendlines.
>
>
> Please advise how we can help improve user friendliness without using
> provocative language. However, I can understand your frustration, I once had
> similar experiences with this very piece of software (and its lack of user
> friendliness).
Okay, see my attached patch for Debian docs.
In addition, I have the suggestion for upstream to print clearly visible
error messages with advices for users instead of hidding them somewhere
in the debug logs which you can get with -ddddddddd only and which you
need to filter with your mind from different internal log noise.
And I suggest to change the manpage of wpa_passphrase:
| wpa_passphrase - Set WPA passphrase for a SSID
Wrong. It does not set anything. It just generates a config snippet
AFAICS.
Better: "generates WPA-PSK configuration for a SSID/passphrase pair".
To OVERVIEW, add an explanation sentense: "The passphrase and SSID are
scrambled to generate a hexadezimal representation of the preshared
key."
> I will do, to the best of my ability, what is required to enhance the
> user-friendliness quality of wpasupplicant, but first the problem areas need
> to be clearly identified. What specifically is required to satisfy your
> experiences with wpasupplicant?
>
> Are you frustrated at our ifupdown.sh program and documentation? Or the
> upstream documentation? Or both?
Well, both. Your documentation is good, but a bit hard to overview. See
below. About upstream docs, it is not user-friendly. Look at the manpage of
wpa_supplicant. There is a quick-start chapter, but how long do you need
to actually find that quick-start chapter? I would do following changes
(no idea whether you or upstream would like to do that)...
wpa_supplicant:
OVERVIEW. Three screens, far too long. Full of technical details that
only few users need to know in that depth. Hard to extract the
information that you need for initial configuration. I would move the
chapter to the bottom and rename it to "TECHNICAL OVERVIEW". Or maybe
moved to wpa_background manpage. For a normal setup, I would begin with
an OVERVIEW chapter with just few sentenses:
"
| wpa_supplicant is a helper application used to establish secure
| connection trough wireless interfaces using an encryption mechanism
| known as WPA (a variant of IEEE 802.1X standard). wpa_supplicant
| supports various WPA modes: the simple mode with a preshared key (aka
| WPA-PSK or "WPA-Personal"), WPA with user authentication (EAP, see
| "TECHNICAL OVERVIEW" for details).
|
| From application view, wpa_supplicant is a background daemon, watching
| the state of an interface and communicating with the peer about WPA
| related issues.
|
| Several WiFi drivers on Linux and BSD do support WPA encryption: hostap,
| hermes, madwifi, atmel, wext (generic, recommended), ndiswrapper,
| broadcom, ipw, wired, bsd (generic, recommended), ndis. See SUPPORTED
| DRIVERS below for detailed explanation.
"
SUPPORTED FEATURES. Three screens listing every submode. Do I want to read
all that (unless I have trouble?)? Not really. The ones who care
will find that information either way. I would move the chapter to
bottom, together with "TECHNICAL OVERVIEW".
"AVAILABLE DRIVERS" and "SUPPORTED DRIVERS" - merge those chapters and
move the result to somewhere below COMMAND LINE OPTIONS. There is
duplicated information. When I look for the name of my NIC ("Intel") I
will find it either way.
"QUICK START" : this chapter should come immediately after the short
OVERVIEW. It should also say in the first sentenses that the actual
installation of wpa_supplicant may differ and $user should consult the
distribution's mechanisms. Eg. on Debian this is integrated into
ifupdown, I assume that some GUI tools do integrate it already somehow.
"ARCHITECTURE": should follow QUICK START.
"COMMAND LINE OPTIONS": should follow ARCHITECTURE.
>
> Would you like us to better explain the purpose/advantage of generating a
> hexadecimal psk in our documentation? Would you like us to discuss this with
> upstream and make sure the upstream manpage/docs are more clear about why
> wpa_passphrase is useful?
>
> Here is an extract from README.modes that attempts to explain the assumptions
> that our ifupdown.sh script makes:
>
> <quote>
> Notes About Managed Mode
> ========================
You will laugh... I have not found that chapter. Why? As said, I tried
the first example, assuming that I have the PSK (see, the whole world
calls the passphrase "key" or "psk"). It didn't work, no meaningfull
error messages / hints. I started debugging my connection setup, then I
looked trough the -dddd output, still got no clue. Frustrated. Tried the
old config, that worked.
> The wpasupplicant ifupdown script makes assumptions about the 'type' of input
> that is valid for each option. For example, it assumes that some input is
> plaintext and wraps quotation marks around the input before passing it on
> to wpa_cli, which then adds the input to the network block being formed via
> the wpa_supplicant ctrl_interface socket. This can be a point of confusion,
> and
> something that has tricked more than a few people in the past. For example:
I see. Then what about printing warnings to the user? Really, that is
technicaly not hard to do.
> Do we make poor assumptions? Are our assumptions not clear enough to
> understand?
Yes, my fault, I have to admit that. I have not found that chapter. When
I try to realize why, I have only one explanation: there is an example.
There is another example. Both without variable descriptions. Then there
is a lengthy description of "how it works". That is the place where I
stopped reading, since I know how it works and I only expect
non-interesting details there and EOF. But the first important
information comes two screens later (wpa_passphrase hint) and the really
useful examples come another screen later. And the chapter is called
"NOTES ABOUT MANAGED MODE", the name is a bit too generic. Though I
cannot imagine a better name now...
Eduard.
--
Schafft in der Wirklichkeit mehr Glück!
Dann braucht ihr nicht soviel Ersatz in meinen Worten.
-- Wolfgang Biermann
-------------- next part --------------
diff -u wpasupplicant-0.5.4/debian/changelog wpasupplicant-0.5.4/debian/changelog
--- wpasupplicant-0.5.4/debian/changelog
+++ wpasupplicant-0.5.4/debian/changelog
@@ -1,3 +1,19 @@
+wpasupplicant (0.5.4-6) unstable; urgency=low
+
+ * documentation change on README.Debian
+ + reordered sections by importance for a new user
+ + rewrote the first chapter to give a fluent introduction, refered to
+ wireless-tools doc ("like you configure your WEP keys" is pointless if
+ user does not do it that way and does not know what is meant that at all).
+ + add missing .gz to README.notes path
+ * README.modes:
+ + in examples, sorted variables by importance
+ + reordered chapters by importance
+ + added comments to wpa-psk and wpa-passphrase to avoid the confusion of
+ them
+
+ -- Eduard Bloch <blade at debian.org> Sat, 12 Aug 2006 13:30:42 +0200
+
wpasupplicant (0.5.4-5) unstable; urgency=low
* STDIN was not given to external mapping script correctly. Use the power of
diff -u wpasupplicant-0.5.4/debian/README.Debian wpasupplicant-0.5.4/debian/README.Debian
--- wpasupplicant-0.5.4/debian/README.Debian
+++ wpasupplicant-0.5.4/debian/README.Debian
@@ -1,15 +1,48 @@
-wpasupplicant in debian
+wpasupplicant in Debian
=======================
wpasupplicant is now integrated into ifupdown. You can configure it in
-/etc/network/interface, just like you would configure your WEP keys. Please see
-/usr/share/doc/wpasupplicant/README.modes for details.
+/etc/network/interface in a similar way to the one used for WEP keys [1]. After
+that, wpa_supplicant will be executed by ifup on request without further user
+intervention.
+
+For details about integration into the interfaces file, see
+/usr/share/doc/wpasupplicant/README.modes.gz .
+
+The old method of wpasupplicant invocation was the other way round, invoking it
+from an init script. This method is no longer recommended, however there are
+instructions below for reverting to the old behaviour.
-This means that wpasupplicant is now controlled by ifupdown, and not the other
-way round, like it used to be with the old init script method. See further below
-for instructions how to revert to the old behavior.
+[1] As described in /usr/share/doc/wireless-tools/README.Debian
+wpasupplicant, Wireless Extension 18 and the Linux 2.6.14 kernel
+================================================================
+
+WPA/WPA2 support was added in Wireless Extension 18.
+
+This version (or more correctly, WE 19) was included in the Linux 2.6.14
+kernel, and is therefore supported by 2.6.14-compliant drivers such as
+ipw2200 v1.0.8.
+
+wpasupplicant supports this new capability from 0.4.6.
+
+In order to take advantage of this WE 18 support you need to use
+wpasupplicant's wext driver. You may have previously used a specific driver
+such as "-D ipw" for older kernels, but to use the new WE 18 features in
+kernel 2.6.14 or later, you'll want to use the generic "wext" driver instead.
+
+You may check which version of Wireless Extensions your current kernel uses by
+inspecting /proc/net/wireless (the "WE" entry).
+
+wpasupplicant, Prism54 support
+==============================
+
+Note that previously this software was compiled with support for
+driver_prism54. However, this support never worked, and is still not
+supported upstream. Therefore, I've disabled this so people do not
+get the false impression that it is actually working.
+
wpa_supplicant as system daemon
===============================
@@ -59,29 +92,5 @@
-wpasupplicant, Wireless Extension 18 and the Linux 2.6.14 kernel
-================================================================
-
-WPA/WPA2 support was added in Wireless Extension 18.
-
-This version (or more correctly, WE 19) was included in the Linux 2.6.14
-kernel, and is therefore supported by 2.6.14-compliant drivers such as
-ipw2200 v1.0.8.
-
-wpasupplicant supports this new capability from 0.4.6.
-
-In order to take advantage of this WE 18 support you need to use
-wpasupplicant's wext driver. You may have previously used a specific driver
-such as "-D ipw" for older kernels, but to use the new WE 18 features in
-kernel 2.6.14 or later, you'll want to use the generic "wext" driver instead.
-
-You may check which version of Wireless Extensions your current kernel uses by
-inspecting /proc/net/wireless (the "WE" entry).
-
-wpasupplicant, Prism54 support
-==============================
-
-Note that previously this software was compiled with support for
-driver_prism54. However, this support never worked, and is still not
-supported upstream. Therefore, I've disabled this so people do not
-get the false impression that it is actually working.
-
-- Kyle McMartin <kyle at debian.org>
Sat Jan 28 14:12:20 EST 2006
+
+ -- Eduard Bloch <blade at debian.org>
+ Sat, 12 Aug 2006 13:38:39 +0200
diff -u wpasupplicant-0.5.4/debian/README.modes wpasupplicant-0.5.4/debian/README.modes
--- wpasupplicant-0.5.4/debian/README.modes
+++ wpasupplicant-0.5.4/debian/README.modes
@@ -13,9 +13,9 @@
2. Mode #1: Managed Mode
- Examples
- - How It Works
- Table of Common Options
- Notes About Managed Mode
+ - How It Works
3. Mode #2: Roaming Mode
- wpa_supplicant.conf
@@ -88,11 +88,12 @@
# Connect to access point of ssid 'homezone' with an encryption type of
# WPA-PSK/WPA2-PSK, using the the 'wext' driver backend of wpa_supplicant
-# The psk is given as a hexadecimal string, without quotes. DHCP is used to
-# obtain a network address.
+# The psk is given as an encoded hexadecimal string, without quotes. DHCP is
+# used to obtain a network address.
iface wlan0 inet dhcp
wpa-driver wext
wpa-ssid homezone
+ # encoded from the plaintext passphrase, see options description below
wpa-psk 000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f
# Connect to access point of ssid 'HotSpot1' and bssid of '00:1a:2b:3c:4d:5e'
@@ -100,19 +101,21 @@
# backend of wpa_supplicant. The passphrase is given as a plaintext string,
# without quotes. A static network address assignment is used.
iface ath0 inet static
- wpa-driver madwifi
- wpa-ssid HotSpot1
- wpa-bssid 00:1a:2b:3c:4d:5e
- wpa-passphrase madhotspot
- wpa-key-mgmt WPA-PSK
- wpa-pairwise TKIP CCMP
- wpa-group TKIP CCMP
- wpa-proto WPA RSN
- address 192.168.0.100
- netmask 255.255.255.0
- network 192.168.0.0
- broadcast 192.168.0.255
- gateway 192.168.0.1
+ wpa-driver madwifi
+ wpa-ssid HotSpot1
+ wpa-bssid 00:1a:2b:3c:4d:5e
+ # human readable passphrase instead of wpa-psk, see below
+ wpa-passphrase madhotspot
+ wpa-key-mgmt WPA-PSK
+ wpa-pairwise TKIP CCMP
+ wpa-group TKIP CCMP
+ wpa-proto WPA RSN
+ # usual settings
+ address 192.168.0.100
+ netmask 255.255.255.0
+ network 192.168.0.0
+ broadcast 192.168.0.255
+ gateway 192.168.0.1
# User supplied wpa_supplicant.conf is used for eth1. All network information
# is contained within the user supplied wpa_supplicant.conf. No wpa-driver type
@@ -120,41 +123,12 @@
iface eth1 inet dhcp
wpa-conf /path/to/wpa_supplicant.conf
-How It Works
-============
-
-As mentioned earlier, each wpa_supplicant specific element is prefixed with
-'wpa-'. Each element correlates to a property of wpa_supplicant described in
-the wpa_supplicant.conf(5), wpa_supplicant(8) and wpa_cli(8) manpages. The
-supplicant is launched without any pre-configuration whatsoever, and wpa_cli
-forms a network configuration from the input provided by the 'wpa-*' lines.
-Initially, wpa_supplicant/wpa_cli does not directly set the properties of the
-device (like setting an essid with iwconfig, for example), rather it informs
-the device of what access point is suitable to associate with. Once the device
-has scanned the area, and found that the suitable access point is available for
-use, these properties are set.
-
-The script that does all the work is located at:
-
- /etc/wpa_supplicant/ifupdown.sh
-
-It is executed by run-parts, which in turn is invoked by ifupdown during the
-'pre-up', 'pre-down' and 'post-down' phases.
-
-In the 'pre-up' phase, a wpa_supplicant daemon is launched, if wpa-roam is used
-a wpa_cli daemon is lauched and then there is a series of wpa_cli commands that
-set up a network configuration according to what 'wpa-' options were used in
-/etc/network/interfaces for the physical device.
-
-In the 'pre-down' phase, the wpa_cli daemon is killed if it exists.
-
-In the 'post-down' phase, the wpa_supplicant daemon is killed.
-
Table of Common Options
=======================
-A brief summary of common 'wpa-' options that may be used in the
-/etc/network/interfaces stanza for a wireless device:
+Here is a brief summary of common 'wpa-' options that may be used in the
+/etc/network/interfaces stanza for a wireless device. See below for hints about
+valid or invalid input.
NOTE: ALL values are CASE SeNsItVe
@@ -228,6 +202,36 @@
# Valid, unquoted plaintext string
wpa-passphrase validinput
+How It Works
+============
+
+As mentioned earlier, each wpa_supplicant specific element is prefixed with
+'wpa-'. Each element correlates to a property of wpa_supplicant described in
+the wpa_supplicant.conf(5), wpa_supplicant(8) and wpa_cli(8) manpages. The
+supplicant is launched without any pre-configuration whatsoever, and wpa_cli
+forms a network configuration from the input provided by the 'wpa-*' lines.
+Initially, wpa_supplicant/wpa_cli does not directly set the properties of the
+device (like setting an essid with iwconfig, for example), rather it informs
+the device of what access point is suitable to associate with. Once the device
+has scanned the area, and found that the suitable access point is available for
+use, these properties are set.
+
+The script that does all the work is located at:
+
+ /etc/wpa_supplicant/ifupdown.sh
+
+It is executed by run-parts, which in turn is invoked by ifupdown during the
+'pre-up', 'pre-down' and 'post-down' phases.
+
+In the 'pre-up' phase, a wpa_supplicant daemon is launched, if wpa-roam is used
+a wpa_cli daemon is lauched and then there is a series of wpa_cli commands that
+set up a network configuration according to what 'wpa-' options were used in
+/etc/network/interfaces for the physical device.
+
+In the 'pre-down' phase, the wpa_cli daemon is killed if it exists.
+
+In the 'post-down' phase, the wpa_supplicant daemon is killed.
+
3. Mode #2: Roaming Mode
========================
More information about the Pkg-wpa-devel
mailing list