aboutsummaryrefslogtreecommitdiffstats
path: root/wpa_supplicant/doc/docbook
diff options
context:
space:
mode:
authorJouni Malinen <j@w1.fi>2008-02-28 01:34:43 (GMT)
committerJouni Malinen <jm@jm.kir.nu>2008-02-28 01:34:43 (GMT)
commit6fc6879bd55a394f807cbbe927df736c190cb8ab (patch)
treecdf50da0c58f21510a808d53502a060d911ff243 /wpa_supplicant/doc/docbook
downloadhostap-6fc6879bd55a394f807cbbe927df736c190cb8ab.zip
hostap-6fc6879bd55a394f807cbbe927df736c190cb8ab.tar.gz
hostap-6fc6879bd55a394f807cbbe927df736c190cb8ab.tar.bz2
Re-initialize hostapd/wpa_supplicant git repository based on 0.6.3 release
Diffstat (limited to 'wpa_supplicant/doc/docbook')
-rw-r--r--wpa_supplicant/doc/docbook/.gitignore6
-rw-r--r--wpa_supplicant/doc/docbook/Makefile27
-rw-r--r--wpa_supplicant/doc/docbook/wpa_background.sgml101
-rw-r--r--wpa_supplicant/doc/docbook/wpa_cli.sgml338
-rw-r--r--wpa_supplicant/doc/docbook/wpa_gui.sgml76
-rw-r--r--wpa_supplicant/doc/docbook/wpa_passphrase.sgml73
-rw-r--r--wpa_supplicant/doc/docbook/wpa_priv.sgml148
-rw-r--r--wpa_supplicant/doc/docbook/wpa_supplicant.conf.sgml238
-rw-r--r--wpa_supplicant/doc/docbook/wpa_supplicant.sgml795
9 files changed, 1802 insertions, 0 deletions
diff --git a/wpa_supplicant/doc/docbook/.gitignore b/wpa_supplicant/doc/docbook/.gitignore
new file mode 100644
index 0000000..8c3945c
--- /dev/null
+++ b/wpa_supplicant/doc/docbook/.gitignore
@@ -0,0 +1,6 @@
+manpage.links
+manpage.refs
+*.8
+*.5
+*.html
+*.pdf
diff --git a/wpa_supplicant/doc/docbook/Makefile b/wpa_supplicant/doc/docbook/Makefile
new file mode 100644
index 0000000..aaeee2e
--- /dev/null
+++ b/wpa_supplicant/doc/docbook/Makefile
@@ -0,0 +1,27 @@
+all: man html pdf
+
+FILES += wpa_background
+FILES += wpa_cli
+FILES += wpa_gui
+FILES += wpa_passphrase
+FILES += wpa_priv
+FILES += wpa_supplicant.conf
+FILES += wpa_supplicant
+
+man:
+ for i in $(FILES); do docbook2man $$i.sgml; done
+
+html:
+ for i in $(FILES); do docbook2html $$i.sgml && \
+ mv index.html $$i.html; done
+
+pdf:
+ for i in $(FILES); do docbook2pdf $$i.sgml; done
+
+
+clean:
+ rm -f wpa_background.8 wpa_cli.8 wpa_gui.8 wpa_passphrase.8 wpa_priv.8 wpa_supplicant.8
+ rm -f wpa_supplicant.conf.5
+ rm -f manpage.links manpage.refs
+ rm -f $(FILES:%=%.pdf)
+ rm -f $(FILES:%=%.html)
diff --git a/wpa_supplicant/doc/docbook/wpa_background.sgml b/wpa_supplicant/doc/docbook/wpa_background.sgml
new file mode 100644
index 0000000..f47235b
--- /dev/null
+++ b/wpa_supplicant/doc/docbook/wpa_background.sgml
@@ -0,0 +1,101 @@
+<!doctype refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
+
+<refentry>
+ <refmeta>
+ <refentrytitle>wpa_background</refentrytitle>
+ <manvolnum>8</manvolnum>
+ </refmeta>
+ <refnamediv>
+ <refname>wpa_background</refname>
+ <refpurpose>Background information on Wi-Fi Protected Access and IEEE 802.11i</refpurpose>
+ </refnamediv>
+ <refsect1>
+ <title>WPA</title>
+
+ <para>The original security mechanism of IEEE 802.11 standard was
+ not designed to be strong and has proven to be insufficient for
+ most networks that require some kind of security. Task group I
+ (Security) of IEEE 802.11 working group
+ (http://www.ieee802.org/11/) has worked to address the flaws of
+ the base standard and has in practice completed its work in May
+ 2004. The IEEE 802.11i amendment to the IEEE 802.11 standard was
+ approved in June 2004 and published in July 2004.</para>
+
+ <para>Wi-Fi Alliance (http://www.wi-fi.org/) used a draft version
+ of the IEEE 802.11i work (draft 3.0) to define a subset of the
+ security enhancements that can be implemented with existing wlan
+ hardware. This is called Wi-Fi Protected Access&lt;TM&gt; (WPA). This
+ has now become a mandatory component of interoperability testing
+ and certification done by Wi-Fi Alliance. Wi-Fi provides
+ information about WPA at its web site
+ (http://www.wi-fi.org/OpenSection/protected_access.asp).</para>
+
+ <para>IEEE 802.11 standard defined wired equivalent privacy (WEP)
+ algorithm for protecting wireless networks. WEP uses RC4 with
+ 40-bit keys, 24-bit initialization vector (IV), and CRC32 to
+ protect against packet forgery. All these choices have proven to
+ be insufficient: key space is too small against current attacks,
+ RC4 key scheduling is insufficient (beginning of the pseudorandom
+ stream should be skipped), IV space is too small and IV reuse
+ makes attacks easier, there is no replay protection, and non-keyed
+ authentication does not protect against bit flipping packet
+ data.</para>
+
+ <para>WPA is an intermediate solution for the security issues. It
+ uses Temporal Key Integrity Protocol (TKIP) to replace WEP. TKIP
+ is a compromise on strong security and possibility to use existing
+ hardware. It still uses RC4 for the encryption like WEP, but with
+ per-packet RC4 keys. In addition, it implements replay protection,
+ keyed packet authentication mechanism (Michael MIC).</para>
+
+ <para>Keys can be managed using two different mechanisms. WPA can
+ either use an external authentication server (e.g., RADIUS) and
+ EAP just like IEEE 802.1X is using or pre-shared keys without need
+ for additional servers. Wi-Fi calls these "WPA-Enterprise" and
+ "WPA-Personal", respectively. Both mechanisms will generate a
+ master session key for the Authenticator (AP) and Supplicant
+ (client station).</para>
+
+ <para>WPA implements a new key handshake (4-Way Handshake and
+ Group Key Handshake) for generating and exchanging data encryption
+ keys between the Authenticator and Supplicant. This handshake is
+ also used to verify that both Authenticator and Supplicant know
+ the master session key. These handshakes are identical regardless
+ of the selected key management mechanism (only the method for
+ generating master session key changes).</para>
+ </refsect1>
+
+ <refsect1>
+ <title>IEEE 802.11i / WPA2</title>
+
+ <para>The design for parts of IEEE 802.11i that were not included
+ in WPA has finished (May 2004) and this amendment to IEEE 802.11
+ was approved in June 2004. Wi-Fi Alliance is using the final IEEE
+ 802.11i as a new version of WPA called WPA2. This includes, e.g.,
+ support for more robust encryption algorithm (CCMP: AES in Counter
+ mode with CBC-MAC) to replace TKIP and optimizations for handoff
+ (reduced number of messages in initial key handshake,
+ pre-authentication, and PMKSA caching).</para>
+ </refsect1>
+
+ <refsect1>
+ <title>See Also</title>
+ <para>
+ <citerefentry>
+ <refentrytitle>wpa_supplicant</refentrytitle>
+ <manvolnum>8</manvolnum>
+ </citerefentry>
+ </para>
+ </refsect1>
+
+ <refsect1>
+ <title>Legal</title>
+ <para>wpa_supplicant is copyright (c) 2003-2007,
+ Jouni Malinen <email>j@w1.fi</email> and
+ contributors.
+ All Rights Reserved.</para>
+
+ <para>This program is dual-licensed under both the GPL version 2
+ and BSD license. Either license may be used at your option.</para>
+ </refsect1>
+</refentry>
diff --git a/wpa_supplicant/doc/docbook/wpa_cli.sgml b/wpa_supplicant/doc/docbook/wpa_cli.sgml
new file mode 100644
index 0000000..d55aee4
--- /dev/null
+++ b/wpa_supplicant/doc/docbook/wpa_cli.sgml
@@ -0,0 +1,338 @@
+<!doctype refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
+
+<refentry>
+ <refmeta>
+ <refentrytitle>wpa_cli</refentrytitle>
+ <manvolnum>8</manvolnum>
+ </refmeta>
+ <refnamediv>
+ <refname>wpa_cli</refname>
+
+ <refpurpose>WPA command line client</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <cmdsynopsis>
+ <command>wpa_cli</command>
+ <arg>-p <replaceable>path to ctrl sockets</replaceable></arg>
+ <arg>-i <replaceable>ifname</replaceable></arg>
+ <arg>-hvB</arg>
+ <arg>-a <replaceable>action file</replaceable></arg>
+ <arg>-P <replaceable>pid file</replaceable></arg>
+ <arg><replaceable>command ...</replaceable></arg>
+ </cmdsynopsis>
+ </refsynopsisdiv>
+
+ <refsect1>
+ <title>Overview</title>
+
+ <para>wpa_cli is a text-based frontend program for interacting
+ with wpa_supplicant. It is used to query current status, change
+ configuration, trigger events, and request interactive user
+ input.</para>
+
+ <para>wpa_cli can show the current authentication status, selected
+ security mode, dot11 and dot1x MIBs, etc. In addition, it can
+ configure some variables like EAPOL state machine parameters and
+ trigger events like reassociation and IEEE 802.1X
+ logoff/logon. wpa_cli provides a user interface to request
+ authentication information, like username and password, if these
+ are not included in the configuration. This can be used to
+ implement, e.g., one-time-passwords or generic token card
+ authentication where the authentication is based on a
+ challenge-response that uses an external device for generating the
+ response.</para>
+
+ <para>The control interface of wpa_supplicant can be configured to
+ allow non-root user access (ctrl_interface GROUP= parameter in the
+ configuration file). This makes it possible to run wpa_cli with a
+ normal user account.</para>
+
+ <para>wpa_cli supports two modes: interactive and command
+ line. Both modes share the same command set and the main
+ difference is in interactive mode providing access to unsolicited
+ messages (event messages, username/password requests).</para>
+
+ <para>Interactive mode is started when wpa_cli is executed without
+ including the command as a command line parameter. Commands are
+ then entered on the wpa_cli prompt. In command line mode, the same
+ commands are entered as command line arguments for wpa_cli.</para>
+ </refsect1>
+ <refsect1>
+ <title>Interactive authentication parameters request</title>
+
+ <para>When wpa_supplicant need authentication parameters, like
+ username and password, which are not present in the configuration
+ file, it sends a request message to all attached frontend programs,
+ e.g., wpa_cli in interactive mode. wpa_cli shows these requests
+ with "CTRL-REQ-&lt;type&gt;-&lt;id&gt;:&lt;text&gt;"
+ prefix. &lt;type&gt; is IDENTITY, PASSWORD, or OTP
+ (one-time-password). &lt;id&gt; is a unique identifier for the
+ current network. &lt;text&gt; is description of the request. In
+ case of OTP request, it includes the challenge from the
+ authentication server.</para>
+
+ <para>The reply to these requests can be given with 'identity',
+ 'password', and 'otp' commands. &lt;id&gt; needs to be copied from the
+ the matching request. 'password' and 'otp' commands can be used
+ regardless of whether the request was for PASSWORD or OTP. The
+ main difference between these two commands is that values given
+ with 'password' are remembered as long as wpa_supplicant is
+ running whereas values given with 'otp' are used only once and
+ then forgotten, i.e., wpa_supplicant will ask frontend for a new
+ value for every use. This can be used to implement
+ one-time-password lists and generic token card -based
+ authentication.</para>
+
+ <para>Example request for password and a matching reply:</para>
+
+<blockquote><programlisting>
+CTRL-REQ-PASSWORD-1:Password needed for SSID foobar
+> password 1 mysecretpassword
+</programlisting></blockquote>
+
+ <para>Example request for generic token card challenge-response:</para>
+
+<blockquote><programlisting>
+CTRL-REQ-OTP-2:Challenge 1235663 needed for SSID foobar
+> otp 2 9876
+</programlisting></blockquote>
+
+ </refsect1>
+ <refsect1>
+ <title>Command Arguments</title>
+ <variablelist>
+ <varlistentry>
+ <term>-p path</term>
+
+ <listitem><para>Change the path where control sockets should
+ be found.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>-i ifname</term>
+
+ <listitem><para>Specify the interface that is being
+ configured. By default, choose the first interface found with
+ a control socket in the socket path.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>-h</term>
+ <listitem><para>Help. Show a usage message.</para></listitem>
+ </varlistentry>
+
+
+ <varlistentry>
+ <term>-v</term>
+ <listitem><para>Show version information.</para></listitem>
+ </varlistentry>
+
+
+ <varlistentry>
+ <term>-B</term>
+ <listitem><para>Run as a daemon in the background.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>-a file</term>
+
+ <listitem><para>Run in daemon mode executing the action file
+ based on events from wpa_supplicant. The specified file will
+ be executed with the first argument set to interface name and
+ second to "CONNECTED" or "DISCONNECTED" depending on the event.
+ This can be used to execute networking tools required to configure
+ the interface.</para>
+
+ <para>Additionally, three environmental variables are available to
+ the file: WPA_CTRL_DIR, WPA_ID, and WPA_ID_STR. WPA_CTRL_DIR
+ contains the absolute path to the ctrl_interface socket. WPA_ID
+ contains the unique network_id identifier assigned to the active
+ network, and WPA_ID_STR contains the content of the id_str option.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>-P file</term>
+
+ <listitem><para>Set the location of the PID
+ file.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>command</term>
+
+ <listitem><para>Run a command. The available commands are
+ listed in the next section.</para></listitem>
+
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+ <refsect1>
+ <title>Commands</title>
+ <para>The following commands are available:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term>status</term>
+ <listitem>
+ <para>get current WPA/EAPOL/EAP status</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>mib</term>
+ <listitem>
+ <para>get MIB variables (dot1x, dot11)</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>help</term>
+ <listitem>
+ <para>show this usage help</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>interface [ifname]</term>
+ <listitem>
+ <para>show interfaces/select interface</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>level &lt;debug level&gt;</term>
+ <listitem>
+ <para>change debug level</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>license</term>
+ <listitem>
+ <para>show full wpa_cli license</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>logoff</term>
+ <listitem>
+ <para>IEEE 802.1X EAPOL state machine logoff</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>logon</term>
+ <listitem>
+ <para>IEEE 802.1X EAPOL state machine logon</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>set</term>
+ <listitem>
+ <para>set variables (shows list of variables when run without arguments)</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>pmksa</term>
+ <listitem>
+ <para>show PMKSA cache</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>reassociate</term>
+ <listitem>
+ <para>force reassociation</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>reconfigure</term>
+ <listitem>
+ <para>force wpa_supplicant to re-read its configuration file</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>preauthenticate &lt;BSSID&gt;</term>
+ <listitem>
+ <para>force preauthentication</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>identity &lt;network id&gt; &lt;identity&gt;</term>
+ <listitem>
+ <para>configure identity for an SSID</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>password &lt;network id&gt; &lt;password&gt;</term>
+ <listitem>
+ <para>configure password for an SSID</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>pin &lt;network id&gt; &lt;pin&gt;</term>
+ <listitem>
+ <para>configure pin for an SSID</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>otp &lt;network id&gt; &lt;password&gt;</term>
+ <listitem>
+ <para>configure one-time-password for an SSID</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>bssid &lt;network id&gt; &lt;BSSID&gt;</term>
+ <listitem>
+ <para>set preferred BSSID for an SSID</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>list_networks</term>
+ <listitem>
+ <para>list configured networks</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>terminate</term>
+ <listitem>
+ <para>terminate <command>wpa_supplicant</command></para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>quit</term>
+ <listitem><para>exit wpa_cli</para></listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+ <refsect1>
+ <title>See Also</title>
+ <para>
+ <citerefentry>
+ <refentrytitle>wpa_supplicant</refentrytitle>
+ <manvolnum>8</manvolnum>
+ </citerefentry>
+ </para>
+ </refsect1>
+ <refsect1>
+ <title>Legal</title>
+ <para>wpa_supplicant is copyright (c) 2003-2007,
+ Jouni Malinen <email>j@w1.fi</email> and
+ contributors.
+ All Rights Reserved.</para>
+
+ <para>This program is dual-licensed under both the GPL version 2
+ and BSD license. Either license may be used at your option.</para>
+ </refsect1>
+</refentry>
diff --git a/wpa_supplicant/doc/docbook/wpa_gui.sgml b/wpa_supplicant/doc/docbook/wpa_gui.sgml
new file mode 100644
index 0000000..32bcee0
--- /dev/null
+++ b/wpa_supplicant/doc/docbook/wpa_gui.sgml
@@ -0,0 +1,76 @@
+<!doctype refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
+
+<refentry>
+ <refmeta>
+ <refentrytitle>wpa_gui</refentrytitle>
+ <manvolnum>8</manvolnum>
+ </refmeta>
+ <refnamediv>
+ <refname>wpa_gui</refname>
+
+ <refpurpose>WPA Graphical User Interface</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <cmdsynopsis>
+ <command>wpa_gui</command>
+ <arg>-p <replaceable>path to ctrl sockets</replaceable></arg>
+ <arg>-i <replaceable>ifname</replaceable></arg>
+ </cmdsynopsis>
+ </refsynopsisdiv>
+
+ <refsect1>
+ <title>Overview</title>
+
+ <para>wpa_gui is a QT graphical frontend program for interacting
+ with wpa_supplicant. It is used to query current status, change
+ configuration and request interactive user input.</para>
+
+ <para>wpa_gui supports (almost) all of the interactive status and
+ configuration features of the command line client, wpa_cli. Refer
+ to the wpa_cli manpage for a comprehensive list of the
+ interactive mode features.</para>
+ </refsect1>
+ <refsect1>
+ <title>Command Arguments</title>
+ <variablelist>
+ <varlistentry>
+ <term>-p path</term>
+
+ <listitem><para>Change the path where control sockets should
+ be found.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>-i ifname</term>
+
+ <listitem><para>Specify the interface that is being
+ configured. By default, choose the first interface found with
+ a control socket in the socket path.</para></listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+ <refsect1>
+ <title>See Also</title>
+ <para>
+ <citerefentry>
+ <refentrytitle>wpa_cli</refentrytitle>
+ <manvolnum>8</manvolnum>
+ </citerefentry>
+ <citerefentry>
+ <refentrytitle>wpa_supplicant</refentrytitle>
+ <manvolnum>8</manvolnum>
+ </citerefentry>
+ </para>
+ </refsect1>
+ <refsect1>
+ <title>Legal</title>
+ <para>wpa_supplicant is copyright (c) 2003-2007,
+ Jouni Malinen <email>j@w1.fi</email> and
+ contributors.
+ All Rights Reserved.</para>
+
+ <para>This program is dual-licensed under both the GPL version 2
+ and BSD license. Either license may be used at your option.</para>
+ </refsect1>
+</refentry>
diff --git a/wpa_supplicant/doc/docbook/wpa_passphrase.sgml b/wpa_supplicant/doc/docbook/wpa_passphrase.sgml
new file mode 100644
index 0000000..402ea09
--- /dev/null
+++ b/wpa_supplicant/doc/docbook/wpa_passphrase.sgml
@@ -0,0 +1,73 @@
+<!doctype refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
+
+<refentry>
+ <refmeta>
+ <refentrytitle>wpa_passphrase</refentrytitle>
+ <manvolnum>8</manvolnum>
+ </refmeta>
+ <refnamediv>
+ <refname>wpa_passphrase</refname>
+ <refpurpose>Generate a WPA PSK from an ASCII passphrase for a SSID</refpurpose>
+ </refnamediv>
+ <refsynopsisdiv>
+ <cmdsynopsis>
+ <command>wpa_passphrase</command>
+ <arg><replaceable>ssid</replaceable></arg>
+ <arg><replaceable>passphrase</replaceable></arg>
+ </cmdsynopsis>
+ </refsynopsisdiv>
+
+ <refsect1>
+ <title>Overview</title>
+
+ <para><command>wpa_passphrase</command> pre-computes PSK entries for
+ network configuration blocks of a
+ <filename>wpa_supplicant.conf</filename> file. An ASCII passphrase
+ and SSID are used to generate a 256-bit PSK.</para>
+ </refsect1>
+
+ <refsect1>
+ <title>Options</title>
+ <variablelist>
+ <varlistentry>
+ <term>ssid</term>
+ <listitem>
+ <para>The SSID whose passphrase should be derived.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>passphrase</term>
+ <listitem>
+ <para>The passphrase to use. If not included on the command line,
+ passphrase will be read from standard input.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+
+ <refsect1>
+ <title>See Also</title>
+ <para>
+ <citerefentry>
+ <refentrytitle>wpa_supplicant.conf</refentrytitle>
+ <manvolnum>5</manvolnum>
+ </citerefentry>
+ <citerefentry>
+ <refentrytitle>wpa_supplicant</refentrytitle>
+ <manvolnum>8</manvolnum>
+ </citerefentry>
+ </para>
+
+ </refsect1>
+ <refsect1>
+ <title>Legal</title>
+ <para>wpa_supplicant is copyright (c) 2003-2007,
+ Jouni Malinen <email>j@w1.fi</email> and
+ contributors.
+ All Rights Reserved.</para>
+
+ <para>This program is dual-licensed under both the GPL version 2
+ and BSD license. Either license may be used at your option.</para>
+ </refsect1>
+</refentry>
diff --git a/wpa_supplicant/doc/docbook/wpa_priv.sgml b/wpa_supplicant/doc/docbook/wpa_priv.sgml
new file mode 100644
index 0000000..43a468c
--- /dev/null
+++ b/wpa_supplicant/doc/docbook/wpa_priv.sgml
@@ -0,0 +1,148 @@
+<!doctype refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
+
+<refentry>
+ <refmeta>
+ <refentrytitle>wpa_priv</refentrytitle>
+ <manvolnum>8</manvolnum>
+ </refmeta>
+ <refnamediv>
+ <refname>wpa_priv</refname>
+
+ <refpurpose>wpa_supplicant privilege separation helper</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <cmdsynopsis>
+ <command>wpa_priv</command>
+ <arg>-c <replaceable>ctrl path</replaceable></arg>
+ <arg>-Bdd</arg>
+ <arg>-P <replaceable>pid file</replaceable></arg>
+ <arg>driver:ifname <replaceable>[driver:ifname ...]</replaceable></arg>
+ </cmdsynopsis>
+ </refsynopsisdiv>
+
+ <refsect1>
+ <title>Overview</title>
+
+ <para><command>wpa_priv</command> is a privilege separation helper that
+ minimizes the size of <command>wpa_supplicant</command> code that needs
+ to be run with root privileges.</para>
+
+ <para>If enabled, privileged operations are done in the wpa_priv process
+ while leaving rest of the code (e.g., EAP authentication and WPA
+ handshakes) to operate in an unprivileged process (wpa_supplicant) that
+ can be run as non-root user. Privilege separation restricts the effects
+ of potential software errors by containing the majority of the code in an
+ unprivileged process to avoid the possibility of a full system
+ compromise.</para>
+
+ <para><command>wpa_priv</command> needs to be run with network admin
+ privileges (usually, root user). It opens a UNIX domain socket for each
+ interface that is included on the command line; any other interface will
+ be off limits for <command>wpa_supplicant</command> in this kind of
+ configuration. After this, <command>wpa_supplicant</command> can be run as
+ a non-root user (e.g., all standard users on a laptop or as a special
+ non-privileged user account created just for this purpose to limit access
+ to user files even further).</para>
+ </refsect1>
+ <refsect1>
+ <title>Example configuration</title>
+
+ <para>The following steps are an example of how to configure
+ <command>wpa_priv</command> to allow users in the 'wpapriv' group
+ to communicate with <command>wpa_supplicant</command> with privilege
+ separation:</para>
+
+ <para>Create user group (e.g., wpapriv) and assign users that
+ should be able to use wpa_supplicant into that group.</para>
+
+ <para>Create /var/run/wpa_priv directory for UNIX domain sockets and
+ control user access by setting it accessible only for the wpapriv
+ group:</para>
+
+<blockquote><programlisting>
+mkdir /var/run/wpa_priv
+chown root:wpapriv /var/run/wpa_priv
+chmod 0750 /var/run/wpa_priv
+</programlisting></blockquote>
+
+ <para>Start <command>wpa_priv</command> as root (e.g., from system
+ startup scripts) with the enabled interfaces configured on the
+ command line:</para>
+
+<blockquote><programlisting>
+wpa_priv -B -c /var/run/wpa_priv -P /var/run/wpa_priv.pid wext:wlan0
+</programlisting></blockquote>
+
+ <para>Run <command>wpa_supplicant</command> as non-root with a user
+ that is in the wpapriv group:</para>
+
+<blockquote><programlisting>
+wpa_supplicant -i ath0 -c wpa_supplicant.conf
+</programlisting></blockquote>
+
+ </refsect1>
+ <refsect1>
+ <title>Command Arguments</title>
+ <variablelist>
+ <varlistentry>
+ <term>-c ctrl path</term>
+
+ <listitem><para>Specify the path to wpa_priv control directory
+ (Default: /var/run/wpa_priv/).</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>-B</term>
+ <listitem><para>Run as a daemon in the background.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>-P file</term>
+
+ <listitem><para>Set the location of the PID
+ file.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>driver:ifname [driver:ifname ...]</term>
+
+ <listitem><para>The &lt;driver&gt; string dictates which of the
+ supported <command>wpa_supplicant</command> driver backends is to be
+ used. To get a list of supported driver types see wpa_supplicant help
+ (e.g, wpa_supplicant -h). The driver backend supported by most good
+ drivers is 'wext'.</para>
+
+ <para>The &lt;ifname&gt; string specifies which network
+ interface is to be managed by <command>wpa_supplicant</command>
+ (e.g., wlan0 or ath0).</para>
+
+ <para><command>wpa_priv</command> does not use the network interface
+ before <command>wpa_supplicant</command> is started, so it is fine to
+ include network interfaces that are not available at the time wpa_priv
+ is started. wpa_priv can control multiple interfaces with one process,
+ but it is also possible to run multiple <command>wpa_priv</command>
+ processes at the same time, if desired.</para></listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+ <refsect1>
+ <title>See Also</title>
+ <para>
+ <citerefentry>
+ <refentrytitle>wpa_supplicant</refentrytitle>
+ <manvolnum>8</manvolnum>
+ </citerefentry>
+ </para>
+ </refsect1>
+ <refsect1>
+ <title>Legal</title>
+ <para>wpa_supplicant is copyright (c) 2003-2007,
+ Jouni Malinen <email>j@w1.fi</email> and
+ contributors.
+ All Rights Reserved.</para>
+
+ <para>This program is dual-licensed under both the GPL version 2
+ and BSD license. Either license may be used at your option.</para>
+ </refsect1>
+</refentry>
diff --git a/wpa_supplicant/doc/docbook/wpa_supplicant.conf.sgml b/wpa_supplicant/doc/docbook/wpa_supplicant.conf.sgml
new file mode 100644
index 0000000..00bf6f5
--- /dev/null
+++ b/wpa_supplicant/doc/docbook/wpa_supplicant.conf.sgml
@@ -0,0 +1,238 @@
+<!doctype refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
+<refentry>
+ <refmeta>
+ <refentrytitle>wpa_supplicant.conf</refentrytitle>
+ <manvolnum>5</manvolnum>
+ </refmeta>
+ <refnamediv>
+ <refname>wpa_supplicant.conf</refname>
+ <refpurpose>configuration file for wpa_supplicant</refpurpose>
+ </refnamediv>
+ <refsect1>
+ <title>Overview</title>
+
+ <para><command>wpa_supplicant</command> is configured using a text
+ file that lists all accepted networks and security policies,
+ including pre-shared keys. See the example configuration file,
+ probably in <command>/usr/share/doc/wpa_supplicant/</command>, for
+ detailed information about the configuration format and supported
+ fields.</para>
+
+ <para>All file paths in this configuration file should use full
+ (absolute, not relative to working directory) path in order to allow
+ working directory to be changed. This can happen if wpa_supplicant is
+ run in the background.</para>
+
+ <para>Changes to configuration file can be reloaded be sending
+ SIGHUP signal to <command>wpa_supplicant</command> ('killall -HUP
+ wpa_supplicant'). Similarly, reloading can be triggered with
+ the 'wpa_cli reconfigure' command.</para>
+
+ <para>Configuration file can include one or more network blocks,
+ e.g., one for each used SSID. wpa_supplicant will automatically
+ select the best network based on the order of network blocks in
+ the configuration file, network security level (WPA/WPA2 is
+ preferred), and signal strength.</para>
+ </refsect1>
+
+ <refsect1>
+ <title>Quick Examples</title>
+
+ <orderedlist>
+ <listitem>
+
+ <para>WPA-Personal (PSK) as home network and WPA-Enterprise with
+ EAP-TLS as work network.</para>
+
+<blockquote><programlisting>
+# allow frontend (e.g., wpa_cli) to be used by all users in 'wheel' group
+ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=wheel
+#
+# home network; allow all valid ciphers
+network={
+ ssid="home"
+ scan_ssid=1
+ key_mgmt=WPA-PSK
+ psk="very secret passphrase"
+}
+#
+# work network; use EAP-TLS with WPA; allow only CCMP and TKIP ciphers
+network={
+ ssid="work"
+ scan_ssid=1
+ key_mgmt=WPA-EAP
+ pairwise=CCMP TKIP
+ group=CCMP TKIP
+ eap=TLS
+ identity="user@example.com"
+ ca_cert="/etc/cert/ca.pem"
+ client_cert="/etc/cert/user.pem"
+ private_key="/etc/cert/user.prv"
+ private_key_passwd="password"
+}
+</programlisting></blockquote>
+ </listitem>
+
+ <listitem>
+ <para>WPA-RADIUS/EAP-PEAP/MSCHAPv2 with RADIUS servers that
+ use old peaplabel (e.g., Funk Odyssey and SBR, Meetinghouse
+ Aegis, Interlink RAD-Series)</para>
+
+<blockquote><programlisting>
+ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=wheel
+network={
+ ssid="example"
+ scan_ssid=1
+ key_mgmt=WPA-EAP
+ eap=PEAP
+ identity="user@example.com"
+ password="foobar"
+ ca_cert="/etc/cert/ca.pem"
+ phase1="peaplabel=0"
+ phase2="auth=MSCHAPV2"
+}
+</programlisting></blockquote>
+ </listitem>
+
+ <listitem>
+ <para>EAP-TTLS/EAP-MD5-Challenge configuration with anonymous
+ identity for the unencrypted use. Real identity is sent only
+ within an encrypted TLS tunnel.</para>
+
+
+<blockquote><programlisting>
+ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=wheel
+network={
+ ssid="example"
+ scan_ssid=1
+ key_mgmt=WPA-EAP
+ eap=TTLS
+ identity="user@example.com"
+ anonymous_identity="anonymous@example.com"
+ password="foobar"
+ ca_cert="/etc/cert/ca.pem"
+ phase2="auth=MD5"
+}
+</programlisting></blockquote>
+
+ </listitem>
+
+ <listitem>
+ <para>IEEE 802.1X (i.e., no WPA) with dynamic WEP keys
+ (require both unicast and broadcast); use EAP-TLS for
+ authentication</para>
+
+<blockquote><programlisting>
+ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=wheel
+network={
+ ssid="1x-test"
+ scan_ssid=1
+ key_mgmt=IEEE8021X
+ eap=TLS
+ identity="user@example.com"
+ ca_cert="/etc/cert/ca.pem"
+ client_cert="/etc/cert/user.pem"
+ private_key="/etc/cert/user.prv"
+ private_key_passwd="password"
+ eapol_flags=3
+}
+</programlisting></blockquote>
+ </listitem>
+
+
+ <listitem>
+ <para>Catch all example that allows more or less all
+ configuration modes. The configuration options are used based
+ on what security policy is used in the selected SSID. This is
+ mostly for testing and is not recommended for normal
+ use.</para>
+
+<blockquote><programlisting>
+ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=wheel
+network={
+ ssid="example"
+ scan_ssid=1
+ key_mgmt=WPA-EAP WPA-PSK IEEE8021X NONE
+ pairwise=CCMP TKIP
+ group=CCMP TKIP WEP104 WEP40
+ psk="very secret passphrase"
+ eap=TTLS PEAP TLS
+ identity="user@example.com"
+ password="foobar"
+ ca_cert="/etc/cert/ca.pem"
+ client_cert="/etc/cert/user.pem"
+ private_key="/etc/cert/user.prv"
+ private_key_passwd="password"
+ phase1="peaplabel=0"
+ ca_cert2="/etc/cert/ca2.pem"
+ client_cert2="/etc/cer/user.pem"
+ private_key2="/etc/cer/user.prv"
+ private_key2_passwd="password"
+}
+</programlisting></blockquote>
+ </listitem>
+
+ <listitem>
+ <para>Authentication for wired Ethernet. This can be used with
+ 'wired' interface (-Dwired on command line).</para>
+
+<blockquote><programlisting>
+ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=wheel
+ap_scan=0
+network={
+ key_mgmt=IEEE8021X
+ eap=MD5
+ identity="user"
+ password="password"
+ eapol_flags=0
+}
+</programlisting></blockquote>
+ </listitem>
+ </orderedlist>
+
+
+
+
+
+ </refsect1>
+ <refsect1>
+ <title>Certificates</title>
+
+ <para>Some EAP authentication methods require use of
+ certificates. EAP-TLS uses both server side and client
+ certificates whereas EAP-PEAP and EAP-TTLS only require the server
+ side certificate. When client certificate is used, a matching
+ private key file has to also be included in configuration. If the
+ private key uses a passphrase, this has to be configured in
+ wpa_supplicant.conf ("private_key_passwd").</para>
+
+ <para>wpa_supplicant supports X.509 certificates in PEM and DER
+ formats. User certificate and private key can be included in the
+ same file.</para>
+
+ <para>If the user certificate and private key is received in
+ PKCS#12/PFX format, they need to be converted to suitable PEM/DER
+ format for wpa_supplicant. This can be done, e.g., with following
+ commands:</para>
+<blockquote><programlisting>
+# convert client certificate and private key to PEM format
+openssl pkcs12 -in example.pfx -out user.pem -clcerts
+# convert CA certificate (if included in PFX file) to PEM format
+openssl pkcs12 -in example.pfx -out ca.pem -cacerts -nokeys
+</programlisting></blockquote>
+ </refsect1>
+
+ <refsect1>
+ <title>See Also</title>
+ <para>
+ <citerefentry>
+ <refentrytitle>wpa_supplicant</refentrytitle>
+ <manvolnum>8</manvolnum>
+ </citerefentry>
+ <citerefentry>
+ <refentrytitle>openssl</refentrytitle>
+ <manvolnum>1</manvolnum>
+ </citerefentry>
+ </para>
+ </refsect1>
+</refentry>
diff --git a/wpa_supplicant/doc/docbook/wpa_supplicant.sgml b/wpa_supplicant/doc/docbook/wpa_supplicant.sgml
new file mode 100644
index 0000000..21c4951
--- /dev/null
+++ b/wpa_supplicant/doc/docbook/wpa_supplicant.sgml
@@ -0,0 +1,795 @@
+<!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 have 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>The available drivers to specify with the -D option are:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term>hostap</term>
+ <listitem>
+ <para>(default) Host AP driver (Intersil Prism2/2.5/3).
+ (this can also be used with Linuxant DriverLoader).</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>hermes</term>
+ <listitem>
+ <para>Agere Systems Inc. driver (Hermes-I/Hermes-II).</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>madwifi</term>
+ <listitem>
+ <para>MADWIFI 802.11 support (Atheros, etc.).</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>atmel</term>
+ <listitem>
+ <para>ATMEL AT76C5XXx (USB, PCMCIA).</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>wext</term>
+ <listitem>
+ <para>Linux wireless extensions (generic).</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ndiswrapper</term>
+ <listitem>
+ <para>Linux ndiswrapper.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>broadcom</term>
+ <listitem>
+ <para>Broadcom wl.o driver.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ipw</term>
+ <listitem>
+ <para>Intel ipw2100/2200 driver.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>wired</term>
+ <listitem>
+ <para>wpa_supplicant wired Ethernet 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>
+ <variablelist>
+ <varlistentry>
+ <term>-b br_ifname</term>
+ <listitem>
+ <para>Optional bridge interface name.</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.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>-C ctrl_interface</term>
+ <listitem>
+ <para>Path to ctrl_interface socket (only used if -c is not).</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>-i ifname</term>
+ <listitem>
+ <para>Interface to listen on.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>-d</term>
+ <listitem>
+ <para>Increase debugging verbosity (-dd even more).</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>-D driver</term>
+ <listitem>
+ <para>Driver to use. 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.</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 (GPL and BSD).</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>-p</term>
+ <listitem>
+ <para>Driver parameters.</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 (-qq even less).</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>-u</term>
+ <listitem>
+ <para>Enabled DBus control interface.</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><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 hostap -N \
+ -c wpa2.conf -i ath0 -D madwifi
+</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>Host AP driver for Prism2/2.5/3 (development
+ snapshot/v0.2.x)</term>
+ <listitem>
+ <para> (http://hostap.epitest.fi/) Driver needs to be set in
+ Managed mode ('iwconfig wlan0 mode managed'). Please note
+ that station firmware version needs to be 1.7.0 or newer to
+ work in WPA mode.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Linuxant DriverLoader</term>
+ <listitem>
+ <para>(http://www.linuxant.com/driverloader/)
+ with Windows NDIS driver for your wlan card supporting WPA.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Agere Systems Inc. Linux Driver</term>
+ <listitem>
+ <para> (http://www.agere.com/support/drivers/) Please note
+ that the driver interface file (driver_hermes.c) and hardware
+ specific include files are not included in the wpa_supplicant
+ distribution. You will need to copy these from the source
+ package of the Agere driver.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>madwifi driver for cards based on Atheros chip set (ar521x)</term>
+ <listitem>
+ <para> (http://sourceforge.net/projects/madwifi/) Please
+ note that you will need to modify the wpa_supplicant .config
+ file to use the correct path for the madwifi driver root
+ directory (CFLAGS += -I../madwifi/wpa line in example
+ defconfig).</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ATMEL AT76C5XXx driver for USB and PCMCIA cards</term>
+ <listitem>
+ <para> (http://atmelwlandriver.sourceforge.net/).</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Linux ndiswrapper</term>
+ <listitem>
+ <para> (http://ndiswrapper.sourceforge.net/) with Windows
+ NDIS driver.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Broadcom wl.o driver</term>
+ <listitem>
+ <para> This is a generic Linux driver for Broadcom IEEE
+ 802.11a/g cards. However, it is proprietary driver that is
+ not publicly available except for couple of exceptions, mainly
+ Broadcom-based APs/wireless routers that use Linux. The driver
+ binary can be downloaded, e.g., from Linksys support site
+ (http://www.linksys.com/support/gpl.asp) for Linksys
+ WRT54G. The GPL tarball includes cross-compiler and the needed
+ header file, wlioctl.h, for compiling wpa_supplicant. This
+ driver support in wpa_supplicant is expected to work also with
+ other devices based on Broadcom driver (assuming the driver
+ includes client mode support).</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term> Intel ipw2100 driver</term>
+ <listitem>
+ <para> (http://sourceforge.net/projects/ipw2100/)</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Intel ipw2200 driver</term>
+ <listitem>
+ <para> (http://sourceforge.net/projects/ipw2200/)</para>
+ </listitem>
+ </varlistentry>
+
+ <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 'start' 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 'stop' 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-2007,
+ Jouni Malinen <email>j@w1.fi</email> and
+ contributors.
+ All Rights Reserved.</para>
+
+ <para>This program is dual-licensed under both the GPL version 2
+ and BSD license. Either license may be used at your option.</para>
+ </refsect1>
+</refentry>