First draft of WPA page master
authorjrmarino <jrmarino@web>
Fri, 27 Mar 2015 21:10:02 +0000 (21:10 +0000)
committerCharlie Root <root@leaf.dragonflybsd.org>
Fri, 27 Mar 2015 21:10:02 +0000 (21:10 +0000)
docs/docs/newhandbook/WirelessNetwork/index.mdwn

index 066831f..a692e9b 100644 (file)
@@ -103,11 +103,11 @@ Once this information has been added to /boot/loader.conf, reboot the DragonFly
     ath0: [ITHREAD]
     ath0: AR2413 mac 7.9 RF2413 phy 4.5
 
-### Infrastructure Mode
+## Infrastructure Mode
 
 Infrastructure (BSS) mode is the mode that is typically used. In this mode, a number of wireless access points are connected to a wired network. Each wireless network has its own name, called the SSID. Wireless clients connect to the wireless access points.
 
-#### How to Find Access Points
+### How to Find Access Points
 
 To scan for available networks, use ifconfig(8). This request may take a few moments to complete as it requires the system to switch to each available wireless frequency and probe for available access points. Only the superuser can initiate a scan:
 
@@ -136,13 +136,13 @@ One can also display the current list of known networks with:
 
 This information may be updated automatically by the adapter or manually with a scan request. Old data is automatically removed from the cache, so over time this list may shrink unless more scans are done.
 
-#### Basic Settings
+### Basic Settings
 
 This section provides a simple example of how to make the wireless network adapter work in DragonFly without encryption. Once familiar with these concepts, it is strongly recommend to use WPA to set up the wireless network.
 
 There are three basic steps to configure a wireless network: select an access point, authenticate the station, and configure an IP address. The following sections discuss each step.
 
-##### Selecting an Access Point
+#### Selecting an Access Point
 
 Most of the time, it is sufficient to let the system choose an access point using the builtin heuristics. This is the default behaviour when an interface is marked as up or it is listed in */etc/rc.conf*:
 
@@ -166,7 +166,7 @@ There are other ways to constrain the choice of an access point, such as limitin
 
 This example will force the card to operate in 802.11g, which is defined only for 2.4GHz frequencies so any 5GHz channels will not be considered. This can also be achieved with the channel parameter, which locks operation to one specific frequency, and the chanlist parameter, to specify a list of channels for scanning. More information about these parameters can be found in ifconfig(8).
 
-##### Authentication
+#### Authentication
 
 Once an access point is selected, the station needs to authenticate before it can pass data. Authentication can happen in several ways. The most common scheme, open authentication, allows any station to join the network and communicate. This is the authentication to use for test purposes the first time a wireless network is setup. Other schemes require cryptographic handshakes to be completed before data traffic can flow, either using pre-shared keys or secrets, or more complex schemes that involve backend services such as RADIUS. Open authentication is the default setting. The next most common setup is WPA-PSK, also known as WPA Personal.
 
@@ -177,7 +177,7 @@ _Note_: If using an Apple® AirPort® Extreme base station for an access point,
 
 In general, shared key authentication should be avoided because it uses the WEP key material in a highly-constrained manner, making it even easier to crack the key. If WEP must be used for compatibility with legacy devices, it is better to use WEP with open authentication.
 
-##### Getting an IP Address with DHCP
+#### Getting an IP Address with DHCP
 
 Once an access point is selected and the authentication parameters are set, an IP address must be obtained in order to communicate. Most of the time, the IP address is obtained via DHCP. To achieve that, edit */etc/rc.conf* and add DHCP to the configuration for the device:
 
@@ -203,14 +203,14 @@ Once the interface is running, use ifconfig(8) to see the status of the interfac
 
 The *status: associated line* means that it is connected to the wireless network. The bssid *00:13:46:49:41:76* is the MAC address of the access point and authmode OPEN indicates that the communication is not encrypted.
 
-##### Static IP Address
+#### Static IP Address
 
 In an IP address cannot be obtained from a DHCP server, set a fixed IP address. Replace the DHCP keyword shown above with the address information. Be sure to retain any other parameters for selecting the access point:
 
     wlans_ath0="wlan0"
     ifconfig_wlan0="inet 192.168.1.100 netmask 255.255.255.0 ssid your_ssid_here"
 
