Security

Security Model

ResolveDB separates DNS answer integrity, transport confidentiality, query authorization, API authorization, and application payload confidentiality. These controls solve different problems and should not be treated as interchangeable.

DNSSEC

resolvedb.net is DNSSEC-signed in production. The fleet uses an ECDSA P-256 KSK and an Ed25519 ZSK, persists both keys, and refreshes RRSIGs in process. Negative answers use DNSSEC-signed NSEC black lies.

dig +dnssec get.quebec.weather.public.v1.resolvedb.net TXT

When querying through a validating recursive resolver, the ad flag indicates that the resolver validated the chain. An RRSIG in a response is not by itself proof that the client performed validation.

Query Privacy

UDP, TCP, DoH, and DoT use the same ResolveDB authorization gate. Plaintext DNS is accepted, but the entire qname is visible to network observers. This matters for private records because the qname contains a bearer credential.

kdig @dot.resolvedb.io +tls-ca +tls-hostname=dot.resolvedb.io \
  get.quebec.weather.public.v1.resolvedb.net TXT

Private Hosted Records

Hosted namespaces are private by default. Mint an opaque query token under the namespace API:

curl -X POST https://api.resolvedb.com/api/v1/namespaces/NAMESPACE_ID/query_tokens \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"production-reader","expires_in_days":30}'

The plaintext rdbq token is returned only once; Rails stores only its SHA-256 digest. The token is bound to one namespace, expires, can be revoked, and is placed in the single query params label:

get.auth-rdbq<52>.config.acme-catalog.v1.resolvedb.net

Missing, expired, revoked, wrong-namespace, and unknown-namespace requests fail closed with DNS REFUSED. Successful private answers have TTL 0, directing compliant recursive caches not to retain them; intermediaries can apply brief floors or stale-serving policy.

Use DoH or DoT for every qname containing auth-. Treat the complete qname as a secret in logs, shell history, traces, and error reports.

REST API Keys

REST API keys are independent from DNS query tokens. API-key scopes can limit:

• Operations to read, write, or both
• Access to an explicit list of namespaces

GET and HEAD require read; mutating requests require write. Record, namespace, query-token, query-log, usage, and webhook endpoints apply the namespace allowlist. API-key principals cannot manage API keys, two-factor authentication, organizations, customer sessions, billing, passkeys, or account profile and verification flows.

{
  "operations": ["read", "write"],
  "namespaces": ["acme-catalog"]
}

API key tokens are returned only at creation and stored as SHA-256 digests.

Authentication Boundaries

Production DNS authorization supports opaque rdbq namespace query tokens. Rails customer-session JWTs and scoped API keys authenticate REST requests only; neither belongs in a DNS qname. JWT-label support exists as library code but is not wired to the production authoritative DNS or DoH request paths.

Payload Confidentiality

ResolveDB does not automatically encrypt customer record values. Encrypt sensitive content in the application before Base64-encoding and storing it, and keep encryption keys outside ResolveDB. AES-256-GCM is a suitable authenticated encryption construction when nonces are generated uniquely for each key.

DNSSEC authenticates an answer but does not make it confidential. DoH and DoT encrypt the network hop but do not provide end-to-end application encryption.

Dataset Attestations

Attested datasets have two distinct signature layers:

• DNSSEC authenticates the DNS response.
• A payload-level Ed25519 operator attestation signs the canonical dataset manifest.

Hosted customer records do not automatically receive the dataset attestation signature.

Best Practices

1. Use DoH or DoT for every authenticated DNS query.
2. Store API keys and rdbq tokens in a secret manager.
3. Scope API keys to the minimum operations and namespaces required.
4. Use short query-token expirations and revoke unused tokens.
5. Redact complete authenticated qnames from logs and telemetry.
6. Encrypt sensitive record values before sending them to ResolveDB.
7. Validate DNSSEC when answer authenticity matters.

Next Steps

• Quickstart - Create a namespace, record, and query token
• UQRP Protocol - Query and response formats
• DNS Access Methods - DoH and DoT configuration