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