TrustedFirmware Git Browser
Code Review Sign In
review.trustedfirmware.org / TF-M / tf-m-tools / 3de5ab1ecd5f42a8c939de5d6521f997efd0f86a / . / tf_fuzz / docs / tf_fuzz_dir.rst
blob: 6ad0a382f0643952c442ccfb09f62152d6221b74 [file] [log] [blame]
Karl Zhang3de5ab12021-05-31 11:45:48 +0800[diff] [blame^]1#######################################
2TF-Fuzz (Trusted-Firmware Fuzzer) guide
3#######################################
4
5************
6Introduction
7************
8
9TF-Fuzz is a TF-M fuzzing tool, at the PSA-call level. At the time of writing
10this at least, presentations available at:
11
12- https://www.trustedfirmware.org/docs/TF-M_Fuzzing_Tool_TFOrg.pdf
13- https://zoom.us/rec/share/1dxZcZit111IadadyFqFU7IoP5X5aaa8gXUdr_UInxmMbyLzEqEmXQdx79-IWQ9p
14
15(These presentation materials may not all be viewable by all parties.)
16
17To build TF-Fuzz, simply type ``make`` in this directory. The executable,
18called ``tfz``, is placed in this directory.
19
20To run ``tfz``, two environment variables must first be assigned. In bash
21syntax:
22
23.. code-block:: bash
24
25 export TF_FUZZ_LIB_DIR=<path to this TF-M installation>/tools/tf_fuzz/lib
26 export TF_FUZZ_BPLATE=tfm_boilerplate.txt
27
28Examples of usage can be found in the ``demo`` directory.
29
30**********************************
31``.../tf_fuzz`` directory contents
32**********************************
33.. code-block:: bash
34
35 assets calls demo parser tests regression
36 backupStuff class_forwards.hpp lib document tf_fuzz.cpp utility
37 boilerplate commands Makefile template tf_fuzz.hpp visualStudio
38
39*************
40Code Overview
41*************
42To help understand the code, below is a C++-class hierarchy used in this code
43base. They are explained further in the documents in their respective
44directories, so the file names where the classes are defined is listed below (this,
45very roughly in order of functional interactions, of chronological usage during
46execution, and of most-to-least importance):
47
48.. code-block:: bash
49
50 template_line ./template/template_line.hpp
51 sst_template_line ./template/template_line.hpp
52 read_sst_template_line ./template/sst_template_line.hpp
53 remove_sst_template_line ./template/sst_template_line.hpp
54 set_sst_template_line ./template/sst_template_line.hpp
55 policy_template_line ./template/template_line.hpp
56 read_policy_template_line ./template/crypto_template_line.hpp
57 set_policy_template_line ./template/crypto_template_line.hpp
58 key_template_line ./template/template_line.hpp
59 read_key_template_line ./template/crypto_template_line.hpp
60 remove_key_template_line ./template/crypto_template_line.hpp
61 set_key_template_line ./template/crypto_template_line.hpp
62 security_template_line ./template/template_line.hpp
63 security_hash_template_line ./template/secure_template_line.hpp
64
65 psa_call ./calls/psa_call.hpp
66 crypto_call ./calls/psa_call.hpp
67 policy_call ./calls/crypto_call.hpp
68 init_policy_call ./calls/crypto_call.hpp
69 reset_policy_call ./calls/crypto_call.hpp
70 add_policy_usage_call ./calls/crypto_call.hpp
71 set_policy_lifetime_call ./calls/crypto_call.hpp
72 set_policy_type_call ./calls/crypto_call.hpp
73 set_policy_algorithm_call ./calls/crypto_call.hpp
74 set_policy_usage_call ./calls/crypto_call.hpp
75 get_policy_lifetime_call ./calls/crypto_call.hpp
76 get_policy_type_call ./calls/crypto_call.hpp
77 get_policy_algorithm_call ./calls/crypto_call.hpp
78 get_policy_usage_call ./calls/crypto_call.hpp
79 get_policy_size_call ./calls/crypto_call.hpp
80 get_policy_call ./calls/crypto_call.hpp
81 key_call ./calls/crypto_call.hpp
82 generate_key_call ./calls/crypto_call.hpp
83 create_key_call ./calls/crypto_call.hpp
84 copy_key_call ./calls/crypto_call.hpp
85 read_key_data_call ./calls/crypto_call.hpp
86 remove_key_call ./calls/crypto_call.hpp
87 sst_call ./calls/psa_call.hpp
88 sst_remove_call ./calls/sst_call.hpp
89 sst_get_call ./calls/sst_call.hpp
90 sst_set_call ./calls/sst_call.hpp
91 security_call ./calls/psa_call.hpp
92 hash_call ./calls/security_call.hpp
93
94 boilerplate ./boilerplate/boilerplate.hpp
95
96 psa_asset ./assets/psa_asset.hpp
97 crypto_asset ./assets/crypto_asset.hpp
98 policy_asset ./assets/crypto_asset.hpp
99 key_asset ./assets/crypto_asset.hpp
100 sst_asset ./assets/sst_asset.hpp
101
102 tf_fuzz_info ./tf_fuzz.hpp
103
104 variables ./utility/variables.hpp
105 crc32 ./utility/compute.hpp
106
107 gibberish ./utility/gibberish.hpp
108
109 expect_info ./utility/data_blocks.hpp
110 set_data_info ./utility/data_blocks.hpp
111 asset_name_id_info ./utility/data_blocks.hpp
112
113TF-Fuzz now has better-organized management of variables in the generated code.
114In particular, it maintains a list of variables named in the test template, and
115implicit in the code, notably variables assets are ``read`` into. It also now has
116completely separate execution phases to parse the test template, simulate the
117sequence of PSA calls generated, and write out the expected results. That
118simulation is only in enough detail to predict expected results. Since TF-Fuzz
119currectly mostly addresses only SST calls, that simulation is very simple in
120nature -- just tracking data movement.
121
122--------------
123
124*Copyright (c) 2020, Arm Limited. All rights reserved.*