-#### WPA
+### WPA
 
 Wi-Fi Protected Access (WPA) is a security protocol used together with 802.11 networks to address the lack of proper authentication and the weakness of WEP. WPA leverages the 802.1X authentication protocol and uses one of several ciphers instead of WEP for data integrity. The only cipher required by WPA is the Temporary Key Integrity Protocol (TKIP). TKIP is a cipher that extends the basic RC4 cipher used by WEP by adding integrity checking, tamper detection, and measures for responding to detected intrusions. TKIP is designed to work on legacy hardware with only software modification. It represents a compromise that improves security but is still not entirely immune to attack. WPA also specifies the AES-CCMP cipher as an alternative to TKIP, and that is preferred when possible. For this specification, the term WPA2 or RSN is commonly used.
 
@@ -218,7 +218,7 @@ WPA defines authentication and encryption protocols. Authentication is most comm
 
 The control of the wireless connection and the key negotiation or authentication with a server is done using wpa_supplicant(8). This program requires a configuration file, */etc/wpa_supplicant.conf*, to run. More information regarding this file can be found in wpa_supplicant.conf(5).
  
-##### WPA-PSK
+#### WPA-PSK
 
 WPA-PSK, also known as WPA Personal, is based on a pre-shared key (PSK) which is generated from a given password and used as the master key in the wireless network. This means every wireless user will share the same key. WPA-PSK is intended for small networks where the use of an authentication server is not possible or desired.
 
@@ -226,7 +226,7 @@ The first step is the configuration of */etc/wpa_supplicant.conf* with the SSID
 
     network={
       ssid="dragonap"
-      psk="freebsdmall"
+      psk="dragonmall"
     }
 
 Then, in */etc/rc.conf*, indicate that the wireless device configuration will be done with WPA and the IP address will be obtained with DHCP:
@@ -303,7 +303,7 @@ When DHCP is not used, the default gateway and the nameserver also have to be ma
     > route add default your_default_router
     > echo "nameserver your_DNS_server" >> /etc/resolv.conf
 
-##### WPA with EAP-TLS
+#### WPA with EAP-TLS
 
 The second way to use WPA is with an 802.1X backend authentication server. In this case, WPA is called WPA Enterprise to differentiate it from the less secure WPA Personal. Authentication in WPA Enterprise is based on the Extensible Authentication Protocol (EAP).
 
@@ -322,7 +322,7 @@ As previously, the configuration is done via */etc/wpa_supplicant.conf*:
       ca_cert="/etc/certs/cacert.pem"          [6]
       client_cert="/etc/certs/clientcert.pem"  [7]
       private_key="/etc/certs/clientkey.pem"   [8]
-      private_key_passwd="freebsdmallclient"   [9]
+      private_key_passwd="dragonmallclient"    [9]
     }
 
  1. This field indicates the network name (SSID).
@@ -361,7 +361,7 @@ The next step is to bring up the interface:
 
 It is also possible to bring up the interface manually using wpa_supplicant(8) and ifconfig(8).
  
-##### WPA with EAP-TTLS
+#### WPA with EAP-TTLS
 
 With EAP-TTLS, both the authentication server and the client need a certificate. With EAP-TTLS, a client certificate is optional. This method is similar to a web server which creates a secure SSL tunnel even if visitors do not have client-side certificates. EAP-TTLS uses an encrypted TLS tunnel for safe transport of the authentication data.
 
@@ -409,7 +409,7 @@ The next step is to bring up the interface:
           bgscanintvl 300 bgscanidle 250 roam:rssi 7 roam:rate 5 protmode CTS
           wme burst roaming MANUAL
  
-##### WPA with EAP-PEAP
+#### WPA with EAP-PEAP
 
 _Note_: PEAPv0/EAP-MSCHAPv2 is the most common PEAP method. In this chapter, the term PEAP is used to refer to that method.
 
@@ -463,7 +463,7 @@ Then, bring up the interface:
           bgscanintvl 300 bgscanidle 250 roam:rssi 7 roam:rate 5 protmode CTS
           wme burst roaming MANUAL
 
-#### WEP
+### WEP
 
 Wired Equivalent Privacy (WEP) is part of the original 802.11 standard. There is no authentication mechanism, only a weak form of access control which is easily cracked.
 
@@ -474,7 +474,6 @@ WEP can be set up using ifconfig(8):
       ssid my_net wepmode on weptxkey 3 wepkey 3:0x3456789012
 
  + The *weptxkey* specifies which WEP key will be used in the transmission. This example uses the third key. This must match the setting on the access point. When unsure which key is used by the access point, try 1 (the first key) for this value.
-
  + The *wepkey* selects one of the WEP keys. It should be in the format *index:key*. Key 1 is used by default; the index only needs to be set when using a key other than the first key.
 
 _Note_: Replace the 0x3456789012 with the key configured for use on the access point.
