diff options
Diffstat (limited to 'wpa_supplicant/doc/docbook')
| -rw-r--r-- | wpa_supplicant/doc/docbook/.gitignore | 6 | ||||
| -rw-r--r-- | wpa_supplicant/doc/docbook/Makefile | 27 | ||||
| -rw-r--r-- | wpa_supplicant/doc/docbook/manpage.links | 0 | ||||
| -rw-r--r-- | wpa_supplicant/doc/docbook/manpage.refs | 4 | ||||
| -rw-r--r-- | wpa_supplicant/doc/docbook/wpa_background.8 | 84 | ||||
| -rw-r--r-- | wpa_supplicant/doc/docbook/wpa_background.sgml | 101 | ||||
| -rw-r--r-- | wpa_supplicant/doc/docbook/wpa_cli.8 | 210 | ||||
| -rw-r--r-- | wpa_supplicant/doc/docbook/wpa_cli.sgml | 339 | ||||
| -rw-r--r-- | wpa_supplicant/doc/docbook/wpa_gui.8 | 51 | ||||
| -rw-r--r-- | wpa_supplicant/doc/docbook/wpa_gui.sgml | 85 | ||||
| -rw-r--r-- | wpa_supplicant/doc/docbook/wpa_passphrase.8 | 40 | ||||
| -rw-r--r-- | wpa_supplicant/doc/docbook/wpa_passphrase.sgml | 73 | ||||
| -rw-r--r-- | wpa_supplicant/doc/docbook/wpa_priv.8 | 120 | ||||
| -rw-r--r-- | wpa_supplicant/doc/docbook/wpa_priv.sgml | 148 | ||||
| -rw-r--r-- | wpa_supplicant/doc/docbook/wpa_supplicant.8 | 571 | ||||
| -rw-r--r-- | wpa_supplicant/doc/docbook/wpa_supplicant.conf.5 | 225 | ||||
| -rw-r--r-- | wpa_supplicant/doc/docbook/wpa_supplicant.conf.sgml | 239 | ||||
| -rw-r--r-- | wpa_supplicant/doc/docbook/wpa_supplicant.sgml | 818 |
18 files changed, 3141 insertions, 0 deletions
diff --git a/wpa_supplicant/doc/docbook/.gitignore b/wpa_supplicant/doc/docbook/.gitignore new file mode 100644 index 000000000000..8c3945c526b5 --- /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 000000000000..aaeee2eee453 --- /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/manpage.links b/wpa_supplicant/doc/docbook/manpage.links new file mode 100644 index 000000000000..e69de29bb2d1 --- /dev/null +++ b/wpa_supplicant/doc/docbook/manpage.links diff --git a/wpa_supplicant/doc/docbook/manpage.refs b/wpa_supplicant/doc/docbook/manpage.refs new file mode 100644 index 000000000000..16ffc791b0e1 --- /dev/null +++ b/wpa_supplicant/doc/docbook/manpage.refs @@ -0,0 +1,4 @@ +{ + '' => '', + '' => '' +} diff --git a/wpa_supplicant/doc/docbook/wpa_background.8 b/wpa_supplicant/doc/docbook/wpa_background.8 new file mode 100644 index 000000000000..3bda3f4e5033 --- /dev/null +++ b/wpa_supplicant/doc/docbook/wpa_background.8 @@ -0,0 +1,84 @@ +.\" This manpage has been automatically generated by docbook2man +.\" from a DocBook document. This tool can be found at: +.\" <http://shell.ipoline.com/~elmert/comp/docbook2X/> +.\" Please send any bug reports, improvements, comments, patches, +.\" etc. to Steve Cheng <steve@ggi-project.org>. +.TH "WPA_BACKGROUND" "8" "15 February 2009" "" "" + +.SH NAME +wpa_background \- Background information on Wi-Fi Protected Access and IEEE 802.11i +.SH "WPA" +.PP +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. +.PP +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<TM> (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). +.PP +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. +.PP +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). +.PP +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). +.PP +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). +.SH "IEEE 802.11I / WPA2" +.PP +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). +.SH "SEE ALSO" +.PP +\fBwpa_supplicant\fR(8) +.SH "LEGAL" +.PP +wpa_supplicant is copyright (c) 2003-2007, +Jouni Malinen <j@w1.fi> and +contributors. +All Rights Reserved. +.PP +This program is dual-licensed under both the GPL version 2 +and BSD license. Either license may be used at your option. diff --git a/wpa_supplicant/doc/docbook/wpa_background.sgml b/wpa_supplicant/doc/docbook/wpa_background.sgml new file mode 100644 index 000000000000..f47235b17118 --- /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<TM> (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.8 b/wpa_supplicant/doc/docbook/wpa_cli.8 new file mode 100644 index 000000000000..4e4aa461166c --- /dev/null +++ b/wpa_supplicant/doc/docbook/wpa_cli.8 @@ -0,0 +1,210 @@ +.\" This manpage has been automatically generated by docbook2man +.\" from a DocBook document. This tool can be found at: +.\" <http://shell.ipoline.com/~elmert/comp/docbook2X/> +.\" Please send any bug reports, improvements, comments, patches, +.\" etc. to Steve Cheng <steve@ggi-project.org>. +.TH "WPA_CLI" "8" "15 February 2009" "" "" + +.SH NAME +wpa_cli \- WPA command line client +.SH SYNOPSIS + +\fBwpa_cli\fR [ \fB-p \fIpath to ctrl sockets\fB\fR ] [ \fB-i \fIifname\fB\fR ] [ \fB-hvB\fR ] [ \fB-a \fIaction file\fB\fR ] [ \fB-P \fIpid file\fB\fR ] [ \fB\fIcommand ...\fB\fR ] + +.SH "OVERVIEW" +.PP +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. +.PP +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. +.PP +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. +.PP +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). +.PP +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. +.SH "INTERACTIVE AUTHENTICATION PARAMETERS REQUEST" +.PP +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-<type>-<id>:<text>" +prefix. <type> is IDENTITY, PASSWORD, or OTP +(one-time-password). <id> is a unique identifier for the +current network. <text> is description of the request. In +case of OTP request, it includes the challenge from the +authentication server. +.PP +The reply to these requests can be given with +\fBidentity\fR, \fBpassword\fR, and +\fBotp\fR commands. <id> needs to be copied from +the matching request. \fBpassword\fR and +\fBotp\fR 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 \fBpassword\fR are +remembered as long as wpa_supplicant is running whereas values given +with \fBotp\fR 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. +.PP +Example request for password and a matching reply: +.sp +.RS + +.nf +CTRL-REQ-PASSWORD-1:Password needed for SSID foobar +> password 1 mysecretpassword +.fi +.RE +.PP +Example request for generic token card challenge-response: +.sp +.RS + +.nf +CTRL-REQ-OTP-2:Challenge 1235663 needed for SSID foobar +> otp 2 9876 +.fi +.RE +.SH "COMMAND ARGUMENTS" +.TP +\fB-p path\fR +Change the path where control sockets should +be found. +.TP +\fB-i ifname\fR +Specify the interface that is being +configured. By default, choose the first interface found with +a control socket in the socket path. +.TP +\fB-h\fR +Help. Show a usage message. +.TP +\fB-v\fR +Show version information. +.TP +\fB-B\fR +Run as a daemon in the background. +.TP +\fB-a file\fR +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. + +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. +.TP +\fB-P file\fR +Set the location of the PID +file. +.TP +\fBcommand\fR +Run a command. The available commands are +listed in the next section. +.SH "COMMANDS" +.PP +The following commands are available: +.TP +\fBstatus\fR +get current WPA/EAPOL/EAP status +.TP +\fBmib\fR +get MIB variables (dot1x, dot11) +.TP +\fBhelp\fR +show this usage help +.TP +\fBinterface [ifname]\fR +show interfaces/select interface +.TP +\fBlevel <debug level>\fR +change debug level +.TP +\fBlicense\fR +show full wpa_cli license +.TP +\fBlogoff\fR +IEEE 802.1X EAPOL state machine logoff +.TP +\fBlogon\fR +IEEE 802.1X EAPOL state machine logon +.TP +\fBset\fR +set variables (shows list of variables when run without arguments) +.TP +\fBpmksa\fR +show PMKSA cache +.TP +\fBreassociate\fR +force reassociation +.TP +\fBreconfigure\fR +force wpa_supplicant to re-read its configuration file +.TP +\fBpreauthenticate <BSSID>\fR +force preauthentication +.TP +\fBidentity <network id> <identity>\fR +configure identity for an SSID +.TP +\fBpassword <network id> <password>\fR +configure password for an SSID +.TP +\fBpin <network id> <pin>\fR +configure pin for an SSID +.TP +\fBotp <network id> <password>\fR +configure one-time-password for an SSID +.TP +\fBbssid <network id> <BSSID>\fR +set preferred BSSID for an SSID +.TP +\fBlist_networks\fR +list configured networks +.TP +\fBterminate\fR +terminate \fBwpa_supplicant\fR +.TP +\fBquit\fR +exit wpa_cli +.SH "SEE ALSO" +.PP +\fBwpa_supplicant\fR(8) +.SH "LEGAL" +.PP +wpa_supplicant is copyright (c) 2003-2007, +Jouni Malinen <j@w1.fi> and +contributors. +All Rights Reserved. +.PP +This program is dual-licensed under both the GPL version 2 +and BSD license. Either license may be used at your option. diff --git a/wpa_supplicant/doc/docbook/wpa_cli.sgml b/wpa_supplicant/doc/docbook/wpa_cli.sgml new file mode 100644 index 000000000000..1fe98f4fc56e --- /dev/null +++ b/wpa_supplicant/doc/docbook/wpa_cli.sgml @@ -0,0 +1,339 @@ +<!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-<type>-<id>:<text>" + prefix. <type> is IDENTITY, PASSWORD, or OTP + (one-time-password). <id> is a unique identifier for the + current network. <text> 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 + <emphasis>identity</emphasis>, <emphasis>password</emphasis>, and + <emphasis>otp</emphasis> commands. <id> needs to be copied from + the matching request. <emphasis>password</emphasis> and + <emphasis>otp</emphasis> 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 <emphasis>password</emphasis> are + remembered as long as wpa_supplicant is running whereas values given + with <emphasis>otp</emphasis> 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 <debug level></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 <BSSID></term> + <listitem> + <para>force preauthentication</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>identity <network id> <identity></term> + <listitem> + <para>configure identity for an SSID</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>password <network id> <password></term> + <listitem> + <para>configure password for an SSID</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>pin <network id> <pin></term> + <listitem> + <para>configure pin for an SSID</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>otp <network id> <password></term> + <listitem> + <para>configure one-time-password for an SSID</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>bssid <network id> <BSSID></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.8 b/wpa_supplicant/doc/docbook/wpa_gui.8 new file mode 100644 index 000000000000..2f4f638d28b1 --- /dev/null +++ b/wpa_supplicant/doc/docbook/wpa_gui.8 @@ -0,0 +1,51 @@ +.\" This manpage has been automatically generated by docbook2man +.\" from a DocBook document. This tool can be found at: +.\" <http://shell.ipoline.com/~elmert/comp/docbook2X/> +.\" Please send any bug reports, improvements, comments, patches, +.\" etc. to Steve Cheng <steve@ggi-project.org>. +.TH "WPA_GUI" "8" "15 February 2009" "" "" + +.SH NAME +wpa_gui \- WPA Graphical User Interface +.SH SYNOPSIS + +\fBwpa_gui\fR [ \fB-p \fIpath to ctrl sockets\fB\fR ] [ \fB-i \fIifname\fB\fR ] [ \fB-t\fR ] + +.SH "OVERVIEW" +.PP +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. +.PP +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. +.SH "COMMAND ARGUMENTS" +.TP +\fB-p path\fR +Change the path where control sockets should +be found. +.TP +\fB-i ifname\fR +Specify the interface that is being +configured. By default, choose the first interface found with +a control socket in the socket path. +.TP +\fB-t\fR +Start program in the system tray only (if the window +manager supports it). By default the main status window is +shown. +.SH "SEE ALSO" +.PP +\fBwpa_cli\fR(8) +\fBwpa_supplicant\fR(8) +.SH "LEGAL" +.PP +wpa_supplicant is copyright (c) 2003-2007, +Jouni Malinen <j@w1.fi> and +contributors. +All Rights Reserved. +.PP +This program is dual-licensed under both the GPL version 2 +and BSD license. Either license may be used at your option. diff --git a/wpa_supplicant/doc/docbook/wpa_gui.sgml b/wpa_supplicant/doc/docbook/wpa_gui.sgml new file mode 100644 index 000000000000..41b58492440e --- /dev/null +++ b/wpa_supplicant/doc/docbook/wpa_gui.sgml @@ -0,0 +1,85 @@ +<!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> + <arg>-t</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> + + <varlistentry> + <term>-t</term> + + <listitem><para>Start program in the system tray only (if the window + manager supports it). By default the main status window is + shown.</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.8 b/wpa_supplicant/doc/docbook/wpa_passphrase.8 new file mode 100644 index 000000000000..b123daad8091 --- /dev/null +++ b/wpa_supplicant/doc/docbook/wpa_passphrase.8 @@ -0,0 +1,40 @@ +.\" This manpage has been automatically generated by docbook2man +.\" from a DocBook document. This tool can be found at: +.\" <http://shell.ipoline.com/~elmert/comp/docbook2X/> +.\" Please send any bug reports, improvements, comments, patches, +.\" etc. to Steve Cheng <steve@ggi-project.org>. +.TH "WPA_PASSPHRASE" "8" "15 February 2009" "" "" + +.SH NAME +wpa_passphrase \- Generate a WPA PSK from an ASCII passphrase for a SSID +.SH SYNOPSIS + +\fBwpa_passphrase\fR [ \fB\fIssid\fB\fR ] [ \fB\fIpassphrase\fB\fR ] + +.SH "OVERVIEW" +.PP +\fBwpa_passphrase\fR pre-computes PSK entries for +network configuration blocks of a +\fIwpa_supplicant.conf\fR file. An ASCII passphrase +and SSID are used to generate a 256-bit PSK. +.SH "OPTIONS" +.TP +\fBssid\fR +The SSID whose passphrase should be derived. +.TP +\fBpassphrase\fR +The passphrase to use. If not included on the command line, +passphrase will be read from standard input. +.SH "SEE ALSO" +.PP +\fBwpa_supplicant.conf\fR(5) +\fBwpa_supplicant\fR(8) +.SH "LEGAL" +.PP +wpa_supplicant is copyright (c) 2003-2007, +Jouni Malinen <j@w1.fi> and +contributors. +All Rights Reserved. +.PP +This program is dual-licensed under both the GPL version 2 +and BSD license. Either license may be used at your option. diff --git a/wpa_supplicant/doc/docbook/wpa_passphrase.sgml b/wpa_supplicant/doc/docbook/wpa_passphrase.sgml new file mode 100644 index 000000000000..402ea091f9af --- /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.8 b/wpa_supplicant/doc/docbook/wpa_priv.8 new file mode 100644 index 000000000000..2191cec94e9c --- /dev/null +++ b/wpa_supplicant/doc/docbook/wpa_priv.8 @@ -0,0 +1,120 @@ +.\" This manpage has been automatically generated by docbook2man +.\" from a DocBook document. This tool can be found at: +.\" <http://shell.ipoline.com/~elmert/comp/docbook2X/> +.\" Please send any bug reports, improvements, comments, patches, +.\" etc. to Steve Cheng <steve@ggi-project.org>. +.TH "WPA_PRIV" "8" "15 February 2009" "" "" + +.SH NAME +wpa_priv \- wpa_supplicant privilege separation helper +.SH SYNOPSIS + +\fBwpa_priv\fR [ \fB-c \fIctrl path\fB\fR ] [ \fB-Bdd\fR ] [ \fB-P \fIpid file\fB\fR ] [ \fBdriver:ifname \fI[driver:ifname ...]\fB\fR ] + +.SH "OVERVIEW" +.PP +\fBwpa_priv\fR is a privilege separation helper that +minimizes the size of \fBwpa_supplicant\fR code that needs +to be run with root privileges. +.PP +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. +.PP +\fBwpa_priv\fR 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 \fBwpa_supplicant\fR in this kind of +configuration. After this, \fBwpa_supplicant\fR 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). +.SH "EXAMPLE CONFIGURATION" +.PP +The following steps are an example of how to configure +\fBwpa_priv\fR to allow users in the +\fBwpapriv\fR group to communicate with +\fBwpa_supplicant\fR with privilege separation: +.PP +Create user group (e.g., wpapriv) and assign users that +should be able to use wpa_supplicant into that group. +.PP +Create /var/run/wpa_priv directory for UNIX domain sockets and +control user access by setting it accessible only for the wpapriv +group: +.sp +.RS + +.nf +mkdir /var/run/wpa_priv +chown root:wpapriv /var/run/wpa_priv +chmod 0750 /var/run/wpa_priv +.fi +.RE +.PP +Start \fBwpa_priv\fR as root (e.g., from system +startup scripts) with the enabled interfaces configured on the +command line: +.sp +.RS + +.nf +wpa_priv -B -c /var/run/wpa_priv -P /var/run/wpa_priv.pid wext:wlan0 +.fi +.RE +.PP +Run \fBwpa_supplicant\fR as non-root with a user +that is in the wpapriv group: +.sp +.RS + +.nf +wpa_supplicant -i ath0 -c wpa_supplicant.conf +.fi +.RE +.SH "COMMAND ARGUMENTS" +.TP +\fB-c ctrl path\fR +Specify the path to wpa_priv control directory +(Default: /var/run/wpa_priv/). +.TP +\fB-B\fR +Run as a daemon in the background. +.TP +\fB-P file\fR +Set the location of the PID +file. +.TP +\fBdriver:ifname [driver:ifname ...]\fR +The <driver> string dictates which of the +supported \fBwpa_supplicant\fR 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 \fBwext\fR\&. + +The <ifname> string specifies which network +interface is to be managed by \fBwpa_supplicant\fR +(e.g., wlan0 or ath0). + +\fBwpa_priv\fR does not use the network interface +before \fBwpa_supplicant\fR 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 \fBwpa_priv\fR +processes at the same time, if desired. +.SH "SEE ALSO" +.PP +\fBwpa_supplicant\fR(8) +.SH "LEGAL" +.PP +wpa_supplicant is copyright (c) 2003-2007, +Jouni Malinen <j@w1.fi> and +contributors. +All Rights Reserved. +.PP +This program is dual-licensed under both the GPL version 2 +and BSD license. Either license may be used at your option. diff --git a/wpa_supplicant/doc/docbook/wpa_priv.sgml b/wpa_supplicant/doc/docbook/wpa_priv.sgml new file mode 100644 index 000000000000..89b8a9221965 --- /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 + <emphasis>wpapriv</emphasis> 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 <driver> 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 <emphasis>wext</emphasis>.</para> + + <para>The <ifname> 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.8 b/wpa_supplicant/doc/docbook/wpa_supplicant.8 new file mode 100644 index 000000000000..0106c69697f0 --- /dev/null +++ b/wpa_supplicant/doc/docbook/wpa_supplicant.8 @@ -0,0 +1,571 @@ +.\" This manpage has been automatically generated by docbook2man +.\" from a DocBook document. This tool can be found at: +.\" <http://shell.ipoline.com/~elmert/comp/docbook2X/> +.\" Please send any bug reports, improvements, comments, patches, +.\" etc. to Steve Cheng <steve@ggi-project.org>. +.TH "WPA_SUPPLICANT" "8" "15 February 2009" "" "" + +.SH NAME +wpa_supplicant \- Wi-Fi Protected Access client and IEEE 802.1X supplicant +.SH SYNOPSIS + +\fBwpa_supplicant\fR [ \fB-BddfhKLqqtuvW\fR ] [ \fB-i\fIifname\fB\fR ] [ \fB-c\fIconfig file\fB\fR ] [ \fB-D\fIdriver\fB\fR ] [ \fB-P\fIPID_file\fB\fR ] [ \fB-f\fIoutput file\fB\fR ] + +.SH "OVERVIEW" +.PP +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. +.PP +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. +.PP +\fBwpa_supplicant\fR 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. +.PP +\fBwpa_supplicant\fR is designed to be a +"daemon" program that runs in the background and acts as the +backend component controlling the wireless +connection. \fBwpa_supplicant\fR supports separate +frontend programs and an example text-based frontend, +\fBwpa_cli\fR, is included with +wpa_supplicant. +.PP +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. +.PP +After \fBwpa_supplicant\fR 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. +.PP +The following steps are used when associating with an AP +using WPA: +.TP 0.2i +\(bu +\fBwpa_supplicant\fR requests the kernel +driver to scan neighboring BSSes +.TP 0.2i +\(bu +\fBwpa_supplicant\fR selects a BSS based on +its configuration +.TP 0.2i +\(bu +\fBwpa_supplicant\fR requests the kernel +driver to associate with the chosen BSS +.TP 0.2i +\(bu +If WPA-EAP: integrated IEEE 802.1X Supplicant +completes EAP authentication with the +authentication server (proxied by the Authenticator in the +AP) +.TP 0.2i +\(bu +If WPA-EAP: master key is received from the IEEE 802.1X +Supplicant +.TP 0.2i +\(bu +If WPA-PSK: \fBwpa_supplicant\fR uses PSK +as the master session key +.TP 0.2i +\(bu +\fBwpa_supplicant\fR completes WPA 4-Way +Handshake and Group Key Handshake with the Authenticator +(AP) +.TP 0.2i +\(bu +\fBwpa_supplicant\fR configures encryption +keys for unicast and broadcast +.TP 0.2i +\(bu +normal data packets can be transmitted and received +.SH "SUPPORTED FEATURES" +.PP +Supported WPA/IEEE 802.11i features: +.TP 0.2i +\(bu +WPA-PSK ("WPA-Personal") +.TP 0.2i +\(bu +WPA with EAP (e.g., with RADIUS authentication server) +("WPA-Enterprise") Following authentication methods are +supported with an integrate IEEE 802.1X Supplicant: +.RS +.TP 0.2i +\(bu +EAP-TLS +.RE +.RS +.TP 0.2i +\(bu +EAP-PEAP/MSCHAPv2 (both PEAPv0 and PEAPv1) +.TP 0.2i +\(bu +EAP-PEAP/TLS (both PEAPv0 and PEAPv1) +.TP 0.2i +\(bu +EAP-PEAP/GTC (both PEAPv0 and PEAPv1) +.TP 0.2i +\(bu +EAP-PEAP/OTP (both PEAPv0 and PEAPv1) +.TP 0.2i +\(bu +EAP-PEAP/MD5-Challenge (both PEAPv0 and PEAPv1) +.TP 0.2i +\(bu +EAP-TTLS/EAP-MD5-Challenge +.TP 0.2i +\(bu +EAP-TTLS/EAP-GTC +.TP 0.2i +\(bu +EAP-TTLS/EAP-OTP +.TP 0.2i +\(bu +EAP-TTLS/EAP-MSCHAPv2 +.TP 0.2i +\(bu +EAP-TTLS/EAP-TLS +.TP 0.2i +\(bu +EAP-TTLS/MSCHAPv2 +.TP 0.2i +\(bu +EAP-TTLS/MSCHAP +.TP 0.2i +\(bu +EAP-TTLS/PAP +.TP 0.2i +\(bu +EAP-TTLS/CHAP +.TP 0.2i +\(bu +EAP-SIM +.TP 0.2i +\(bu +EAP-AKA +.TP 0.2i +\(bu +EAP-PSK +.TP 0.2i +\(bu +EAP-PAX +.TP 0.2i +\(bu +LEAP (note: requires special support from +the driver for IEEE 802.11 authentication) +.TP 0.2i +\(bu +(following methods are supported, but since +they do not generate keying material, they cannot be used +with WPA or IEEE 802.1X WEP keying) +.TP 0.2i +\(bu +EAP-MD5-Challenge +.TP 0.2i +\(bu +EAP-MSCHAPv2 +.TP 0.2i +\(bu +EAP-GTC +.TP 0.2i +\(bu +EAP-OTP +.RE +.TP 0.2i +\(bu +key management for CCMP, TKIP, WEP104, WEP40 +.TP 0.2i +\(bu +RSN/WPA2 (IEEE 802.11i) +.RS +.TP 0.2i +\(bu +pre-authentication +.TP 0.2i +\(bu +PMKSA caching +.RE +.SH "AVAILABLE DRIVERS" +.PP +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 +(\fBwpa_supplicant -h\fR). +.TP +\fBhostap\fR +(default) Host AP driver (Intersil Prism2/2.5/3). +(this can also be used with Linuxant DriverLoader). +.TP +\fBhermes\fR +Agere Systems Inc. driver (Hermes-I/Hermes-II). +.TP +\fBmadwifi\fR +MADWIFI 802.11 support (Atheros, etc.). +.TP +\fBatmel\fR +ATMEL AT76C5XXx (USB, PCMCIA). +.TP +\fBwext\fR +Linux wireless extensions (generic). +.TP +\fBndiswrapper\fR +Linux ndiswrapper. +.TP +\fBbroadcom\fR +Broadcom wl.o driver. +.TP +\fBipw\fR +Intel ipw2100/2200 driver. +.TP +\fBwired\fR +wpa_supplicant wired Ethernet driver +.TP +\fBroboswitch\fR +wpa_supplicant Broadcom switch driver +.TP +\fBbsd\fR +BSD 802.11 support (Atheros, etc.). +.TP +\fBndis\fR +Windows NDIS driver. +.SH "COMMAND LINE OPTIONS" +.PP +Most command line options have global scope. Some are given per +interface, and are only valid if at least one \fB-i\fR option +is specified, otherwise they're ignored. Option groups for different +interfaces must be separated by \fB-N\fR option. +.TP +\fB-b br_ifname\fR +Optional bridge interface name. (Per interface) +.TP +\fB-B\fR +Run daemon in the background. +.TP +\fB-c filename\fR +Path to configuration file. (Per interface) +.TP +\fB-C ctrl_interface\fR +Path to ctrl_interface socket (Per interface. Only used if +\fB-c\fR is not). +.TP +\fB-i ifname\fR +Interface to listen on. Multiple instances of this option can +be present, one per interface, separated by \fB-N\fR +option (see below). +.TP +\fB-d\fR +Increase debugging verbosity (\fB-dd\fR even +more). +.TP +\fB-D driver\fR +Driver to use. (Per interface, see the available options +below.) +.TP +\fB-f output file\fR +Log output to specified file instead of stdout. +.TP +\fB-g global ctrl_interface\fR +Path to global ctrl_interface socket. If specified, interface +definitions may be omitted. +.TP +\fB-K\fR +Include keys (passwords, etc.) in debug output. +.TP +\fB-t\fR +Include timestamp in debug messages. +.TP +\fB-h\fR +Help. Show a usage message. +.TP +\fB-L\fR +Show license (GPL and BSD). +.TP +\fB-p\fR +Driver parameters. (Per interface) +.TP +\fB-P PID_file\fR +Path to PID file. +.TP +\fB-q\fR +Decrease debugging verbosity (\fB-qq\fR even +less). +.TP +\fB-u\fR +Enabled DBus control interface. If enabled, interface +definitions may be omitted. +.TP +\fB-v\fR +Show version. +.TP +\fB-W\fR +Wait for a control interface monitor before starting. +.TP +\fB-N\fR +Start describing new interface. +.SH "EXAMPLES" +.PP +In most common cases, \fBwpa_supplicant\fR is +started with: +.sp +.RS + +.nf +wpa_supplicant -B -c/etc/wpa_supplicant.conf -iwlan0 +.fi +.RE +.PP +This makes the process fork into background. +.PP +The easiest way to debug problems, and to get debug log for +bug reports, is to start \fBwpa_supplicant\fR on +foreground with debugging enabled: +.sp +.RS + +.nf +wpa_supplicant -c/etc/wpa_supplicant.conf -iwlan0 -d +.fi +.RE +.PP +\fBwpa_supplicant\fR 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: +.sp +.RS + +.nf +wpa_supplicant \\ + -c wpa1.conf -i wlan0 -D hostap -N \\ + -c wpa2.conf -i ath0 -D madwifi +.fi +.RE +.SH "OS REQUIREMENTS" +.PP +Current hardware/software requirements: +.TP 0.2i +\(bu +Linux kernel 2.4.x or 2.6.x with Linux Wireless +Extensions v15 or newer +.TP 0.2i +\(bu +FreeBSD 6-CURRENT +.TP 0.2i +\(bu +Microsoft Windows with WinPcap (at least WinXP, may work +with other versions) +.SH "SUPPORTED DRIVERS" +.TP +\fBHost AP driver for Prism2/2.5/3 (development snapshot/v0.2.x)\fR +(http://hostap.epitest.fi/) Driver needs to be set in +Managed mode (\fBiwconfig wlan0 mode managed\fR). +Please note that station firmware version needs to be 1.7.0 or +newer to work in WPA mode. +.TP +\fBLinuxant DriverLoader\fR +(http://www.linuxant.com/driverloader/) +with Windows NDIS driver for your wlan card supporting WPA. +.TP +\fBAgere Systems Inc. Linux Driver\fR +(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. +.TP +\fBmadwifi driver for cards based on Atheros chip set (ar521x)\fR +(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). +.TP +\fBATMEL AT76C5XXx driver for USB and PCMCIA cards\fR +(http://atmelwlandriver.sourceforge.net/). +.TP +\fBLinux ndiswrapper\fR +(http://ndiswrapper.sourceforge.net/) with Windows +NDIS driver. +.TP +\fBBroadcom wl.o driver\fR +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). +.TP +\fB Intel ipw2100 driver\fR +(http://sourceforge.net/projects/ipw2100/) +.TP +\fBIntel ipw2200 driver\fR +(http://sourceforge.net/projects/ipw2200/) +.TP +\fBLinux wireless extensions\fR +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. +.TP +\fBWired Ethernet drivers\fR +Use ap_scan=0. +.TP +\fBBSD net80211 layer (e.g., Atheros driver)\fR +At the moment, this is for FreeBSD 6-CURRENT branch. +.TP +\fBWindows NDIS\fR +The current Windows port requires WinPcap +(http://winpcap.polito.it/). See README-Windows.txt for more +information. +.PP +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. +.SH "ARCHITECTURE" +.PP +The +\fBwpa_supplicant\fR system consists of the following +components: +.TP +\fB\fIwpa_supplicant.conf\fB \fR +the configuration file describing all networks that the +user wants the computer to connect to. +.TP +\fBwpa_supplicant\fR +the program that directly interacts with the +network interface. +.TP +\fBwpa_cli\fR +the +client program that provides a high-level interface to the +functionality of the daemon. +.TP +\fBwpa_passphrase\fR +a utility needed to construct +\fIwpa_supplicant.conf\fR files that include +encrypted passwords. +.SH "QUICK START" +.PP +First, make a configuration file, e.g. +\fI/etc/wpa_supplicant.conf\fR, that describes the networks +you are interested in. See \fBwpa_supplicant.conf\fR(5) +for details. +.PP +Once the configuration is ready, you can test whether the +configuration works by running \fBwpa_supplicant\fR +with following command to start it on foreground with debugging +enabled: +.sp +.RS + +.nf +wpa_supplicant -iwlan0 -c/etc/wpa_supplicant.conf -d + +.fi +.RE +.PP +Assuming everything goes fine, you can start using following +command to start \fBwpa_supplicant\fR on background +without debugging: +.sp +.RS + +.nf +wpa_supplicant -iwlan0 -c/etc/wpa_supplicant.conf -B + +.fi +.RE +.PP +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. +.SH "INTERFACE TO PCMCIA-CS/CARDMRG" +.PP +For example, following small changes to pcmcia-cs scripts +can be used to enable WPA support: +.PP +Add MODE="Managed" and WPA="y" to the network scheme in +\fI/etc/pcmcia/wireless.opts\fR\&. +.PP +Add the following block to the end of \fBstart\fR +action handler in \fI/etc/pcmcia/wireless\fR: +.sp +.RS + +.nf +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 + +.fi +.RE +.PP +Add the following block to the end of \fBstop\fR +action handler (may need to be separated from other actions) in +\fI/etc/pcmcia/wireless\fR: +.sp +.RS + +.nf +if [ "$WPA" = "y" -a -x /usr/local/bin/wpa_supplicant ]; then + killall wpa_supplicant +fi + +.fi +.RE +.PP +This will make \fBcardmgr\fR start +\fBwpa_supplicant\fR when the card is plugged +in. +.SH "SEE ALSO" +.PP +\fBwpa_background\fR(8) +\fBwpa_supplicant.conf\fR(5) +\fBwpa_cli\fR(8) +\fBwpa_passphrase\fR(8) +.SH "LEGAL" +.PP +wpa_supplicant is copyright (c) 2003-2007, +Jouni Malinen <j@w1.fi> and +contributors. +All Rights Reserved. +.PP +This program is dual-licensed under both the GPL version 2 +and BSD license. Either license may be used at your option. diff --git a/wpa_supplicant/doc/docbook/wpa_supplicant.conf.5 b/wpa_supplicant/doc/docbook/wpa_supplicant.conf.5 new file mode 100644 index 000000000000..7a01ea2f5d31 --- /dev/null +++ b/wpa_supplicant/doc/docbook/wpa_supplicant.conf.5 @@ -0,0 +1,225 @@ +.\" This manpage has been automatically generated by docbook2man +.\" from a DocBook document. This tool can be found at: +.\" <http://shell.ipoline.com/~elmert/comp/docbook2X/> +.\" Please send any bug reports, improvements, comments, patches, +.\" etc. to Steve Cheng <steve@ggi-project.org>. +.TH "WPA_SUPPLICANT.CONF" "5" "15 February 2009" "" "" + +.SH NAME +wpa_supplicant.conf \- configuration file for wpa_supplicant +.SH "OVERVIEW" +.PP +\fBwpa_supplicant\fR 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 \fB/usr/share/doc/wpa_supplicant/\fR, for +detailed information about the configuration format and supported +fields. +.PP +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. +.PP +Changes to configuration file can be reloaded be sending +SIGHUP signal to \fBwpa_supplicant\fR ('killall -HUP +wpa_supplicant'). Similarly, reloading can be triggered with +the \fBwpa_cli reconfigure\fR command. +.PP +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. +.SH "QUICK EXAMPLES" +.TP 3 +1. +WPA-Personal (PSK) as home network and WPA-Enterprise with +EAP-TLS as work network. +.sp +.RS + +.nf +# 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" +} +.fi +.RE +.TP 3 +2. +WPA-RADIUS/EAP-PEAP/MSCHAPv2 with RADIUS servers that +use old peaplabel (e.g., Funk Odyssey and SBR, Meetinghouse +Aegis, Interlink RAD-Series) +.sp +.RS + +.nf +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" +} +.fi +.RE +.TP 3 +3. +EAP-TTLS/EAP-MD5-Challenge configuration with anonymous +identity for the unencrypted use. Real identity is sent only +within an encrypted TLS tunnel. +.sp +.RS + +.nf +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" +} +.fi +.RE +.TP 3 +4. +IEEE 802.1X (i.e., no WPA) with dynamic WEP keys +(require both unicast and broadcast); use EAP-TLS for +authentication +.sp +.RS + +.nf +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 +} +.fi +.RE +.TP 3 +5. +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. +.sp +.RS + +.nf +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" +} +.fi +.RE +.TP 3 +6. +Authentication for wired Ethernet. This can be used with +\fBwired\fR or \fBroboswitch\fR interface +(-Dwired or -Droboswitch on command line). +.sp +.RS + +.nf +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 +} +.fi +.RE +.SH "CERTIFICATES" +.PP +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"). +.PP +wpa_supplicant supports X.509 certificates in PEM and DER +formats. User certificate and private key can be included in the +same file. +.PP +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: +.sp +.RS + +.nf +# 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 +.fi +.RE +.SH "SEE ALSO" +.PP +\fBwpa_supplicant\fR(8) +\fBopenssl\fR(1) 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 000000000000..462039d9ed93 --- /dev/null +++ b/wpa_supplicant/doc/docbook/wpa_supplicant.conf.sgml @@ -0,0 +1,239 @@ +<!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 <emphasis>wpa_cli reconfigure</emphasis> 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 + <emphasis>wired</emphasis> or <emphasis>roboswitch</emphasis> interface + (-Dwired or -Droboswitch 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 000000000000..9798cedf16a3 --- /dev/null +++ b/wpa_supplicant/doc/docbook/wpa_supplicant.sgml @@ -0,0 +1,818 @@ +<!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>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>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. (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 (GPL and 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><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 (<emphasis>iwconfig wlan0 mode managed</emphasis>). + 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<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-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> |