Bug 160269
| Summary: | [patch] Handbook wireless section: sand off some rough edges | ||||||
|---|---|---|---|---|---|---|---|
| Product: | Documentation | Reporter: | Warren Block <wblock> | ||||
| Component: | Books & Articles | Assignee: | Warren Block <wblock> | ||||
| Status: | Closed FIXED | ||||||
| Severity: | Affects Only Me | ||||||
| Priority: | Normal | ||||||
| Version: | Latest | ||||||
| Hardware: | Any | ||||||
| OS: | Any | ||||||
| Attachments: |
|
||||||
|
Description
Warren Block
2011-08-29 01:40:03 UTC
On Sun, Aug 28, 2011 at 5:38 PM, Warren Block <wblock@wonkity.com> wrote: > >>Number: =A0 =A0 =A0 =A0 160269 >>Category: =A0 =A0 =A0 docs >>Synopsis: =A0 =A0 =A0 [patch] Handbook wireless section: sand off some ro= ugh edges >>Confidential: =A0 no >>Severity: =A0 =A0 =A0 non-critical >>Priority: =A0 =A0 =A0 low >>Responsible: =A0 =A0freebsd-doc >>State: =A0 =A0 =A0 =A0 =A0open >>Quarter: >>Keywords: >>Date-Required: >>Class: =A0 =A0 =A0 =A0 =A0doc-bug >>Submitter-Id: =A0 current-users >>Arrival-Date: =A0 Mon Aug 29 00:40:03 UTC 2011 >>Closed-Date: >>Last-Modified: >>Originator: =A0 =A0 Warren Block >>Release: =A0 =A0 =A0 =A08-STABLE >>Organization: >>Environment: > FreeBSD lightning 8.2-STABLE FreeBSD 8.2-STABLE #0: Fri Aug 26 13:17:14 M= DT 2011 =A0 =A0 root@lightning:/usr/obj/usr/src/sys/LIGHTNING =A0i386 >>Description: > Fix some wording and punctuation in the advanced networking/wireless sect= ion of the Handbook. >>How-To-Repeat: > Read the later parts of the wireless section. >>Fix: > Apply patch. > > > > --- en_US.ISO8859-1/books/handbook/advanced-networking/chapter.sgml.orig = =A0 =A0 =A0 =A02011-08-28 17:57:28.000000000 -0600 > +++ en_US.ISO8859-1/books/handbook/advanced-networking/chapter.sgml =A0 = =A0 2011-08-28 18:35:33.000000000 -0600 > @@ -1225,7 +1225,7 @@ > =A0 =A0 =A0 =A0 =A0 =A0the 802.1X authentication protocol and uses one of= several > =A0 =A0 =A0 =A0 =A0 =A0ciphers instead of WEP for data integrity. =A0The = only > =A0 =A0 =A0 =A0 =A0 =A0cipher required by WPA is TKIP (Temporary Key Inte= grity > - =A0 =A0 =A0 =A0 =A0 Protocol) which is a cipher that extends the basic = RC4 > + =A0 =A0 =A0 =A0 =A0 Protocol). =A0TKIP is a cipher that extends the bas= ic RC4 > =A0 =A0 =A0 =A0 =A0 =A0cipher used by WEP by adding integrity checking, t= amper > =A0 =A0 =A0 =A0 =A0 =A0detection, and measures for responding to any dete= cted > =A0 =A0 =A0 =A0 =A0 =A0intrusions. =A0TKIP is designed to work on legacy = hardware > @@ -1243,7 +1243,7 @@ > =A0 =A0 =A0 =A0 =A0 =A0station and the access point using a pre-shared se= cret. > =A0 =A0 =A0 =A0 =A0 =A0The former is commonly termed WPA Enterprise with = the > =A0 =A0 =A0 =A0 =A0 =A0latter known as WPA Personal. =A0Since most people= will not > - =A0 =A0 =A0 =A0 =A0 set up a RADIUS backend server for wireless network= , > + =A0 =A0 =A0 =A0 =A0 set up a RADIUS backend server for their wireless n= etwork, > =A0 =A0 =A0 =A0 =A0 =A0WPA-PSK is by far the most commonly encountered > =A0 =A0 =A0 =A0 =A0 =A0configuration for WPA.</para> > > @@ -1258,7 +1258,7 @@ > =A0 =A0 =A0 =A0 =A0<sect5 id=3D"network-wireless-wpa-wpa-psk"> > =A0 =A0 =A0 =A0 =A0 =A0<title>WPA-PSK</title> > > - =A0 =A0 =A0 =A0 =A0 <para>WPA-PSK also known as WPA-Personal is based o= n a > + =A0 =A0 =A0 =A0 =A0 <para>WPA-PSK, also known as WPA-Personal, is based= on a > =A0 =A0 =A0 =A0 =A0 =A0 =A0pre-shared key (PSK) generated from a given pa= ssword and > =A0 =A0 =A0 =A0 =A0 =A0 =A0that will be used as the master key in the wir= eless > =A0 =A0 =A0 =A0 =A0 =A0 =A0network. =A0This means every wireless user wil= l share the > @@ -1289,7 +1289,7 @@ > =A0 =A0 =A0 =A0 =A0 =A0<programlisting>wlans_ath0=3D"wlan0" > =A0ifconfig_wlan0=3D"WPA DHCP"</programlisting> > > - =A0 =A0 =A0 =A0 =A0 <para>Then, we can bring up the interface:</para> > + =A0 =A0 =A0 =A0 =A0 <para>Then we can bring up the interface:</para> > > =A0 =A0 =A0 =A0 =A0 =A0<screen>&prompt.root; <userinput><filename>/etc/rc= .d/netif</filename> start</userinput> > =A0Starting wpa_supplicant. > @@ -1342,16 +1342,16 @@ > =A0 =A0 =A0 wme burst roaming MANUAL</screen> > > =A0 =A0 =A0 =A0 =A0 =A0<note> > - =A0 =A0 =A0 =A0 =A0 =A0 <para>If the <filename>/etc/rc.conf</filename> = is set up > + =A0 =A0 =A0 =A0 =A0 =A0 <para>If <filename>/etc/rc.conf</filename> is s= et up > =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0with the line <literal>ifconfig_wlan0=3D"D= HCP"</literal> > - =A0 =A0 =A0 =A0 =A0 =A0 =A0 then it is no need to run the > - =A0 =A0 =A0 =A0 =A0 =A0 =A0 <command>dhclient</command> command manuall= y, > + =A0 =A0 =A0 =A0 =A0 =A0 =A0 then it is not necessary to run the > + =A0 =A0 =A0 =A0 =A0 =A0 =A0 <command>dhclient</command> command manuall= y. This isn't entirely true. You can specify other options like "SYNCDHCP", "ssid <foo> DHCP", etc, and it will achieve what's described below. Manual execution of dhclient in general should be discouraged for most users. > =A0 =A0 =A0 =A0 =A0 =A0<para>EAP does not come with an encryption method,= it was > =A0 =A0 =A0 =A0 =A0 =A0 =A0decided to embed EAP inside an encrypted tunne= l. =A0Many > - =A0 =A0 =A0 =A0 =A0 =A0 types of EAP authentication methods have been d= esigned, > - =A0 =A0 =A0 =A0 =A0 =A0 the most common methods are EAP-TLS, EAP-TTLS a= nd > + =A0 =A0 =A0 =A0 =A0 =A0 types of EAP authentication methods have been d= esigned. > + =A0 =A0 =A0 =A0 =A0 =A0 The most common methods are EAP-TLS, EAP-TTLS a= nd > =A0 =A0 =A0 =A0 =A0 =A0 =A0EAP-PEAP.</para> Maybe it should say something like "There are many EAP authentication methods: the most common ones are EAP-TLS, EAP-TTLS, and EAP-PEAP" ? > =A0 =A0 =A0 =A0 =A0 =A0<para>EAP-TLS (EAP with Transport Layer Security) = is a > @@ -1555,7 +1555,7 @@ > =A0 =A0 =A0 =A0 =A0 =A0 =A0<callout arearefs=3D"co-ttls-cacert"> > =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0<para>The <literal>ca_cert</literal> field= indicates > =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0the pathname of the CA certificate fil= e. =A0This file > - =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 is needed to verify the server certific= at.</para> > + =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 is needed to verify the server certific= ate.</para> > =A0 =A0 =A0 =A0 =A0 =A0 =A0</callout> > > =A0 =A0 =A0 =A0 =A0 =A0 =A0<callout arearefs=3D"co-ttls-pha2"> > @@ -1599,10 +1599,10 @@ > > =A0 =A0 =A0 =A0 =A0 =A0<para>PEAP (Protected EAP) has been designed as an > =A0 =A0 =A0 =A0 =A0 =A0 =A0alternative to EAP-TTLS. =A0There are two type= s of PEAP > - =A0 =A0 =A0 =A0 =A0 =A0 methods, the most common one is PEAPv0/EAP-MSCH= APv2. =A0In > + =A0 =A0 =A0 =A0 =A0 =A0 methods; the most common one is PEAPv0/EAP-MSCH= APv2. =A0In That could be a colon instead. > =A0 =A0 =A0 =A0 =A0 =A0 =A0the rest of this document, we will use the PEA= P term to > =A0 =A0 =A0 =A0 =A0 =A0 =A0refer to that EAP method. =A0PEAP is the most = used EAP > - =A0 =A0 =A0 =A0 =A0 =A0 standard after EAP-TLS, in other words if you h= ave a > + =A0 =A0 =A0 =A0 =A0 =A0 standard after EAP-TLS. =A0In other words, if y= ou have a This could be a semicolon. > =A0 =A0 =A0 =A0 =A0 =A0 =A0network with mixed OSes, PEAP should be the mo= st > =A0 =A0 =A0 =A0 =A0 =A0 =A0supported standard after EAP-TLS.</para> > > @@ -1610,9 +1610,9 @@ > =A0 =A0 =A0 =A0 =A0 =A0 =A0certificate to authenticate clients by creatin= g an > =A0 =A0 =A0 =A0 =A0 =A0 =A0encrypted TLS tunnel between the client and th= e > =A0 =A0 =A0 =A0 =A0 =A0 =A0authentication server, which protects the ensu= ing > - =A0 =A0 =A0 =A0 =A0 =A0 exchange of authentication information. =A0In t= erm of > + =A0 =A0 =A0 =A0 =A0 =A0 exchange of authentication information. =A0In t= erms of > =A0 =A0 =A0 =A0 =A0 =A0 =A0security the difference between EAP-TTLS and P= EAP is > - =A0 =A0 =A0 =A0 =A0 =A0 that PEAP authentication broadcasts the usernam= e in > + =A0 =A0 =A0 =A0 =A0 =A0 that PEAP authentication broadcasts the usernam= e in the > =A0 =A0 =A0 =A0 =A0 =A0 =A0clear, only the password is sent in the encryp= ted TLS > =A0 =A0 =A0 =A0 =A0 =A0 =A0tunnel. This sentence is extremely wordy. The rest of the changes are good incremental improvements to the existing doc :). Thanks! -Garrett With all due respect to Garrett [but not his mail client's handling of whitespace], On Mon, 29 Aug 2011, Warren Block wrote: > > --- en_US.ISO8859-1/books/handbook/advanced-networking/chapter.sgml.orig 2011-08-28 17:57:28.000000000 -0600 > +++ en_US.ISO8859-1/books/handbook/advanced-networking/chapter.sgml 2011-08-28 18:35:33.000000000 -0600 > @@ -1380,16 +1380,16 @@ > <title>WPA with EAP-TLS</title> > > <para>The second way to use WPA is with an 802.1X backend > - authentication server, in this case WPA is called > - WPA-Enterprise to make difference with the less secure > - WPA-Personal with its pre-shared key. The > - authentication in WPA-Enterprise is based on EAP > + authentication server. In this case WPA is called > + WPA-Enterprise to differentiate it from the less secure > + WPA-Personal with its pre-shared key. > + Authentication in WPA-Enterprise is based on EAP > (Extensible Authentication Protocol).</para> This doesn't feel quite right; I would use "is based on the Extensible Authentication Protocol (EAP)." > > <para>EAP does not come with an encryption method, it was > decided to embed EAP inside an encrypted tunnel. Many > - types of EAP authentication methods have been designed, > - the most common methods are EAP-TLS, EAP-TTLS and > + types of EAP authentication methods have been designed. > + The most common methods are EAP-TLS, EAP-TTLS and > EAP-PEAP.</para> > > <para>EAP-TLS (EAP with Transport Layer Security) is a > @@ -1610,9 +1610,9 @@ > certificate to authenticate clients by creating an > encrypted TLS tunnel between the client and the > authentication server, which protects the ensuing > - exchange of authentication information. In term of > + exchange of authentication information. In terms of > security the difference between EAP-TTLS and PEAP is > - that PEAP authentication broadcasts the username in > + that PEAP authentication broadcasts the username in the > clear, only the password is sent in the encrypted TLS > tunnel. EAP-TTLS will use the TLS tunnel for both As Garrett mentions, this sentence is getting pretty long. I would put a comma after "security", and a linking word before "only the password is sent ...". Maybe "meaning", or "so that". > username and password.</para> > @@ -1661,7 +1661,7 @@ > first phase of the authentication (the TLS > tunnel). According to the authentication server > used, you will have to specify a specific label > - for the authentication. Most of time, the label > + for the authentication. Most of the time, the label I think the "the" in "the authentication" is not needed. > will be <quote>client EAP encryption</quote> which > is set by using <literal>peaplabel=0</literal>. > More information can be found in the > @@ -1861,8 +1861,8 @@ > <para>This output displays the card capabilities; the > <literal>HOSTAP</literal> word confirms this wireless card > can act as an Access Point. Various supported ciphers are > - also mentioned: WEP, TKIP, AES, etc., these informations > - are important to know what security protocols could be set > + also mentioned: WEP, TKIP, AES, etc., this information I would change this comma to a full stop. (Maybe a semicolon, but it would be a bit odd to have colon and semicolon in such proximity.) Thanks for assembling all these fixes into a patch! -Ben Kaduk > + is important to know what security protocols could be set > on the Access Point.</para> > > <para>The wireless device can only be put into hostap mode Looks good; thanks for doing the follow-up! -Ben Responsible Changed From-To: freebsd-doc->wblock Take. State Changed From-To: open->closed Committed. |
