doc/testing_tools.doxygen

   1 /**
   2 \page testing_tools Testing and development tools
   3
   4 [ \ref eapol_test "eapol_test" |
   5 \ref preauth_test "preauth_test" |
   6 \ref driver_test "driver_test" |
   7 \ref unit_tests "Unit tests" |
   8 \ref wpa_trace "Tracing code" ]
   9
  10 %wpa_supplicant source tree includes number of testing and development
  11 tools that make it easier to test the programs without having to setup
  12 a full test setup with wireless cards. In addition, these tools can be
  13 used to implement automatic tests suites.
  14
  15 \section eapol_test eapol_test - EAP peer and RADIUS client testing
  16
  17 eapol_test is a program that links together the same EAP peer
  18 implementation that %wpa_supplicant is using and the RADIUS
  19 authentication client code from hostapd. In addition, it has minimal
  20 glue code to combine these two components in similar ways to IEEE
  21 802.1X/EAPOL Authenticator state machines. In other words, it
  22 integrates IEEE 802.1X Authenticator (normally, an access point) and
  23 IEEE 802.1X Supplicant (normally, a wireless client) together to
  24 generate a single program that can be used to test EAP methods without
  25 having to setup an access point and a wireless client.
  26
  27 The main uses for eapol_test are in interoperability testing of EAP
  28 methods against RADIUS servers and in development testing for new EAP
  29 methods. It can be easily used to automate EAP testing for
  30 interoperability and regression since the program can be run from
  31 shell scripts without require additional test components apart from a
  32 RADIUS server. For example, the automated EAP tests described in
  33 eap_testing.txt are implemented with eapol_test. Similarly, eapol_test
  34 could be used to implement an automated regression test suite for a
  35 RADIUS authentication server.
  36
  37 eapol_test uses the same build time configuration file, .config, as
  38 %wpa_supplicant. This file is used to select which EAP methods are
  39 included in eapol_test. This program is not built with the default
  40 Makefile target, so a separate make command needs to be used to
  41 compile the tool:
  42
  43 \verbatim
  44 make eapol_test
  45 \endverbatim
  46
  47 The resulting eapol_test binary has following command like options:
  48
  49 \verbatim
  50 usage:
  51 eapol_test [-nWS] -c<conf> [-a<AS IP>] [-p<AS port>] [-s<AS secret>] \
  52            [-r<count>] [-t<timeout>] [-C<Connect-Info>] \
  53            [-M<client MAC address>]
  54 eapol_test scard
  55 eapol_test sim <PIN> <num triplets> [debug]
  56
  57 options:
  58   -c<conf> = configuration file
  59   -a<AS IP> = IP address of the authentication server, default 127.0.0.1
  60   -p<AS port> = UDP port of the authentication server, default 1812
  61   -s<AS secret> = shared secret with the authentication server, default 'radius'
  62   -r<count> = number of re-authentications
  63   -W = wait for a control interface monitor before starting
  64   -S = save configuration after authentiation
  65   -n = no MPPE keys expected
  66   -t<timeout> = sets timeout in seconds (default: 30 s)
  67   -C<Connect-Info> = RADIUS Connect-Info (default: CONNECT 11Mbps 802.11b)
  68   -M<client MAC address> = Set own MAC address (Calling-Station-Id,
  69                            default: 02:00:00:00:00:01)
  70 \endverbatim
  71
  72
  73 As an example,
  74 \verbatim
  75 eapol_test -ctest.conf -a127.0.0.1 -p1812 -ssecret -r1
  76 \endverbatim
  77 tries to complete EAP authentication based on the network
  78 configuration from test.conf against the RADIUS server running on the
  79 local host. A re-authentication is triggered to test fast
  80 re-authentication. The configuration file uses the same format for
  81 network blocks as %wpa_supplicant.
  82
  83
  84 \section preauth_test preauth_test - WPA2 pre-authentication and EAP peer testing
  85
  86 preauth_test is similar to eapol_test in the sense that in combines
  87 EAP peer implementation with something else, in this case, with WPA2
  88 pre-authentication. This tool can be used to test pre-authentication
  89 based on the code that %wpa_supplicant is using. As such, it tests
  90 both the %wpa_supplicant implementation and the functionality of an
  91 access point.
  92
  93 preauth_test is built with:
  94
  95 \verbatim
  96 make preauth_test
  97 \endverbatim
  98
  99 and it uses following command line arguments:
 100
 101 \verbatim
 102 usage: preauth_test <conf> <target MAC address> <ifname>
 103 \endverbatim
 104
 105 For example,
 106 \verbatim
 107 preauth_test test.conf 02:11:22:33:44:55 eth0
 108 \endverbatim
 109 would use network configuration from test.conf to try to complete
 110 pre-authentication with AP using BSSID 02:11:22:33:44:55. The
 111 pre-authentication packets would be sent using the eth0 interface.
 112
 113
 114 \section driver_test driver_test - driver interface for testing wpa_supplicant
 115
 116 %wpa_supplicant was designed to support number of different ways to
 117 communicate with a network device driver. This design uses \ref
 118 driver_wrapper "driver interface API" and number of driver interface
 119 implementations. One of these is driver_test.c, i.e., a test driver
 120 interface that is actually not using any drivers. Instead, it provides
 121 a mechanism for running %wpa_supplicant without having to have a
 122 device driver or wireless LAN hardware for that matter.
 123
 124 driver_test can be used to talk directly with hostapd's driver_test
 125 component to create a test setup where one or more clients and access
 126 points can be tested within one test host and without having to have
 127 multiple wireless cards. This makes it easier to test the core code in
 128 %wpa_supplicant, and hostapd for that matter. Since driver_test uses
 129 the same driver API than any other driver interface implementation,
 130 the core code of %wpa_supplicant and hostapd can be tested with the
 131 same coverage as one would get when using real wireless cards. The
 132 only area that is not tested is the driver interface implementation
 133 (driver_*.c).
 134
 135 Having the possibility to use simulated network components makes it
 136 much easier to do development testing while adding new features and to
 137 reproduce reported bugs. As such, it is often easiest to just do most
 138 of the development and bug fixing without using real hardware. Once
 139 the driver_test setup has been used to implement a new feature or fix
 140 a bug, the end result can be verified with wireless LAN cards. In many
 141 cases, this may even be unnecessary, depending on what area the
 142 feature/bug is relating to. Of course, changes to driver interfaces
 143 will still require use of real hardware.
 144
 145 Since multiple components can be run within a single host, testing of
 146 complex network configuration, e.g., large number of clients
 147 association with an access point, becomes quite easy. All the tests
 148 can also be automated without having to resort to complex test setup
 149 using remote access to multiple computers.
 150
 151 driver_test can be included in the %wpa_supplicant build in the same
 152 way as any other driver interface, i.e., by adding the following line
 153 into .config:
 154
 155 \verbatim
 156 CONFIG_DRIVER_TEST=y
 157 \endverbatim
 158
 159 When running %wpa_supplicant, the test interface is selected by using
 160 \a -Dtest command line argument. The interface name (\a -i argument)
 161 can be selected arbitrarily, i.e., it does not need to match with any
 162 existing network interface. The interface name is used to generate a
 163 MAC address, so when using multiple clients, each should use a
 164 different interface, e.g., \a sta1, \a sta2, and so on.
 165
 166 %wpa_supplicant and hostapd are configured in the same way as they
 167 would be for normal use. Following example shows a simple test setup
 168 for WPA-PSK.
 169
 170 hostapd is configured with following psk-test.conf configuration file:
 171
 172 \verbatim
 173 driver=test
 174
 175 interface=ap1
 176 logger_stdout=-1
 177 logger_stdout_level=0
 178 debug=2
 179 dump_file=/tmp/hostapd.dump
 180
 181 test_socket=/tmp/Test/ap1
 182
 183 ssid=jkm-test-psk
 184
 185 wpa=1
 186 wpa_key_mgmt=WPA-PSK
 187 wpa_pairwise=TKIP
 188 wpa_passphrase=12345678
 189 \endverbatim
 190
 191 and started with following command:
 192
 193 \verbatim
 194 hostapd psk-test.conf
 195 \endverbatim
 196
 197 %wpa_supplicant uses following configuration file:
 198
 199 \verbatim
 200 driver_param=test_socket=/tmp/Test/ap1
 201
 202 network={
 203     ssid="jkm-test-psk"
 204     key_mgmt=WPA-PSK
 205     psk="12345678"
 206 }
 207 \endverbatim
 208
 209 %wpa_supplicant can then be started with following command:
 210
 211 \verbatim
 212 wpa_supplicant -Dtest -cpsk-test.conf -ista1 -ddK
 213 \endverbatim
 214
 215 If run without debug information, i.e., with
 216
 217 \verbatim
 218 wpa_supplicant -Dtest -cpsk-test.conf -ista1
 219 \endverbatim
 220
 221 %wpa_supplicant completes authentication and prints following events:
 222
 223 \verbatim
 224 Trying to associate with 02:b8:a6:62:08:5a (SSID='jkm-test-psk' freq=0 MHz)
 225 Associated with 02:b8:a6:62:08:5a
 226 WPA: Key negotiation completed with 02:b8:a6:62:08:5a [PTK=TKIP GTK=TKIP]
 227 CTRL-EVENT-CONNECTED - Connection to 02:b8:a6:62:08:5a completed (auth)
 228 \endverbatim
 229
 230 If test setup is using multiple clients, it is possible to run
 231 multiple %wpa_supplicant processes. Alternatively, the support for
 232 multiple interfaces can be used with just one process to save some
 233 resources on single-CPU systems. For example, following command runs
 234 two clients:
 235
 236 \verbatim
 237 ./wpa_supplicant -Dtest -cpsk-test.conf -ista1 \
 238         -N -Dtest -cpsk-test.conf -ista2
 239 \endverbatim
 240
 241 This shows following event log:
 242
 243 \verbatim
 244 Trying to associate with 02:b8:a6:62:08:5a (SSID='jkm-test-psk' freq=0 MHz)
 245 Associated with 02:b8:a6:62:08:5a
 246 WPA: Key negotiation completed with 02:b8:a6:62:08:5a [PTK=TKIP GTK=TKIP]
 247 CTRL-EVENT-CONNECTED - Connection to 02:b8:a6:62:08:5a completed (auth)
 248 Trying to associate with 02:b8:a6:62:08:5a (SSID='jkm-test-psk' freq=0 MHz)
 249 Associated with 02:b8:a6:62:08:5a
 250 WPA: Key negotiation completed with 02:b8:a6:62:08:5a [PTK=TKIP GTK=TKIP]
 251 CTRL-EVENT-CONNECTED - Connection to 02:b8:a6:62:08:5a completed (auth)
 252 \endverbatim
 253
 254 hostapd shows this with following events:
 255
 256 \verbatim
 257 ap1: STA 02:b5:64:63:30:63 IEEE 802.11: associated
 258 ap1: STA 02:b5:64:63:30:63 WPA: pairwise key handshake completed (WPA)
 259 ap1: STA 02:b5:64:63:30:63 WPA: group key handshake completed (WPA)
 260 ap1: STA 02:2a:c4:18:5b:f3 IEEE 802.11: associated
 261 ap1: STA 02:2a:c4:18:5b:f3 WPA: pairwise key handshake completed (WPA)
 262 ap1: STA 02:2a:c4:18:5b:f3 WPA: group key handshake completed (WPA)
 263 \endverbatim
 264
 265 By default, driver_param is simulating a driver that uses the WPA/RSN
 266 IE generated by %wpa_supplicant. Driver-generated IE and AssocInfo
 267 events can be tested by adding \a use_associnfo=1 to the \a driver_param
 268 line in the configuration file. For example:
 269
 270 \verbatim
 271 driver_param=test_socket=/tmp/Test/ap1 use_associnfo=1
 272 \endverbatim
 273
 274
 275 \section unit_tests Unit tests
 276
 277 Number of the components (.c files) used in %wpa_supplicant define
 278 their own unit tests for automated validation of the basic
 279 functionality. Most of the tests for cryptographic algorithms are
 280 using standard test vectors to validate functionality. These tests can
 281 be useful especially when verifying port to a new CPU target.
 282
 283 The test programs are collected in the tests subdirectory. All
 284 automated unit tests can be run with
 285
 286 \verbatim
 287 make run-tests
 288 \endverbatim
 289
 290 This make target builds and runs each test and terminates with zero
 291 exit code if all tests were completed successfully.
 292
 293
 294 \section wpa_trace Tracing code for developer debuggin
 295
 296 %wpa_supplicant and hostapd can be built with tracing code that will
 297 track and analyze memory allocations and other resource registrations
 298 and certain API uses. If incorrect use is detected, a backtrace of the
 299 call location (and/or allocation location) is shown. This can also be
 300 used to detect certain categories of memory leaks and report them
 301 automatically when the program is terminated. The report will also
 302 include information about forgotten eloop events.
 303
 304 The trace code can be enabled with CONFIG_WPA_TRACE=y build
 305 option. More verbose backtrace information can be generated if libbfd
 306 is available and the binaries are not stripped of symbol
 307 information. This is enabled with CONFIG_WPA_TRACE_BFD=y.
 308
 309 For example, a memory leak (forgotten os_free() call) would show up
 310 like this when the program is terminated:
 311
 312 \verbatim
 313 MEMLEAK[0x82d200]: len 128
 314 WPA_TRACE: memleak - START
 315 [0]: ./wpa_supplicant(os_malloc+0x59) [0x41a5e9]
 316      os_malloc() ../src/utils/os_unix.c:359
 317 [1]: ./wpa_supplicant(os_zalloc+0x16) [0x41a676]
 318      os_zalloc() ../src/utils/os_unix.c:418
 319 [2]: ./wpa_supplicant(wpa_supplicant_init+0x38) [0x48b508]
 320      wpa_supplicant_init() wpa_supplicant.c:2315
 321 [3]: ./wpa_supplicant(main+0x2f3) [0x491073]
 322      main() main.c:252
 323 WPA_TRACE: memleak - END
 324 MEMLEAK: total 128 bytes
 325 \endverbatim
 326
 327 Another type of error that can be detected is freeing of memory area
 328 that was registered for some use and is still be referenced:
 329
 330 \verbatim
 331 WPA_TRACE: Freeing referenced memory - START
 332 [2]: ./wpa_supplicant(os_free+0x5c) [0x41a53c]
 333      os_free() ../src/utils/os_unix.c:411
 334 [3]: ./wpa_supplicant(wpa_supplicant_remove_iface+0x30) [0x48b380]
 335      wpa_supplicant_remove_iface() wpa_supplicant.c:2259
 336 [4]: ./wpa_supplicant(wpa_supplicant_deinit+0x20) [0x48b3e0]
 337      wpa_supplicant_deinit() wpa_supplicant.c:2430
 338 [5]: ./wpa_supplicant(main+0x357) [0x4910d7]
 339      main() main.c:276
 340 WPA_TRACE: Freeing referenced memory - END
 341 WPA_TRACE: Reference registration - START
 342 [1]: ./wpa_supplicant [0x41c040]
 343      eloop_trace_sock_add_ref() ../src/utils/eloop.c:94
 344 [2]: ./wpa_supplicant(wpa_supplicant_ctrl_iface_deinit+0x17) [0x473247]
 345      wpa_supplicant_ctrl_iface_deinit() ctrl_iface_unix.c:436
 346 [3]: ./wpa_supplicant [0x48b21c]
 347      wpa_supplicant_cleanup() wpa_supplicant.c:378
 348      wpa_supplicant_deinit_iface() wpa_supplicant.c:2155
 349 [4]: ./wpa_supplicant(wpa_supplicant_remove_iface+0x30) [0x48b380]
 350      wpa_supplicant_remove_iface() wpa_supplicant.c:2259
 351 [5]: ./wpa_supplicant(wpa_supplicant_deinit+0x20) [0x48b3e0]
 352      wpa_supplicant_deinit() wpa_supplicant.c:2430
 353 [6]: ./wpa_supplicant(main+0x357) [0x4910d7]
 354      main() main.c:276
 355 WPA_TRACE: Reference registration - END
 356 Aborted
 357 \endverbatim
 358
 359 This type of error results in showing backtraces for both the location
 360 where the incorrect freeing happened and the location where the memory
 361 area was marked referenced.
 362
 363 */