|
8 | 8 | [](https://sonarcloud.io/summary/new_code?id=c-ares_c-ares) |
9 | 9 | [](https://scan.coverity.com/projects/c-ares) |
10 | 10 |
|
11 | | -This is c-ares, an asynchronous resolver library. It is intended for |
| 11 | +## Overview |
| 12 | +[c-ares](https://c-ares.org) is a modern DNS (stub) resolver library, written in |
| 13 | +C. It provides interfaces for asynchronous queries while trying to abstract the |
| 14 | +intricacies of the underlying DNS protocol. It was originally intended for |
12 | 15 | applications which need to perform DNS queries without blocking, or need to |
13 | | -perform multiple DNS queries in parallel. The primary examples of such |
14 | | -applications are servers which communicate with multiple clients and programs |
15 | | -with graphical user interfaces. |
| 16 | +perform multiple DNS queries in parallel. |
16 | 17 |
|
17 | | -The full source code is available in the ['c-ares' release archives](https://c-ares.org/download/), |
18 | | -and in a git repository: https://github.com/c-ares/c-ares. See the |
19 | | -[INSTALL.md](INSTALL.md) file for build information. |
| 18 | +One of the goals of c-ares is to be a better DNS resolver than is provided by |
| 19 | +your system, regardless of which system you use. We recommend using |
| 20 | +the c-ares library in all network applications even if the initial goal of |
| 21 | +asynchronous resolution is not necessary to your application. |
20 | 22 |
|
21 | | -If you find bugs, correct flaws, have questions or have comments in general in |
22 | | -regard to c-ares (or by all means the original ares too), get in touch with us |
23 | | -on the c-ares mailing list: https://lists.haxx.se/listinfo/c-ares |
| 23 | +c-ares will build with any C89 compiler and is [MIT licensed](LICENSE.md), |
| 24 | +which makes it suitable for both free and commercial software. c-ares runs on |
| 25 | +Linux, FreeBSD, OpenBSD, MacOS, Solaris, AIX, Windows, Android, iOS and many |
| 26 | +more operating systems. |
24 | 27 |
|
25 | | -c-ares is distributed under the MIT license. |
| 28 | +c-ares has a strong focus on security, implementing safe parsers and data |
| 29 | +builders used throughout the code, thus avoiding many of the common pitfalls |
| 30 | +of other C libraries. Through automated testing with our extensive testing |
| 31 | +framework, c-ares is constantly validated with a range of static and dynamic |
| 32 | +analyzers, as well as being constantly fuzzed by [OSS Fuzz](https://github.com/google/oss-fuzz). |
26 | 33 |
|
27 | | -You'll find all c-ares details and news here: |
28 | | - https://c-ares.org/ |
| 34 | +While c-ares has been around for over 20 years, it has been actively maintained |
| 35 | +both in regards to the latest DNS RFCs as well as updated to follow the latest |
| 36 | +best practices in regards to C coding standards. |
29 | 37 |
|
| 38 | +## Code |
30 | 39 |
|
31 | | -## Notes for c-ares hackers |
| 40 | +The full source code and revision history is available in our |
| 41 | +[GitHub repository](https://github.com/c-ares/c-ares). Our signed releases |
| 42 | +are available in the ['c-ares' release archives](https://c-ares.org/download/). |
32 | 43 |
|
33 | | -* The distributed `ares_build.h` file is only intended to be used on systems |
34 | | - which can not run the also distributed configure script. |
35 | 44 |
|
36 | | -* The distributed `ares_build.h` file is generated as a copy of `ares_build.h.dist` |
37 | | - when the c-ares source code distribution archive file is originally created. |
| 45 | +See the [INSTALL.md](INSTALL.md) file for build information. |
38 | 46 |
|
39 | | -* If you check out from git on a non-configure platform, you must run the |
40 | | - appropriate `buildconf*` script to set up `ares_build.h` and other local files |
41 | | - before being able to compile the library. |
| 47 | +## Communication |
42 | 48 |
|
43 | | -* On systems capable of running the `configure` script, the `configure` process |
44 | | - will overwrite the distributed `ares_build.h` file with one that is suitable |
45 | | - and specific to the library being configured and built, this new file is |
46 | | - generated from the `ares_build.h.in` template file. |
| 49 | +**Issues** and **Feature Requests** should be reported to our |
| 50 | +[GitHub Issues](https://github.com/c-ares/c-ares/issues) page. |
47 | 51 |
|
48 | | -* If you intend to distribute an already compiled c-ares library you **MUST** |
49 | | - also distribute along with it the generated `ares_build.h` which has been |
50 | | - used to compile it. Otherwise, the library will be of no use for the users of |
51 | | - the library that you have built. It is **your** responsibility to provide this |
52 | | - file. No one at the c-ares project can know how you have built the library. |
| 52 | +**Discussions** around c-ares and its use, are held on |
| 53 | +[GitHub Discussions](https://github.com/c-ares/c-ares/discussions/categories/q-a) |
| 54 | +or the [Mailing List](https://lists.haxx.se/mailman/listinfo/c-ares). Mailing |
| 55 | +List archive [here](https://lists.haxx.se/pipermail/c-ares/). |
| 56 | +Please, do not mail volunteers privately about c-ares. |
53 | 57 |
|
54 | | -* File `ares_build.h` includes platform and configuration dependent info, |
55 | | - and must not be modified by anyone. Configure script generates it for you. |
| 58 | +**Security vulnerabilities** are treated according to our |
| 59 | +[Security Procedure](SECURITY.md), please email c-ares-security at |
| 60 | + haxx.se if you suspect one. |
56 | 61 |
|
57 | | -* We cannot assume anything else but very basic compiler features being |
58 | | - present. While c-ares requires an ANSI C compiler to build, some of the |
59 | | - earlier ANSI compilers clearly can't deal with some preprocessor operators. |
60 | 62 |
|
61 | | -* Newlines must remain unix-style for older compilers' sake. |
| 63 | +## Release keys |
62 | 64 |
|
63 | | -* Comments must be written in the old-style /* unnested C-fashion */ |
| 65 | +Primary GPG keys for c-ares Releasers (some Releasers sign with subkeys): |
64 | 66 |
|
65 | | -* Try to keep line lengths below 80 columns. |
| 67 | +* **Daniel Stenberg** <<daniel@haxx.se>> |
| 68 | + `27EDEAF22F3ABCEB50DB9A125CC908FDB71E12C2` |
| 69 | +* **Brad House** <<brad@brad-house.com>> |
| 70 | + `DA7D64E4C82C6294CB73A20E22E3D13B5411B7CA` |
| 71 | + |
| 72 | +To import the full set of trusted release keys (including subkeys possibly used |
| 73 | +to sign releases): |
| 74 | + |
| 75 | +```bash |
| 76 | +gpg --keyserver hkps://keyserver.ubuntu.com --recv-keys 27EDEAF22F3ABCEB50DB9A125CC908FDB71E12C2 # Daniel Stenberg |
| 77 | +gpg --keyserver hkps://keys.openpgp.org --recv-keys DA7D64E4C82C6294CB73A20E22E3D13B5411B7CA # Brad House |
| 78 | +``` |
| 79 | + |
| 80 | +### Verifying signatures |
| 81 | + |
| 82 | +For each release `c-ares-X.Y.Z.tar.gz` there is a corresponding |
| 83 | +`c-ares-X.Y.Z.tar.gz.asc` file which contains the detached signature for the |
| 84 | +release. |
| 85 | + |
| 86 | +After fetching all of the possible valid signing keys and loading into your |
| 87 | +keychain as per the prior section, you can simply run the command below on |
| 88 | +the downloaded package and detached signature: |
| 89 | + |
| 90 | +```bash |
| 91 | +% gpg -v --verify c-ares-1.29.0.tar.gz.asc c-ares-1.29.0.tar.gz |
| 92 | +gpg: enabled compatibility flags: |
| 93 | +gpg: Signature made Fri May 24 02:50:38 2024 EDT |
| 94 | +gpg: using RSA key 27EDEAF22F3ABCEB50DB9A125CC908FDB71E12C2 |
| 95 | +gpg: using pgp trust model |
| 96 | +gpg: Good signature from "Daniel Stenberg <daniel@haxx.se>" [unknown] |
| 97 | +gpg: WARNING: This key is not certified with a trusted signature! |
| 98 | +gpg: There is no indication that the signature belongs to the owner. |
| 99 | +Primary key fingerprint: 27ED EAF2 2F3A BCEB 50DB 9A12 5CC9 08FD B71E 12C2 |
| 100 | +gpg: binary signature, digest algorithm SHA512, key algorithm rsa2048 |
| 101 | +``` |
0 commit comments