{"id":16776352,"url":"https://github.com/ameshkov/dnscrypt","last_synced_at":"2025-04-04T20:12:51.631Z","repository":{"id":47444544,"uuid":"162045034","full_name":"ameshkov/dnscrypt","owner":"ameshkov","description":"DNSCrypt v2 protocol implementation + a command-line tool","archived":false,"fork":false,"pushed_at":"2024-03-15T12:37:50.000Z","size":317,"stargazers_count":74,"open_issues_count":7,"forks_count":14,"subscribers_count":6,"default_branch":"master","last_synced_at":"2024-10-14T07:09:39.153Z","etag":null,"topics":["dns","dnscrypt","go"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"unlicense","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ameshkov.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-12-16T22:02:03.000Z","updated_at":"2024-09-06T00:14:34.000Z","dependencies_parsed_at":"2024-03-15T13:34:53.783Z","dependency_job_id":"4fce66a7-21c0-4f4e-9e19-321571ac3758","html_url":"https://github.com/ameshkov/dnscrypt","commit_stats":null,"previous_names":[],"tags_count":25,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ameshkov%2Fdnscrypt","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ameshkov%2Fdnscrypt/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ameshkov%2Fdnscrypt/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ameshkov%2Fdnscrypt/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ameshkov","download_url":"https://codeload.github.com/ameshkov/dnscrypt/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247242681,"owners_count":20907134,"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","go"],"created_at":"2024-10-13T07:09:42.453Z","updated_at":"2025-04-04T20:12:51.603Z","avatar_url":"https://github.com/ameshkov.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Code Coverage](https://img.shields.io/codecov/c/github/ameshkov/dnscrypt/master.svg)](https://codecov.io/github/ameshkov/dnscrypt?branch=master)\n[![Go Report Card](https://goreportcard.com/badge/github.com/ameshkov/dnscrypt)](https://goreportcard.com/report/ameshkov/dnscrypt)\n[![Go Doc](https://godoc.org/github.com/ameshkov/dnscrypt?status.svg)](https://godoc.org/github.com/ameshkov/dnscrypt)\n\n# DNSCrypt Go\n\nGolang-implementation of the [DNSCrypt v2 protocol](https://dnscrypt.info/protocol).\n\nThis repo includes everything you need to work with DNSCrypt. You can run your own resolver, make DNS lookups to other DNSCrypt resolvers, and you can use it as a library in your own projects.\n\n* [Command-line tool](#commandline)\n    * [How to install](#install)\n    * [How to configure](#configure)\n      * [Converting dnscrypt-wrapper configuration](#convertfromwrapper)\n    * [Running a server](#runningserver)\n    * [Making lookups](#lookup)\n* [Programming interface](#api)\n    * [Client](#client)\n    * [Server](#server)\n\n## \u003ca id=\"commandline\"\u003e\u003c/a\u003e Command-line tool\n\n`dnscrypt` is a helper tool that can work as a DNSCrypt client or server.\n\nPlease note, that even though this tool can work as a server, it's purpose is merely testing. Use [dnsproxy](https://github.com/AdguardTeam/dnsproxy) or [AdGuard Home](https://github.com/AdguardTeam/AdGuardHome) for real-life purposes.\n\n\n### \u003ca id=\"install\"\u003e\u003c/a\u003e How to install\n\nDownload and unpack an archive for your platform from the [latest release](https://github.com/ameshkov/dnscrypt/releases).\n\nHomebrew:\n```\nbrew install ameshkov/tap/dnscrypt\n```\n\n### \u003ca id=\"configure\"\u003e\u003c/a\u003e How to configure\n\nGenerate a configuration file for running a DNSCrypt server:\n\n```\n./dnscrypt generate\n\n[generate command options]\n      -p, --provider-name= DNSCrypt provider name. Param is required.\n      -o, --out=           Path to the resulting config file. Param is required.\n      -k, --private-key=   Private key (hex-encoded)\n      -t, --ttl=           Certificate time-to-live (seconds)\n```\n\nIt will generate a configuration file that looks like this:\n\n```yaml\nprovider_name: 2.dnscrypt-cert.example.org\npublic_key: F11DDBCC4817E543845FDDD4CB881849B64226F3DE397625669D87B919BC4FB0\nprivate_key: 5752095FFA56D963569951AFE70FE1690F378D13D8AD6F8054DFAA100907F8B6F11DDBCC4817E543845FDDD4CB881849B64226F3DE397625669D87B919BC4FB0\nresolver_secret: 9E46E79FEB3AB3D45F4EB3EA957DEAF5D9639A0179F1850AFABA7E58F87C74C4\nresolver_public: 9327C5E64783E19C339BD6B680A56DB85521CC6E4E0CA5DF5274E2D3CE026C6B\nes_version: 1\ncertificate_ttl: 0s\n```\n\n* `provider_name` - DNSCrypt resolver name.\n* `public_key`, `private_key` - keypair that is used by the DNSCrypt resolver to sign the certificate.\n* `resolver_secret`, `resolver_public` - keypair that is used by the DNSCrypt resolver to encrypt and decrypt messages.\n* `es_version` - crypto to use. Can be `1` (XSalsa20Poly1305) or `2` (XChacha20Poly1305).\n* `certificate_ttl` - certificate time-to-live. By default it's set to `0` and in this case 1-year cert is generated. The certificate is generated on `dnscrypt` start-up and it will only be valid for the specified amount of time. You should periodically restart `dnscrypt` to rotate the cert. \n\n#### \u003ca id=\"convertfromwrapper\"\u003e\u003c/a\u003e Converting [dnscrypt-wrapper](https://github.com/cofyc/dnscrypt-wrapper) configuration\n\nAlso, to create a configuration, you can use the keys generated using [dnscrypt-wrapper](https://github.com/cofyc/dnscrypt-wrapper) by running the command:\n\n```\n./dnscrypt convert-dnscrypt-wrapper\n\n[convert-dnscrypt-wrapper command options]\n      -p, --private-key=     Path to the DNSCrypt resolver private key file that is used for signing certificates. Param is required.\n      -r, --resolver-secret= Path to the Short-term privacy key file for encrypting/decrypting DNS queries. If not specified, resolver_secret and resolver_public will be randomly generated.\n      -n, --provider-name=   DNSCrypt provider name. Param is required.\n      -o, --out=             Path to the resulting config file. Param is required.\n      -t, --ttl=             Certificate time-to-live (seconds)\n```\n\n\n### \u003ca id=\"runningserver\"\u003e\u003c/a\u003e Running a server\n\nThis configuration file can be used to run a DNSCrypt forwarding server:\n\n```\n./dnscrypt server \n\n[server command options]\n      -c, --config=  Path to the DNSCrypt configuration file. Param is required.\n      -f, --forward= Forwards DNS queries to the specified address (default: 94.140.14.140:53)\n      -l, --listen=  Listening addresses (default: 0.0.0.0)\n      -p, --port=    Listening ports (default: 443)\n```\n\nNow you can go to https://dnscrypt.info/stamps and use `provider_name` and `public_key` from this configuration to generate a DNS stamp. Here's how it looks like for a server running on `127.0.0.1:443`:\n\n```\nsdns://AQcAAAAAAAAADTEyNy4wLjAuMTo0NDMg8R3bzEgX5UOEX93Uy4gYSbZCJvPeOXYlZp2HuRm8T7AbMi5kbnNjcnlwdC1jZXJ0LmV4YW1wbGUub3Jn\n```\n\n### \u003ca id=\"lookup\"\u003e\u003c/a\u003e Making lookups\n\nYou can use that stamp to send a DNSCrypt request to your server:\n\n```\n./dnscrypt lookup-stamp\n\n[lookup-stamp command options]\n      -n, --network= network type (tcp/udp) (default: udp)\n      -s, --stamp=   DNSCrypt resolver stamp. Param is required.\n      -d, --domain=  Domain to resolve. Param is required.\n      -t, --type=    DNS query type (default: A)\n```\n\nYou can also send a DNSCrypt request using a command that does not require stamps:\n\n```\n./dnscrypt lookup \\\n\n[lookup command options]\n      -n, --network=       network type (tcp/udp) (default: udp)\n      -p, --provider-name= DNSCrypt resolver provider name. Param is required.\n      -k, --public-key=    DNSCrypt resolver public key. Param is required.\n      -a, --addr=          Resolver address (IP[:port]). By default, the port is 443. Param is required.\n      -d, --domain=        Domain to resolve. Param is required.\n      -t, --type=          DNS query type (default: A)\n```\n\n## \u003ca id=\"api\"\u003e\u003c/a\u003e Programming interface\n\n### \u003ca id=\"client\"\u003e\u003c/a\u003e Client\n\n```go\nimport (\n    \"github.com/ameshkov/dnscrypt/v2\"\n)\n\n// AdGuard DNS stamp\nstampStr := \"sdns://AQMAAAAAAAAAETk0LjE0MC4xNC4xNDo1NDQzINErR_JS3PLCu_iZEIbq95zkSV2LFsigxDIuUso_OQhzIjIuZG5zY3J5cHQuZGVmYXVsdC5uczEuYWRndWFyZC5jb20\"\n\n// Initializing the DNSCrypt client\nc := dnscrypt.Client{Net: \"udp\", Timeout: 10 * time.Second}\n\n// Fetching and validating the server certificate\nresolverInfo, err := c.Dial(stampStr)\nif err != nil {\n    return err\n}\n\n// Create a DNS request\nreq := dns.Msg{}\nreq.Id = dns.Id()\nreq.RecursionDesired = true\nreq.Question = []dns.Question{\n    {\n        Name: \"google-public-dns-a.google.com.\",\n        Qtype: dns.TypeA,\n        Qclass: dns.ClassINET,\n    },\n}\n\n// Get the DNS response\nreply, err := c.Exchange(\u0026req, resolverInfo)\n```\n\n## \u003ca id=\"server\"\u003e\u003c/a\u003e Server\n\n```go\nimport (\n    \"github.com/ameshkov/dnscrypt/v2\"\n)\n\n// Prepare the test DNSCrypt server config\nrc, err := dnscrypt.GenerateResolverConfig(\"example.org\", nil)\nif err != nil {\n    return err\n}\n\ncert, err := rc.CreateCert()\nif err != nil {\n    return err\n}\n\ns := \u0026dnscrypt.Server{\n    ProviderName: rc.ProviderName,\n    ResolverCert: cert,\n    Handler:      dnscrypt.DefaultHandler,\n}\n\n// Prepare TCP listener\ntcpConn, err := net.ListenTCP(\"tcp\", \u0026net.TCPAddr{IP: net.IPv4zero, Port: 443})\nif err != nil {\n    return err\n}\n\n// Prepare UDP listener\nudpConn, err := net.ListenUDP(\"udp\", \u0026net.UDPAddr{IP: net.IPv4zero, Port: 443})\nif err != nil {\n    return err\n}\n\n// Start the server\ngo s.ServeUDP(udpConn)\ngo s.ServeTCP(tcpConn)\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fameshkov%2Fdnscrypt","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fameshkov%2Fdnscrypt","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fameshkov%2Fdnscrypt/lists"}