tests/README

   1 hostap.git test tools
   2 ---------------------
   3
   4 The tests directory with its subdirectories contain number of tools used
   5 for testing wpa_supplicant and hostapd implementations.
   6
   7 hwsim directory contains the test setup for full system testing of
   8 wpa_supplicant and hostapd with a simulated radio (mac80211_hwsim). See
   9 hwsim/READM and hwsim/vm/README for more details.
  10
  11
  12 Build testing
  13 -------------
  14
  15 wpa_supplicant and hostapd support number of build option
  16 combinations. The test scripts in the build subdirectory can be used to
  17 verify that various combinations do not break the builds. More
  18 configuration examples can be added there
  19 (build-{hostapd,wpa_supplicant}-*.config) to get them included in test
  20 builds.
  21
  22 # Example
  23 cd build
  24 ./run-build-tests.h
  25
  26
  27 Fuzz testing
  28 ------------
  29
  30 Newer fuzz testing tools are under the fuzzing directory. See
  31 fuzzing/README for more details on them. The following text describes
  32 the older fuzz testing tools that are subject to removal once the same
  33 newer tools have the same coverage available.
  34
  35 Number of the test tools here can be used for fuzz testing with tools
  36 like American fuzzy lop (afl-fuzz) that are designed to modify an
  37 external file for program input. ap-mgmt-fuzzer, eapol-fuzzer,
  38 test-eapol, test-json, test-tls, and test-x509 are examples of such
  39 tools that expose hostap.git module functionality with input from a file
  40 specified on the command line.
  41
  42 Here are some examples of how fuzzing can be performed:
  43
  44 ##### JSON parser
  45 make clean
  46 CC=afl-gcc make test-json
  47 mkdir json-examples
  48 cat > json-examples/1.json <<EOF
  49 {"a":[[]],"b":1,"c":"q","d":{"e":[{}]}}
  50 EOF
  51 afl-fuzz -i json-examples -o json-findings -- $PWD/test-json @@
  52
  53 Alternatively, using libFuzzer from LLVM:
  54 make clean
  55 make test-json LIBFUZZER=y
  56 mkdir json-examples
  57 cat > json-examples/1.json <<EOF
  58 {"a":[[]],"b":1,"c":"q","d":{"e":[{}]}}
  59 EOF
  60 ./test-json json-examples
  61
  62 ##### EAPOL-Key Supplicant
  63 make clean
  64 CC=afl-gcc make test-eapol TEST_FUZZ=y
  65 mkdir eapol-auth-examples
  66 ./test-eapol auth write eapol-auth-examples/auth.msg
  67 afl-fuzz -i eapol-auth-examples -o eapol-auth-findings -- $PWD/test-eapol auth read @@
  68
  69 ##### EAPOL-Key Authenticator
  70 make clean
  71 CC=afl-gcc make test-eapol TEST_FUZZ=y
  72 mkdir eapol-supp-examples
  73 ./test-eapol supp write eapol-supp-examples/supp.msg
  74 afl-fuzz -i eapol-supp-examples -o eapol-supp-findings -- $PWD/test-eapol supp read @@
  75
  76 ##### TLS client
  77 make clean
  78 CC=afl-gcc make test-tls TEST_FUZZ=y
  79 mkdir tls-server-examples
  80 ./test-tls server write tls-server-examples/server.msg
  81 afl-fuzz -i tls-server-examples -o tls-server-findings -- $PWD/test-tls server read @@
  82
  83 ##### TLS server
  84 make clean
  85 CC=afl-gcc make test-tls TEST_FUZZ=y
  86 mkdir tls-client-examples
  87 ./test-tls client write tls-client-examples/client.msg
  88 afl-fuzz -i tls-client-examples -o tls-client-findings -- $PWD/test-tls client read @@
  89
  90 ##### AP management frame processing
  91 cd ap-mgmt-fuzzer
  92 make clean
  93 CC=afl-gcc make
  94 mkdir multi-examples
  95 cp multi.dat multi-examples
  96 afl-fuzz -i multi-examples -o multi-findings -- $PWD/ap-mgmt-fuzzer -m @@
  97
  98 ##### EAPOL-Key Supplicant (separate)
  99 cd eapol-fuzzer
 100 make clean
 101 CC=afl-gcc make
 102 mkdir eapol-examples
 103 cp *.dat eapol-examples
 104 afl-fuzz -i eapol-examples -o eapol-findings -- $PWD/eapol-fuzzer @@
 105
 106 ##### P2P
 107 cd p2p-fuzzer
 108 make clean
 109 CC=afl-gcc make
 110 mkdir p2p-proberesp-examples
 111 cp proberesp*.dat p2p-proberesp-examples
 112 afl-fuzz -i p2p-proberesp-examples -o p2p-proberesp-findings -- $PWD/p2p-fuzzer proberesp @@
 113 mkdir p2p-action-examples
 114 cp go*.dat inv*.dat p2ps*.dat p2p-action-examples
 115 afl-fuzz -i p2p-action-examples -o p2p-action-findings -- $PWD/p2p-fuzzer action @@
 116
 117 ##### WNM
 118 cd wnm-fuzzer
 119 make clean
 120 CC=afl-gcc make
 121 mkdir wnm-examples
 122 cp *.dat wnm-examples
 123 afl-fuzz -i wnm-examples -o wnm-findings -- $PWD/wnm-fuzzer @@