• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# [![c-ares logo](https://c-ares.org/art/c-ares-logo.svg)](https://c-ares.org/)
2
3[![Build Status](https://api.cirrus-ci.com/github/c-ares/c-ares.svg?branch=main)](https://cirrus-ci.com/github/c-ares/c-ares)
4[![Windows Build Status](https://ci.appveyor.com/api/projects/status/aevgc5914tm72pvs/branch/main?svg=true)](https://ci.appveyor.com/project/c-ares/c-ares/branch/main)
5[![Coverage Status](https://coveralls.io/repos/github/c-ares/c-ares/badge.svg?branch=main)](https://coveralls.io/github/c-ares/c-ares?branch=main)
6[![CII Best Practices](https://bestpractices.coreinfrastructure.org/projects/291/badge)](https://bestpractices.coreinfrastructure.org/projects/291)
7[![Fuzzing Status](https://oss-fuzz-build-logs.storage.googleapis.com/badges/c-ares.svg)](https://bugs.chromium.org/p/oss-fuzz/issues/list?sort=-opened&can=1&q=proj:c-ares)
8[![Bugs](https://sonarcloud.io/api/project_badges/measure?project=c-ares_c-ares&metric=bugs)](https://sonarcloud.io/summary/new_code?id=c-ares_c-ares)
9[![Coverity Scan Status](https://scan.coverity.com/projects/c-ares/badge.svg)](https://scan.coverity.com/projects/c-ares)
10
11- [Overview](#overview)
12- [Code](#code)
13- [Communication](#communication)
14- [Release Keys](#release-keys)
15  - [Verifying signatures](#verifying-signatures)
16- [Features](#features)
17  - [RFCs and Proposals](#supported-rfcs-and-proposals)
18
19## Overview
20[c-ares](https://c-ares.org) is a modern DNS (stub) resolver library, written in
21C. It provides interfaces for asynchronous queries while trying to abstract the
22intricacies of the underlying DNS protocol.  It was originally intended for
23applications which need to perform DNS queries without blocking, or need to
24perform multiple DNS queries in parallel.
25
26One of the goals of c-ares is to be a better DNS resolver than is provided by
27your system, regardless of which system you use.  We recommend using
28the c-ares library in all network applications even if the initial goal of
29asynchronous resolution is not necessary to your application.
30
31c-ares will build with any C89 compiler and is [MIT licensed](LICENSE.md),
32which makes it suitable for both free and commercial software. c-ares runs on
33Linux, FreeBSD, OpenBSD, MacOS, Solaris, AIX, Windows, Android, iOS and many
34more operating systems.
35
36c-ares has a strong focus on security, implementing safe parsers and data
37builders used throughout the code, thus avoiding many of the common pitfalls
38of other C libraries.  Through automated testing with our extensive testing
39framework, c-ares is constantly validated with a range of static and dynamic
40analyzers, as well as being constantly fuzzed by [OSS Fuzz](https://github.com/google/oss-fuzz).
41
42While c-ares has been around for over 20 years, it has been actively maintained
43both in regards to the latest DNS RFCs as well as updated to follow the latest
44best practices in regards to C coding standards.
45
46## Code
47
48The full source code and revision history is available in our
49[GitHub  repository](https://github.com/c-ares/c-ares).  Our signed releases
50are available in the [release archives](https://c-ares.org/download/).
51
52
53See the [INSTALL.md](INSTALL.md) file for build information.
54
55## Communication
56
57**Issues** and **Feature Requests** should be reported to our
58[GitHub Issues](https://github.com/c-ares/c-ares/issues) page.
59
60**Discussions** around c-ares and its use, are held on
61[GitHub Discussions](https://github.com/c-ares/c-ares/discussions/categories/q-a)
62or the [Mailing List](https://lists.haxx.se/mailman/listinfo/c-ares).  Mailing
63List archive [here](https://lists.haxx.se/pipermail/c-ares/).
64Please, do not mail volunteers privately about c-ares.
65
66**Security vulnerabilities** are treated according to our
67[Security Procedure](SECURITY.md), please email c-ares-security at
68 haxx.se if you suspect one.
69
70
71## Release keys
72
73Primary GPG keys for c-ares Releasers (some Releasers sign with subkeys):
74
75* **Daniel Stenberg** <<daniel@haxx.se>>
76  `27EDEAF22F3ABCEB50DB9A125CC908FDB71E12C2`
77* **Brad House** <<brad@brad-house.com>>
78  `DA7D64E4C82C6294CB73A20E22E3D13B5411B7CA`
79
80To import the full set of trusted release keys (including subkeys possibly used
81to sign releases):
82
83```bash
84gpg --keyserver hkps://keyserver.ubuntu.com --recv-keys 27EDEAF22F3ABCEB50DB9A125CC908FDB71E12C2 # Daniel Stenberg
85gpg --keyserver hkps://keyserver.ubuntu.com --recv-keys DA7D64E4C82C6294CB73A20E22E3D13B5411B7CA # Brad House
86```
87
88### Verifying signatures
89
90For each release `c-ares-X.Y.Z.tar.gz` there is a corresponding
91`c-ares-X.Y.Z.tar.gz.asc` file which contains the detached signature for the
92release.
93
94After fetching all of the possible valid signing keys and loading into your
95keychain as per the prior section, you can simply run the command below on
96the downloaded package and detached signature:
97
98```bash
99% gpg -v --verify c-ares-1.29.0.tar.gz.asc c-ares-1.29.0.tar.gz
100gpg: enabled compatibility flags:
101gpg: Signature made Fri May 24 02:50:38 2024 EDT
102gpg:                using RSA key 27EDEAF22F3ABCEB50DB9A125CC908FDB71E12C2
103gpg: using pgp trust model
104gpg: Good signature from "Daniel Stenberg <daniel@haxx.se>" [unknown]
105gpg: WARNING: This key is not certified with a trusted signature!
106gpg:          There is no indication that the signature belongs to the owner.
107Primary key fingerprint: 27ED EAF2 2F3A BCEB 50DB  9A12 5CC9 08FD B71E 12C2
108gpg: binary signature, digest algorithm SHA512, key algorithm rsa2048
109```
110
111## Features
112
113See [Features](FEATURES.md)
114
115### Supported RFCs and Proposals
116- [RFC1035](https://datatracker.ietf.org/doc/html/rfc1035).
117  Initial/Base DNS RFC
118- [RFC2671](https://datatracker.ietf.org/doc/html/rfc2671),
119  [RFC6891](https://datatracker.ietf.org/doc/html/rfc6891).
120  EDNS0 option (meta-RR)
121- [RFC3596](https://datatracker.ietf.org/doc/html/rfc3596).
122  IPv6 Address. `AAAA` Record.
123- [RFC2782](https://datatracker.ietf.org/doc/html/rfc2782).
124  Server Selection. `SRV` Record.
125- [RFC3403](https://datatracker.ietf.org/doc/html/rfc3403).
126  Naming Authority Pointer. `NAPTR` Record.
127- [RFC6698](https://datatracker.ietf.org/doc/html/rfc6698).
128  DNS-Based Authentication of Named Entities (DANE) Transport Layer Security (TLS) Protocol.
129  `TLSA` Record.
130- [RFC9460](https://datatracker.ietf.org/doc/html/rfc9460).
131  General Purpose Service Binding, Service Binding type for use with HTTPS.
132  `SVCB` and `HTTPS` Records.
133- [RFC7553](https://datatracker.ietf.org/doc/html/rfc7553).
134  Uniform Resource Identifier. `URI` Record.
135- [RFC6844](https://datatracker.ietf.org/doc/html/rfc6844).
136  Certification Authority Authorization. `CAA` Record.
137- [RFC2535](https://datatracker.ietf.org/doc/html/rfc2535),
138  [RFC2931](https://datatracker.ietf.org/doc/html/rfc2931).
139  `SIG0` Record. Only basic parser, not full implementation.
140- [RFC7873](https://datatracker.ietf.org/doc/html/rfc7873),
141  [RFC9018](https://datatracker.ietf.org/doc/html/rfc9018).
142  DNS Cookie off-path dns poisoning and amplification mitigation.
143- [draft-vixie-dnsext-dns0x20-00](https://datatracker.ietf.org/doc/html/draft-vixie-dnsext-dns0x20-00).
144  DNS 0x20 query name case randomization to prevent cache poisioning attacks.
145- [RFC7686](https://datatracker.ietf.org/doc/html/rfc7686).
146  Reject queries for `.onion` domain names with `NXDOMAIN`.
147- [RFC2606](https://datatracker.ietf.org/doc/html/rfc2606),
148  [RFC6761](https://datatracker.ietf.org/doc/html/rfc6761).
149  Special case treatment for `localhost`/`.localhost`.
150- [RFC2308](https://datatracker.ietf.org/doc/html/rfc2308),
151  [RFC9520](https://datatracker.ietf.org/doc/html/rfc9520).
152  Negative Caching of DNS Resolution Failures.
153- [RFC6724](https://datatracker.ietf.org/doc/html/rfc6724).
154  IPv6 address sorting as used by `ares_getaddrinfo()`.
155- [RFC7413](https://datatracker.ietf.org/doc/html/rfc7413).
156  TCP FastOpen (TFO) for 0-RTT TCP Connection Resumption.
157- [RFC3986](https://datatracker.ietf.org/doc/html/rfc3986).
158  Uniform Resource Identifier (URI). Used for server configuration.
159