logo

oasis-root

Compiled tree of Oasis Linux based on own branch at <https://hacktivis.me/git/oasis/> git clone https://anongit.hacktivis.me/git/oasis-root.git

wpa_supplicant.8 (14267B)


  1. .\" This manpage has been automatically generated by docbook2man
  2. .\" from a DocBook document. This tool can be found at:
  3. .\" <http://shell.ipoline.com/~elmert/comp/docbook2X/>
  4. .\" Please send any bug reports, improvements, comments, patches,
  5. .\" etc. to Steve Cheng <steve@ggi-project.org>.
  6. .TH "WPA_SUPPLICANT" "8" "1 February 2023" "" ""
  7. .SH NAME
  8. wpa_supplicant \- Wi-Fi Protected Access client and IEEE 802.1X supplicant
  9. .SH SYNOPSIS
  10. \fBwpa_supplicant\fR [ \fB-BddfhKLqqsTtuvW\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 ] [ \fB-I\fIadditional config file\fB\fR ]
  11. .SH "OVERVIEW"
  12. .PP
  13. Wireless networks do not require physical access to the network equipment
  14. in the same way that wired networks do. This makes it easier for unauthorized
  15. users to passively monitor a network and capture all transmitted frames.
  16. In addition, unauthorized use of the network is much easier. In many cases,
  17. this can happen even without user's explicit knowledge since the wireless
  18. LAN adapter may have been configured to automatically join any available
  19. network.
  20. .PP
  21. Link-layer encryption can be used to provide a layer of security for
  22. wireless networks. The original wireless LAN standard, IEEE 802.11,
  23. included a simple encryption mechanism, WEP. However, that proved to
  24. be flawed in many areas and networks protected with WEP cannot be considered
  25. secure. IEEE 802.1X authentication and frequently changed dynamic WEP keys
  26. can be used to improve the network security, but even that has inherited
  27. security issues due to the use of WEP for encryption. Wi-Fi Protected
  28. Access and the IEEE 802.11i amendment to the wireless LAN standard introduce
  29. a much improved mechanism for securing wireless networks. IEEE 802.11i
  30. enabled networks that are using CCMP (an encryption mechanism based on the strong
  31. cryptographic algorithm AES) can finally be called secure and used for
  32. applications which require efficient protection against unauthorized
  33. access.
  34. .PP
  35. \fBwpa_supplicant\fR is an implementation of
  36. the WPA Supplicant component, i.e., the part that runs in the
  37. client stations. It implements WPA key negotiation with a WPA
  38. Authenticator and EAP authentication with Authentication
  39. Server. In addition, it controls the roaming and IEEE 802.11
  40. authentication/association of the wireless LAN driver.
  41. .PP
  42. \fBwpa_supplicant\fR is designed to be a
  43. "daemon" program that runs in the background and acts as the
  44. backend component controlling the wireless
  45. connection. \fBwpa_supplicant\fR supports separate
  46. frontend programs and an example text-based frontend,
  47. \fBwpa_cli\fR, is included with
  48. wpa_supplicant.
  49. .PP
  50. Before wpa_supplicant can do its work, the network interface
  51. must be available. That means that the physical device must be
  52. present and enabled, and the driver for the device must be
  53. loaded. The daemon will exit immediately if the device is not already
  54. available.
  55. .PP
  56. After \fBwpa_supplicant\fR has configured the
  57. network device, higher level configuration of the device, such as DHCP, may
  58. proceed. There are a variety of ways to integrate wpa_supplicant
  59. into a machine's networking scripts, a few of which are described
  60. in sections below.
  61. .PP
  62. The following steps are used when associating with an AP
  63. using WPA:
  64. .TP 0.2i
  65. \(bu
  66. \fBwpa_supplicant\fR requests the kernel
  67. driver to scan neighboring BSSes (Basic Service Set)
  68. .TP 0.2i
  69. \(bu
  70. \fBwpa_supplicant\fR selects a BSS based on
  71. its configuration
  72. .TP 0.2i
  73. \(bu
  74. \fBwpa_supplicant\fR requests the kernel
  75. driver to associate with the chosen BSS
  76. .TP 0.2i
  77. \(bu
  78. If WPA-EAP: integrated IEEE 802.1X Supplicant
  79. completes EAP authentication with the
  80. authentication server (proxied by the Authenticator in the
  81. AP)
  82. .TP 0.2i
  83. \(bu
  84. If WPA-EAP: master key is received from the IEEE 802.1X
  85. Supplicant
  86. .TP 0.2i
  87. \(bu
  88. If WPA-PSK: \fBwpa_supplicant\fR uses PSK
  89. as the master session key
  90. .TP 0.2i
  91. \(bu
  92. \fBwpa_supplicant\fR completes WPA 4-Way
  93. Handshake and Group Key Handshake with the Authenticator
  94. (AP)
  95. .TP 0.2i
  96. \(bu
  97. \fBwpa_supplicant\fR configures encryption
  98. keys for unicast and broadcast
  99. .TP 0.2i
  100. \(bu
  101. normal data packets can be transmitted and received
  102. .SH "SUPPORTED FEATURES"
  103. .PP
  104. Supported WPA/IEEE 802.11i features:
  105. .TP 0.2i
  106. \(bu
  107. WPA-PSK ("WPA-Personal")
  108. .TP 0.2i
  109. \(bu
  110. WPA with EAP (e.g., with RADIUS authentication server)
  111. ("WPA-Enterprise") Following authentication methods are
  112. supported with an integrate IEEE 802.1X Supplicant:
  113. .RS
  114. .TP 0.2i
  115. \(bu
  116. EAP-TLS
  117. .RE
  118. .RS
  119. .TP 0.2i
  120. \(bu
  121. EAP-PEAP/MSCHAPv2 (both PEAPv0 and PEAPv1)
  122. .TP 0.2i
  123. \(bu
  124. EAP-PEAP/TLS (both PEAPv0 and PEAPv1)
  125. .TP 0.2i
  126. \(bu
  127. EAP-PEAP/GTC (both PEAPv0 and PEAPv1)
  128. .TP 0.2i
  129. \(bu
  130. EAP-PEAP/OTP (both PEAPv0 and PEAPv1)
  131. .TP 0.2i
  132. \(bu
  133. EAP-PEAP/MD5-Challenge (both PEAPv0 and PEAPv1)
  134. .TP 0.2i
  135. \(bu
  136. EAP-TTLS/EAP-MD5-Challenge
  137. .TP 0.2i
  138. \(bu
  139. EAP-TTLS/EAP-GTC
  140. .TP 0.2i
  141. \(bu
  142. EAP-TTLS/EAP-OTP
  143. .TP 0.2i
  144. \(bu
  145. EAP-TTLS/EAP-MSCHAPv2
  146. .TP 0.2i
  147. \(bu
  148. EAP-TTLS/EAP-TLS
  149. .TP 0.2i
  150. \(bu
  151. EAP-TTLS/MSCHAPv2
  152. .TP 0.2i
  153. \(bu
  154. EAP-TTLS/MSCHAP
  155. .TP 0.2i
  156. \(bu
  157. EAP-TTLS/PAP
  158. .TP 0.2i
  159. \(bu
  160. EAP-TTLS/CHAP
  161. .TP 0.2i
  162. \(bu
  163. EAP-SIM
  164. .TP 0.2i
  165. \(bu
  166. EAP-AKA
  167. .TP 0.2i
  168. \(bu
  169. EAP-PSK
  170. .TP 0.2i
  171. \(bu
  172. EAP-PAX
  173. .TP 0.2i
  174. \(bu
  175. LEAP (note: requires special support from
  176. the driver for IEEE 802.11 authentication)
  177. .TP 0.2i
  178. \(bu
  179. (following methods are supported, but since
  180. they do not generate keying material, they cannot be used
  181. with WPA or IEEE 802.1X WEP keying)
  182. .TP 0.2i
  183. \(bu
  184. EAP-MD5-Challenge
  185. .TP 0.2i
  186. \(bu
  187. EAP-MSCHAPv2
  188. .TP 0.2i
  189. \(bu
  190. EAP-GTC
  191. .TP 0.2i
  192. \(bu
  193. EAP-OTP
  194. .RE
  195. .TP 0.2i
  196. \(bu
  197. key management for CCMP, TKIP, WEP104, WEP40
  198. .TP 0.2i
  199. \(bu
  200. RSN/WPA2 (IEEE 802.11i)
  201. .RS
  202. .TP 0.2i
  203. \(bu
  204. pre-authentication
  205. .TP 0.2i
  206. \(bu
  207. PMKSA caching
  208. .RE
  209. .SH "AVAILABLE DRIVERS"
  210. .PP
  211. A summary of available driver backends is below. Support for each
  212. of the driver backends is chosen at wpa_supplicant compile time. For a
  213. list of supported driver backends that may be used with the -D option on
  214. your system, refer to the help output of wpa_supplicant
  215. (\fBwpa_supplicant -h\fR).
  216. .TP
  217. \fBnl80211\fR
  218. Uses the modern Linux nl80211/cfg80211 netlink-based
  219. interface (most new drivers).
  220. .TP
  221. \fBwext\fR
  222. Uses the legacy Linux wireless extensions ioctl-based
  223. interface (older hardware/drivers).
  224. .TP
  225. \fBwired\fR
  226. wpa_supplicant wired Ethernet driver
  227. .TP
  228. \fBmacsec_linux\fR
  229. MACsec Ethernet driver for Linux
  230. .TP
  231. \fBroboswitch\fR
  232. wpa_supplicant Broadcom switch driver
  233. .TP
  234. \fBnone\fR
  235. no driver (RADIUS server/WPS ER only)
  236. .TP
  237. \fBbsd\fR
  238. BSD 802.11 support (Atheros, etc.).
  239. .TP
  240. \fBndis\fR
  241. Windows NDIS driver.
  242. .SH "COMMAND LINE OPTIONS"
  243. .PP
  244. Most command line options have global scope. Some are given per
  245. interface, and are only valid if at least one \fB-i\fR option
  246. is specified, otherwise they're ignored. Option groups for different
  247. interfaces must be separated by \fB-N\fR option.
  248. .TP
  249. \fB-b br_ifname\fR
  250. Optional bridge interface name. (Per interface)
  251. .TP
  252. \fB-B\fR
  253. Run daemon in the background.
  254. .TP
  255. \fB-c filename\fR
  256. Path to configuration file. (Per interface)
  257. .TP
  258. \fB-C ctrl_interface\fR
  259. Path to ctrl_interface socket (Per interface. Only used if
  260. \fB-c\fR is not).
  261. .TP
  262. \fB-i ifname\fR
  263. Interface to listen on. Multiple instances of this option can
  264. be present, one per interface, separated by \fB-N\fR
  265. option (see below).
  266. .TP
  267. \fB-I filename\fR
  268. Path to additional configuration file.
  269. .TP
  270. \fB-d\fR
  271. Increase debugging verbosity (\fB-dd\fR even
  272. more).
  273. .TP
  274. \fB-D driver\fR
  275. Driver to use (can be multiple drivers: nl80211,wext).
  276. (Per interface, see the available options below.)
  277. .TP
  278. \fB-e entropy file\fR
  279. File for \fBwpa_supplicant\fR to use to
  280. maintain its internal entropy store in over restarts.
  281. .TP
  282. \fB-f output file\fR
  283. Log output to specified file instead of stdout. (This
  284. is only available if \fBwpa_supplicant\fR was
  285. built with the CONFIG_DEBUG_FILE
  286. option.)
  287. .TP
  288. \fB-g global ctrl_interface\fR
  289. Path to global ctrl_interface socket. If specified, interface
  290. definitions may be omitted.
  291. .TP
  292. \fB-K\fR
  293. Include keys (passwords, etc.) in debug output.
  294. .TP
  295. \fB-h\fR
  296. Help. Show a usage message.
  297. .TP
  298. \fB-L\fR
  299. Show license (BSD).
  300. .TP
  301. \fB-o override driver\fR
  302. Override the driver parameter for new
  303. interfaces.
  304. .TP
  305. \fB-O override ctrl_interface\fR
  306. Override the ctrl_interface parameter for new
  307. interfaces.
  308. .TP
  309. \fB-p\fR
  310. Driver parameters. (Per interface)
  311. .TP
  312. \fB-P PID_file\fR
  313. Path to PID file.
  314. .TP
  315. \fB-q\fR
  316. Decrease debugging verbosity (\fB-qq\fR even
  317. less).
  318. .TP
  319. \fB-s\fR
  320. Log output to syslog instead of stdout. (This is only
  321. available if \fBwpa_supplicant\fR was built
  322. with the CONFIG_DEBUG_SYSLOG
  323. option.)
  324. .TP
  325. \fB-T\fR
  326. Log output to Linux tracing in addition to any other
  327. destinations. (This is only available
  328. if \fBwpa_supplicant\fR was built with
  329. the CONFIG_DEBUG_LINUX_TRACING
  330. option.)
  331. .TP
  332. \fB-t\fR
  333. Include timestamp in debug messages.
  334. .TP
  335. \fB-u\fR
  336. Enable DBus control interface. If enabled, interface
  337. definitions may be omitted. (This is only available
  338. if \fBwpa_supplicant\fR was built with
  339. the CONFIG_CTRL_IFACE_DBUS_NEW option.)
  340. .TP
  341. \fB-v\fR
  342. Show version.
  343. .TP
  344. \fB-W\fR
  345. Wait for a control interface monitor before starting.
  346. .TP
  347. \fB-N\fR
  348. Start describing new interface.
  349. .SH "EXAMPLES"
  350. .PP
  351. In most common cases, \fBwpa_supplicant\fR is
  352. started with:
  353. .sp
  354. .RS
  355. .nf
  356. wpa_supplicant -B -c/etc/wpa_supplicant.conf -iwlan0
  357. .fi
  358. .RE
  359. .PP
  360. This makes the process fork into the background.
  361. .PP
  362. The easiest way to debug problems, and to get a debug log for
  363. bug reports, is to start \fBwpa_supplicant\fR in the
  364. foreground with debugging enabled:
  365. .sp
  366. .RS
  367. .nf
  368. wpa_supplicant -c/etc/wpa_supplicant.conf -iwlan0 -d
  369. .fi
  370. .RE
  371. .PP
  372. If the specific driver wrapper is not known beforehand, it is
  373. possible to specify multiple comma separated driver wrappers on the command
  374. line. \fBwpa_supplicant\fR will use the first driver
  375. wrapper that is able to initialize the interface.
  376. .sp
  377. .RS
  378. .nf
  379. wpa_supplicant -Dnl80211,wext -c/etc/wpa_supplicant.conf -iwlan0
  380. .fi
  381. .RE
  382. .PP
  383. \fBwpa_supplicant\fR can control multiple
  384. interfaces (radios) either by running one process for each
  385. interface separately or by running just one process and list of
  386. options at command line. Each interface is separated with -N
  387. argument. As an example, following command would start
  388. wpa_supplicant for two interfaces:
  389. .sp
  390. .RS
  391. .nf
  392. wpa_supplicant \\
  393. -c wpa1.conf -i wlan0 -D nl80211 -N \\
  394. -c wpa2.conf -i ath0 -D wext
  395. .fi
  396. .RE
  397. .SH "OS REQUIREMENTS"
  398. .PP
  399. Current hardware/software requirements:
  400. .TP 0.2i
  401. \(bu
  402. Linux kernel 2.6.30 or higher with
  403. nl80211/cfg80211 support
  404. .TP 0.2i
  405. \(bu
  406. Linux kernel 2.4.x or higher with Linux Wireless
  407. Extensions v15 or newer
  408. .TP 0.2i
  409. \(bu
  410. FreeBSD 6-CURRENT
  411. .TP 0.2i
  412. \(bu
  413. Microsoft Windows with WinPcap (at least WinXP, may work
  414. with other versions)
  415. .SH "SUPPORTED DRIVERS"
  416. .TP
  417. \fBLinux nl80211/cfg80211\fR
  418. This is the preferred driver for Linux.
  419. .TP
  420. \fBLinux wireless extensions\fR
  421. In theory, any driver that supports Linux wireless
  422. extensions can be used with IEEE 802.1X (i.e., not WPA) when
  423. using ap_scan=0 option in configuration file.
  424. .TP
  425. \fBWired Ethernet drivers\fR
  426. Use ap_scan=0.
  427. .TP
  428. \fBBSD net80211 layer (e.g., Atheros driver)\fR
  429. At the moment, this is for FreeBSD 6-CURRENT branch.
  430. .TP
  431. \fBWindows NDIS\fR
  432. The current Windows port requires WinPcap
  433. (http://winpcap.polito.it/). See README-Windows.txt for more
  434. information.
  435. .PP
  436. wpa_supplicant was designed to be portable for different
  437. drivers and operating systems. Hopefully, support for more wlan
  438. cards and OSes will be added in the future. See developer.txt for
  439. more information about the design of wpa_supplicant and porting to
  440. other drivers. One main goal is to add full WPA/WPA2 support to
  441. Linux wireless extensions to allow new drivers to be supported
  442. without having to implement new driver-specific interface code in
  443. wpa_supplicant.
  444. .SH "ARCHITECTURE"
  445. .PP
  446. The
  447. \fBwpa_supplicant\fR system consists of the following
  448. components:
  449. .TP
  450. \fB\fIwpa_supplicant.conf\fB \fR
  451. the configuration file describing all networks that the
  452. user wants the computer to connect to.
  453. .TP
  454. \fBwpa_supplicant\fR
  455. the program that directly interacts with the
  456. network interface.
  457. .TP
  458. \fBwpa_cli\fR
  459. the
  460. client program that provides a high-level interface to the
  461. functionality of the daemon.
  462. .TP
  463. \fBwpa_passphrase\fR
  464. a utility needed to construct
  465. \fIwpa_supplicant.conf\fR files that include
  466. encrypted passwords.
  467. .SH "QUICK START"
  468. .PP
  469. First, make a configuration file, e.g.
  470. \fI/etc/wpa_supplicant.conf\fR, that describes the networks
  471. you are interested in. See \fBwpa_supplicant.conf\fR(5)
  472. for details.
  473. .PP
  474. Once the configuration is ready, you can test whether the
  475. configuration works by running \fBwpa_supplicant\fR
  476. with following command to start it on foreground with debugging
  477. enabled:
  478. .sp
  479. .RS
  480. .nf
  481. wpa_supplicant -iwlan0 -c/etc/wpa_supplicant.conf -d
  482. .fi
  483. .RE
  484. .PP
  485. Assuming everything goes fine, you can start using following
  486. command to start \fBwpa_supplicant\fR on background
  487. without debugging:
  488. .sp
  489. .RS
  490. .nf
  491. wpa_supplicant -iwlan0 -c/etc/wpa_supplicant.conf -B
  492. .fi
  493. .RE
  494. .PP
  495. Please note that if you included more than one driver
  496. interface in the build time configuration (.config), you may need
  497. to specify which interface to use by including -D<driver
  498. name> option on the command line.
  499. .SH "INTERFACE TO PCMCIA-CS/CARDMRG"
  500. .PP
  501. For example, the following small changes to pcmcia-cs scripts
  502. can be used to enable WPA support:
  503. .PP
  504. Add MODE="Managed" and WPA="y" to the network scheme in
  505. \fI/etc/pcmcia/wireless.opts\fR\&.
  506. .PP
  507. Add the following block to the end of \fBstart\fR
  508. action handler in \fI/etc/pcmcia/wireless\fR:
  509. .sp
  510. .RS
  511. .nf
  512. if [ "$WPA" = "y" -a -x /usr/local/bin/wpa_supplicant ]; then
  513. /usr/local/bin/wpa_supplicant -B -c/etc/wpa_supplicant.conf -i$DEVICE
  514. fi
  515. .fi
  516. .RE
  517. .PP
  518. Add the following block to the end of \fBstop\fR
  519. action handler (may need to be separated from other actions) in
  520. \fI/etc/pcmcia/wireless\fR:
  521. .sp
  522. .RS
  523. .nf
  524. if [ "$WPA" = "y" -a -x /usr/local/bin/wpa_supplicant ]; then
  525. killall wpa_supplicant
  526. fi
  527. .fi
  528. .RE
  529. .PP
  530. This will make \fBcardmgr\fR start
  531. \fBwpa_supplicant\fR when the card is plugged
  532. in.
  533. .SH "SEE ALSO"
  534. .PP
  535. \fBwpa_background\fR(8)
  536. \fBwpa_supplicant.conf\fR(5)
  537. \fBwpa_cli\fR(8)
  538. \fBwpa_passphrase\fR(8)
  539. .SH "LEGAL"
  540. .PP
  541. wpa_supplicant is copyright (c) 2003-2022,
  542. Jouni Malinen <j@w1.fi> and
  543. contributors.
  544. All Rights Reserved.
  545. .PP
  546. This program is licensed under the BSD license (the one with
  547. advertisement clause removed).