{"id":21464227,"url":"https://github.com/shuque/adns_server","last_synced_at":"2025-07-15T03:32:35.327Z","repository":{"id":143298399,"uuid":"158060783","full_name":"shuque/adns_server","owner":"shuque","description":"An authoritative DNS server","archived":false,"fork":false,"pushed_at":"2024-07-21T00:40:17.000Z","size":94,"stargazers_count":11,"open_issues_count":1,"forks_count":3,"subscribers_count":4,"default_branch":"master","last_synced_at":"2024-07-21T20:05:35.479Z","etag":null,"topics":["authoritative","compact","deleg","denial","dns","dnssec","nsec","nsec3","nxname","server"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/shuque.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"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}},"created_at":"2018-11-18T07:41:00.000Z","updated_at":"2024-07-20T21:46:47.000Z","dependencies_parsed_at":"2024-02-03T22:19:18.921Z","dependency_job_id":"9e34e3d7-a915-4108-aebb-b5dbfc161ba1","html_url":"https://github.com/shuque/adns_server","commit_stats":null,"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shuque%2Fadns_server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shuque%2Fadns_server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shuque%2Fadns_server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shuque%2Fadns_server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/shuque","download_url":"https://codeload.github.com/shuque/adns_server/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":226017327,"owners_count":17560465,"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":["authoritative","compact","deleg","denial","dns","dnssec","nsec","nsec3","nxname","server"],"created_at":"2024-11-23T07:30:23.847Z","updated_at":"2025-07-15T03:32:35.314Z","avatar_url":"https://github.com/shuque.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# adns_server\n\nThis is a fully functional authoritative DNS server written in Python.\nIt serves DNS zones in master file format. I mainly use it for functional\ntesting and prototyping new protocol features. It is not intended for\nproduction use or high performance applications.\n\n## DNSSEC Support\n\nThe server implements the DNSSEC protocol extensions. It can serve\npre-signed master file format zones, both NSEC and NSEC3 (e.g. zones\ngenerated with an offline signer like BIND's dnssec-signzone). It can\nalso perform online signing with a combined signing key, using the\n[Compact Denial of Existence](https://datatracker.ietf.org/doc/draft-ietf-dnsop-compact-denial-of-existence/) method, using either NSEC or NSEC3, and can also do traditional NSEC3\nWhite Lies.\n\nThe 'dnssec: true' parameter must be specified in the configuration file\nfor signed zones. The 'dynamic_signing: true' and 'private_key: /path/to/privatekey.pem'\noptions are needed for online signing.\n\n## DELEG Support\n\nThe server can support delivery of the\n[experimental DELEG record](https://github.com/fl1ger/deleg) in referral\nresponses, using the private RR type, 65287. DELEG is a newly proposed\nmechanism to support extensible delegation capabilities in the DNS, and\nis planned to (eventually) replace both the DS and parent-side NS records.\nA per zone configuration flag \"deleg_enabled\" needs to be set to true to use\nthis feature.\n\nFor signed zones, it can currently only be used with the online signing modes.\nThis is because most tools that generate pre-signed zones won't be able to\ndeal with a gratuitous \"DELEG\" record contained in the input. If they accept it,\nthey will likely treat it as non-authoritative \"glue\" and not sign it. And a\ntraditional authoritative server will need additional logic to return it in a\nreferral response. This program will recognize the DELEG record and will place\nit in the referral of the corresponding delegation along with a dynamically\ngenerated signature. (In the future, I may write my own modified zone signer,\nafter which the program could also serve pre-signed zones with DELEG).\n\nThis program also supports returning DELEG from unsigned zones, as well as\nDELEG referrals to subzones that aren't signed. The rules for processing\nsuch referrals on the resolver side need to be very carefully spelled out\nin the specification to avoid security problems. For example, if a secure\ntransport capability (e.g. DOT, DOH, DOQ) for a delegated zone needs to be\nobtained without DNSSEC, then an alternate means of authenticating the\nchannel to the server needs to be used (e.g. the delegating parent zone would\nneed to have pre-configured DNS over TLS/DoH/QUIC and require Internet PKI\nauthentication of its server certificates).\n\nDELEG supports off-path authentication of a child zone's secure entry point\nDNSKEY(s). For this mode of operation, it would be prudent for a validating\nresolver to require DNSSEC in the parent zone. Otherwise it would involve\neither leap of faith authentication, or authenticating the transport channel\nto the delegating server in some way, e.g. with the Internet PKI, which would\nallow any Public CA to compromise DNSSEC authentication.\n\nWhile the protocol details are still being developed, here is a quick summary\nof the behavior as currently implemented in this program for signed zones: the\nDELEG record is a delegation record that appears in the parent zone, whose\nowner name matches the name of the delegated zone, similar to DS, and like the\nDS record, it is authoritative in the parent. When a delegation contains both\na DS and DELEG record set, then both are returned in the referral response with\ntheir signatures. When only one of them is present, it is returned along with\nthe NSEC or NSEC3 record set matching the delegated name (to prove that the other\ndoesn't exist). Confirming the existence of DELEG capabilities will likely also\nneed a secure signal via a new DS digest type, or a new DNSKEY flag. Those\nsignals can be loaded from zone file data.\n\n\n### Pre-requisites\n\n* Python 3\n* Python Cryptography module\n* The dnspython module, version 2.3 or greater\n* sortedcontainers\n* PyYAML module\n* siphash module (for DNS cookie support)\n* cachetools (for online signature cache)\n\n### Installation\n\nTo install from a local copy of this repository:\n\n```\npip3 install .\n```\n\nTo install from the git repo directly:\n\n```\npip3 install git+https://github.com/shuque/adns_server.git@v0.5.2\n```\n\n### Usage\n\n```\n$ adns_server.py -h\nReading config from: adnsconfig.yaml\nadns_server.py version 0.5.2\nUsage: adns_server.py [\u003cOptions\u003e]\n\nOptions:\n       -h:        Print usage string\n       -c file:   Configuration file (default 'adnsconfig.yaml')\n       -d:        Turn on debugging\n       -p N:      Listen on port N (default 53)\n       -s A:      Bind to server address A (default wildcard address)\n       -u uname:  Drop privileges to UID of specified username\n                  (if server started running as root)\n       -g group:  Drop provileges to GID of specified groupname\n                  (if server started running as root)\n       -4:        Use IPv4 only\n       -6:        Use IPv6 only\n       -f:        Remain attached to foreground (default don't)\n       -e N:      Max EDNS bufsize in octets for responses we send out.\n                  (-e 0 will disable EDNS support)\n\nNote: a configuration file that minimally specifies the zones to load\nmust be present.\n```\n\n### Configuration file\n\nAn example configuration file looks like the following. At a minimum\nit needs so specify the \"zones:\" section, defining the zone names and\nzone files for each zone that the server will serve.\n\nThe configuration file supports additional options beyond what can\nbe specified via command line switches. Such as contents of the NSID\noption, DNSSEC parameters, etc.\n\n```\nconfig:\n  port: 5309\n  user: \"named\"\n  group: \"named\"\n  edns: 1432\n  minimal_any: false\n  nsid: \"dnstest.example.com\"\nzones:\n  - name: \"example.com\"\n    file: \"zonefile.example\"\n  - name: \"signedzone.com\"\n    dnssec: true\n    file: \"zonefile.signedzone\"\n  - name \"onlinesigning.com\"\n    dnssec: true\n    file \"zonefile.onlinesigning\"\n    dynamic_signing: true\n    private_key: \"/path/to/privatekey.pem\"\n```\n\n### Key Generation for Online Signing\n\nThis repo also includes a small script, genkey.pl, to help generate\nDNSSEC keys used for online signing configurations.\n\n```\n$ ./genkey.py -h\nusage: genkey.py [-h] [-a N] [-f N] zone\n\npositional arguments:\n  zone        DNS zone name\n\noptional arguments:\n  -h, --help  show this help message and exit\n  -a N        DNSSEC algorithm number (default: 13)\n  -f N        Value of DNSKEY flags field (default: 257)\n  ```\n\n  An example usage to generate an ECDSA NIST P256 (algorithm 13)\n  key for example.com follows.\n\n  ```\n  $ ./genkey.py example.com\n### Private Key file contents:\n-----BEGIN PRIVATE KEY-----\nXXXXXXX+++++++++++++++++++++REDACTEDKEY+++++++++++++++++XXXXXXXX\nXXXXXXX+++++++++++++++++++++REDACTEDKEY+++++++++++++++++XXXXXXXX\nXXXXXXX+++++++++++++++++++++REDACTEDKEY+++++++++XXXXXXXX\n-----END PRIVATE KEY-----\n\n### DNSKEY RDATA:\n257 3 13 oBQvOkuVPdp7Wes6EcWra7UlyI3u9EeM nRd79CSmq4ggIobc7oVPxTq3NhespdTC hZ4gArRqrftxjsUxjP0dOQ==\n### DNSKEY keytag: 56959\n\n### DNSKEY RRset:\nexample.com. 7200 IN DNSKEY 257 3 13 oBQvOkuVPdp7Wes6EcWra7UlyI3u9EeM nRd79CSmq4ggIobc7oVPxTq3NhespdTC hZ4gArRqrftxjsUxjP0dOQ==\n\n### DS record\n56959 13 2 ac2c59edcb0d9021d6898e2824cd63fd67c3d8c0b6da69943121b5b5263bdbad\n```","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshuque%2Fadns_server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fshuque%2Fadns_server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshuque%2Fadns_server/lists"}