po4yka/RIPDPI / .agents/skills/encrypted-dns
encrypted-dns
VerifiedReference for the ripdpi-dns-resolver crate: DoH/DoT/DNSCrypt/DoQ/ODoH, health scoring, bootstrap IPs, tamper diagnostics. Use when touching encrypted DNS resolution, failover, or tamper detection.
Supported protocols
| Protocol | RFC/Spec | Transport | Default port | TLS required |
|---|---|---|---|---|
| DoH | RFC 8484 | HTTPS POST with application/dns-message | 443 | Yes (HTTPS) |
| DoT | RFC 7858 | TCP + TLS, length-prefixed DNS wire format | 853 | Yes |
| DNSCrypt | dnscrypt.info spec | TCP, XSalsa20Poly1305 (ChaChaBox) | 443 | No (own crypto) |
| DoQ | RFC 9250 | QUIC bidirectional streams, length-prefixed | 853 | Yes (QUIC TLS) |
| ODoH | RFC 9230 | HTTPS POST with application/oblivious-dns-message, HPKE-encrypted payload | 443 | Yes (HTTPS + HPKE) |
All protocols use standard DNS wire format (RFC 1035) for the query and response payloads. The protocol layer only differs in how the wire bytes are transported and encrypted.
DoQ does not support SOCKS5 transport because SOCKS5 is TCP-only; the
resolver returns EncryptedDnsError::Request if you try.
Architecture
The crate (native/rust/crates/ripdpi-dns-resolver) is organized by concern, one
top-level <name>.rs module file plus a <name>/ directory of submodules for
each area. List the current layout rather than trusting a snapshot:
find native/rust/crates/ripdpi-dns-resolver/src -name '*.rs' | sort
At a high level:
pool.rs+pool/{builder,exchange,fallback_order,health_updates,ranking,tests}.rs--ResolverPool/ResolverPoolBuilder, the LRU fallback cache, and health-based rotation.resolver.rs+resolver/{connection,dispatch,dnscrypt_transport,doh,doq,doq_tests,dot,state,tcp}.rs--EncryptedDnsResolver, protocol dispatch (dispatch.rs), and per-protocol exchange logic;resolver/doh/further splits the manual HTTP/1.1 DoH path into request/response/chunked-body helpers.health.rs+health/{oracle_policy,registry,score,snapshot,tests}.rs--HealthRegistry, EWMA scoring.transport.rs+transport/{client,framing,normalize,util,wire}.rs-- shared TLS config, endpoint normalization (normalize.rs), DNS wire helpers, andextract_ip_answers().dnscrypt.rs+dnscrypt/{certificate,cipher,framing,identity,padding}.rs-- DNSCrypt crypto.doh_pipeline.rs+doh_pipeline/{builder,cache,https_bindings,ip_candidates,lookup,types}.rs-- higher-level DoH batch-lookup pipeline (DohResolverPipeline) used by the diagnostics/oracle side.https_service_binding.rs+https_service_binding/{cursor,dto,ech,records}.rs-- HTTPS/SVCB record parsing (used by ODoH config discovery and ECH).odoh.rs-- ODoH client-side config resolution and HPKE query/response handling (no submodule split yet).types/--EncryptedDnsProtocol,EncryptedDnsEndpoint,EncryptedDnsError,EncryptedDnsConnectHooks,OdohEndpointConfig, and related public types, re-exported fromlib.rs.tests/{mod,pipeline,pool,https_service_binding}.rs-- integration tests (see Testing patterns below).
Health scoring
HealthRegistry tracks per-endpoint and per-bootstrap-IP health using
exponentially weighted moving averages (EWMA).
Score model (health/score.rs:HealthScore):
ewma_success_rate: decays toward 0.5 (neutral prior) with configurable half-life (default 60s viaDEFAULT_HEALTH_HALF_LIFEin pool.rs)ewma_latency_ms: decays toward 200ms initial prior- Composite:
success_rate * 0.7 + (1 - latency/2000) * 0.3
How scores influence pool selection (pool/ranking.rs:try_order()):
HealthRegistry::rank_indices()sorts endpoints by composite score (best first)- Cold-start override: if the top-ranked endpoint has zero observations, the
fallback_cachefield (anLruCacheinpool.rs) promotes the most recently successful endpoint to rank 0 - Round-robin injection: every N-th call, the rotation counter promotes a non-top-2 endpoint to position 1, preventing starvation of lower-ranked endpoints that may have recovered
SNI blocking penalty: record_sni_blocked() records failure with a 4000ms
latency penalty, rapidly deprioritizing endpoints whose TLS handshake is being
RST-injected by middlebox DPI equipment.
Bootstrap IP ranking: rank_bootstrap_ips() uses the same EWMA model on
per-IP health data. Both build_doh_client() and connect_direct_tcp_with()
consult this ranking to try the healthiest bootstrap IP first.
Sharing across pool recreations: ResolverPoolBuilder::health_registry()
accepts a pre-existing registry so that dropping and rebuilding a pool preserves
all accumulated health data.
DNSCrypt specifics
DNSCrypt uses its own crypto layer instead of TLS. The crypto implementation
lives in dnscrypt.rs/dnscrypt/, and the exchange logic in
resolver/dnscrypt_transport.rs:exchange_dnscrypt().
Certificate lifecycle (fetch_dnscrypt_certificate() / current_dnscrypt_certificate()):
- Query the provider for
2.dnscrypt-cert.<provider_name>TXT records - Parse the 124-byte certificate (
DNSCRYPT_CERT_SIZE):- Bytes 0-3: magic
DNSC(DNSCRYPT_CERT_MAGIC) - Bytes 4-5: es_version (must be 2 = XSalsa20Poly1305)
- Bytes 8-71: Ed25519 signature over the signed portion (bytes 72-123)
- Bytes 72-103: resolver's X25519 public key
- Bytes 104-111: client_magic (8 bytes, prefixed to every query)
- Bytes 116-119: valid_from (Unix timestamp)
- Bytes 120-123: valid_until (Unix timestamp)
- Bytes 0-3: magic
- Verify Ed25519 signature using the provider's public key (
ring::signature) - Cache in
Mutex<Option<DnsCryptCachedCertificate>>, reuse until 60s before expiry
Query encryption (exchange_dnscrypt_with_session()):
- Generate ephemeral X25519 keypair (
crypto_box::SecretKey) - Build
ChaChaBoxfrom resolver public key + client secret - Generate random 12-byte nonce half (
DNSCRYPT_QUERY_NONCE_HALF) - Pad query to 64-byte blocks (
dnscrypt_pad(): append 0x80 then 0x00s) - Encrypt with ChaChaBox using full 24-byte nonce
- Wrap:
client_magic || client_public_key || nonce_half || ciphertext
Response decryption (decrypt_dnscrypt_response()):
- Verify 8-byte response magic (
DNSCRYPT_RESPONSE_MAGIC) - Extract full 24-byte nonce; verify first 12 bytes match query nonce half
- Decrypt with ChaChaBox, then unpad (
dnscrypt_unpad(): find last 0x80)
ODoH (Oblivious DoH)
Implementation lives in src/odoh.rs (no submodule split) and uses the
odoh-rs crate for the RFC 9230 HPKE encrypt/decrypt/message framing
(ObliviousDoHMessage, encrypt_query(), decrypt_response(), compose(),
parse()). Dispatch is EncryptedDnsResolver::exchange_odoh(), wired from
resolver/dispatch.rs; default port is 443 like DoH.
Config discovery (OdohConfigSource): Bundled and CustomBytes variants
carry pre-fetched config bytes with a retrieval time and TTL; HttpsSvcb
parses the target's HTTPS/SVCB record (key 32769, ODOHCONFIG_SVCB_KEY) via
parse_https_service_bindings() from https_service_binding.rs. HttpsSvcb
config lookup carries an OdohConfigLookupSecurity tag and must be
EncryptedDns; a PlainDns tag returns OdohError::PlaintextConfigLookup
before use, so ODoH config material is never trusted from a plaintext lookup.
Bootstrap problem
When system DNS is poisoned, you cannot resolve the hostname of your encrypted
DNS server (e.g., dns.google) via the poisoned system resolver. The solution
is hardcoded bootstrap IPs in EncryptedDnsEndpoint::bootstrap_ips.
How it works:
normalize_endpoint()enforcesMissingBootstrapIpserror forDirecttransport if no bootstrap IPs are provided- For DoH:
build_doh_client()callsreqwest::ClientBuilder::resolve_to_addrs()to pin the hostname to bootstrap IPs, bypassing system DNS entirely - For DoT/DNSCrypt/DoQ:
connect_direct_tcp_with()iterates bootstrap IPs directly, connecting toSocketAddr::new(ip, port)without any DNS lookup - SOCKS5 transport delegates resolution to the proxy (
socks5h://scheme), bypassing the bootstrap problem entirely
EncryptedDnsConnectHooks: allows the Android VPN layer to inject a custom
DirectTcpConnector (for protect-socket bypass) and DirectUdpBinder (for
DoQ). When a TCP connector hook is set, DoH falls back to manual HTTP/1.1
over the hooked TCP stream (exchange_doh_manually()) instead of reqwest.
DNS tamper detection
The diagnostics runner uses encrypted DNS as a ground-truth oracle to detect DNS tampering by the ISP/middlebox.
Detection flow (native/rust/crates/ripdpi-diagnostics-runner/src/strategy.rs:detect_strategy_probe_dns_tampering()):
- For each target domain, resolve via system DNS (
resolve_addresses()) - Resolve the same domain via encrypted DNS (
resolve_via_encrypted_dns()) - Compare results:
- System returns NXDOMAIN but encrypted returns IPs ->
DnsTampering - System returns different IPs than encrypted ->
DnsTampering - System resolves suspiciously fast ->
is_dns_injection_suspected()heuristic
- System returns NXDOMAIN but encrypted returns IPs ->
- Results feed into
diagnosis.rswhich emitsdns_tamperingdiagnostic codes
Diagnostics DNS helper (ripdpi-diagnostics-dns/src/dns.rs, consumed through ripdpi-diagnostics-runner):
resolve_via_encrypted_dns()creates a one-shotEncryptedDnsResolverwith a preconfigured endpoint and callsexchange_blocking()extract_ip_answers()(re-exported from ripdpi-dns-resolver) parses A/AAAA records from the response bytesbuild_fallback_encrypted_dns_endpoints()indns.rsprovides 3-4 fallback DoH resolvers when the primary fails. Used in bothdetect_strategy_probe_dns_tampering()andrun_dns_probe().
Built-in DNS providers
Default provider and ordering
Default encrypted DNS is AdGuard (changed from Cloudflare). Priority:
AdGuard > DNS.SB > Mullvad > Google IP > Cloudflare IP > Google > Quad9 > Cloudflare.
Defined solely in BuiltInDnsProviders (DnsResolverConfig.kt); the Rust crate
has no equivalent default-ordering constant, it just resolves whatever endpoint
list it is given. Do not silently reorder the built-in providers or change the
default provider unless the user explicitly asks for it -- ordering changes
propagate to EncryptedDnsPathSelection and are
compatibility-sensitive for existing remembered-policy state.
DNS.SB TLS server name
tlsServerName for DNS.SB is "dns.sb" (not "doh.dns.sb"). The DoT cert
at port 853 is only valid for dns.sb; doh.dns.sb causes handshake failures.
Eager DNS failover
VpnEncryptedDnsFailoverController triggers immediately on catastrophic errors
(connection reset, refused, "operation not permitted") via isCatastrophicDnsError(),
skipping the 2-failure threshold for bootstrap-phase queries (<=3 queries attempted).
DNS failure counting
The native tunnel counts bootstrap connection failures in dnsFailuresTotal.
Previously only DNS query failures (after successful connection) were counted;
connection-level failures during bootstrap were silently dropped.
Adding a new DNS protocol
End-to-end walkthrough for adding a hypothetical "DoX" protocol (module paths
reflect the current per-concern split; re-run the find command above if the
layout has moved further since):
-
types/endpoint.rs: Add a
Doq-style variant toEncryptedDnsProtocol, implementas_str()anddefault_port(). Add any protocol-specific fields toEncryptedDnsEndpoint. Add error variants toEncryptedDnsError(types/error.rs) and classify them inkind(). -
transport/normalize.rs: Add a normalization branch in
normalize_endpoint()to validate required fields and fill defaults. If the protocol needs TLS, reusebuild_client_config()fromtransport.rs. -
resolver/dispatch.rs + resolver.rs: Add an
exchange_dox()method onEncryptedDnsResolverand wire it into the protocol dispatch match. If the protocol uses connection reuse, add a variant toPooledConnectionand implementtake_dox_session()/connect_dox_session()following the DoT/DNSCrypt pattern (seeresolver/dot.rs,resolver/dnscrypt_transport.rs). If it needs a persistent client (likequinn::Endpointfor DoQ), add it toResolverInnerinresolver/state.rsand initialize inwith_health(). -
lib.rs: No changes needed unless you add new public types -- the protocol enum variant propagates through existing re-exports.
-
pool.rs: No changes needed --
ResolverPoolis protocol-agnostic. It delegates toEncryptedDnsResolver::exchange_with_metadata(). -
tests/: Add integration tests following the existing patterns in
tests/pool.rs/tests/pipeline.rs:- Spawn a local server (see
DnsCryptTestServer, TLS listener patterns) - Create an endpoint pointing to
127.0.0.1with the local port - Test both success path and error conditions
- Spawn a local server (see
Testing patterns
Integration tests (src/tests/{mod,pipeline,pool,https_service_binding}.rs):
- Local TLS servers using
rcgenself-signed certs +rustls::ServerConfig - Local DNSCrypt servers with test Ed25519 keypairs
turmoilcrate for deterministic network simulation (used forTcpClientStreamtrait)local-network-fixturedev-dependency for network test infrastructure
Unit tests (inline in each module, plus dedicated <module>/tests.rs files
for health/ and pool/):
health/tests.rs: fake clock (advancing_fake_clock()) for deterministic EWMA testingdnscrypt.rs: Ed25519 keypair generation for certificate round-trip testspool/tests.rs: manual fallback cache seeding to test cold-start behavior
Mock resolvers: Tests create EncryptedDnsResolver::with_extra_tls_roots()
pointing to localhost with self-signed certificate DER bytes passed as extra
TLS roots. The EncryptedDnsConnectHooks mechanism allows injecting custom
TCP connectors for test isolation.
Key test helpers:
build_query(name)-> DNS wire-format query bytesbuild_response(query, answer_ip)-> DNS wire-format response bytesDnsCryptTestServer-> full DNSCrypt server with cert generation + crypto
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 193k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 193k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 193k | Updated | Claude CodeCodex | Verified | Install |