Bug#382314: [pkg-wpa-devel] Bug#382314: Need to scramble wpa-psk? Apparently yes, but not obvious

[Kel Modderman]

On Saturday 12 August 2006 22:40, Eduard Bloch wrote:
> #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.

Yes, I agree. Thanks for reading the doc and providing such feedback. It will 
be improved now, according to your recommendations (as a result of your 
frustration ;-).

And of course you are right, I _do_ know the internals, and I _completely_ 
rely on the feedback of NEW users, such as yourself, to improve the docs.

>
> 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)

Ok, will look into it. Sorting hex strings from plaintext is not totally 
trivial, but string lengths can provide a good indication of what to expect 
in terms of input. String lengths should be checked for regardless of this 
exact problem in any case . . .

>
> And at least Debian's documentation clearly distinguishes between the
> key and the key (err, psk used for psk mode vs. passphrase).

Okay, if the current attempt to explain the pitfalls did not catch you, then 
it can be improved.

>
> > > 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.

Yep, simple and mergable diff, thanks.

>
> 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."

Okay, I'll queue that in my "trivial patches for upstream" list.

>
> > 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.

I mostly agree with the above. As i see it, a large part of what you have 
identified is in the layout of the documentation; putting what is immediately 
required first, and technical bullshit later.

It may take quite some time, effort and convincing to make these changes in 
upstream.

>
> > 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.

Okay, a real world of example of wpa-passphrase may have caught you. At least 
something that immediately notified you that a psk was not just a psk, there 
are in fact two types of psk ;-)

>
> > 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.

As pointed out earlier. But even these warnings are easy to miss, even more so 
when you have set this up to be automatic. But at least they assist when 
beginning the manual troubleshooting in face of problems. . .

>
> > 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...

Well, I'll try and improve the docs for future releases. I am telling you now, 
if you'd have seen the docs for previous releases you initial report would 
have had many more capitalised words ;-)

Thanks, Kel.