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>`.