Identity and Resolver Credentials

ClearDNS separates internal operational identity from the credential presented to the DNS resolver.

That distinction is important. The internal identifiers organize a policy and its devices. Resolver Credential V1 is a separate wire representation designed specifically for encrypted DNS transport. Neither should be confused with a person's real-world identity.

Identity vocabulary#

A ClearDNS device relationship contains three scopes:

Policy ID#

The Policy ID identifies a ClearDNS policy. It is an internal 12-character uppercase base36 value consisting of a 10-character payload and two check letters.

Member ID#

A separate middle identifier represents the member/user scope within a policy. It allows multiple people or logical members to exist under one policy without introducing an email/password account identity.

Device ID#

The Device ID identifies an individual device binding. Like the Policy ID, it uses a 10-character uppercase base36 payload plus two check letters.

What the check letters do#

The two trailing letters on Policy IDs and Device IDs are an integrity check, not the cryptographic security mechanism.

Each identifier's payload passes through a fixed structural checksum, and the result becomes the two trailing check letters. The resolver can therefore reject malformed internal identifiers after decoding, without treating arbitrary 12-character strings as valid IDs. This checksum is inexpensive by design. Its purpose is structural validation before state authority is consulted.

Why the internal identity is not sent directly#

Earlier generations of a DNS identity system could concatenate internal IDs into a hostname or URL. ClearDNS does not do that in Resolver Credential V1.

Instead, the resolver wire carries a separate value with this shape:

[A-Za-z]{33}

The wire credential contains letters only, and its exact capitalization matters. The same logical Resolver Credential can be used by supported encrypted DNS transports while the internal identifiers remain in their canonical internal format.

Step 1: build the canonical transport value#

The variable portions of the internal policy, member and device identity are deterministically encoded into a fixed-width canonical representation: 33 uppercase letters (A-Z).

The conversion is reversible. The resolver can decode a canonical value back to the internal identifiers, and decoded values outside the valid internal identity domain are rejected. The transport representation is not encryption and is not intended to conceal the pseudonymous operational identifiers.

The check letters from the Policy ID and Device ID are not carried in the transport value. They are recomputed and revalidated after decoding.

Step 2: authenticate capitalization#

The 33-letter uppercase canonical value is not yet the wire credential.

ClearDNS computes a domain-separated HMAC-SHA256 using a private server-held resolver key and the canonical value. The authentication output determines the exact capitalization of the 33 letters, one HMAC-derived decision per letter.

The result is an exact mixed-case 33-letter Resolver Credential.

Illustrative shape:

aBcDEfGhijKLMnoPqRstUVwxyzABcDeFg

That example is only a shape illustration, not a valid ClearDNS credential.

Why capitalization is part of authentication#

DNS-related infrastructure frequently treats hostnames case-insensitively. Logs, copied values, normalization layers or other systems may change case.

Resolver Credential V1 deliberately makes case preservation security-relevant. A normalized all-uppercase or all-lowercase copy does not retain the HMAC-derived case pattern. The design adds an authentication property to information that normal hostname processing would otherwise ignore.

To be precise about the primitive: HMAC-SHA256 is the internal mechanism, but Resolver Credential V1 exposes 33 HMAC-derived capitalization decisions, one per letter, not a 256-bit transmitted authenticator. HMAC authenticates the transport representation; it does not encrypt or hide the encoded identity.

Resolver Credential V1 uses 33 HMAC-derived capitalization decisions. If the canonical 33-letter sequence is known but its authenticated capitalization is lost, there are 2^33, or 8,589,934,592, possible capitalization patterns.

Only one pattern is valid for that canonical credential. A blind capitalization guess has a nominal 1 in 8,589,934,592 chance of matching before server-side validation and other controls are considered.

This calculation describes the case-authentication layer only. It is not the total entropy of the underlying operational identity and should not be read as 33-bit total credential security.

An exact mixed-case copy already contains the authenticated case pattern, so capitalization guessing is no longer relevant. An exact copy can reproduce resolver possession under the same binding until that binding is removed or replaced. ClearDNS therefore treats the Resolver Credential as sensitive resolver configuration.

Resolver possession is not Dashboard administration. An exact Resolver Credential does not, by itself, unlock normal Dashboard functionality. Dashboard access requires an authenticated browser session and satisfaction of the member's separate Dashboard security requirement.

The case-authentication layer and the Dashboard PIN protect different boundaries. If the 33 canonical letters are known but both the authenticated capitalization and a six-digit Dashboard PIN are unknown, the two unknowns represent a nominal combined space of:

8,589,934,592 x 1,000,000 = 8,589,934,592,000,000

That is approximately 8.59 quadrillion possible combinations before server-side controls are considered.

This is a nominal combination count, not a claim of 53-bit cryptographic security. The PIN is an online authorization control with server-side rate limiting, and the case-authentication calculation applies only when the authenticated capitalization is unknown. If an attacker already has the exact mixed-case Resolver Credential, only the separate Dashboard authorization controls remain relevant to Dashboard access.

Validation order#

The resolver validates a presented credential in a strict order:

