hostap/wpa_supplicant/doc/docbook/wpa_supplicant.sgml - nest-learning-thermostat/5.6.2/hostap - Git at Google

 <!doctype refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">

 <refentry>
   <refmeta>
     <refentrytitle>wpa_supplicant</refentrytitle>
     <manvolnum>8</manvolnum>
   </refmeta>
   <refnamediv>
     <refname>wpa_supplicant</refname>
     <refpurpose>Wi-Fi Protected Access client and IEEE 802.1X supplicant</refpurpose>
   </refnamediv>
   <refsynopsisdiv>
     <cmdsynopsis>
       <command>wpa_supplicant</command>
       <arg>-BddfhKLqqtuvW</arg>
       <arg>-i<replaceable>ifname</replaceable></arg>
       <arg>-c<replaceable>config file</replaceable></arg>
       <arg>-D<replaceable>driver</replaceable></arg>
       <arg>-P<replaceable>PID_file</replaceable></arg>
       <arg>-f<replaceable>output file</replaceable></arg>
     </cmdsynopsis>
   </refsynopsisdiv>
   <refsect1>
     <title>Overview</title>

     <para>
     Wireless networks do not require physical access to the network equipment
     in the same way as wired networks. This makes it easier for unauthorized
     users to passively monitor a network and capture all transmitted frames.
     In addition, unauthorized use of the network is much easier. In many cases,
     this can happen even without user's explicit knowledge since the wireless
     LAN adapter may have been configured to automatically join any available
     network.
     </para>

     <para>
     Link-layer encryption can be used to provide a layer of security for
     wireless networks. The original wireless LAN standard, IEEE 802.11,
     included a simple encryption mechanism, WEP. However, that proved to
     be flawed in many areas and network protected with WEP cannot be consider
     secure. IEEE 802.1X authentication and frequently changed dynamic WEP keys
     can be used to improve the network security, but even that has inherited
     security issues due to the use of WEP for encryption. Wi-Fi Protected
     Access and IEEE 802.11i amendment to the wireless LAN standard introduce
     a much improvement mechanism for securing wireless networks. IEEE 802.11i
     enabled networks that are using CCMP (encryption mechanism based on strong
     cryptographic algorithm AES) can finally be called secure used for
     applications which require efficient protection against unauthorized
     access.
     </para>

     <para><command>wpa_supplicant</command> is an implementation of
     the WPA Supplicant component, i.e., the part that runs in the
     client stations. It implements WPA key negotiation with a WPA
     Authenticator and EAP authentication with Authentication
     Server. In addition, it controls the roaming and IEEE 802.11
     authentication/association of the wireless LAN driver.</para>

     <para><command>wpa_supplicant</command> is designed to be a
     "daemon" program that runs in the background and acts as the
     backend component controlling the wireless
     connection. <command>wpa_supplicant</command> supports separate
     frontend programs and an example text-based frontend,
     <command>wpa_cli</command>, is included with
     wpa_supplicant.</para>

     <para>Before wpa_supplicant can do its work, the network interface
     must be available.  That means that the physical device must be
     present and enabled, and the driver for the device must be
     loaded. The daemon will exit immediately if the device is not already
     available.</para>

     <para>After <command>wpa_supplicant</command> has configured the
     network device, higher level configuration such as DHCP may
     proceed.  There are a variety of ways to integrate wpa_supplicant
     into a machine's networking scripts, a few of which are described
     in sections below.</para>

     <para>The following steps are used when associating with an AP
     using WPA:</para>

     <itemizedlist>
       <listitem>
 	<para><command>wpa_supplicant</command> requests the kernel
 	driver to scan neighboring BSSes</para>
       </listitem>

       <listitem>
 	<para><command>wpa_supplicant</command> selects a BSS based on
 	its configuration</para>
       </listitem>

       <listitem>
 	<para><command>wpa_supplicant</command> requests the kernel
         driver to associate with the chosen BSS</para>
       </listitem>

       <listitem>
 	<para>If WPA-EAP: integrated IEEE 802.1X Supplicant
         completes EAP authentication with the
         authentication server (proxied by the Authenticator in the
         AP)</para>
       </listitem>

       <listitem>
 	<para>If WPA-EAP: master key is received from the IEEE 802.1X
 	Supplicant</para>
       </listitem>

       <listitem>
 	<para>If WPA-PSK: <command>wpa_supplicant</command> uses PSK
 	as the master session key</para>
       </listitem>

       <listitem>
 	<para><command>wpa_supplicant</command> completes WPA 4-Way
         Handshake and Group Key Handshake with the Authenticator
         (AP)</para>
       </listitem>

       <listitem>
 	<para><command>wpa_supplicant</command> configures encryption
 	keys for unicast and broadcast</para>
       </listitem>

       <listitem>
 	<para>normal data packets can be transmitted and received</para>
       </listitem>
     </itemizedlist>
   </refsect1>

   <refsect1>
     <title>Supported Features</title>
     <para>Supported WPA/IEEE 802.11i features:</para>
     <itemizedlist>
       <listitem>
 	<para>WPA-PSK ("WPA-Personal")</para>
       </listitem>

       <listitem>
 	<para>WPA with EAP (e.g., with RADIUS authentication server)
        ("WPA-Enterprise") Following authentication methods are
        supported with an integrate IEEE 802.1X Supplicant:</para>

 	<itemizedlist>
 	  <listitem>
 	    <para>EAP-TLS</para>
 	  </listitem>
 	</itemizedlist>

 	<itemizedlist>
 	  <listitem>
 	    <para>EAP-PEAP/MSCHAPv2 (both PEAPv0 and PEAPv1)</para>
 	  </listitem>


 	  <listitem>
 	    <para>EAP-PEAP/TLS (both PEAPv0 and PEAPv1)</para>
 	  </listitem>

 	  <listitem>
 	    <para>EAP-PEAP/GTC (both PEAPv0 and PEAPv1)</para>
 	  </listitem>

 	  <listitem>
 	    <para>EAP-PEAP/OTP (both PEAPv0 and PEAPv1)</para>
 	  </listitem>

 	  <listitem>
 	    <para>EAP-PEAP/MD5-Challenge (both PEAPv0 and PEAPv1)</para>
 	  </listitem>

 	  <listitem>
 	    <para>EAP-TTLS/EAP-MD5-Challenge</para>
 	  </listitem>

 	  <listitem>
 	    <para>EAP-TTLS/EAP-GTC</para>
 	  </listitem>

           <listitem><para>EAP-TTLS/EAP-OTP</para></listitem>

           <listitem><para>EAP-TTLS/EAP-MSCHAPv2</para></listitem>

           <listitem><para>EAP-TTLS/EAP-TLS</para></listitem>

           <listitem><para>EAP-TTLS/MSCHAPv2</para></listitem>

           <listitem><para>EAP-TTLS/MSCHAP</para></listitem>

           <listitem><para>EAP-TTLS/PAP</para></listitem>

           <listitem><para>EAP-TTLS/CHAP</para></listitem>

           <listitem><para>EAP-SIM</para></listitem>

           <listitem><para>EAP-AKA</para></listitem>

           <listitem><para>EAP-PSK</para></listitem>

           <listitem><para>EAP-PAX</para></listitem>

           <listitem><para>LEAP (note: requires special support from
           the driver for IEEE 802.11 authentication)</para></listitem>

           <listitem><para>(following methods are supported, but since
           they do not generate keying material, they cannot be used
           with WPA or IEEE 802.1X WEP keying)</para></listitem>

           <listitem><para>EAP-MD5-Challenge </para></listitem>

           <listitem><para>EAP-MSCHAPv2</para></listitem>

           <listitem><para>EAP-GTC</para></listitem>

           <listitem><para>EAP-OTP</para></listitem>
 	</itemizedlist>
       </listitem>

       <listitem>
 	<para>key management for CCMP, TKIP, WEP104, WEP40</para>
       </listitem>

       <listitem>
 	<para>RSN/WPA2 (IEEE 802.11i)</para>
 	<itemizedlist>
 	  <listitem>
 	    <para>pre-authentication</para>
 	  </listitem>

 	  <listitem>
 	    <para>PMKSA caching</para>
 	  </listitem>
 	</itemizedlist>
       </listitem>
     </itemizedlist>
   </refsect1>

   <refsect1>
     <title>Available Drivers</title>
     <para>A summary of available driver backends is below. Support for each
     of the driver backends is chosen at wpa_supplicant compile time. For a
     list of supported driver backends that may be used with the -D option on
     your system, refer to the help output of wpa_supplicant
     (<emphasis>wpa_supplicant -h</emphasis>).</para>

     <variablelist>
       <varlistentry>
 	<term>wext</term>
 	<listitem>
 	  <para>Linux wireless extensions (generic).</para>
 	</listitem>
       </varlistentry>

       <varlistentry>
 	<term>wired</term>
 	<listitem>
 	  <para>wpa_supplicant wired Ethernet driver</para>
 	</listitem>
       </varlistentry>

       <varlistentry>
 	<term>roboswitch</term>
 	<listitem>
 	  <para>wpa_supplicant Broadcom switch driver</para>
 	</listitem>
       </varlistentry>

       <varlistentry>
 	<term>bsd</term>
 	<listitem>
 	  <para>BSD 802.11 support (Atheros, etc.).</para>
 	</listitem>
       </varlistentry>

       <varlistentry>
 	<term>ndis</term>
 	<listitem>
 	  <para>Windows NDIS driver.</para>
 	</listitem>
       </varlistentry>
     </variablelist>
   </refsect1>

   <refsect1>
     <title>Command Line Options</title>
     <para>Most command line options have global scope. Some are given per
     interface, and are only valid if at least one <option>-i</option> option
     is specified, otherwise they're ignored. Option groups for different
     interfaces must be separated by <option>-N</option> option.</para>
     <variablelist>
       <varlistentry>
 	<term>-b br_ifname</term>
 	<listitem>
 	  <para>Optional bridge interface name. (Per interface)</para>
 	</listitem>
       </varlistentry>

       <varlistentry>
 	<term>-B</term>
 	<listitem>
 	  <para>Run daemon in the background.</para>
 	</listitem>
       </varlistentry>

       <varlistentry>
 	<term>-c filename</term>
 	<listitem>
 	  <para>Path to configuration file. (Per interface)</para>
 	</listitem>
       </varlistentry>

       <varlistentry>
 	<term>-C ctrl_interface</term>
 	<listitem>
 	  <para>Path to ctrl_interface socket (Per interface. Only used if
 		  <option>-c</option> is not).</para>
 	</listitem>
       </varlistentry>

       <varlistentry>
 	<term>-i ifname</term>
 	<listitem>
 	  <para>Interface to listen on. Multiple instances of this option can
 	  be present, one per interface, separated by <option>-N</option>
 	  option (see below).</para>
 	</listitem>
       </varlistentry>

       <varlistentry>
 	<term>-d</term>
 	<listitem>
 	  <para>Increase debugging verbosity (<option>-dd</option> even
 		  more).</para>
 	</listitem>
       </varlistentry>

       <varlistentry>
 	<term>-D driver</term>
 	<listitem>
 	  <para>Driver to use (can be multiple drivers: nl80211,wext).
 		  (Per interface, see the available options below.)</para>
 	</listitem>
       </varlistentry>

       <varlistentry>
 	<term>-f output file</term>
 	<listitem>
 	  <para>Log output to specified file instead of stdout.</para>
 	</listitem>
       </varlistentry>

       <varlistentry>
 	<term>-g global ctrl_interface</term>
 	<listitem>
 	  <para>Path to global ctrl_interface socket. If specified, interface
 	  definitions may be omitted.</para>
 	</listitem>
       </varlistentry>

       <varlistentry>
 	<term>-K</term>
 	<listitem>
 	  <para>Include keys (passwords, etc.) in debug output.</para>
 	</listitem>
       </varlistentry>

       <varlistentry>
 	<term>-t</term>
 	<listitem>
 	  <para>Include timestamp in debug messages.</para>
 	</listitem>
       </varlistentry>

       <varlistentry>
 	<term>-h</term>
 	<listitem>
 	  <para>Help.  Show a usage message.</para>
 	</listitem>
       </varlistentry>

       <varlistentry>
 	<term>-L</term>
 	<listitem>
 	  <para>Show license (BSD).</para>
 	</listitem>
       </varlistentry>

       <varlistentry>
 	<term>-p</term>
 	<listitem>
 	  <para>Driver parameters. (Per interface)</para>
 	</listitem>
       </varlistentry>

       <varlistentry>
 	<term>-P PID_file</term>
 	<listitem>
 	  <para>Path to PID file.</para>
 	</listitem>
       </varlistentry>

       <varlistentry>
 	<term>-q</term>
 	<listitem>
 	  <para>Decrease debugging verbosity (<option>-qq</option> even
 		  less).</para>
 	</listitem>
       </varlistentry>

       <varlistentry>
 	<term>-u</term>
 	<listitem>
 	  <para>Enabled DBus control interface. If enabled, interface
 	  definitions may be omitted.</para>
 	</listitem>
       </varlistentry>

       <varlistentry>
 	<term>-v</term>
 	<listitem>
 	  <para>Show version.</para>
 	</listitem>
       </varlistentry>

       <varlistentry>
 	<term>-W</term>
 	<listitem>
 	  <para>Wait for a control interface monitor before starting.</para>
 	</listitem>
       </varlistentry>

       <varlistentry>
 	<term>-N</term>
 	<listitem>
 	  <para>Start describing new interface.</para>
 	</listitem>
       </varlistentry>
     </variablelist>
   </refsect1>

   <refsect1>
     <title>Examples</title>

     <para>In most common cases, <command>wpa_supplicant</command> is
     started with:</para>

 <blockquote><programlisting>
 wpa_supplicant -B -c/etc/wpa_supplicant.conf -iwlan0
 </programlisting></blockquote>

     <para>This makes the process fork into background.</para>

     <para>The easiest way to debug problems, and to get debug log for
     bug reports, is to start <command>wpa_supplicant</command> on
     foreground with debugging enabled:</para>

 <blockquote><programlisting>
 wpa_supplicant -c/etc/wpa_supplicant.conf -iwlan0 -d
 </programlisting></blockquote>

     <para>If the specific driver wrapper is not known beforehand, it is
     possible to specify multiple comma separated driver wrappers on the command
     line. <command>wpa_supplicant</command> will use the first driver
     wrapper that is able to initialize the interface.</para>

 <blockquote><programlisting>
 wpa_supplicant -Dnl80211,wext -c/etc/wpa_supplicant.conf -iwlan0
 </programlisting></blockquote>

     <para><command>wpa_supplicant</command> can control multiple
     interfaces (radios) either by running one process for each
     interface separately or by running just one process and list of
     options at command line. Each interface is separated with -N
     argument. As an example, following command would start
     wpa_supplicant for two interfaces:</para>

 <blockquote><programlisting>
 wpa_supplicant \
 	-c wpa1.conf -i wlan0 -D nl80211 -N \
 	-c wpa2.conf -i ath0 -D wext
 </programlisting></blockquote>
   </refsect1>

   <refsect1>
     <title>OS Requirements</title>
     <para>Current hardware/software requirements:</para>

     <itemizedlist>
       <listitem>
 	<para>Linux kernel 2.4.x or 2.6.x with Linux Wireless
 	Extensions v15 or newer</para>
       </listitem>


       <listitem>
 	<para>FreeBSD 6-CURRENT</para>
       </listitem>

       <listitem>
 	<para>Microsoft Windows with WinPcap (at least WinXP, may work
 	with other versions)</para>
       </listitem>
     </itemizedlist>
   </refsect1>

   <refsect1>
     <title>Supported Drivers</title>
     <variablelist>
       <varlistentry>
 	<term>Linux wireless extensions</term>
 	<listitem>
 	  <para>In theory, any driver that supports Linux wireless
 	extensions can be used with IEEE 802.1X (i.e., not WPA) when
 	using ap_scan=0 option in configuration file.</para>
 	</listitem>
       </varlistentry>

       <varlistentry>
 	<term>Wired Ethernet drivers</term>
 	<listitem>
 	  <para>Use ap_scan=0.</para>
 	</listitem>
       </varlistentry>

       <varlistentry>
 	<term>BSD net80211 layer (e.g., Atheros driver)</term>
 	<listitem>
 	  <para>At the moment, this is for FreeBSD 6-CURRENT branch.</para>
 	</listitem>
       </varlistentry>

       <varlistentry>
 	<term>Windows NDIS</term>
 	<listitem>
 	  <para>The current Windows port requires WinPcap
 	(http://winpcap.polito.it/).  See README-Windows.txt for more
 	information.</para>
 	</listitem>
       </varlistentry>
     </variablelist>


     <para>wpa_supplicant was designed to be portable for different
     drivers and operating systems. Hopefully, support for more wlan
     cards and OSes will be added in the future. See developer.txt for
     more information about the design of wpa_supplicant and porting to
     other drivers. One main goal is to add full WPA/WPA2 support to
     Linux wireless extensions to allow new drivers to be supported
     without having to implement new driver-specific interface code in
     wpa_supplicant.</para>
   </refsect1>

   <refsect1>
     <title>Architecture</title> <para>The
     <command>wpa_supplicant</command> system consists of the following
     components:</para>

     <variablelist>
       <varlistentry>
 	<term><filename>wpa_supplicant.conf</filename> </term>
 	<listitem>
         <para>the configuration file describing all networks that the
         user wants the computer to connect to.  </para>
 	</listitem>
       </varlistentry>
       <varlistentry>
 	<term><command>wpa_supplicant</command></term>
         <listitem><para>the program that directly interacts with the
         network interface.  </para></listitem>
       </varlistentry>
       <varlistentry>
 	<term><command>wpa_cli</command></term> <listitem><para> the
 	client program that provides a high-level interface to the
 	functionality of the daemon.  </para></listitem>
       </varlistentry>
       <varlistentry>
 	<term><command>wpa_passphrase</command></term>
         <listitem><para>a utility needed to construct
         <filename>wpa_supplicant.conf</filename> files that include
         encrypted passwords.</para></listitem>
       </varlistentry>
     </variablelist>
   </refsect1>

   <refsect1>
     <title>Quick Start</title>

     <para>First, make a configuration file, e.g.
     <filename>/etc/wpa_supplicant.conf</filename>, that describes the networks
     you are interested in.  See <citerefentry>
 	<refentrytitle>wpa_supplicant.conf</refentrytitle>
 	<manvolnum>5</manvolnum>
       </citerefentry>
     for details.</para>

     <para>Once the configuration is ready, you can test whether the
     configuration works by running <command>wpa_supplicant</command>
     with following command to start it on foreground with debugging
     enabled:</para>

     <blockquote><programlisting>
 wpa_supplicant -iwlan0 -c/etc/wpa_supplicant.conf -d
     </programlisting></blockquote>

     <para>Assuming everything goes fine, you can start using following
     command to start <command>wpa_supplicant</command> on background
     without debugging:</para>

     <blockquote><programlisting>
 wpa_supplicant -iwlan0 -c/etc/wpa_supplicant.conf -B
     </programlisting></blockquote>

     <para>Please note that if you included more than one driver
     interface in the build time configuration (.config), you may need
     to specify which interface to use by including -D&lt;driver
     name&gt; option on the command line.</para>

     <!-- XXX at this point, the page could include a little script
          based on wpa_cli to wait for a connection and then run
          dhclient -->

   </refsect1>

   <refsect1>
     <title>Interface to pcmcia-cs/cardmrg</title>

     <para>For example, following small changes to pcmcia-cs scripts
     can be used to enable WPA support:</para>

     <para>Add MODE="Managed" and WPA="y" to the network scheme in
     <filename>/etc/pcmcia/wireless.opts</filename>.</para>

     <para>Add the following block to the end of <emphasis>start</emphasis>
     action handler in <filename>/etc/pcmcia/wireless</filename>:</para>

     <blockquote><programlisting>
 if [ "$WPA" = "y" -a -x /usr/local/bin/wpa_supplicant ]; then
     /usr/local/bin/wpa_supplicant -B -c/etc/wpa_supplicant.conf -i$DEVICE
 fi
     </programlisting></blockquote>


     <para>Add the following block to the end of <emphasis>stop</emphasis>
     action handler (may need to be separated from other actions) in
     <filename>/etc/pcmcia/wireless</filename>:</para>

     <blockquote><programlisting>
 if [ "$WPA" = "y" -a -x /usr/local/bin/wpa_supplicant ]; then
     killall wpa_supplicant
 fi
     </programlisting></blockquote>

     <para>This will make <command>cardmgr</command> start
     <command>wpa_supplicant</command> when the card is plugged
     in.</para>
   </refsect1>

   <refsect1>
     <title>See Also</title>
     <para>
       <citerefentry>
 	<refentrytitle>wpa_background</refentrytitle>
 	<manvolnum>8</manvolnum>
       </citerefentry>
       <citerefentry>
 	<refentrytitle>wpa_supplicant.conf</refentrytitle>
 	<manvolnum>5</manvolnum>
       </citerefentry>
       <citerefentry>
 	<refentrytitle>wpa_cli</refentrytitle>
 	<manvolnum>8</manvolnum>
       </citerefentry>
       <citerefentry>
 	<refentrytitle>wpa_passphrase</refentrytitle>
 	<manvolnum>8</manvolnum>
       </citerefentry>
     </para>
   </refsect1>
   <refsect1>
     <title>Legal</title>
     <para>wpa_supplicant is copyright (c) 2003-2012,
     Jouni Malinen <email>j@w1.fi</email> and
     contributors.
     All Rights Reserved.</para>

     <para>This program is licensed under the BSD license (the one with
     advertisement clause removed).</para>
   </refsect1>
 </refentry>
	<!doctype refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">

	<refentry>
	<refmeta>
	<refentrytitle>wpa_supplicant</refentrytitle>
	<manvolnum>8</manvolnum>
	</refmeta>
	<refnamediv>
	<refname>wpa_supplicant</refname>
	<refpurpose>Wi-Fi Protected Access client and IEEE 802.1X supplicant</refpurpose>
	</refnamediv>
	<refsynopsisdiv>
	<cmdsynopsis>
	<command>wpa_supplicant</command>
	<arg>-BddfhKLqqtuvW</arg>
	<arg>-i<replaceable>ifname</replaceable></arg>
	<arg>-c<replaceable>config file</replaceable></arg>
	<arg>-D<replaceable>driver</replaceable></arg>
	<arg>-P<replaceable>PID_file</replaceable></arg>
	<arg>-f<replaceable>output file</replaceable></arg>
	</cmdsynopsis>
	</refsynopsisdiv>
	<refsect1>
	<title>Overview</title>

	<para>
	Wireless networks do not require physical access to the network equipment
	in the same way as wired networks. This makes it easier for unauthorized
	users to passively monitor a network and capture all transmitted frames.
	In addition, unauthorized use of the network is much easier. In many cases,
	this can happen even without user's explicit knowledge since the wireless
	LAN adapter may have been configured to automatically join any available
	network.
	</para>

	<para>
	Link-layer encryption can be used to provide a layer of security for
	wireless networks. The original wireless LAN standard, IEEE 802.11,
	included a simple encryption mechanism, WEP. However, that proved to
	be flawed in many areas and network protected with WEP cannot be consider
	secure. IEEE 802.1X authentication and frequently changed dynamic WEP keys
	can be used to improve the network security, but even that has inherited
	security issues due to the use of WEP for encryption. Wi-Fi Protected
	Access and IEEE 802.11i amendment to the wireless LAN standard introduce
	a much improvement mechanism for securing wireless networks. IEEE 802.11i
	enabled networks that are using CCMP (encryption mechanism based on strong
	cryptographic algorithm AES) can finally be called secure used for
	applications which require efficient protection against unauthorized
	access.
	</para>

	<para><command>wpa_supplicant</command> is an implementation of
	the WPA Supplicant component, i.e., the part that runs in the
	client stations. It implements WPA key negotiation with a WPA
	Authenticator and EAP authentication with Authentication
	Server. In addition, it controls the roaming and IEEE 802.11
	authentication/association of the wireless LAN driver.</para>

	<para><command>wpa_supplicant</command> is designed to be a
	"daemon" program that runs in the background and acts as the
	backend component controlling the wireless
	connection. <command>wpa_supplicant</command> supports separate
	frontend programs and an example text-based frontend,
	<command>wpa_cli</command>, is included with
	wpa_supplicant.</para>

	<para>Before wpa_supplicant can do its work, the network interface
	must be available. That means that the physical device must be
	present and enabled, and the driver for the device must be
	loaded. The daemon will exit immediately if the device is not already
	available.</para>

	<para>After <command>wpa_supplicant</command> has configured the
	network device, higher level configuration such as DHCP may
	proceed. There are a variety of ways to integrate wpa_supplicant
	into a machine's networking scripts, a few of which are described
	in sections below.</para>

	<para>The following steps are used when associating with an AP
	using WPA:</para>

	<itemizedlist>
	<listitem>
	<para><command>wpa_supplicant</command> requests the kernel
	driver to scan neighboring BSSes</para>
	</listitem>

	<listitem>
	<para><command>wpa_supplicant</command> selects a BSS based on
	its configuration</para>
	</listitem>

	<listitem>
	<para><command>wpa_supplicant</command> requests the kernel
	driver to associate with the chosen BSS</para>
	</listitem>

	<listitem>
	<para>If WPA-EAP: integrated IEEE 802.1X Supplicant
	completes EAP authentication with the
	authentication server (proxied by the Authenticator in the
	AP)</para>
	</listitem>

	<listitem>
	<para>If WPA-EAP: master key is received from the IEEE 802.1X
	Supplicant</para>
	</listitem>

	<listitem>
	<para>If WPA-PSK: <command>wpa_supplicant</command> uses PSK
	as the master session key</para>
	</listitem>

	<listitem>
	<para><command>wpa_supplicant</command> completes WPA 4-Way
	Handshake and Group Key Handshake with the Authenticator
	(AP)</para>
	</listitem>

	<listitem>
	<para><command>wpa_supplicant</command> configures encryption
	keys for unicast and broadcast</para>
	</listitem>

	<listitem>
	<para>normal data packets can be transmitted and received</para>
	</listitem>
	</itemizedlist>
	</refsect1>

	<refsect1>
	<title>Supported Features</title>
	<para>Supported WPA/IEEE 802.11i features:</para>
	<itemizedlist>
	<listitem>
	<para>WPA-PSK ("WPA-Personal")</para>
	</listitem>

	<listitem>
	<para>WPA with EAP (e.g., with RADIUS authentication server)
	("WPA-Enterprise") Following authentication methods are
	supported with an integrate IEEE 802.1X Supplicant:</para>

	<itemizedlist>
	<listitem>
	<para>EAP-TLS</para>
	</listitem>
	</itemizedlist>

	<itemizedlist>
	<listitem>
	<para>EAP-PEAP/MSCHAPv2 (both PEAPv0 and PEAPv1)</para>
	</listitem>


	<listitem>
	<para>EAP-PEAP/TLS (both PEAPv0 and PEAPv1)</para>
	</listitem>

	<listitem>
	<para>EAP-PEAP/GTC (both PEAPv0 and PEAPv1)</para>
	</listitem>

	<listitem>
	<para>EAP-PEAP/OTP (both PEAPv0 and PEAPv1)</para>
	</listitem>

	<listitem>
	<para>EAP-PEAP/MD5-Challenge (both PEAPv0 and PEAPv1)</para>
	</listitem>

	<listitem>
	<para>EAP-TTLS/EAP-MD5-Challenge</para>
	</listitem>

	<listitem>
	<para>EAP-TTLS/EAP-GTC</para>
	</listitem>

	<listitem><para>EAP-TTLS/EAP-OTP</para></listitem>

	<listitem><para>EAP-TTLS/EAP-MSCHAPv2</para></listitem>

	<listitem><para>EAP-TTLS/EAP-TLS</para></listitem>

	<listitem><para>EAP-TTLS/MSCHAPv2</para></listitem>

	<listitem><para>EAP-TTLS/MSCHAP</para></listitem>

	<listitem><para>EAP-TTLS/PAP</para></listitem>

	<listitem><para>EAP-TTLS/CHAP</para></listitem>

	<listitem><para>EAP-SIM</para></listitem>

	<listitem><para>EAP-AKA</para></listitem>

	<listitem><para>EAP-PSK</para></listitem>

	<listitem><para>EAP-PAX</para></listitem>

	<listitem><para>LEAP (note: requires special support from
	the driver for IEEE 802.11 authentication)</para></listitem>

	<listitem><para>(following methods are supported, but since
	they do not generate keying material, they cannot be used
	with WPA or IEEE 802.1X WEP keying)</para></listitem>

	<listitem><para>EAP-MD5-Challenge </para></listitem>

	<listitem><para>EAP-MSCHAPv2</para></listitem>

	<listitem><para>EAP-GTC</para></listitem>

	<listitem><para>EAP-OTP</para></listitem>
	</itemizedlist>
	</listitem>

	<listitem>
	<para>key management for CCMP, TKIP, WEP104, WEP40</para>
	</listitem>

	<listitem>
	<para>RSN/WPA2 (IEEE 802.11i)</para>
	<itemizedlist>
	<listitem>
	<para>pre-authentication</para>
	</listitem>

	<listitem>
	<para>PMKSA caching</para>
	</listitem>
	</itemizedlist>
	</listitem>
	</itemizedlist>
	</refsect1>

	<refsect1>
	<title>Available Drivers</title>
	<para>A summary of available driver backends is below. Support for each
	of the driver backends is chosen at wpa_supplicant compile time. For a
	list of supported driver backends that may be used with the -D option on
	your system, refer to the help output of wpa_supplicant
	(<emphasis>wpa_supplicant -h</emphasis>).</para>

	<variablelist>
	<varlistentry>
	<term>wext</term>
	<listitem>
	<para>Linux wireless extensions (generic).</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>wired</term>
	<listitem>
	<para>wpa_supplicant wired Ethernet driver</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>roboswitch</term>
	<listitem>
	<para>wpa_supplicant Broadcom switch driver</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>bsd</term>
	<listitem>
	<para>BSD 802.11 support (Atheros, etc.).</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>ndis</term>
	<listitem>
	<para>Windows NDIS driver.</para>
	</listitem>
	</varlistentry>
	</variablelist>
	</refsect1>

	<refsect1>
	<title>Command Line Options</title>
	<para>Most command line options have global scope. Some are given per
	interface, and are only valid if at least one <option>-i</option> option
	is specified, otherwise they're ignored. Option groups for different
	interfaces must be separated by <option>-N</option> option.</para>
	<variablelist>
	<varlistentry>
	<term>-b br_ifname</term>
	<listitem>
	<para>Optional bridge interface name. (Per interface)</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>-B</term>
	<listitem>
	<para>Run daemon in the background.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>-c filename</term>
	<listitem>
	<para>Path to configuration file. (Per interface)</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>-C ctrl_interface</term>
	<listitem>
	<para>Path to ctrl_interface socket (Per interface. Only used if
	<option>-c</option> is not).</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>-i ifname</term>
	<listitem>
	<para>Interface to listen on. Multiple instances of this option can
	be present, one per interface, separated by <option>-N</option>
	option (see below).</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>-d</term>
	<listitem>
	<para>Increase debugging verbosity (<option>-dd</option> even
	more).</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>-D driver</term>
	<listitem>
	<para>Driver to use (can be multiple drivers: nl80211,wext).
	(Per interface, see the available options below.)</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>-f output file</term>
	<listitem>
	<para>Log output to specified file instead of stdout.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>-g global ctrl_interface</term>
	<listitem>
	<para>Path to global ctrl_interface socket. If specified, interface
	definitions may be omitted.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>-K</term>
	<listitem>
	<para>Include keys (passwords, etc.) in debug output.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>-t</term>
	<listitem>
	<para>Include timestamp in debug messages.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>-h</term>
	<listitem>
	<para>Help. Show a usage message.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>-L</term>
	<listitem>
	<para>Show license (BSD).</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>-p</term>
	<listitem>
	<para>Driver parameters. (Per interface)</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>-P PID_file</term>
	<listitem>
	<para>Path to PID file.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>-q</term>
	<listitem>
	<para>Decrease debugging verbosity (<option>-qq</option> even
	less).</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>-u</term>
	<listitem>
	<para>Enabled DBus control interface. If enabled, interface
	definitions may be omitted.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>-v</term>
	<listitem>
	<para>Show version.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>-W</term>
	<listitem>
	<para>Wait for a control interface monitor before starting.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>-N</term>
	<listitem>
	<para>Start describing new interface.</para>
	</listitem>
	</varlistentry>
	</variablelist>
	</refsect1>

	<refsect1>
	<title>Examples</title>

	<para>In most common cases, <command>wpa_supplicant</command> is
	started with:</para>

	<blockquote><programlisting>
	wpa_supplicant -B -c/etc/wpa_supplicant.conf -iwlan0
	</programlisting></blockquote>

	<para>This makes the process fork into background.</para>

	<para>The easiest way to debug problems, and to get debug log for
	bug reports, is to start <command>wpa_supplicant</command> on
	foreground with debugging enabled:</para>

	<blockquote><programlisting>
	wpa_supplicant -c/etc/wpa_supplicant.conf -iwlan0 -d
	</programlisting></blockquote>

	<para>If the specific driver wrapper is not known beforehand, it is
	possible to specify multiple comma separated driver wrappers on the command
	line. <command>wpa_supplicant</command> will use the first driver
	wrapper that is able to initialize the interface.</para>

	<blockquote><programlisting>
	wpa_supplicant -Dnl80211,wext -c/etc/wpa_supplicant.conf -iwlan0
	</programlisting></blockquote>

	<para><command>wpa_supplicant</command> can control multiple
	interfaces (radios) either by running one process for each
	interface separately or by running just one process and list of
	options at command line. Each interface is separated with -N
	argument. As an example, following command would start
	wpa_supplicant for two interfaces:</para>

	<blockquote><programlisting>
	wpa_supplicant \
	-c wpa1.conf -i wlan0 -D nl80211 -N \
	-c wpa2.conf -i ath0 -D wext
	</programlisting></blockquote>
	</refsect1>

	<refsect1>
	<title>OS Requirements</title>
	<para>Current hardware/software requirements:</para>

	<itemizedlist>
	<listitem>
	<para>Linux kernel 2.4.x or 2.6.x with Linux Wireless
	Extensions v15 or newer</para>
	</listitem>


	<listitem>
	<para>FreeBSD 6-CURRENT</para>
	</listitem>

	<listitem>
	<para>Microsoft Windows with WinPcap (at least WinXP, may work
	with other versions)</para>
	</listitem>
	</itemizedlist>
	</refsect1>

	<refsect1>
	<title>Supported Drivers</title>
	<variablelist>
	<varlistentry>
	<term>Linux wireless extensions</term>
	<listitem>
	<para>In theory, any driver that supports Linux wireless
	extensions can be used with IEEE 802.1X (i.e., not WPA) when
	using ap_scan=0 option in configuration file.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>Wired Ethernet drivers</term>
	<listitem>
	<para>Use ap_scan=0.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>BSD net80211 layer (e.g., Atheros driver)</term>
	<listitem>
	<para>At the moment, this is for FreeBSD 6-CURRENT branch.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>Windows NDIS</term>
	<listitem>
	<para>The current Windows port requires WinPcap
	(http://winpcap.polito.it/). See README-Windows.txt for more
	information.</para>
	</listitem>
	</varlistentry>
	</variablelist>


	<para>wpa_supplicant was designed to be portable for different
	drivers and operating systems. Hopefully, support for more wlan
	cards and OSes will be added in the future. See developer.txt for
	more information about the design of wpa_supplicant and porting to
	other drivers. One main goal is to add full WPA/WPA2 support to
	Linux wireless extensions to allow new drivers to be supported
	without having to implement new driver-specific interface code in
	wpa_supplicant.</para>
	</refsect1>

	<refsect1>
	<title>Architecture</title> <para>The
	<command>wpa_supplicant</command> system consists of the following
	components:</para>

	<variablelist>
	<varlistentry>
	<term><filename>wpa_supplicant.conf</filename> </term>
	<listitem>
	<para>the configuration file describing all networks that the
	user wants the computer to connect to. </para>
	</listitem>
	</varlistentry>
	<varlistentry>
	<term><command>wpa_supplicant</command></term>
	<listitem><para>the program that directly interacts with the
	network interface. </para></listitem>
	</varlistentry>
	<varlistentry>
	<term><command>wpa_cli</command></term> <listitem><para> the
	client program that provides a high-level interface to the
	functionality of the daemon. </para></listitem>
	</varlistentry>
	<varlistentry>
	<term><command>wpa_passphrase</command></term>
	<listitem><para>a utility needed to construct
	<filename>wpa_supplicant.conf</filename> files that include
	encrypted passwords.</para></listitem>
	</varlistentry>
	</variablelist>
	</refsect1>

	<refsect1>
	<title>Quick Start</title>

	<para>First, make a configuration file, e.g.
	<filename>/etc/wpa_supplicant.conf</filename>, that describes the networks
	you are interested in. See <citerefentry>
	<refentrytitle>wpa_supplicant.conf</refentrytitle>
	<manvolnum>5</manvolnum>
	</citerefentry>
	for details.</para>

	<para>Once the configuration is ready, you can test whether the
	configuration works by running <command>wpa_supplicant</command>
	with following command to start it on foreground with debugging
	enabled:</para>

	<blockquote><programlisting>
	wpa_supplicant -iwlan0 -c/etc/wpa_supplicant.conf -d
	</programlisting></blockquote>

	<para>Assuming everything goes fine, you can start using following
	command to start <command>wpa_supplicant</command> on background
	without debugging:</para>

	<blockquote><programlisting>
	wpa_supplicant -iwlan0 -c/etc/wpa_supplicant.conf -B
	</programlisting></blockquote>

	<para>Please note that if you included more than one driver
	interface in the build time configuration (.config), you may need
	to specify which interface to use by including -D<driver
	name> option on the command line.</para>

	<!-- XXX at this point, the page could include a little script
	based on wpa_cli to wait for a connection and then run
	dhclient -->

	</refsect1>

	<refsect1>
	<title>Interface to pcmcia-cs/cardmrg</title>

	<para>For example, following small changes to pcmcia-cs scripts
	can be used to enable WPA support:</para>

	<para>Add MODE="Managed" and WPA="y" to the network scheme in
	<filename>/etc/pcmcia/wireless.opts</filename>.</para>

	<para>Add the following block to the end of <emphasis>start</emphasis>
	action handler in <filename>/etc/pcmcia/wireless</filename>:</para>

	<blockquote><programlisting>
	if [ "$WPA" = "y" -a -x /usr/local/bin/wpa_supplicant ]; then
	/usr/local/bin/wpa_supplicant -B -c/etc/wpa_supplicant.conf -i$DEVICE
	fi
	</programlisting></blockquote>


	<para>Add the following block to the end of <emphasis>stop</emphasis>
	action handler (may need to be separated from other actions) in
	<filename>/etc/pcmcia/wireless</filename>:</para>

	<blockquote><programlisting>
	if [ "$WPA" = "y" -a -x /usr/local/bin/wpa_supplicant ]; then
	killall wpa_supplicant
	fi
	</programlisting></blockquote>

	<para>This will make <command>cardmgr</command> start
	<command>wpa_supplicant</command> when the card is plugged
	in.</para>
	</refsect1>

	<refsect1>
	<title>See Also</title>
	<para>
	<citerefentry>
	<refentrytitle>wpa_background</refentrytitle>
	<manvolnum>8</manvolnum>
	</citerefentry>
	<citerefentry>
	<refentrytitle>wpa_supplicant.conf</refentrytitle>
	<manvolnum>5</manvolnum>
	</citerefentry>
	<citerefentry>
	<refentrytitle>wpa_cli</refentrytitle>
	<manvolnum>8</manvolnum>
	</citerefentry>
	<citerefentry>
	<refentrytitle>wpa_passphrase</refentrytitle>
	<manvolnum>8</manvolnum>
	</citerefentry>
	</para>
	</refsect1>
	<refsect1>
	<title>Legal</title>
	<para>wpa_supplicant is copyright (c) 2003-2012,
	Jouni Malinen <email>j@w1.fi</email> and
	contributors.
	All Rights Reserved.</para>

	<para>This program is licensed under the BSD license (the one with
	advertisement clause removed).</para>
	</refsect1>
	</refentry>