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
21extern "C" {
22#endif
23
24typedef uint16_t dfsan_label;
25
26/// Stores information associated with a specific label identifier.  A label
27/// may be a base label created using dfsan_create_label, with associated
28/// text description and user data, or an automatically created union label,
29/// which represents the union of two label identifiers (which may themselves
30/// be base or union labels).
31struct dfsan_label_info {
32  // Fields for union labels, set to 0 for base labels.
33  dfsan_label l1;
34  dfsan_label l2;
35
36  // Fields for base labels.
37  const char *desc;
38  void *userdata;
39};
40
41/// Signature of the callback argument to dfsan_set_write_callback().
42typedef void (*dfsan_write_callback_t)(int fd, const void *buf, size_t count);
43
44/// Computes the union of \c l1 and \c l2, possibly creating a union label in
45/// the process.
46dfsan_label dfsan_union(dfsan_label l1, dfsan_label l2);
47
48/// Creates and returns a base label with the given description and user data.
49dfsan_label dfsan_create_label(const char *desc, void *userdata);
50
51/// Sets the label for each address in [addr,addr+size) to \c label.
52void dfsan_set_label(dfsan_label label, void *addr, size_t size);
53
54/// Sets the label for each address in [addr,addr+size) to the union of the
55/// current label for that address and \c label.
56void dfsan_add_label(dfsan_label label, void *addr, size_t size);
57
58/// Retrieves the label associated with the given data.
59///
60/// The type of 'data' is arbitrary.  The function accepts a value of any type,
61/// which can be truncated or extended (implicitly or explicitly) as necessary.
62/// The truncation/extension operations will preserve the label of the original
63/// value.
64dfsan_label dfsan_get_label(long data);
65
66/// Retrieves the label associated with the data at the given address.
67dfsan_label dfsan_read_label(const void *addr, size_t size);
68
69/// Retrieves a pointer to the dfsan_label_info struct for the given label.
70const struct dfsan_label_info *dfsan_get_label_info(dfsan_label label);
71
72/// Returns whether the given label label contains the label elem.
73int dfsan_has_label(dfsan_label label, dfsan_label elem);
74
75/// If the given label label contains a label with the description desc, returns
76/// that label, else returns 0.
77dfsan_label dfsan_has_label_with_desc(dfsan_label label, const char *desc);
78
79/// Returns the number of labels allocated.
80size_t dfsan_get_label_count(void);
81
82/// Flushes the DFSan shadow, i.e. forgets about all labels currently associated
83/// with the application memory. Will work only if there are no other
84/// threads executing DFSan-instrumented code concurrently.
85/// Use this call to start over the taint tracking within the same procces.
86void dfsan_flush(void);
87
88/// Sets a callback to be invoked on calls to write().  The callback is invoked
89/// before the write is done.  The write is not guaranteed to succeed when the
90/// callback executes.  Pass in NULL to remove any callback.
91void dfsan_set_write_callback(dfsan_write_callback_t labeled_write_callback);
92
93/// Writes the labels currently used by the program to the given file
94/// descriptor. The lines of the output have the following format:
95///
96/// <label> <parent label 1> <parent label 2> <label description if any>
97void dfsan_dump_labels(int fd);
98
99/// Interceptor hooks.
100/// Whenever a dfsan's custom function is called the corresponding
101/// hook is called it non-zero. The hooks should be defined by the user.
102/// The primary use case is taint-guided fuzzing, where the fuzzer
103/// needs to see the parameters of the function and the labels.
104/// FIXME: implement more hooks.
105void dfsan_weak_hook_memcmp(void *caller_pc, const void *s1, const void *s2,
106                            size_t n, dfsan_label s1_label,
107                            dfsan_label s2_label, dfsan_label n_label);
108void dfsan_weak_hook_strncmp(void *caller_pc, const char *s1, const char *s2,
109                             size_t n, dfsan_label s1_label,
110                             dfsan_label s2_label, dfsan_label n_label);
111#ifdef __cplusplus
112}  // extern "C"
113
114template <typename T>
115void dfsan_set_label(dfsan_label label, T &data) { // NOLINT
116  dfsan_set_label(label, (void *)&data, sizeof(T));
117}
118
119#endif
120
121#endif  // DFSAN_INTERFACE_H
122