README.md (7912B)
1 # [](https://c-ares.org/) 2 3 [](https://cirrus-ci.com/github/c-ares/c-ares) 4 [](https://ci.appveyor.com/project/c-ares/c-ares/branch/main) 5 [](https://coveralls.io/github/c-ares/c-ares?branch=main) 6 [](https://bestpractices.coreinfrastructure.org/projects/291) 7 [](https://bugs.chromium.org/p/oss-fuzz/issues/list?sort=-opened&can=1&q=proj:c-ares) 8 [](https://sonarcloud.io/summary/new_code?id=c-ares_c-ares) 9 [](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 21 C. It provides interfaces for asynchronous queries while trying to abstract the 22 intricacies of the underlying DNS protocol. It was originally intended for 23 applications which need to perform DNS queries without blocking, or need to 24 perform multiple DNS queries in parallel. 25 26 One of the goals of c-ares is to be a better DNS resolver than is provided by 27 your system, regardless of which system you use. We recommend using 28 the c-ares library in all network applications even if the initial goal of 29 asynchronous resolution is not necessary to your application. 30 31 c-ares will build with any C89 compiler and is [MIT licensed](LICENSE.md), 32 which makes it suitable for both free and commercial software. c-ares runs on 33 Linux, FreeBSD, OpenBSD, MacOS, Solaris, AIX, Windows, Android, iOS and many 34 more operating systems. 35 36 c-ares has a strong focus on security, implementing safe parsers and data 37 builders used throughout the code, thus avoiding many of the common pitfalls 38 of other C libraries. Through automated testing with our extensive testing 39 framework, c-ares is constantly validated with a range of static and dynamic 40 analyzers, as well as being constantly fuzzed by [OSS Fuzz](https://github.com/google/oss-fuzz). 41 42 While c-ares has been around for over 20 years, it has been actively maintained 43 both in regards to the latest DNS RFCs as well as updated to follow the latest 44 best practices in regards to C coding standards. 45 46 ## Code 47 48 The full source code and revision history is available in our 49 [GitHub repository](https://github.com/c-ares/c-ares). Our signed releases 50 are available in the [release archives](https://c-ares.org/download/). 51 52 53 See 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) 62 or the [Mailing List](https://lists.haxx.se/mailman/listinfo/c-ares). Mailing 63 List archive [here](https://lists.haxx.se/pipermail/c-ares/). 64 Please, 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 73 Primary 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 80 To import the full set of trusted release keys (including subkeys possibly used 81 to sign releases): 82 83 ```bash 84 gpg --keyserver hkps://keyserver.ubuntu.com --recv-keys 27EDEAF22F3ABCEB50DB9A125CC908FDB71E12C2 # Daniel Stenberg 85 gpg --keyserver hkps://keyserver.ubuntu.com --recv-keys DA7D64E4C82C6294CB73A20E22E3D13B5411B7CA # Brad House 86 ``` 87 88 ### Verifying signatures 89 90 For 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 92 release. 93 94 After fetching all of the possible valid signing keys and loading into your 95 keychain as per the prior section, you can simply run the command below on 96 the 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 100 gpg: enabled compatibility flags: 101 gpg: Signature made Fri May 24 02:50:38 2024 EDT 102 gpg: using RSA key 27EDEAF22F3ABCEB50DB9A125CC908FDB71E12C2 103 gpg: using pgp trust model 104 gpg: Good signature from "Daniel Stenberg <daniel@haxx.se>" [unknown] 105 gpg: WARNING: This key is not certified with a trusted signature! 106 gpg: There is no indication that the signature belongs to the owner. 107 Primary key fingerprint: 27ED EAF2 2F3A BCEB 50DB 9A12 5CC9 08FD B71E 12C2 108 gpg: binary signature, digest algorithm SHA512, key algorithm rsa2048 109 ``` 110 111 ## Features 112 113 See [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.