@@ -496,6 +495,223 @@ Then:
     Trying to associate with 00:13:46:49:41:76 (SSID='dlinkap' freq=2437 MHz)
     Associated with 00:13:46:49:41:76
 
-### Ad-hoc Mode
+## Ad-hoc Mode
+
+IBSS mode, also called ad-hoc mode, is designed for point to point connections. For example, to establish an ad-hoc network between the machines _A_ and _B_, choose two IP addresses and a SSID.
+
+On _A_:
+
+    > ifconfig wlan0 create wlandev ath0 wlanmode adhoc
+    > ifconfig wlan0 inet 192.168.0.1 netmask 255.255.255.0 ssid dragonap
+    > ifconfig wlan0
+      wlan0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> metric 0 mtu 1500
+         ether 00:11:95:c3:0d:ac
+         inet 192.168.0.1 netmask 0xffffff00 broadcast 192.168.0.255
+         media: IEEE 802.11 Wireless Ethernet autoselect mode 11g <adhoc>
+         status: running
+         ssid dragonap channel 2 (2417 Mhz 11g) bssid 02:11:95:c3:0d:ac
+         country US ecm authmode OPEN privacy OFF txpower 21.5 scanvalid 60
+         protmode CTS wme burst
+
+The *adhoc* parameter indicates that the interface is running in IBSS mode.
+
+_B_ should now be able to detect _A_:
+
+    > ifconfig wlan0 create wlandev ath0 wlanmode adhoc
+    > ifconfig wlan0 up scan
+      SSID/MESH ID    BSSID              CHAN RATE   S:N     INT CAPS
+      dragonap       02:11:95:c3:0d:ac    2   54M -64:-96  100 IS   WME
+
+The *I* in the output confirms that _A_ is in ad-hoc mode. Now, configure _B_ with a different IP address:
+
+    > ifconfig wlan0 inet 192.168.0.2 netmask 255.255.255.0 ssid dragonap
+    > ifconfig wlan0
+      wlan0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> metric 0 mtu 1500
+         ether 00:11:95:d5:43:62
+         inet 192.168.0.2 netmask 0xffffff00 broadcast 192.168.0.255
+         media: IEEE 802.11 Wireless Ethernet autoselect mode 11g <adhoc>
+         status: running
+         ssid dragonap channel 2 (2417 Mhz 11g) bssid 02:11:95:c3:0d:ac
+         country US ecm authmode OPEN privacy OFF txpower 21.5 scanvalid 60
+         protmode CTS wme burst
+
+Both _A_ and _B_ are now ready to exchange information.
+
+## DragonFly Host Access Points
+
+DragonFly BSD can act as an Access Point (AP) which eliminates the need to buy a hardware AP or run an ad-hoc network. This can be particularly useful when a DragonFly machine is acting as a gateway to another network such as the Internet.
+
+### Basic Settings
+
+Before configuring a DragonFly machine as an AP, the kernel must be configured with the appropriate networking support for the wireless card as well as the security protocols being used. For more details, see "Basic Setup"
+
+_Note_: The NDIS driver wrapper for Windows® drivers does not currently support AP operation. Only native DragonFly wireless drivers support AP mode.
+
+Once wireless networking support is loaded, check if the wireless device supports the host-based access point mode, also known as hostap mode:
+
+    > ifconfig wlan0 create wlandev ath0
+    > ifconfig wlan0 list caps
+    drivercaps=6f85edc1<STA,FF,TURBOP,IBSS,HOSTAP,AHDEMO,TXPMGT,SHSLOT,SHPREAMBLE,MONITOR,MBSS,WPA1,WPA2,BURST,WME,WDS,BGSCAN,TXFRAG>
+    cryptocaps=1f<WEP,TKIP,AES,AES_CCM,TKIPMIC>
+
+This output displays the card's capabilities. The HOSTAP word confirms that this wireless card can act as an AP. Various supported ciphers are also listed: WEP, TKIP, and AES. This information indicates which security protocols can be used on the AP.
+
+The wireless device can only be put into hostap mode during the creation of the network pseudo-device, so a previously created device must be destroyed first:
+
+    > ifconfig wlan0 destroy
+
+then regenerated with the correct option before setting the other parameters:
+
+    > ifconfig wlan0 create wlandev ath0 wlanmode hostap
+    > ifconfig wlan0 inet 192.168.0.1 netmask 255.255.255.0 ssid dragonap mode 11g channel 1
+
+Use ifconfig(8) again to see the status of the wlan0 interface:
+
+    > ifconfig wlan0
+      wlan0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> metric 0 mtu 1500
+         ether 00:11:95:c3:0d:ac
+         inet 192.168.0.1 netmask 0xffffff00 broadcast 192.168.0.255
+         media: IEEE 802.11 Wireless Ethernet autoselect mode 11g <hostap>
+         status: running
+         ssid dragonap channel 1 (2412 Mhz 11g) bssid 00:11:95:c3:0d:ac
+         country US ecm authmode OPEN privacy OFF txpower 21.5 scanvalid 60
+         protmode CTS wme burst dtimperiod 1 -dfs
+
+The hostap parameter indicates the interface is running in the host-based access point mode.
+
+The interface configuration can be done automatically at boot time by adding the following lines to */etc/rc.conf*:
+
+    wlans_ath0="wlan0"
+    create_args_wlan0="wlanmode hostap"
+    ifconfig_wlan0="inet 192.168.0.1 netmask 255.255.255.0 ssid dragonap mode 11g channel 1"
+
+### Host-based Access Point Without Authentication or Encryption
+
+Although it is not recommended to run an AP without any authentication or encryption, this is a simple way to check if the AP is working. This configuration is also important for debugging client issues.
+
+Once the AP is configured, initiate a scan from another wireless machine to find the AP:
+
+    > ifconfig wlan0 create wlandev ath0
+    > ifconfig wlan0 up scan
+    SSID/MESH ID    BSSID              CHAN RATE   S:N     INT CAPS
+    dragonap        00:11:95:c3:0d:ac    1   54M -66:-96  100 ES   WME
+
+The client machine found the AP and can be associated with it:
+
+    > ifconfig wlan0 inet 192.168.0.2 netmask 255.255.255.0 ssid dragonap
+    > ifconfig wlan0
+      wlan0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> metric 0 mtu 1500
+         ether 00:11:95:d5:43:62
+         inet 192.168.0.2 netmask 0xffffff00 broadcast 192.168.0.255
+         media: IEEE 802.11 Wireless Ethernet OFDM/54Mbps mode 11g
+         status: associated
+         ssid dragonfap channel 1 (2412 Mhz 11g) bssid 00:11:95:c3:0d:ac
+         country US ecm authmode OPEN privacy OFF txpower 21.5 bmiss 7
+         scanvalid 60 bgscan bgscanintvl 300 bgscanidle 250 roam:rssi 7
+         roam:rate 5 protmode CTS wme burst
+
+### WPA Host-based Access Point
+
+This section focuses on setting up a DragonFly AP using the WPA security protocol. More details regarding WPA and the configuration of WPA-based wireless clients can be found in "WPA" Section.
+
+The hostapd(8) daemon is used to deal with client authentication and key management on the WPA-enabled AP.
+
+The following configuration operations are performed on the DragonFly machine acting as the AP. Once the AP is correctly working, hostapd(8) should be automatically enabled at boot with the following line in */etc/rc.conf*:
+
+    hostapd_enable="YES"
+
+Before trying to configure hostapd(8), first configure the basic settings.
+
+#### WPA-PSK
+
+WPA-PSK is intended for small networks where the use of a backend authentication server is not possible or desired.
+
+The configuration is done in */etc/hostapd.conf*:
+
+    interface=wlan0                   [1]
+    debug=1                           [2]
+    ctrl_interface=/var/run/hostapd   [3]
+    ctrl_interface_group=wheel        [4]
+    ssid=dragonap                     [5]
+    wpa=1                             [6]
+    wpa_passphrase=dragonmall         [7]
+    wpa_key_mgmt=WPA-PSK              [8]
+    wpa_pairwise=CCMP TKIP            [9]
+
+ 1. This field indicates the wireless interface used for the AP.
+ 2. This field sets the level of verbosity during the execution of hostapd(8). A value of 1 represents the minimal level.
+ 3. The ctrl_interface field gives the pathname of the directory used by hostapd(8) to store its domain socket files for the communication with external programs such as hostapd_cli(8). The default value is used in this example.
+ 4. The ctrl_interface_group line sets the group which is allowed to access the control interface files.
+ 5. This field sets the network name.
+ 6. The wpa field enables WPA and specifies which WPA authentication protocol will be required. A value of 1 configures the AP for WPA-PSK.
+ 7. The wpa_passphrase field contains the ASCII passphrase for WPA authentication.
+ 8. The wpa_key_mgmt line refers to the key management protocol to use. This example sets WPA-PSK.
+ 9. The wpa_pairwise field indicates the set of accepted encryption algorithms by the AP. In this example, both TKIP (WPA) and CCMP (WPA2) ciphers are accepted. The CCMP cipher is an alternative to TKIP and is strongly preferred when possible. TKIP should be used solely for stations incapable of doing CCMP.
+
+The next step is to start hostapd(8):
+
+    > service hostapd forcestart
+
+    > ifconfig wlan0
+      wlan0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 2290
+         inet 192.168.0.1 netmask 0xffffff00 broadcast 192.168.0.255
+         inet6 fe80::211:95ff:fec3:dac%ath0 prefixlen 64 scopeid 0x4
+         ether 00:11:95:c3:0d:ac
+         media: IEEE 802.11 Wireless Ethernet autoselect mode 11g <hostap>
+         status: associated
+         ssid dragonap channel 1 bssid 00:11:95:c3:0d:ac
+         authmode WPA2/802.11i privacy MIXED deftxkey 2 TKIP 2:128-bit txpowmax 36 protmode CTS dtimperiod 1 bintval 100
+
+Once the AP is running, the clients can associate with it. See "WPA" Section for more details. It is possible to see the stations associated with the AP using *ifconfig wlan0 list sta*.
+
+### WEP Host-based Access Point
+
+It is not recommended to use WEP for setting up an AP since there is no authentication mechanism and the encryption is easily cracked. Some legacy wireless cards only support WEP and these cards will only support an AP without authentication or encryption.
+
+The wireless device can now be put into hostap mode and configured with the correct SSID and IP address:
+
+    > ifconfig wlan0 create wlandev ath0 wlanmode hostap
+    > ifconfig wlan0 inet 192.168.0.1 netmask 255.255.255.0 \
+       ssid dragonap wepmode on weptxkey 3 wepkey 3:0x3456789012 mode 11g
+
+ + The *weptxkey* indicates which WEP key will be used in the transmission. This example uses the third key as key numbering starts with 1. This parameter must be specified in order to encrypt the data.
+ + The *wepkey* sets the selected WEP key. It should be in the format *index:key*. If the index is not given, key 1 is set. The index needs to be set when using keys other than the first key.
+
+Use ifconfig(8) to see the status of the wlan0 interface:
+
+    # ifconfig wlan0
+      wlan0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> metric 0 mtu 1500
+         ether 00:11:95:c3:0d:ac
+         inet 192.168.0.1 netmask 0xffffff00 broadcast 192.168.0.255
+         media: IEEE 802.11 Wireless Ethernet autoselect mode 11g <hostap>
+         status: running
+         ssid dragonap channel 4 (2427 Mhz 11g) bssid 00:11:95:c3:0d:ac
+         country US ecm authmode OPEN privacy ON deftxkey 3 wepkey 3:40-bit
+         txpower 21.5 scanvalid 60 protmode CTS wme burst dtimperiod 1 -dfs
+
+From another wireless machine, it is now possible to initiate a scan to find the AP:
+
+    > ifconfig wlan0 create wlandev ath0
+    > ifconfig wlan0 up scan
+    SSID            BSSID              CHAN RATE  S:N   INT CAPS
+    dragonfap        00:11:95:c3:0d:ac    1   54M 22:1   100 EPS
+
+In this example, the client machine found the AP and can associate with it using the correct parameters. See "WEP" for more details.
+
+## Using Both Wired and Wireless Connections
+
+A wired connection provides better performance and reliability, while a wireless connection provides flexibility and mobility. Laptop users typically want to roam seamlessly between the two types of connections.
+
+On DragonFly, it is possible to combine two or even more network interfaces together in a “failover” fashion. This type of configuration uses the most preferred and available connection from a group of network interfaces, and the operating system switches automatically when the link state changes.
+
+## Troubleshooting
+
+This section describes a number of steps to help troubleshoot common wireless networking problems.
+
+ + If the access point is not listed when scanning, check that the configuration has not limited the wireless device to a limited set of channels.
+ + If the device cannot associate with an access point, verify that the configuration matches the settings on the access point. This includes the authentication scheme and any security protocols. Simplify the configuration as much as possible. If using a security protocol such as WPA or WEP, configure the access point for open authentication and no security to see if traffic will pass.  Debugging support is provided by wpa_supplicant(8). Try running this utility manually with -dd and look at the system logs.
+ + Once the system can associate with the access point, diagnose the network configuration using tools like ping(8).
+ + There are many lower-level debugging tools. Debugging messages can be enabled in the 802.11 protocol support layer using wlandebug(8).
 
-IBSS mode, also called ad-hoc mode, is designed for point to point connections. For example, to establish an ad-hoc network between the machines A and B, choose two IP addresses and a SSID.
+    > wlandebug -i ath0 +scan+auth+debug+assoc
+      net.wlan.0.debug: 0 => 0xc80000<assoc,auth,scan>