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 Number of the test tools here can be used for fuzz testing with tools
  31 like American fuzzy lop (afl-fuzz) that are designed to modify an
  32 external file for program input. ap-mgmt-fuzzer, eapol-fuzzer,
  33 test-eapol, test-json, test-tls, and test-x509 are examples of such
  34 tools that expose hostap.git module functionality with input from a file
  35 specified on the command line.
  36
  37 Here are some examples of how fuzzing can be performed:
  38
  39 ##### JSON parser
  40 make clean
  41 CC=afl-gcc make test-json
  42 mkdir json-examples
  43 cat > json-examples/1.json <<EOF
  44 {"a":[[]],"b":1,"c":"q","d":{"e":[{}]}}
  45 EOF
  46 afl-fuzz -i json-examples -o json-findings -- $PWD/test-json @@
  47
  48 Alternatively, using libFuzzer from LLVM:
  49 make clean
  50 make test-json LIBFUZZER=y
  51 mkdir json-examples
  52 cat > json-examples/1.json <<EOF
  53 {"a":[[]],"b":1,"c":"q","d":{"e":[{}]}}
  54 EOF
  55 ./test-json json-examples
  56
  57 ##### EAPOL-Key Supplicant
  58 make clean
  59 CC=afl-gcc make test-eapol TEST_FUZZ=y
  60 mkdir eapol-auth-examples
  61 ./test-eapol auth write eapol-auth-examples/auth.msg
  62 afl-fuzz -i eapol-auth-examples -o eapol-auth-findings -- $PWD/test-eapol auth read @@
  63
  64 ##### EAPOL-Key Authenticator
  65 make clean
  66 CC=afl-gcc make test-eapol TEST_FUZZ=y
  67 mkdir eapol-supp-examples
  68 ./test-eapol supp write eapol-supp-examples/supp.msg
  69 afl-fuzz -i eapol-supp-examples -o eapol-supp-findings -- $PWD/test-eapol supp read @@
  70
  71 ##### TLS client
  72 make clean
  73 CC=afl-gcc make test-tls TEST_FUZZ=y
  74 mkdir tls-server-examples
  75 ./test-tls server write tls-server-examples/server.msg
  76 afl-fuzz -i tls-server-examples -o tls-server-findings -- $PWD/test-tls server read @@
  77
  78 ##### TLS server
  79 make clean
  80 CC=afl-gcc make test-tls TEST_FUZZ=y
  81 mkdir tls-client-examples
  82 ./test-tls client write tls-client-examples/client.msg
  83 afl-fuzz -i tls-client-examples -o tls-client-findings -- $PWD/test-tls client read @@
  84
  85 ##### AP management frame processing
  86 cd ap-mgmt-fuzzer
  87 make clean
  88 CC=afl-gcc make
  89 mkdir multi-examples
  90 cp multi.dat multi-examples
  91 afl-fuzz -i multi-examples -o multi-findings -- $PWD/ap-mgmt-fuzzer -m @@
  92
  93 ##### EAPOL-Key Supplicant (separate)
  94 cd eapol-fuzzer
  95 make clean
  96 CC=afl-gcc make
  97 mkdir eapol-examples
  98 cp *.dat eapol-examples
  99 afl-fuzz -i eapol-examples -o eapol-findings -- $PWD/eapol-fuzzer @@
 100
 101 ##### P2P
 102 cd p2p-fuzzer
 103 make clean
 104 CC=afl-gcc make
 105 mkdir p2p-proberesp-examples
 106 cp proberesp*.dat p2p-proberesp-examples
 107 afl-fuzz -i p2p-proberesp-examples -o p2p-proberesp-findings -- $PWD/p2p-fuzzer proberesp @@
 108 mkdir p2p-action-examples
 109 cp go*.dat inv*.dat p2ps*.dat p2p-action-examples
 110 afl-fuzz -i p2p-action-examples -o p2p-action-findings -- $PWD/p2p-fuzzer action @@
 111
 112 ##### WNM
 113 cd wnm-fuzzer
 114 make clean
 115 CC=afl-gcc make
 116 mkdir wnm-examples
 117 cp *.dat wnm-examples
 118 afl-fuzz -i wnm-examples -o wnm-findings -- $PWD/wnm-fuzzer @@