1. wire shape
2. exact mixed-case HMAC authentication
3. canonical base26 decode and range validation
4. reconstructed internal identifier checks
5. exact device/policy binding authority
6. policy state

This ordering matters. ClearDNS does not first decode an arbitrary credential, fetch policy state and then decide whether the case was correct. Authentication happens before the decoded tuple receives policy authority.

Constant-time case comparison#

The resolver derives the expected mixed-case credential and compares it to the presented 33-character value without using an early-exit character comparison. This keeps the exact case check simple and avoids turning the first mismatched position into an intentional comparison signal.

Fail-closed behavior#

Resolver Credential V1 is a hard protocol boundary.

Malformed credentials, credentials with the wrong capitalization, values outside the valid encoding domain and obsolete identity formats are rejected rather than silently accepted through a legacy parser.

If the resolver's case-authentication capability is unavailable, credential authentication fails closed rather than skipping the check.

Derived, not a second identity database#

The mixed-case Resolver Credential is deterministically derived from the validated internal identity and the resolver's private case-authentication key. It does not need to become a separate human identity or account record.

This is useful operationally because ClearDNS can keep the canonical policy/member/device relationship as the authority while using a transport-specific representation on the DNS wire. It also means the credential for a given device changes only when the underlying identity or the server key changes: creating a new device binding creates a new resolver identity and credential, while re-downloading the same configuration does not.

Possession semantics#

Resolver Credential V1 uses the following possession model:

• the credential is deterministic and has no intrinsic expiration; its lifetime is governed by the binding's authority, not by a timestamp inside the credential;
• an exact copied credential can be used for DNS resolution under the same operational binding until that binding's authority is withdrawn; the case pattern authenticates the credential's form, it does not prevent replay of an exact copy;
• the credential is not bound to device hardware in the current implementation; it is a configuration artifact provisioned for the operational device binding;
• under the current accountless dashboard model, the exact resolver configuration is a sensitive possession artifact and must be protected like other security-sensitive device configuration; a Policy ID alone is not dashboard authorization;
• revocation works through binding authority: removing or disabling the device binding withdraws service from every copy of its credential.

ClearDNS protects the server-side authority and authentication boundaries of the service; the user remains responsible for protecting access to the device and its locally provisioned resolver configuration, just as with other security-sensitive device configuration.

A different possession model#

Every usable identity system ultimately has something whose possession must be protected. Conventional services commonly ask users to protect an email account, a password, recovery channels and authenticated browser sessions. ClearDNS instead provisions an operational resolver identity to the configured device and does not require a separate ClearDNS email/password login.

An exact copy of sensitive ClearDNS resolver configuration must therefore be protected like other authentication material. If a device or environment containing that configuration is compromised, the configuration can potentially be copied; ClearDNS does not describe device compromise as impossible. The architectural difference is that ClearDNS does not additionally create a reusable email/password credential, a password-reset mailbox dependency or a credential-stuffing surface merely to administer DNS policy.

ClearDNS does not eliminate possession risk; it removes unnecessary identity layers around it.

How the possession model differs#

The comparison describes the credential and recovery surfaces required by each model; security ultimately depends on how those surfaces and the client device are protected. In many account-based services, compromise of the user's email account can become an account-recovery path because password-reset links are delivered to that mailbox; ClearDNS does not create a ClearDNS password-reset email flow because there is no conventional ClearDNS account password to reset.

Identifiers are not credentials#

Knowing a ClearDNS Policy ID, Member ID or Device ID is not equivalent to possessing the Resolver Credential or an authorized dashboard session. Those operational identifiers describe scope; they do not independently grant resolver or dashboard authority, and Resolver Credential V1 cannot be recreated from the visible operational identifiers without the server-authenticated credential construction.

DoH and DoT trust separation#

On direct DNS-over-HTTPS paths, the resolver authenticates and decodes Resolver Credential V1.

For the supported DNS-over-TLS path, ClearDNS keeps the gateway more limited. The gateway validates the expected outer shape and preserves the exact credential bytes, but it does not hold the private case-authentication key and does not decode the policy/member/device identity. It forwards the exact credential to the resolver with a separate gateway-to-resolver attestation.

This creates a narrower trust boundary:

DoT client
   |  exact mixed-case credential
   v
transport gateway
   |  opaque forwarding + gateway attestation
   v
resolver authority
   |  case authentication + decode + binding
   v
policy

What Resolver Credential V1 is not#

It is not:

• an email-derived identifier;
• a username;
• a password;
• a public/private keypair;
• encryption of the DNS message;
• an encryption or confidentiality wrapper for the operational identifiers;
• a replacement for TLS;
• proof that a browser is authorized to administer a policy.

Dashboard authorization has its own session-binding mechanism.

Accountless Dashboard Authentication

Security properties at a glance#

Why ClearDNS documents this#

The accountless model should be technically explainable. "Anonymous token" is an incomplete description because it hides the distinction between an internal policy identity, a member scope, a device identity, a resolver transport credential, and an authenticated dashboard session. ClearDNS treats those as separate concepts.

Related technical references#

• Accountless Dashboard Authentication
• Device and Member Enrollment
• Security Model