1 //===-- dfsan_interface.h -------------------------------------------------===//
2 //
3 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
4 // See https://llvm.org/LICENSE.txt for license information.
5 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
6 //
7 //===----------------------------------------------------------------------===//
8 //
9 // This file is a part of DataFlowSanitizer.
10 //
11 // Public interface header.
12 //===----------------------------------------------------------------------===//
13 #ifndef DFSAN_INTERFACE_H
14 #define DFSAN_INTERFACE_H
15
16 #include <stddef.h>
17 #include <stdint.h>
18 #include <sanitizer/common_interface_defs.h>
19
20 #ifdef __cplusplus
21 extern "C" {
22 #endif
23
24 typedef uint8_t dfsan_label;
25 typedef uint32_t dfsan_origin;
26
27 /// Signature of the callback argument to dfsan_set_write_callback().
28 typedef void (*dfsan_write_callback_t)(int fd, const void *buf, size_t count);
29
30 /// Signature of the callback argument to dfsan_set_conditional_callback().
31 typedef void (*dfsan_conditional_callback_t)(dfsan_label label,
32 dfsan_origin origin);
33
34 /// Computes the union of \c l1 and \c l2, resulting in a union label.
35 dfsan_label dfsan_union(dfsan_label l1, dfsan_label l2);
36
37 /// Sets the label for each address in [addr,addr+size) to \c label.
38 void dfsan_set_label(dfsan_label label, void *addr, size_t size);
39
40 /// Sets the label for each address in [addr,addr+size) to the union of the
41 /// current label for that address and \c label.
42 void dfsan_add_label(dfsan_label label, void *addr, size_t size);
43
44 /// Retrieves the label associated with the given data.
45 ///
46 /// The type of 'data' is arbitrary. The function accepts a value of any type,
47 /// which can be truncated or extended (implicitly or explicitly) as necessary.
48 /// The truncation/extension operations will preserve the label of the original
49 /// value.
50 dfsan_label dfsan_get_label(long data);
51
52 /// Retrieves the immediate origin associated with the given data. The returned
53 /// origin may point to another origin.
54 ///
55 /// The type of 'data' is arbitrary.
56 dfsan_origin dfsan_get_origin(long data);
57
58 /// Retrieves the label associated with the data at the given address.
59 dfsan_label dfsan_read_label(const void *addr, size_t size);
60
61 /// Return the origin associated with the first taint byte in the size bytes
62 /// from the address addr.
63 dfsan_origin dfsan_read_origin_of_first_taint(const void *addr, size_t size);
64
65 /// Returns whether the given label label contains the label elem.
66 int dfsan_has_label(dfsan_label label, dfsan_label elem);
67
68 /// Flushes the DFSan shadow, i.e. forgets about all labels currently associated
69 /// with the application memory. Use this call to start over the taint tracking
70 /// within the same process.
71 ///
72 /// Note: If another thread is working with tainted data during the flush, that
73 /// taint could still be written to shadow after the flush.
74 void dfsan_flush(void);
75
76 /// Sets a callback to be invoked on calls to write(). The callback is invoked
77 /// before the write is done. The write is not guaranteed to succeed when the
78 /// callback executes. Pass in NULL to remove any callback.
79 void dfsan_set_write_callback(dfsan_write_callback_t labeled_write_callback);
80
81 /// Sets a callback to be invoked on any conditional expressions which have a
82 /// taint label set. This can be used to find where tainted data influences
83 /// the behavior of the program.
84 /// These callbacks will only be added when -dfsan-conditional-callbacks=true.
85 void dfsan_set_conditional_callback(dfsan_conditional_callback_t callback);
86
87 /// Conditional expressions occur during signal handlers.
88 /// Making callbacks that handle signals well is tricky, so when
89 /// -dfsan-conditional-callbacks=true, conditional expressions used in signal
90 /// handlers will add the labels they see into a global (bitwise-or together).
91 /// This function returns all label bits seen in signal handler conditions.
92 dfsan_label dfsan_get_labels_in_signal_conditional();
93
94 /// Interceptor hooks.
95 /// Whenever a dfsan's custom function is called the corresponding
96 /// hook is called it non-zero. The hooks should be defined by the user.
97 /// The primary use case is taint-guided fuzzing, where the fuzzer
98 /// needs to see the parameters of the function and the labels.
99 /// FIXME: implement more hooks.
100 void dfsan_weak_hook_memcmp(void *caller_pc, const void *s1, const void *s2,
101 size_t n, dfsan_label s1_label,
102 dfsan_label s2_label, dfsan_label n_label);
103 void dfsan_weak_hook_strncmp(void *caller_pc, const char *s1, const char *s2,
104 size_t n, dfsan_label s1_label,
105 dfsan_label s2_label, dfsan_label n_label);
106
107 /// Prints the origin trace of the label at the address addr to stderr. It also
108 /// prints description at the beginning of the trace. If origin tracking is not
109 /// on, or the address is not labeled, it prints nothing.
110 void dfsan_print_origin_trace(const void *addr, const char *description);
111 /// As above, but use an origin id from dfsan_get_origin() instead of address.
112 /// Does not include header line with taint label and address information.
113 void dfsan_print_origin_id_trace(dfsan_origin origin);
114
115 /// Prints the origin trace of the label at the address \p addr to a
116 /// pre-allocated output buffer. If origin tracking is not on, or the address is
117 /// not labeled, it prints nothing.
118 ///
119 /// Typical usage:
120 /// \code
121 /// char kDescription[] = "...";
122 /// char buf[1024];
123 /// dfsan_sprint_origin_trace(&tainted_var, kDescription, buf, sizeof(buf));
124 /// \endcode
125 ///
126 /// Typical usage that handles truncation:
127 /// \code
128 /// char buf[1024];
129 /// int len = dfsan_sprint_origin_trace(&var, nullptr, buf, sizeof(buf));
130 ///
131 /// if (len < sizeof(buf)) {
132 /// ProcessOriginTrace(buf);
133 /// } else {
134 /// char *tmpbuf = new char[len + 1];
135 /// dfsan_sprint_origin_trace(&var, nullptr, tmpbuf, len + 1);
136 /// ProcessOriginTrace(tmpbuf);
137 /// delete[] tmpbuf;
138 /// }
139 /// \endcode
140 ///
141 /// \param addr The tainted memory address whose origin we are printing.
142 /// \param description A description printed at the beginning of the trace.
143 /// \param [out] out_buf The output buffer to write the results to.
144 /// \param out_buf_size The size of \p out_buf.
145 ///
146 /// \returns The number of symbols that should have been written to \p out_buf
147 /// (not including trailing null byte '\0'). Thus, the string is truncated iff
148 /// return value is not less than \p out_buf_size.
149 size_t dfsan_sprint_origin_trace(const void *addr, const char *description,
150 char *out_buf, size_t out_buf_size);
151 /// As above, but use an origin id from dfsan_get_origin() instead of address.
152 /// Does not include header line with taint label and address information.
153 size_t dfsan_sprint_origin_id_trace(dfsan_origin origin, char *out_buf,
154 size_t out_buf_size);
155
156 /// Prints the stack trace leading to this call to a pre-allocated output
157 /// buffer.
158 ///
159 /// For usage examples, see dfsan_sprint_origin_trace.
160 ///
161 /// \param [out] out_buf The output buffer to write the results to.
162 /// \param out_buf_size The size of \p out_buf.
163 ///
164 /// \returns The number of symbols that should have been written to \p out_buf
165 /// (not including trailing null byte '\0'). Thus, the string is truncated iff
166 /// return value is not less than \p out_buf_size.
167 size_t dfsan_sprint_stack_trace(char *out_buf, size_t out_buf_size);
168
169 /// Retrieves the very first origin associated with the data at the given
170 /// address.
171 dfsan_origin dfsan_get_init_origin(const void *addr);
172
173 /// Returns the value of -dfsan-track-origins.
174 /// * 0: do not track origins.
175 /// * 1: track origins at memory store operations.
176 /// * 2: track origins at memory load and store operations.
177 int dfsan_get_track_origins(void);
178 #ifdef __cplusplus
179 } // extern "C"
180
181 template <typename T> void dfsan_set_label(dfsan_label label, T &data) {
182 dfsan_set_label(label, (void *)&data, sizeof(T));
183 }
184
185 #endif
186
187 #endif // DFSAN_INTERFACE_H