From b623634262daf32c28567713f9f00b5d3b6dd2ba Mon Sep 17 00:00:00 2001
From: Jouni Malinen <j@w1.fi>
Date: Sun, 10 Feb 2019 17:59:38 +0200
Subject: [PATCH] tests: Document some of the test tools

This will hopefully make it easier for others to use these test tools.

Signed-off-by: Jouni Malinen <j@w1.fi>
---
 tests/README | 109 +++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 109 insertions(+)
 create mode 100644 tests/README

diff --git a/tests/README b/tests/README
new file mode 100644
index 000000000..68f6023d0
--- /dev/null
+++ b/tests/README
@@ -0,0 +1,109 @@
+hostap.git test tools
+---------------------
+
+The tests directory with its subdirectories contain number of tools used
+for testing wpa_supplicant and hostapd implementations.
+
+hwsim directory contains the test setup for full system testing of
+wpa_supplicant and hostapd with a simulated radio (mac80211_hwsim). See
+hwsim/READM and hwsim/vm/README for more details.
+
+
+Build testing
+-------------
+
+wpa_supplicant and hostapd support number of build option
+combinations. The test scripts in the build subdirectory can be used to
+verify that various combinations do not break the builds. More
+configuration examples can be added there
+(build-{hostapd,wpa_supplicant}-*.config) to get them included in test
+builds.
+
+# Example
+cd build
+./run-build-tests.h
+
+
+Fuzz testing
+------------
+
+Number of the test tools here can be used for fuzz testing with tools
+like American fuzzy lop (afl-fuzz) that are designed to modify an
+external file for program input. ap-mgmt-fuzzer, eapol-fuzzer,
+test-eapol, test-json, test-tls, and test-x509 are examples of such
+tools that expose hostap.git module functionality with input from a file
+specified on the command line.
+
+Here are some examples of how fuzzing can be performed:
+
+##### JSON parser
+make clean
+CC=afl-gcc make test-json
+mkdir json-examples
+cat > json-examples/1.json <<EOF
+{"a":[[]],"b":1,"c":"q","d":{"e":[{}]}}
+EOF
+afl-fuzz -i json-examples -o json-findings -- $PWD/test-json @@
+
+##### EAPOL-Key Supplicant
+make clean
+CC=afl-gcc make test-eapol TEST_FUZZ=y
+mkdir eapol-auth-examples
+./test-eapol auth write eapol-auth-examples/auth.msg
+afl-fuzz -i eapol-auth-examples -o eapol-auth-findings -- $PWD/test-eapol auth read @@
+
+##### EAPOL-Key Authenticator
+make clean
+CC=afl-gcc make test-eapol TEST_FUZZ=y
+mkdir eapol-supp-examples
+./test-eapol supp write eapol-supp-examples/supp.msg
+afl-fuzz -i eapol-supp-examples -o eapol-supp-findings -- $PWD/test-eapol supp read @@
+
+##### TLS client
+make clean
+CC=afl-gcc make test-tls TEST_FUZZ=y
+mkdir tls-server-examples
+./test-tls server write tls-server-examples/server.msg
+afl-fuzz -i tls-server-examples -o tls-server-findings -- $PWD/test-tls server read @@
+
+##### TLS server
+make clean
+CC=afl-gcc make test-tls TEST_FUZZ=y
+mkdir tls-client-examples
+./test-tls client write tls-client-examples/client.msg
+afl-fuzz -i tls-client-examples -o tls-client-findings -- $PWD/test-tls client read @@
+
+##### AP management frame processing
+cd ap-mgmt-fuzzer
+make clean
+CC=afl-gcc make
+mkdir multi-examples
+cp multi.dat multi-examples
+afl-fuzz -i multi-examples -o multi-findings -- $PWD/ap-mgmt-fuzzer -m @@
+
+##### EAPOL-Key Supplicant (separate)
+cd eapol-fuzzer
+make clean
+CC=afl-gcc make
+mkdir eapol-examples
+cp *.dat eapol-examples
+afl-fuzz -i eapol-examples -o eapol-findings -- $PWD/eapol-fuzzer @@
+
+##### P2P
+cd p2p-fuzzer
+make clean
+CC=afl-gcc make
+mkdir p2p-proberesp-examples
+cp proberesp*.dat p2p-proberesp-examples
+afl-fuzz -i p2p-proberesp-examples -o p2p-proberesp-findings -- $PWD/p2p-fuzzer proberesp @@
+mkdir p2p-action-examples
+cp go*.dat inv*.dat p2ps*.dat p2p-action-examples
+afl-fuzz -i p2p-action-examples -o p2p-action-findings -- $PWD/p2p-fuzzer action @@
+
+##### WNM
+cd wnm-fuzzer
+make clean
+CC=afl-gcc make
+mkdir wnm-examples
+cp *.dat wnm-examples
+afl-fuzz -i wnm-examples -o wnm-findings -- $PWD/wnm-fuzzer @@
-- 
2.39.2