1 //===- FuzzedDataProvider.h - Utility header for fuzz targets ---*- C++ -* ===// 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 // 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 //===----------------------------------------------------------------------===// 12 13 #ifndef LLVM_FUZZER_FUZZED_DATA_PROVIDER_H_ 14 #define LLVM_FUZZER_FUZZED_DATA_PROVIDER_H_ 15 16 #include <algorithm> 17 #include <climits> 18 #include <cstddef> 19 #include <cstdint> 20 #include <cstring> 21 #include <initializer_list> 22 #include <string> 23 #include <type_traits> 24 #include <utility> 25 #include <vector> 26 27 // In addition to the comments below, the API is also briefly documented at 28 // https://github.com/google/fuzzing/blob/master/docs/split-inputs.md#fuzzed-data-provider 29 class FuzzedDataProvider { 30 public: 31 // |data| is an array of length |size| that the FuzzedDataProvider wraps to 32 // provide more granular access. |data| must outlive the FuzzedDataProvider. 33 FuzzedDataProvider(const uint8_t *data, size_t size) 34 : data_ptr_(data), remaining_bytes_(size) {} 35 ~FuzzedDataProvider() = default; 36 37 // See the implementation below (after the class definition) for more verbose 38 // comments for each of the methods. 39 40 // Methods returning std::vector of bytes. These are the most popular choice 41 // when splitting fuzzing input into pieces, as every piece is put into a 42 // separate buffer (i.e. ASan would catch any under-/overflow) and the memory 43 // will be released automatically. 44 template <typename T> std::vector<T> ConsumeBytes(size_t num_bytes); 45 template <typename T> 46 std::vector<T> ConsumeBytesWithTerminator(size_t num_bytes, T terminator = 0); 47 template <typename T> std::vector<T> ConsumeRemainingBytes(); 48 49 // Methods returning strings. Use only when you need a std::string or a null 50 // terminated C-string. Otherwise, prefer the methods returning std::vector. 51 std::string ConsumeBytesAsString(size_t num_bytes); 52 std::string ConsumeRandomLengthString(size_t max_length); 53 std::string ConsumeRandomLengthString(); 54 std::string ConsumeRemainingBytesAsString(); 55 56 // Methods returning integer values. 57 template <typename T> T ConsumeIntegral(); 58 template <typename T> T ConsumeIntegralInRange(T min, T max); 59 60 // Methods returning floating point values. 61 template <typename T> T ConsumeFloatingPoint(); 62 template <typename T> T ConsumeFloatingPointInRange(T min, T max); 63 64 // 0 <= return value <= 1. 65 template <typename T> T ConsumeProbability(); 66 67 bool ConsumeBool(); 68 69 // Returns a value chosen from the given enum. 70 template <typename T> T ConsumeEnum(); 71 72 // Returns a value from the given array. 73 template <typename T, size_t size> T PickValueInArray(const T (&array)[size]); 74 template <typename T> T PickValueInArray(std::initializer_list<const T> list); 75 76 // Writes data to the given destination and returns number of bytes written. 77 size_t ConsumeData(void *destination, size_t num_bytes); 78 79 // Reports the remaining bytes available for fuzzed input. 80 size_t remaining_bytes() { return remaining_bytes_; } 81 82 private: 83 FuzzedDataProvider(const FuzzedDataProvider &) = delete; 84 FuzzedDataProvider &operator=(const FuzzedDataProvider &) = delete; 85 86 void CopyAndAdvance(void *destination, size_t num_bytes); 87 88 void Advance(size_t num_bytes); 89 90 template <typename T> 91 std::vector<T> ConsumeBytes(size_t size, size_t num_bytes); 92 93 template <typename TS, typename TU> TS ConvertUnsignedToSigned(TU value); 94 95 const uint8_t *data_ptr_; 96 size_t remaining_bytes_; 97 }; 98 99 // Returns a std::vector containing |num_bytes| of input data. If fewer than 100 // |num_bytes| of data remain, returns a shorter std::vector containing all 101 // of the data that's left. Can be used with any byte sized type, such as 102 // char, unsigned char, uint8_t, etc. 103 template <typename T> 104 std::vector<T> FuzzedDataProvider::ConsumeBytes(size_t num_bytes) { 105 num_bytes = std::min(num_bytes, remaining_bytes_); 106 return ConsumeBytes<T>(num_bytes, num_bytes); 107 } 108 109 // Similar to |ConsumeBytes|, but also appends the terminator value at the end 110 // of the resulting vector. Useful, when a mutable null-terminated C-string is 111 // needed, for example. But that is a rare case. Better avoid it, if possible, 112 // and prefer using |ConsumeBytes| or |ConsumeBytesAsString| methods. 113 template <typename T> 114 std::vector<T> FuzzedDataProvider::ConsumeBytesWithTerminator(size_t num_bytes, 115 T terminator) { 116 num_bytes = std::min(num_bytes, remaining_bytes_); 117 std::vector<T> result = ConsumeBytes<T>(num_bytes + 1, num_bytes); 118 result.back() = terminator; 119 return result; 120 } 121 122 // Returns a std::vector containing all remaining bytes of the input data. 123 template <typename T> 124 std::vector<T> FuzzedDataProvider::ConsumeRemainingBytes() { 125 return ConsumeBytes<T>(remaining_bytes_); 126 } 127 128 // Returns a std::string containing |num_bytes| of input data. Using this and 129 // |.c_str()| on the resulting string is the best way to get an immutable 130 // null-terminated C string. If fewer than |num_bytes| of data remain, returns 131 // a shorter std::string containing all of the data that's left. 132 inline std::string FuzzedDataProvider::ConsumeBytesAsString(size_t num_bytes) { 133 static_assert(sizeof(std::string::value_type) == sizeof(uint8_t), 134 "ConsumeBytesAsString cannot convert the data to a string."); 135 136 num_bytes = std::min(num_bytes, remaining_bytes_); 137 std::string result( 138 reinterpret_cast<const std::string::value_type *>(data_ptr_), num_bytes); 139 Advance(num_bytes); 140 return result; 141 } 142 143 // Returns a std::string of length from 0 to |max_length|. When it runs out of 144 // input data, returns what remains of the input. Designed to be more stable 145 // with respect to a fuzzer inserting characters than just picking a random 146 // length and then consuming that many bytes with |ConsumeBytes|. 147 inline std::string 148 FuzzedDataProvider::ConsumeRandomLengthString(size_t max_length) { 149 // Reads bytes from the start of |data_ptr_|. Maps "\\" to "\", and maps "\" 150 // followed by anything else to the end of the string. As a result of this 151 // logic, a fuzzer can insert characters into the string, and the string 152 // will be lengthened to include those new characters, resulting in a more 153 // stable fuzzer than picking the length of a string independently from 154 // picking its contents. 155 std::string result; 156 157 // Reserve the anticipated capaticity to prevent several reallocations. 158 result.reserve(std::min(max_length, remaining_bytes_)); 159 for (size_t i = 0; i < max_length && remaining_bytes_ != 0; ++i) { 160 char next = ConvertUnsignedToSigned<char>(data_ptr_[0]); 161 Advance(1); 162 if (next == '\\' && remaining_bytes_ != 0) { 163 next = ConvertUnsignedToSigned<char>(data_ptr_[0]); 164 Advance(1); 165 if (next != '\\') 166 break; 167 } 168 result += next; 169 } 170 171 result.shrink_to_fit(); 172 return result; 173 } 174 175 // Returns a std::string of length from 0 to |remaining_bytes_|. 176 inline std::string FuzzedDataProvider::ConsumeRandomLengthString() { 177 return ConsumeRandomLengthString(remaining_bytes_); 178 } 179 180 // Returns a std::string containing all remaining bytes of the input data. 181 // Prefer using |ConsumeRemainingBytes| unless you actually need a std::string 182 // object. 183 inline std::string FuzzedDataProvider::ConsumeRemainingBytesAsString() { 184 return ConsumeBytesAsString(remaining_bytes_); 185 } 186 187 // Returns a number in the range [Type's min, Type's max]. The value might 188 // not be uniformly distributed in the given range. If there's no input data 189 // left, always returns |min|. 190 template <typename T> T FuzzedDataProvider::ConsumeIntegral() { 191 return ConsumeIntegralInRange(std::numeric_limits<T>::min(), 192 std::numeric_limits<T>::max()); 193 } 194 195 // Returns a number in the range [min, max] by consuming bytes from the 196 // input data. The value might not be uniformly distributed in the given 197 // range. If there's no input data left, always returns |min|. |min| must 198 // be less than or equal to |max|. 199 template <typename T> 200 T FuzzedDataProvider::ConsumeIntegralInRange(T min, T max) { 201 static_assert(std::is_integral<T>::value, "An integral type is required."); 202 static_assert(sizeof(T) <= sizeof(uint64_t), "Unsupported integral type."); 203 204 if (min > max) 205 abort(); 206 207 // Use the biggest type possible to hold the range and the result. 208 uint64_t range = static_cast<uint64_t>(max) - min; 209 uint64_t result = 0; 210 size_t offset = 0; 211 212 while (offset < sizeof(T) * CHAR_BIT && (range >> offset) > 0 && 213 remaining_bytes_ != 0) { 214 // Pull bytes off the end of the seed data. Experimentally, this seems to 215 // allow the fuzzer to more easily explore the input space. This makes 216 // sense, since it works by modifying inputs that caused new code to run, 217 // and this data is often used to encode length of data read by 218 // |ConsumeBytes|. Separating out read lengths makes it easier modify the 219 // contents of the data that is actually read. 220 --remaining_bytes_; 221 result = (result << CHAR_BIT) | data_ptr_[remaining_bytes_]; 222 offset += CHAR_BIT; 223 } 224 225 // Avoid division by 0, in case |range + 1| results in overflow. 226 if (range != std::numeric_limits<decltype(range)>::max()) 227 result = result % (range + 1); 228 229 return static_cast<T>(min + result); 230 } 231 232 // Returns a floating point value in the range [Type's lowest, Type's max] by 233 // consuming bytes from the input data. If there's no input data left, always 234 // returns approximately 0. 235 template <typename T> T FuzzedDataProvider::ConsumeFloatingPoint() { 236 return ConsumeFloatingPointInRange<T>(std::numeric_limits<T>::lowest(), 237 std::numeric_limits<T>::max()); 238 } 239 240 // Returns a floating point value in the given range by consuming bytes from 241 // the input data. If there's no input data left, returns |min|. Note that 242 // |min| must be less than or equal to |max|. 243 template <typename T> 244 T FuzzedDataProvider::ConsumeFloatingPointInRange(T min, T max) { 245 if (min > max) 246 abort(); 247 248 T range = .0; 249 T result = min; 250 constexpr T zero(.0); 251 if (max > zero && min < zero && max > min + std::numeric_limits<T>::max()) { 252 // The diff |max - min| would overflow the given floating point type. Use 253 // the half of the diff as the range and consume a bool to decide whether 254 // the result is in the first of the second part of the diff. 255 range = (max / 2.0) - (min / 2.0); 256 if (ConsumeBool()) { 257 result += range; 258 } 259 } else { 260 range = max - min; 261 } 262 263 return result + range * ConsumeProbability<T>(); 264 } 265 266 // Returns a floating point number in the range [0.0, 1.0]. If there's no 267 // input data left, always returns 0. 268 template <typename T> T FuzzedDataProvider::ConsumeProbability() { 269 static_assert(std::is_floating_point<T>::value, 270 "A floating point type is required."); 271 272 // Use different integral types for different floating point types in order 273 // to provide better density of the resulting values. 274 using IntegralType = 275 typename std::conditional<(sizeof(T) <= sizeof(uint32_t)), uint32_t, 276 uint64_t>::type; 277 278 T result = static_cast<T>(ConsumeIntegral<IntegralType>()); 279 result /= static_cast<T>(std::numeric_limits<IntegralType>::max()); 280 return result; 281 } 282 283 // Reads one byte and returns a bool, or false when no data remains. 284 inline bool FuzzedDataProvider::ConsumeBool() { 285 return 1 & ConsumeIntegral<uint8_t>(); 286 } 287 288 // Returns an enum value. The enum must start at 0 and be contiguous. It must 289 // also contain |kMaxValue| aliased to its largest (inclusive) value. Such as: 290 // enum class Foo { SomeValue, OtherValue, kMaxValue = OtherValue }; 291 template <typename T> T FuzzedDataProvider::ConsumeEnum() { 292 static_assert(std::is_enum<T>::value, "|T| must be an enum type."); 293 return static_cast<T>( 294 ConsumeIntegralInRange<uint32_t>(0, static_cast<uint32_t>(T::kMaxValue))); 295 } 296 297 // Returns a copy of the value selected from the given fixed-size |array|. 298 template <typename T, size_t size> 299 T FuzzedDataProvider::PickValueInArray(const T (&array)[size]) { 300 static_assert(size > 0, "The array must be non empty."); 301 return array[ConsumeIntegralInRange<size_t>(0, size - 1)]; 302 } 303 304 template <typename T> 305 T FuzzedDataProvider::PickValueInArray(std::initializer_list<const T> list) { 306 // TODO(Dor1s): switch to static_assert once C++14 is allowed. 307 if (!list.size()) 308 abort(); 309 310 return *(list.begin() + ConsumeIntegralInRange<size_t>(0, list.size() - 1)); 311 } 312 313 // Writes |num_bytes| of input data to the given destination pointer. If there 314 // is not enough data left, writes all remaining bytes. Return value is the 315 // number of bytes written. 316 // In general, it's better to avoid using this function, but it may be useful 317 // in cases when it's necessary to fill a certain buffer or object with 318 // fuzzing data. 319 inline size_t FuzzedDataProvider::ConsumeData(void *destination, 320 size_t num_bytes) { 321 num_bytes = std::min(num_bytes, remaining_bytes_); 322 CopyAndAdvance(destination, num_bytes); 323 return num_bytes; 324 } 325 326 // Private methods. 327 inline void FuzzedDataProvider::CopyAndAdvance(void *destination, 328 size_t num_bytes) { 329 std::memcpy(destination, data_ptr_, num_bytes); 330 Advance(num_bytes); 331 } 332 333 inline void FuzzedDataProvider::Advance(size_t num_bytes) { 334 if (num_bytes > remaining_bytes_) 335 abort(); 336 337 data_ptr_ += num_bytes; 338 remaining_bytes_ -= num_bytes; 339 } 340 341 template <typename T> 342 std::vector<T> FuzzedDataProvider::ConsumeBytes(size_t size, size_t num_bytes) { 343 static_assert(sizeof(T) == sizeof(uint8_t), "Incompatible data type."); 344 345 // The point of using the size-based constructor below is to increase the 346 // odds of having a vector object with capacity being equal to the length. 347 // That part is always implementation specific, but at least both libc++ and 348 // libstdc++ allocate the requested number of bytes in that constructor, 349 // which seems to be a natural choice for other implementations as well. 350 // To increase the odds even more, we also call |shrink_to_fit| below. 351 std::vector<T> result(size); 352 if (size == 0) { 353 if (num_bytes != 0) 354 abort(); 355 return result; 356 } 357 358 CopyAndAdvance(result.data(), num_bytes); 359 360 // Even though |shrink_to_fit| is also implementation specific, we expect it 361 // to provide an additional assurance in case vector's constructor allocated 362 // a buffer which is larger than the actual amount of data we put inside it. 363 result.shrink_to_fit(); 364 return result; 365 } 366 367 template <typename TS, typename TU> 368 TS FuzzedDataProvider::ConvertUnsignedToSigned(TU value) { 369 static_assert(sizeof(TS) == sizeof(TU), "Incompatible data types."); 370 static_assert(!std::numeric_limits<TU>::is_signed, 371 "Source type must be unsigned."); 372 373 // TODO(Dor1s): change to `if constexpr` once C++17 becomes mainstream. 374 if (std::numeric_limits<TS>::is_modulo) 375 return static_cast<TS>(value); 376 377 // Avoid using implementation-defined unsigned to signed conversions. 378 // To learn more, see https://stackoverflow.com/questions/13150449. 379 if (value <= std::numeric_limits<TS>::max()) { 380 return static_cast<TS>(value); 381 } else { 382 constexpr auto TS_min = std::numeric_limits<TS>::min(); 383 return TS_min + static_cast<char>(value - TS_min); 384 } 385 } 386 387 #endif // LLVM_FUZZER_FUZZED_DATA_PROVIDER_H_ 388