DataFlowSanitizer.rst source code [clang_source_code/docs/DataFlowSanitizer.rst]

1	=================
2	DataFlowSanitizer
3	=================
4
5	.. toctree::
6	:hidden:
7
8	DataFlowSanitizerDesign
9
10	.. contents::
11	:local:
12
13	Introduction
14	============
15
16	DataFlowSanitizer is a generalised dynamic data flow analysis.
17
18	Unlike other Sanitizer tools, this tool is not designed to detect a
19	specific class of bugs on its own. Instead, it provides a generic
20	dynamic data flow analysis framework to be used by clients to help
21	detect application-specific issues within their own code.
22
23	Usage
24	=====
25
26	With no program changes, applying DataFlowSanitizer to a program
27	will not alter its behavior. To use DataFlowSanitizer, the program
28	uses API functions to apply tags to data to cause it to be tracked, and to
29	check the tag of a specific data item. DataFlowSanitizer manages
30	the propagation of tags through the program according to its data flow.
31
32	The APIs are defined in the header file ``sanitizer/dfsan_interface.h``.
33	For further information about each function, please refer to the header
34	file.
35
36	ABI List
37	--------
38
39	DataFlowSanitizer uses a list of functions known as an ABI list to decide
40	whether a call to a specific function should use the operating system's native
41	ABI or whether it should use a variant of this ABI that also propagates labels
42	through function parameters and return values. The ABI list file also controls
43	how labels are propagated in the former case. DataFlowSanitizer comes with a
44	default ABI list which is intended to eventually cover the glibc library on
45	Linux but it may become necessary for users to extend the ABI list in cases
46	where a particular library or function cannot be instrumented (e.g. because
47	it is implemented in assembly or another language which DataFlowSanitizer does
48	not support) or a function is called from a library or function which cannot
49	be instrumented.
50
51	DataFlowSanitizer's ABI list file is a :doc:`SanitizerSpecialCaseList`.
52	The pass treats every function in the ``uninstrumented`` category in the
53	ABI list file as conforming to the native ABI. Unless the ABI list contains
54	additional categories for those functions, a call to one of those functions
55	will produce a warning message, as the labelling behavior of the function
56	is unknown. The other supported categories are ``discard``, ``functional``
57	and ``custom``.
58
59	* ``discard`` -- To the extent that this function writes to (user-accessible)
60	memory, it also updates labels in shadow memory (this condition is trivially
61	satisfied for functions which do not write to user-accessible memory). Its
62	return value is unlabelled.
63	* ``functional`` -- Like ``discard``, except that the label of its return value
64	is the union of the label of its arguments.
65	* ``custom`` -- Instead of calling the function, a custom wrapper ``__dfsw_F``
66	is called, where ``F`` is the name of the function. This function may wrap
67	the original function or provide its own implementation. This category is
68	generally used for uninstrumentable functions which write to user-accessible
69	memory or which have more complex label propagation behavior. The signature
70	of ``__dfsw_F`` is based on that of ``F`` with each argument having a
71	label of type ``dfsan_label`` appended to the argument list. If ``F``
72	is of non-void return type a final argument of type ``dfsan_label *``
73	is appended to which the custom function can store the label for the
74	return value. For example:
75
76	.. code-block:: c++
77
78	void f(int x);
79	void __dfsw_f(int x, dfsan_label x_label);
80
81	void memcpy(void dest, const void *src, size_t n);
82	void __dfsw_memcpy(void dest, const void *src, size_t n,
83	dfsan_label dest_label, dfsan_label src_label,
84	dfsan_label n_label, dfsan_label *ret_label);
85
86	If a function defined in the translation unit being compiled belongs to the
87	``uninstrumented`` category, it will be compiled so as to conform to the
88	native ABI. Its arguments will be assumed to be unlabelled, but it will
89	propagate labels in shadow memory.
90
91	For example:
92
93	.. code-block:: none
94
95	# main is called by the C runtime using the native ABI.
96	fun:main=uninstrumented
97	fun:main=discard
98
99	# malloc only writes to its internal data structures, not user-accessible memory.
100	fun:malloc=uninstrumented
101	fun:malloc=discard
102
103	# tolower is a pure function.
104	fun:tolower=uninstrumented
105	fun:tolower=functional
106
107	# memcpy needs to copy the shadow from the source to the destination region.
108	# This is done in a custom function.
109	fun:memcpy=uninstrumented
110	fun:memcpy=custom
111
112	Example
113	=======
114
115	The following program demonstrates label propagation by checking that
116	the correct labels are propagated.
117
118	.. code-block:: c++
119
120	#include <sanitizer/dfsan_interface.h>
121	#include <assert.h>
122
123	int main(void) {
124	int i = 1;
125	dfsan_label i_label = dfsan_create_label("i", 0);
126	dfsan_set_label(i_label, &i, sizeof(i));
127
128	int j = 2;
129	dfsan_label j_label = dfsan_create_label("j", 0);
130	dfsan_set_label(j_label, &j, sizeof(j));
131
132	int k = 3;
133	dfsan_label k_label = dfsan_create_label("k", 0);
134	dfsan_set_label(k_label, &k, sizeof(k));
135
136	dfsan_label ij_label = dfsan_get_label(i + j);
137	assert(dfsan_has_label(ij_label, i_label));
138	assert(dfsan_has_label(ij_label, j_label));
139	assert(!dfsan_has_label(ij_label, k_label));
140
141	dfsan_label ijk_label = dfsan_get_label(i + j + k);
142	assert(dfsan_has_label(ijk_label, i_label));
143	assert(dfsan_has_label(ijk_label, j_label));
144	assert(dfsan_has_label(ijk_label, k_label));
145
146	return 0;
147	}
148
149	Current status
150	==============
151
152	DataFlowSanitizer is a work in progress, currently under development for
153	x86\_64 Linux.
154
155	Design
156	======
157
158	Please refer to the :doc:`design document<DataFlowSanitizerDesign>`.
159

Clang Project