{"id":13552026,"url":"https://github.com/DNSCrypt/doh-server","last_synced_at":"2025-04-03T02:32:49.996Z","repository":{"id":39715471,"uuid":"120375466","full_name":"DNSCrypt/doh-server","owner":"DNSCrypt","description":"Fast, mature, secure DoH and ODoH server proxy written in Rust. Previously known as doh-proxy and rust-doh.","archived":false,"fork":false,"pushed_at":"2024-05-14T03:45:06.000Z","size":308,"stargazers_count":689,"open_issues_count":2,"forks_count":61,"subscribers_count":22,"default_branch":"master","last_synced_at":"2024-05-20T11:23:31.140Z","etag":null,"topics":["dns","dnscrypt","dnscrypt-proxy","doh","doh-connections","doh-proxy","doh-server","doh-service","encrypted-dns-server","http","oblivious-dns-over-https","odoh","proxy","server"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/DNSCrypt.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"open_collective":"dnscrypt"}},"created_at":"2018-02-05T23:29:47.000Z","updated_at":"2024-05-18T09:03:25.000Z","dependencies_parsed_at":"2024-05-05T17:22:42.207Z","dependency_job_id":"f1abc23a-ce9e-48f4-859c-3240dc00a90b","html_url":"https://github.com/DNSCrypt/doh-server","commit_stats":null,"previous_names":["jedisct1/rust-doh"],"tags_count":36,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DNSCrypt%2Fdoh-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DNSCrypt%2Fdoh-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DNSCrypt%2Fdoh-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DNSCrypt%2Fdoh-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/DNSCrypt","download_url":"https://codeload.github.com/DNSCrypt/doh-server/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":213132662,"owners_count":15542149,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["dns","dnscrypt","dnscrypt-proxy","doh","doh-connections","doh-proxy","doh-server","doh-service","encrypted-dns-server","http","oblivious-dns-over-https","odoh","proxy","server"],"created_at":"2024-08-01T12:01:57.660Z","updated_at":"2024-11-03T22:33:14.591Z","avatar_url":"https://github.com/DNSCrypt.png","language":"Rust","readme":"# ![DoH server (and ODoH - Oblivious DoH server)](logo.png)\n\nA fast and secure DoH (DNS-over-HTTPS) and ODoH (Oblivious DoH) server.\n\n`doh-proxy` is written in Rust, and has been battle-tested in production since February 2018. It doesn't do DNS resolution on its own, but can sit in front of any DNS resolver in order to augment it with DoH support.\n\n## Installation\n\n### Option 1: precompiled binaries for Linux\n\nPrecompiled tarballs and Debian packages for Linux/x86_64 [can be downloaded here](https://github.com/jedisct1/doh-server/releases/latest).\n\n### Option 2: from source code\n\nThis requires the [`rust`](https://rustup.rs) compiler to be installed.\n\n* With built-in support for HTTPS (default):\n\n```sh\ncargo install doh-proxy\n```\n\n* Without built-in support for HTTPS:\n\n```sh\ncargo install doh-proxy --no-default-features\n```\n\n## Usage\n\n```text\nUSAGE:\n    doh-proxy [FLAGS] [OPTIONS]\n\nFLAGS:\n    -O, --allow-odoh-post      Allow POST queries over ODoH even if they have been disabed for DoH\n    -K, --disable-keepalive    Disable keepalive\n    -P, --disable-post         Disable POST queries\n    -h, --help                 Prints help information\n    -V, --version              Prints version information\n\nOPTIONS:\n    -E, --err-ttl \u003cerr_ttl\u003e                          TTL for errors, in seconds [default: 2]\n    -H, --hostname \u003chostname\u003e                        Host name (not IP address) DoH clients will use to connect\n    -l, --listen-address \u003clisten_address\u003e            Address to listen to [default: 127.0.0.1:3000]\n    -b, --local-bind-address \u003clocal_bind_address\u003e    Address to connect from\n    -c, --max-clients \u003cmax_clients\u003e                  Maximum number of simultaneous clients [default: 512]\n    -C, --max-concurrent \u003cmax_concurrent\u003e            Maximum number of concurrent requests per client [default: 16]\n    -X, --max-ttl \u003cmax_ttl\u003e                          Maximum TTL, in seconds [default: 604800]\n    -T, --min-ttl \u003cmin_ttl\u003e                          Minimum TTL, in seconds [default: 10]\n    -p, --path \u003cpath\u003e                                URI path [default: /dns-query]\n    -g, --public-address \u003cpublic_address\u003e            External IP address DoH clients will connect to\n    -j, --public-port \u003cpublic_port\u003e                  External port DoH clients will connect to, if not 443\n    -u, --server-address \u003cserver_address\u003e            Address to connect to [default: 9.9.9.9:53]\n    -t, --timeout \u003ctimeout\u003e                          Timeout, in seconds [default: 10]\n    -I, --tls-cert-key-path \u003ctls_cert_key_path\u003e\n            Path to the PEM-encoded secret keys (only required for built-in TLS)\n\n    -i, --tls-cert-path \u003ctls_cert_path\u003e\n            Path to the PEM/PKCS#8-encoded certificates (only required for built-in TLS)\n```\n\nExample command-line:\n\n```sh\ndoh-proxy -H 'doh.example.com' -u 127.0.0.1:53 -g 233.252.0.5\n```\n\nHere, `doh.example.com` is the host name (which should match a name included in the TLS certificate), `127.0.0.1:53` is the address of the DNS resolver, and `233.252.0.5` is the public IP address of the DoH server.\n\n## HTTP/2 and HTTP/3 termination\n\nThe recommended way to use `doh-proxy` is to use a TLS termination proxy (such as [hitch](https://github.com/varnish/hitch) or [relayd](https://man.openbsd.org/relayd.8)), a CDN or a web server with proxying abilities as a front-end.\n\nThat way, the DoH service can be exposed as a virtual host, sharing the same IP addresses as existing websites.\n\nIf `doh-proxy` and the HTTP/2 (/ HTTP/3) front-end run on the same host, using the HTTP protocol to communicate between both is fine.\n\nIf both are on distinct networks, such as when using a CDN, `doh-proxy` can handle HTTPS requests, provided that it was compiled with the `tls` feature.\n\nThe certificates and private keys must be encoded in PEM/PKCS#8 format. They can be stored in the same file.\n\nIf you are using ECDSA certificates and ECDSA private keys start with `-----BEGIN EC PRIVATE KEY-----` and not `-----BEGIN PRIVATE KEY-----`, convert them to PKCS#8 with (in this example, `example.key` is the original file):\n\n```sh\nopenssl pkcs8 -topk8 -nocrypt -in example.key -out example.pkcs8.pem\n```\n\nIn order to enable built-in HTTPS support, add the `--tls-cert-path` option to specify the location of the certificates file, as well as the private keys file using `--tls-cert-key-path`.\n\nOnce HTTPS is enabled, HTTP connections will not be accepted.\n\nA sample self-signed certificate [`localhost.pem`](https://github.com/jedisct1/doh-server/raw/master/localhost.pem) can be used for testing.\nThe file also includes the private key.\n\n[`acme.sh`](https://github.com/acmesh-official/acme.sh) can be used to create and update TLS certificates using Let's Encrypt and other ACME-compliant providers. If you are using it to create ECDSA keys, see above for converting the secret key into PKCS#8.\n\nThe certificates path must be set to the full certificates chain (`fullchain.cer`) and the key path to the secret keys (the `.key` file):\n\n```sh\ndoh-proxy -i /path/to/fullchain.cer -I /path/to/domain.key ...\n```\n\nOnce started, `doh-proxy` automatically reloads the certificates as they change; there is no need to restart the server.\n\nIf clients are getting the `x509: certificate signed by unknown authority` error, double check that the certificate file is the full chain, not the other `.cer` file.\n\n## Accepting both DNSCrypt and DoH connections on port 443\n\nDNSCrypt is an alternative encrypted DNS protocol that is faster and more lightweight than DoH.\n\nBoth DNSCrypt and DoH connections can be accepted on the same TCP port using [Encrypted DNS Server](https://github.com/jedisct1/encrypted-dns-server).\n\nEncrypted DNS Server forwards DoH queries to Nginx or `doh-proxy` when a TLS connection is detected, or directly responds to DNSCrypt queries.\n\nIt also provides DNS caching, server-side filtering, metrics, and TCP connection reuse in order to mitigate exhaustion attacks.\n\nUnless the front-end is a CDN, an ideal setup is to use `doh-proxy` behind `Encrypted DNS Server`.\n\n## Oblivious DoH (ODoH)\n\nOblivious DoH is similar to Anonymized DNSCrypt, but for DoH. It requires relays, but also upstream DoH servers that support the protocol.\n\nThis proxy supports ODoH termination (not relaying) out of the box.\n\nHowever, ephemeral keys are currently only stored in memory. In a load-balanced configuration, sticky sessions must be used.\n\nCurrently available ODoH relays only use `POST` queries.\nSo, `POST` queries have been disabled for regular DoH queries, accepting them is required to be compatible with ODoH relays.\n\nThis can be achieved with the `--allow-odoh-post` command-line switch.\n\n## Operational recommendations\n\n* DoH can be easily detected and blocked using SNI inspection. As a mitigation, DoH endpoints should preferably share the same virtual host as existing, popular websites, rather than being on dedicated virtual hosts.\n* When using DoH, DNS stamps should include a resolver IP address in order to remove a dependency on non-encrypted, non-authenticated, easy-to-block resolvers.\n* Unlike DNSCrypt where users must explicitly trust a DNS server's public key, the security of DoH relies on traditional public Certificate Authorities. Additional root certificates (required by governments, security software, enterprise gateways) installed on a client immediately make DoH vulnerable to MITM. In order to prevent this, DNS stamps should include the hash of the parent certificate.\n* TLS certificates are tied to host names. But domains expire, get reassigned and switch hands all the time. If a domain originally used for a DoH service gets a new, possibly malicious owner, clients still configured to use the service will blindly keep trusting it if the CA is the same. As a mitigation, the CA should sign an intermediate certificate (the only one present in the stamp), itself used to sign the name used by the DoH server. While commercial CAs offer this, Let's Encrypt currently doesn't.\n* Make sure that the front-end supports at least HTTP/2 and TLS 1.3.\n* Internal DoH servers still require TLS certificates. So, if you are planning to deploy an internal server, you need to set up an internal CA, or add self-signed certificates to every single client.\n\n## Example usage with `encrypted-dns-server`\n\nAdd the following section to the configuration file:\n\n```toml\n[tls]\nupstream_addr = \"127.0.0.1:3000\"\n```\n\n## Example usage with `nginx`\n\nIn an existing `server`, a `/dns-query` endpoint can be exposed that way:\n\n```text\nlocation /dns-query {\n  proxy_pass http://127.0.0.1:3000;\n}\n```\n\nThis example assumes that the DoH proxy is listening locally to port `3000`.\n\nHTTP caching can be added (see the `proxy_cache_path` and `proxy_cache` directives in the Nginx documentation), but be aware that a DoH server will quickly create a gigantic amount of files.\n\n## DNS Stamp and certificate hashes\n\nUse the online [DNS stamp calculator](https://dnscrypt.info/stamps/) to compute the stamp for your server.\n\nAdd it to the `[static]` section of [`dnscrypt-proxy`](https://github.com/DNSCrypt/dnscrypt-proxy) and check that everything works as expected.\n\nThen, start `dnscrypt-proxy` with the `-show-certs` command-line flag to print the hashes for your certificate chain.\n\nHere is an example output:\n\n```text\n[NOTICE] Advertised cert: [CN=dohtrial.att.net,O=AT\u0026T Services\\, Inc.,L=Dallas,ST=Texas,C=US] [f679e8451940f06141854dc94e1eb79fa5e04463c15b88f3b392da793c16c353]\n[NOTICE] Advertised cert: [CN=DigiCert Global CA G2,O=DigiCert Inc,C=US] [f61e576877da9650294cccb5f96c75fcb71bda1bbc4646367c4ebeda89d7318f]\n```\n\nThe first printed certificate is the certificate of the server itself. The next line is the one that signed that certificate. As you keep going down, you are getting closer to the certificate authority.\n\nUnless you are using intermediate certificates, your safest option is probably to include the last printed hash certificate in your DNS stamp.\n\nGo back to the online DNS stamp calculator, and copy\u0026paste the hash (in this example: `f61e576877da9650294cccb5f96c75fcb71bda1bbc4646367c4ebeda89d7318f`).\n\nIf you are using Let's Encrypt, the last line is likely to be:\n\n```text\nAdvertised cert: [CN=Let's Encrypt Authority R3,O=Let's Encrypt,C=US] [444ebd67bb83f8807b3921e938ac9178b882bd50aadb11231f044cf5f08df7ce]\n```\n\nThere you have it. Your certificate hash is `444ebd67bb83f8807b3921e938ac9178b882bd50aadb11231f044cf5f08df7ce`.\n\nThis [Go code snippet](https://gist.github.com/d6cb41742a1ceb54d48cc286f3d5c5fa) can also compute the hash of certificates given a `.der` file.\n\n### Common certificate hashes\n\n* Let's Encrypt E1:\n  * `cc1060d39c8329b62b6fbc7d0d6df9309869b981e7e6392d5cd8fa408f4d80e6`\n* Let's Encrypt R3:\n  * `444ebd67bb83f8807b3921e938ac9178b882bd50aadb11231f044cf5f08df7ce`\n* Let's Encrypt R10:\n  * `e644ba6963e335fe765cb9976b12b10eb54294b42477764ccb3a3acca3acb2fc`\n* ZeroSSL:\n  * `9a3a34f727deb9bca51003d9ce9c39f8f27dd9c5242901c2bab1a44e635a0219`\n\n## Clients\n\n`doh-proxy` can be used with [dnscrypt-proxy](https://github.com/DNSCrypt/dnscrypt-proxy) as a client.\n\n`doh-proxy` is used in production for the `doh.crypto.sx` public DNS resolver and many others.\n\nAn extensive list of public DoH servers can be found here: [public encrypted DNS servers](https://github.com/DNSCrypt/dnscrypt-resolvers/blob/master/v3/public-resolvers.md).\n","funding_links":["https://opencollective.com/dnscrypt"],"categories":["Rust","server"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FDNSCrypt%2Fdoh-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FDNSCrypt%2Fdoh-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FDNSCrypt%2Fdoh-server/lists"}