A C library for asynchronous DNS requests (grpc依赖)
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 
 
 
 
Brad House 08b7692703
tests: MacOS needs higher priority on CI systems (#849)
4 months ago
..
fuzzinput Avoid buffer overflow in RC4 loop comparison (#336) 4 years ago
fuzznames Avoid buffer overflow in RC4 loop comparison (#336) 4 years ago
.gitignore Autotools: rework to simplify and fix recent issues (#674) 11 months ago
CMakeLists.txt CI: Add solaris (#814) 5 months ago
Makefile.am Auto reload config on changes (requires EventThread) (#759) 7 months ago
Makefile.inc Auto reload config on changes (requires EventThread) (#759) 7 months ago
Makefile.m32 mark deprecated functions as such (#732) 8 months ago
Makefile.msvc msvc Makefiles: Remove support for MSVC 6 and 7 since we can't target legacy Windows versions supported by those compilers anymore 4 months ago
README.md provide SPDX identifiers and a REUSE CI job to verify 2 years ago
ares-fuzz.c build fix 6 months ago
ares-test-ai.h test: fix outdated license headers 11 months ago
ares-test-fuzz-name.c fix comments 6 months ago
ares-test-fuzz.c build fix 6 months ago
ares-test-init.cc remove tests that have been disabled forever 8 months ago
ares-test-internal.cc Data Structure: Dynamic Array (#841) 4 months ago
ares-test-live.cc try to work around windows ASAN issue by not using std::string::npos 6 months ago
ares-test-main.cc tests: MacOS needs higher priority on CI systems (#849) 4 months ago
ares-test-misc.cc server cookie wasn't being passed back due to missing length 4 months ago
ares-test-mock-ai.cc tests: reduce required testing time for ServerFailoverOpts on most platforms 4 months ago
ares-test-mock-et.cc tests: MacOS needs higher priority on CI systems (#849) 4 months ago
ares-test-mock.cc tests: MacOS needs higher priority on CI systems (#849) 4 months ago
ares-test-ns.cc try to work around windows ASAN issue by not using std::string::npos 6 months ago
ares-test-parse-a.cc DNS 0x20 implementation (#800) 5 months ago
ares-test-parse-aaaa.cc DNS 0x20 implementation (#800) 5 months ago
ares-test-parse-caa.cc Coverage code annotations for identification of desirable paths that need testing (#775) 6 months ago
ares-test-parse-mx.cc Coverage code annotations for identification of desirable paths that need testing (#775) 6 months ago
ares-test-parse-naptr.cc Coverage code annotations for identification of desirable paths that need testing (#775) 6 months ago
ares-test-parse-ns.cc Coverage code annotations for identification of desirable paths that need testing (#775) 6 months ago
ares-test-parse-ptr.cc Add DNS cookie support (RFC7873 + RFC9018) (#833) 4 months ago
ares-test-parse-soa-any.cc Coverage code annotations for identification of desirable paths that need testing (#775) 6 months ago
ares-test-parse-soa.cc Coverage code annotations for identification of desirable paths that need testing (#775) 6 months ago
ares-test-parse-srv.cc Coverage code annotations for identification of desirable paths that need testing (#775) 6 months ago
ares-test-parse-txt.cc DNS RR TXT strings should not be automatically concatenated (#801) 5 months ago
ares-test-parse-uri.cc Coverage code annotations for identification of desirable paths that need testing (#775) 6 months ago
ares-test-parse.cc test: fix outdated license headers 11 months ago
ares-test.cc Implement TCP FastOpen (TFO) RFC7413 (#840) 4 months ago
ares-test.h Refactor connection handling (#839) 4 months ago
ares_queryloop.c clang-format 4 months ago
dns-dump.cc test: fix outdated license headers 11 months ago
dns-proto-test.cc test: fix outdated license headers 11 months ago
dns-proto.cc server cookie wasn't being passed back due to missing length 4 months ago
dns-proto.h Refactor connection handling (#839) 4 months ago
fuzzcheck.sh provide SPDX identifiers and a REUSE CI job to verify 2 years ago

README.md

c-ares Unit Test Suite

This directory holds unit tests for the c-ares library. To build the tests:

  • Build the main c-ares library first, in the directory above this. To enable tests of internal functions, configure the library build to expose hidden symbols with ./configure --disable-symbol-hiding.
  • Generate a configure file by running autoreconf -iv (which requires a local installation of autotools).
  • ./configure
  • make
  • Run the tests with ./arestest, or ./arestest -v for extra debug info.

Points to note:

  • The tests are written in C++11, and so need a C++ compiler that supports this. To avoid adding this as a requirement for the library, the configuration and build of the tests is independent from the library.
  • The tests include some live queries, which will fail when run on a machine without internet connectivity. To skip live tests, run with ./arestest --gtest_filter=-*.Live*.
  • The tests include queries of a mock DNS server. This server listens on port 5300 by default, but the port can be changed with the -p 5300 option to arestest.

Test Types

The test suite includes various different types of test.

  • There are live tests (ares-test-live.cc), which assume that the current machine has a valid DNS setup and connection to the internet; these tests issue queries for real domains but don't particularly check what gets returned. The tests will fail on an offline machine.
  • There are some mock tests (ares-test-mock.cc) that set up a fake DNS server and inject its port into the c-ares library configuration. These tests allow specific response messages to be crafted and injected, and so are likely to be used for many more tests in future.
    • To make this generation/injection easier, the dns-proto.h file includes C++ helper classes for building DNS packets.
  • Other library entrypoints that don't require network activity (e.g. ares_parse_*_reply) are tested directly.
  • A couple of the tests use a helper method of the test fixture to inject memory allocation failures, using a recent change to the c-ares library that allows override of malloc/free.
  • There are some tests of the internal entrypoints of the library (ares-test-internal.c), but these are only enabled if the library was configured with --disable-symbol-hiding and/or --enable-expose-statics.
  • There is also an entrypoint to allow Clang's libfuzzer to drive the packet parsing code in ares_parse_*_reply, together with a standalone wrapper for it (./aresfuzz) to allow use of command line fuzzers (such as afl-fuzz) for further fuzz testing.

Code Coverage Information

To generate code coverage information:

  • Configure both the library and the tests with ./configure --enable-code-coverage before building. This requires the relevant code coverage tools (gcov, lcov) to be installed locally.
  • Run the tests with test/arestest.
  • Generate code coverage output with make code-coverage-capture in the library directory (i.e. not in test/).

Fuzzing

libFuzzer

To fuzz the packet parsing code with libFuzzer, follow the main libFuzzer instructions:

  • Configure the c-ares library and test suite with a recent Clang and a sanitizer, for example:

    % export CFLAGS="-fsanitize=fuzzer-no-link,address"
    % export CC=clang
    % ./configure --disable-shared && make
    
  • Link each of the fuzzer entrypoints in with ares-fuzz.cc:

    % clang -I.. -c ares-test-fuzz.c
    % clang -I.. -c ares-test-fuzz-name.c
    % clang++ -fsanitize=fuzzer,address ares-test-fuzz.o ../.libs/libcares.a -o ares-libfuzzer
    % clang++ -fsanitize=fuzzer,address ares-test-fuzz-name.o ../.libs/libcares.a -o ares-libfuzzer-name
    
  • Run the fuzzer using the starting corpus with:

    % ./ares-libfuzzer fuzzinput/  # OR
    % ./ares-libfuzzer-name fuzznames/
    

AFL

To fuzz using AFL, follow the AFL quick start guide:

  • Download and build AFL.

  • Configure the c-ares library and test tool to use AFL's compiler wrappers:

    % export CC=$AFLDIR/afl-gcc
    % ./configure --disable-shared && make
    % cd test && ./configure && make aresfuzz aresfuzzname
    
  • Run the AFL fuzzer against the starting corpus:

    % mkdir fuzzoutput
    % $AFLDIR/afl-fuzz -i fuzzinput -o fuzzoutput -- ./aresfuzz  # OR
    % $AFLDIR/afl-fuzz -i fuzznames -o fuzzoutput -- ./aresfuzzname
    

AFL Persistent Mode

If a recent version of Clang is available, AFL can use its built-in compiler instrumentation; this configuration also allows the use of a (much) faster persistent mode, where multiple fuzz inputs are run for each process invocation.

  • Download and build a recent AFL, and run make in the llvm_mode subdirectory to ensure that afl-clang-fast gets built.

  • Configure the c-ares library and test tool to use AFL's clang wrappers that use compiler instrumentation:

    % export CC=$AFLDIR/afl-clang-fast
    % ./configure --disable-shared && make
    % cd test && ./configure && make aresfuzz
    
  • Run the AFL fuzzer (in persistent mode) against the starting corpus:

    % mkdir fuzzoutput
    % $AFLDIR/afl-fuzz -i fuzzinput -o fuzzoutput -- ./aresfuzz