1 //===- FuzzedDataProvider.h - Utility header for fuzz targets ---*- C++ -* ===//
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
7 //===----------------------------------------------------------------------===//
8 // A single header library providing an utility class to break up an array of
9 // bytes. Whenever run on the same input, provides the same output, as long as
10 // its methods are called in the same order, with the same arguments.
11 //===----------------------------------------------------------------------===//
13 #ifndef LLVM_FUZZER_FUZZED_DATA_PROVIDER_H_
14 #define LLVM_FUZZER_FUZZED_DATA_PROVIDER_H_
22 #include <initializer_list>
24 #include <type_traits>
28 class FuzzedDataProvider {
30 // |data| is an array of length |size| that the FuzzedDataProvider wraps to
31 // provide more granular access. |data| must outlive the FuzzedDataProvider.
32 FuzzedDataProvider(const uint8_t *data, size_t size)
33 : data_ptr_(data), remaining_bytes_(size) {}
34 ~FuzzedDataProvider() = default;
36 // Returns a std::vector containing |num_bytes| of input data. If fewer than
37 // |num_bytes| of data remain, returns a shorter std::vector containing all
38 // of the data that's left. Can be used with any byte sized type, such as
39 // char, unsigned char, uint8_t, etc.
40 template <typename T> std::vector<T> ConsumeBytes(size_t num_bytes) {
41 num_bytes = std::min(num_bytes, remaining_bytes_);
42 return ConsumeBytes<T>(num_bytes, num_bytes);
45 // Similar to |ConsumeBytes|, but also appends the terminator value at the end
46 // of the resulting vector. Useful, when a mutable null-terminated C-string is
47 // needed, for example. But that is a rare case. Better avoid it, if possible,
48 // and prefer using |ConsumeBytes| or |ConsumeBytesAsString| methods.
50 std::vector<T> ConsumeBytesWithTerminator(size_t num_bytes,
52 num_bytes = std::min(num_bytes, remaining_bytes_);
53 std::vector<T> result = ConsumeBytes<T>(num_bytes + 1, num_bytes);
54 result.back() = terminator;
58 // Returns a std::string containing |num_bytes| of input data. Using this and
59 // |.c_str()| on the resulting string is the best way to get an immutable
60 // null-terminated C string. If fewer than |num_bytes| of data remain, returns
61 // a shorter std::string containing all of the data that's left.
62 std::string ConsumeBytesAsString(size_t num_bytes) {
63 static_assert(sizeof(std::string::value_type) == sizeof(uint8_t),
64 "ConsumeBytesAsString cannot convert the data to a string.");
66 num_bytes = std::min(num_bytes, remaining_bytes_);
68 reinterpret_cast<const std::string::value_type *>(data_ptr_),
74 // Returns a number in the range [min, max] by consuming bytes from the
75 // input data. The value might not be uniformly distributed in the given
76 // range. If there's no input data left, always returns |min|. |min| must
77 // be less than or equal to |max|.
78 template <typename T> T ConsumeIntegralInRange(T min, T max) {
79 static_assert(std::is_integral<T>::value, "An integral type is required.");
80 static_assert(sizeof(T) <= sizeof(uint64_t), "Unsupported integral type.");
85 // Use the biggest type possible to hold the range and the result.
86 uint64_t range = static_cast<uint64_t>(max) - min;
90 while (offset < sizeof(T) * CHAR_BIT && (range >> offset) > 0 &&
91 remaining_bytes_ != 0) {
92 // Pull bytes off the end of the seed data. Experimentally, this seems to
93 // allow the fuzzer to more easily explore the input space. This makes
94 // sense, since it works by modifying inputs that caused new code to run,
95 // and this data is often used to encode length of data read by
96 // |ConsumeBytes|. Separating out read lengths makes it easier modify the
97 // contents of the data that is actually read.
99 result = (result << CHAR_BIT) | data_ptr_[remaining_bytes_];
103 // Avoid division by 0, in case |range + 1| results in overflow.
104 if (range != std::numeric_limits<decltype(range)>::max())
105 result = result % (range + 1);
107 return static_cast<T>(min + result);
110 // Returns a std::string of length from 0 to |max_length|. When it runs out of
111 // input data, returns what remains of the input. Designed to be more stable
112 // with respect to a fuzzer inserting characters than just picking a random
113 // length and then consuming that many bytes with |ConsumeBytes|.
114 std::string ConsumeRandomLengthString(size_t max_length) {
115 // Reads bytes from the start of |data_ptr_|. Maps "\\" to "\", and maps "\"
116 // followed by anything else to the end of the string. As a result of this
117 // logic, a fuzzer can insert characters into the string, and the string
118 // will be lengthened to include those new characters, resulting in a more
119 // stable fuzzer than picking the length of a string independently from
120 // picking its contents.
123 // Reserve the anticipated capaticity to prevent several reallocations.
124 result.reserve(std::min(max_length, remaining_bytes_));
125 for (size_t i = 0; i < max_length && remaining_bytes_ != 0; ++i) {
126 char next = ConvertUnsignedToSigned<char>(data_ptr_[0]);
128 if (next == '\\' && remaining_bytes_ != 0) {
129 next = ConvertUnsignedToSigned<char>(data_ptr_[0]);
137 result.shrink_to_fit();
141 // Returns a std::vector containing all remaining bytes of the input data.
142 template <typename T> std::vector<T> ConsumeRemainingBytes() {
143 return ConsumeBytes<T>(remaining_bytes_);
146 // Prefer using |ConsumeRemainingBytes| unless you actually need a std::string
148 // Returns a std::vector containing all remaining bytes of the input data.
149 std::string ConsumeRemainingBytesAsString() {
150 return ConsumeBytesAsString(remaining_bytes_);
153 // Returns a number in the range [Type's min, Type's max]. The value might
154 // not be uniformly distributed in the given range. If there's no input data
155 // left, always returns |min|.
156 template <typename T> T ConsumeIntegral() {
157 return ConsumeIntegralInRange(std::numeric_limits<T>::min(),
158 std::numeric_limits<T>::max());
161 // Reads one byte and returns a bool, or false when no data remains.
162 bool ConsumeBool() { return 1 & ConsumeIntegral<uint8_t>(); }
164 // Returns a copy of a value selected from a fixed-size |array|.
165 template <typename T, size_t size>
166 T PickValueInArray(const T (&array)[size]) {
167 static_assert(size > 0, "The array must be non empty.");
168 return array[ConsumeIntegralInRange<size_t>(0, size - 1)];
171 template <typename T>
172 T PickValueInArray(std::initializer_list<const T> list) {
173 // static_assert(list.size() > 0, "The array must be non empty.");
174 return *(list.begin() + ConsumeIntegralInRange<size_t>(0, list.size() - 1));
177 // Return an enum value. The enum must start at 0 and be contiguous. It must
178 // also contain |kMaxValue| aliased to its largest (inclusive) value. Such as:
179 // enum class Foo { SomeValue, OtherValue, kMaxValue = OtherValue };
180 template <typename T> T ConsumeEnum() {
181 static_assert(std::is_enum<T>::value, "|T| must be an enum type.");
182 return static_cast<T>(ConsumeIntegralInRange<uint32_t>(
183 0, static_cast<uint32_t>(T::kMaxValue)));
186 // Reports the remaining bytes available for fuzzed input.
187 size_t remaining_bytes() { return remaining_bytes_; }
190 FuzzedDataProvider(const FuzzedDataProvider &) = delete;
191 FuzzedDataProvider &operator=(const FuzzedDataProvider &) = delete;
193 void Advance(size_t num_bytes) {
194 if (num_bytes > remaining_bytes_)
197 data_ptr_ += num_bytes;
198 remaining_bytes_ -= num_bytes;
201 template <typename T>
202 std::vector<T> ConsumeBytes(size_t size, size_t num_bytes_to_consume) {
203 static_assert(sizeof(T) == sizeof(uint8_t), "Incompatible data type.");
205 // The point of using the size-based constructor below is to increase the
206 // odds of having a vector object with capacity being equal to the length.
207 // That part is always implementation specific, but at least both libc++ and
208 // libstdc++ allocate the requested number of bytes in that constructor,
209 // which seems to be a natural choice for other implementations as well.
210 // To increase the odds even more, we also call |shrink_to_fit| below.
211 std::vector<T> result(size);
212 std::memcpy(result.data(), data_ptr_, num_bytes_to_consume);
213 Advance(num_bytes_to_consume);
215 // Even though |shrink_to_fit| is also implementation specific, we expect it
216 // to provide an additional assurance in case vector's constructor allocated
217 // a buffer which is larger than the actual amount of data we put inside it.
218 result.shrink_to_fit();
222 template <typename TS, typename TU> TS ConvertUnsignedToSigned(TU value) {
223 static_assert(sizeof(TS) == sizeof(TU), "Incompatible data types.");
224 static_assert(!std::numeric_limits<TU>::is_signed,
225 "Source type must be unsigned.");
227 // TODO(Dor1s): change to `if constexpr` once C++17 becomes mainstream.
228 if (std::numeric_limits<TS>::is_modulo)
229 return static_cast<TS>(value);
231 // Avoid using implementation-defined unsigned to signer conversions.
232 // To learn more, see https://stackoverflow.com/questions/13150449.
233 if (value <= std::numeric_limits<TS>::max())
234 return static_cast<TS>(value);
236 constexpr auto TS_min = std::numeric_limits<TS>::min();
237 return TS_min + static_cast<char>(value - TS_min);
241 const uint8_t *data_ptr_;
242 size_t remaining_bytes_;
245 #endif // LLVM_FUZZER_FUZZED_DATA_PROVIDER_H_