| Peter Collingbourne | 2eeed71 | 2013-08-07 22:47:34 +0000 | [diff] [blame^] | 1 | ================= |
| 2 | DataFlowSanitizer |
| 3 | ================= |
| 4 | |
| 5 | .. contents:: |
| 6 | :local: |
| 7 | |
| 8 | Introduction |
| 9 | ============ |
| 10 | |
| 11 | DataFlowSanitizer is a generalised dynamic data flow analysis. |
| 12 | |
| 13 | Unlike other Sanitizer tools, this tool is not designed to detect a |
| 14 | specific class of bugs on its own. Instead, it provides a generic |
| 15 | dynamic data flow analysis framework to be used by clients to help |
| 16 | detect application-specific issues within their own code. |
| 17 | |
| 18 | Usage |
| 19 | ===== |
| 20 | |
| 21 | With no program changes, applying DataFlowSanitizer to a program |
| 22 | will not alter its behavior. To use DataFlowSanitizer, the program |
| 23 | uses API functions to apply tags to data to cause it to be tracked, and to |
| 24 | check the tag of a specific data item. DataFlowSanitizer manages |
| 25 | the propagation of tags through the program according to its data flow. |
| 26 | |
| 27 | The APIs are defined in the header file ``sanitizer/dfsan_interface.h``. |
| 28 | For further information about each function, please refer to the header |
| 29 | file. |
| 30 | |
| 31 | Example |
| 32 | ======= |
| 33 | |
| 34 | The following program demonstrates label propagation by checking that |
| 35 | the correct labels are propagated. |
| 36 | |
| 37 | .. code-block:: c++ |
| 38 | |
| 39 | #include <sanitizer/dfsan_interface.h> |
| 40 | #include <assert.h> |
| 41 | |
| 42 | int main(void) { |
| 43 | int i = 1; |
| 44 | dfsan_label i_label = dfsan_create_label("i", 0); |
| 45 | dfsan_set_label(i_label, &i, sizeof(i)); |
| 46 | |
| 47 | int j = 2; |
| 48 | dfsan_label j_label = dfsan_create_label("j", 0); |
| 49 | dfsan_set_label(j_label, &j, sizeof(j)); |
| 50 | |
| 51 | int k = 3; |
| 52 | dfsan_label k_label = dfsan_create_label("k", 0); |
| 53 | dfsan_set_label(k_label, &k, sizeof(k)); |
| 54 | |
| 55 | dfsan_label ij_label = dfsan_get_label(i + j); |
| 56 | assert(dfsan_has_label(ij_label, i_label)); |
| 57 | assert(dfsan_has_label(ij_label, j_label)); |
| 58 | assert(!dfsan_has_label(ij_label, k_label)); |
| 59 | |
| 60 | dfsan_label ijk_label = dfsan_get_label(i + j + k); |
| 61 | assert(dfsan_has_label(ijk_label, i_label)); |
| 62 | assert(dfsan_has_label(ijk_label, j_label)); |
| 63 | assert(dfsan_has_label(ijk_label, k_label)); |
| 64 | |
| 65 | return 0; |
| 66 | } |
| 67 | |
| 68 | Current status |
| 69 | ============== |
| 70 | |
| 71 | DataFlowSanitizer is a work in progress, currently under development for |
| 72 | x86\_64 Linux. |
| 73 | |
| 74 | Design |
| 75 | ====== |
| 76 | |
| 77 | Please refer to the :doc:`design document<DataFlowSanitizerDesign>`. |