contrib/wpa/wpa_supplicant/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
   9 %wpa_supplicant source tree includes number of testing and development
  10 tools that make it easier to test the programs without having to setup
  11 a full test setup with wireless cards. In addition, these tools can be
  12 used to implement automatic tests suites.
  13
  14 \section eapol_test eapol_test - EAP peer and RADIUS client testing
  15
  16 eapol_test is a program that links together the same EAP peer
  17 implementation that %wpa_supplicant is using and the RADIUS
  18 authentication client code from hostapd. In addition, it has minimal
  19 glue code to combine these two components in similar ways to IEEE
  20 802.1X/EAPOL Authenticator state machines. In other words, it
  21 integrates IEEE 802.1X Authenticator (normally, an access point) and
  22 IEEE 802.1X Supplicant (normally, a wireless client) together to
  23 generate a single program that can be used to test EAP methods without
  24 having to setup an access point and a wireless client.
  25
  26 The main uses for eapol_test are in interoperability testing of EAP
  27 methods against RADIUS servers and in development testing for new EAP
  28 methods. It can be easily used to automate EAP testing for
  29 interoperability and regression since the program can be run from
  30 shell scripts without require additional test components apart from a
  31 RADIUS server. For example, the automated EAP tests described in
  32 eap_testing.txt are implemented with eapol_test. Similarly, eapol_test
  33 could be used to implement an automated regression test suite for a
  34 RADIUS authentication server.
  35
  36 eapol_test uses the same build time configuration file, .config, as
  37 %wpa_supplicant. This file is used to select which EAP methods are
  38 included in eapol_test. This program is not built with the default
  39 Makefile target, so a separate make command needs to be used to
  40 compile the tool:
  41
  42 \verbatim
  43 make eapol_test
  44 \endverbatim
  45
  46 The resulting eapol_test binary has following command like options:
  47
  48 \verbatim
  49 usage:
  50 eapol_test [-nWS] -c<conf> [-a<AS IP>] [-p<AS port>] [-s<AS secret>] \
  51            [-r<count>] [-t<timeout>] [-C<Connect-Info>] \
  52            [-M<client MAC address>]
  53 eapol_test scard
  54 eapol_test sim <PIN> <num triplets> [debug]
  55
  56 options:
  57   -c<conf> = configuration file
  58   -a<AS IP> = IP address of the authentication server, default 127.0.0.1
  59   -p<AS port> = UDP port of the authentication server, default 1812
  60   -s<AS secret> = shared secret with the authentication server, default 'radius'
  61   -r<count> = number of re-authentications
  62   -W = wait for a control interface monitor before starting
  63   -S = save configuration after authentiation
  64   -n = no MPPE keys expected
  65   -t<timeout> = sets timeout in seconds (default: 30 s)
  66   -C<Connect-Info> = RADIUS Connect-Info (default: CONNECT 11Mbps 802.11b)
  67   -M<client MAC address> = Set own MAC address (Calling-Station-Id,
  68                            default: 02:00:00:00:00:01)
  69 \endverbatim
  70
  71
  72 As an example,
  73 \verbatim
  74 eapol_test -ctest.conf -a127.0.0.1 -p1812 -ssecret -r1
  75 \endverbatim
  76 tries to complete EAP authentication based on the network
  77 configuration from test.conf against the RADIUS server running on the
  78 local host. A re-authentication is triggered to test fast
  79 re-authentication. The configuration file uses the same format for
  80 network blocks as %wpa_supplicant.
  81
  82
  83 \section preauth_test preauth_test - WPA2 pre-authentication and EAP peer testing
  84
  85 preauth_test is similar to eapol_test in the sense that in combines
  86 EAP peer implementation with something else, in this case, with WPA2
  87 pre-authentication. This tool can be used to test pre-authentication
  88 based on the code that %wpa_supplicant is using. As such, it tests
  89 both the %wpa_supplicant implementation and the functionality of an
  90 access point.
  91
  92 preauth_test is built with:
  93
  94 \verbatim
  95 make preauth_test
  96 \endverbatim
  97
  98 and it uses following command line arguments:
  99
 100 \verbatim
 101 usage: preauth_test <conf> <target MAC address> <ifname>
 102 \endverbatim
 103
 104 For example,
 105 \verbatim
 106 preauth_test test.conf 02:11:22:33:44:55 eth0
 107 \endverbatim
 108 would use network configuration from test.conf to try to complete
 109 pre-authentication with AP using BSSID 02:11:22:33:44:55. The
 110 pre-authentication packets would be sent using the eth0 interface.
 111
 112
 113 \section driver_test driver_test - driver interface for testing wpa_supplicant
 114
 115 %wpa_supplicant was designed to support number of different ways to
 116 communicate with a network device driver. This design uses \ref
 117 driver_wrapper "driver interface API" and number of driver interface
 118 implementations. One of these is driver_test.c, i.e., a test driver
 119 interface that is actually not using any drivers. Instead, it provides
 120 a mechanism for running %wpa_supplicant without having to have a
 121 device driver or wireless LAN hardware for that matter.
 122
 123 driver_test can be used to talk directly with hostapd's driver_test
 124 component to create a test setup where one or more clients and access
 125 points can be tested within one test host and without having to have
 126 multiple wireless cards. This makes it easier to test the core code in
 127 %wpa_supplicant, and hostapd for that matter. Since driver_test uses
 128 the same driver API than any other driver interface implementation,
 129 the core code of %wpa_supplicant and hostapd can be tested with the
 130 same coverage as one would get when using real wireless cards. The
 131 only area that is not tested is the driver interface implementation
 132 (driver_*.c).
 133
 134 Having the possibility to use simulated network components makes it
 135 much easier to do development testing while adding new features and to
 136 reproduce reported bugs. As such, it is often easiest to just do most
 137 of the development and bug fixing without using real hardware. Once
 138 the driver_test setup has been used to implement a new feature or fix
 139 a bug, the end result can be verified with wireless LAN cards. In many
 140 cases, this may even be unnecessary, depending on what area the
 141 feature/bug is relating to. Of course, changes to driver interfaces
 142 will still require use of real hardware.
 143
 144 Since multiple components can be run within a single host, testing of
 145 complex network configuration, e.g., large number of clients
 146 association with an access point, becomes quite easy. All the tests
 147 can also be automated without having to resort to complex test setup
 148 using remote access to multiple computers.
 149
 150 driver_test can be included in the %wpa_supplicant build in the same
 151 way as any other driver interface, i.e., by adding the following line
 152 into .config:
 153
 154 \verbatim
 155 CONFIG_DRIVER_TEST=y
 156 \endverbatim
 157
 158 When running %wpa_supplicant, the test interface is selected by using
 159 \a -Dtest command line argument. The interface name (\a -i argument)
 160 can be selected arbitrarily, i.e., it does not need to match with any
 161 existing network interface. The interface name is used to generate a
 162 MAC address, so when using multiple clients, each should use a
 163 different interface, e.g., \a sta1, \a sta2, and so on.
 164
 165 %wpa_supplicant and hostapd are configured in the same way as they
 166 would be for normal use. Following example shows a simple test setup
 167 for WPA-PSK.
 168
 169 hostapd is configured with following psk-test.conf configuration file:
 170
 171 \verbatim
 172 driver=test
 173
 174 interface=ap1
 175 logger_stdout=-1
 176 logger_stdout_level=0
 177 debug=2
 178 dump_file=/tmp/hostapd.dump
 179
 180 test_socket=/tmp/Test/ap1
 181
 182 ssid=jkm-test-psk
 183
 184 wpa=1
 185 wpa_key_mgmt=WPA-PSK
 186 wpa_pairwise=TKIP
 187 wpa_passphrase=12345678
 188 \endverbatim
 189
 190 and started with following command:
 191
 192 \verbatim
 193 hostapd psk-test.conf
 194 \endverbatim
 195
 196 %wpa_supplicant uses following configuration file:
 197
 198 \verbatim
 199 driver_param=test_socket=/tmp/Test/ap1
 200
 201 network={
 202     ssid="jkm-test-psk"
 203     key_mgmt=WPA-PSK
 204     psk="12345678"
 205 }
 206 \endverbatim
 207
 208 %wpa_supplicant can then be started with following command:
 209
 210 \verbatim
 211 wpa_supplicant -Dtest -cpsk-test.conf -ista1 -ddK
 212 \endverbatim
 213
 214 If run without debug information, i.e., with
 215
 216 \verbatim
 217 wpa_supplicant -Dtest -cpsk-test.conf -ista1
 218 \endverbatim
 219
 220 %wpa_supplicant completes authentication and prints following events:
 221
 222 \verbatim
 223 Trying to associate with 02:b8:a6:62:08:5a (SSID='jkm-test-psk' freq=0 MHz)
 224 Associated with 02:b8:a6:62:08:5a
 225 WPA: Key negotiation completed with 02:b8:a6:62:08:5a [PTK=TKIP GTK=TKIP]
 226 CTRL-EVENT-CONNECTED - Connection to 02:b8:a6:62:08:5a completed (auth)
 227 \endverbatim
 228
 229 If test setup is using multiple clients, it is possible to run
 230 multiple %wpa_supplicant processes. Alternatively, the support for
 231 multiple interfaces can be used with just one process to save some
 232 resources on single-CPU systems. For example, following command runs
 233 two clients:
 234
 235 \verbatim
 236 ./wpa_supplicant -Dtest -cpsk-test.conf -ista1 \
 237         -N -Dtest -cpsk-test.conf -ista2
 238 \endverbatim
 239
 240 This shows following event log:
 241
 242 \verbatim
 243 Trying to associate with 02:b8:a6:62:08:5a (SSID='jkm-test-psk' freq=0 MHz)
 244 Associated with 02:b8:a6:62:08:5a
 245 WPA: Key negotiation completed with 02:b8:a6:62:08:5a [PTK=TKIP GTK=TKIP]
 246 CTRL-EVENT-CONNECTED - Connection to 02:b8:a6:62:08:5a completed (auth)
 247 Trying to associate with 02:b8:a6:62:08:5a (SSID='jkm-test-psk' freq=0 MHz)
 248 Associated with 02:b8:a6:62:08:5a
 249 WPA: Key negotiation completed with 02:b8:a6:62:08:5a [PTK=TKIP GTK=TKIP]
 250 CTRL-EVENT-CONNECTED - Connection to 02:b8:a6:62:08:5a completed (auth)
 251 \endverbatim
 252
 253 hostapd shows this with following events:
 254
 255 \verbatim
 256 ap1: STA 02:b5:64:63:30:63 IEEE 802.11: associated
 257 ap1: STA 02:b5:64:63:30:63 WPA: pairwise key handshake completed (WPA)
 258 ap1: STA 02:b5:64:63:30:63 WPA: group key handshake completed (WPA)
 259 ap1: STA 02:2a:c4:18:5b:f3 IEEE 802.11: associated
 260 ap1: STA 02:2a:c4:18:5b:f3 WPA: pairwise key handshake completed (WPA)
 261 ap1: STA 02:2a:c4:18:5b:f3 WPA: group key handshake completed (WPA)
 262 \endverbatim
 263
 264 By default, driver_param is simulating a driver that uses the WPA/RSN
 265 IE generated by %wpa_supplicant. Driver-generated IE and AssocInfo
 266 events can be tested by adding \a use_associnfo=1 to the \a driver_param
 267 line in the configuration file. For example:
 268
 269 \verbatim
 270 driver_param=test_socket=/tmp/Test/ap1 use_associnfo=1
 271 \endverbatim
 272
 273
 274 \section unit_tests Unit tests
 275
 276 Number of the components (.c files) used in %wpa_supplicant define
 277 their own unit tests for automated validation of the basic
 278 functionality. Most of the tests for cryptographic algorithms are
 279 using standard test vectors to validate functionality. These tests can
 280 be useful especially when verifying port to a new CPU target.
 281
 282 In most cases, these tests are implemented in the end of the same file
 283 with functions that are normally commented out, but ca be included by
 284 defining a pre-processor variable when building the file separately.
 285 The details of the needed build options are included in the Makefile
 286 (test-* targets). All automated unit tests can be run with
 287
 288 \verbatim
 289 make tests
 290 \endverbatim
 291
 292 This make target builds and runs each test and terminates with zero
 293 exit code if all tests were completed successfully.
 294
 295 */