Verifying who sent something¶
A share or a request arrives with a claim attached: this came from an identity
issued by example.com. Every field of that claim is attacker-controlled until
you check it. This page is how you check it.
The chain has four links, and all four have to hold.
1. DNS says which key speaks for the domain¶
Read the _revoked.<domain> TXT record. It pins the SHA-256 fingerprint of the
domain's root key.
This is the anchor. It is the one step an attacker cannot forge by serving you a convincing response, because they do not control the victim's DNS.
2. The domain serves a key matching that pin¶
Fetch GET https://<domain>/api/server and compare fingerprint against the
TXT record. If they disagree, stop — someone is standing between you and the
domain, or the domain is not who it claims.
A key served without a matching DNS pin proves nothing at all: whoever serves the response also chooses what it says.
3. That key signed the identity¶
The probe gives you the sharer's fingerprint and parentSignature. Verify the
signature against the root key from step 2. This is what ties an individual
identity to the domain.
An identity with no parentSignature predates DNS verification. It is not
forged — it is simply unproven, and should read differently from a mismatch.
4. The issuer still stands behind it¶
This is the step most implementations forget, and the one that matters most.
A certificate is minted for ten years and its parentSignature never expires.
Someone removed from a workspace still holds a key that proves exactly what it
proved on their first day. A challenge signature does not help: it proves
possession, which they still have.
Only the issuer's current opinion closes this, and it lives at
GET /api/identities/{fingerprint}/status. The answer is signed by the same
root key you already pinned, so it needs no separate trust and a proxy cannot
rewrite it.
unknown is not revoked
A restored backup or a reinstall answers unknown about identities that
were perfectly valid. Treating the two the same turns a routine restore
into a mass revocation. Report them differently.
Probes staple this answer into the response as statusAssertion so you need no
second round trip — but verify its signature rather than trusting the field,
since it arrives over the same channel as everything else you are checking.
Verifying an attestation¶
An attestation is a statement one domain signs about an identity of another, so it is checked along two chains. Both have to hold.
The attester's chain answers who stands behind the statement.
- The credential names its issuer as
https://<domain>(iss). Steps 1 and 2 above tie that domain's root key to its DNS record. GET https://<domain>/.well-known/jwt-vc-issuerserves the key credentials are signed with. It is not the root key: the root key certifies it, inrevoked_certification— a statement of typecredential-key-v1naming the domain and the key's thumbprint. A key served without that certification proves nothing, for the reason given in step 2.- That key signed the credential, and every disclosure presented with it opens a digest inside the signed part.
- The credential's
statusnames a position in the attester's status list. The list is fetched from the attester's own origin, verified under the same key, and read at that position. A set bit means revoked. A position the list does not reach means nothing can be said, which is reported as unverified, not as revoked.
The holder's chain answers whether whoever presents the credential is the one it was issued to.
- The credential names a key (
cnf). The presentation ends in a key binding signed with that key, which commits to the verifier (aud), to the verifier's nonce, and to exactly the disclosures presented (sd_hash). Without this, a credential is a string anyone who saw it could present. - The credential names the identity that key belongs to
(
revoked_holder). The domain that issued the identity is asked for its status, as in step 4 above. A withdrawn identity ends the use of every credential bound to it — that is how a leaked identity key is answered.
POST /api/attestations/verify walks both chains and returns the verdict.
The verdict is not a policy
A verified attestation says that a domain made a statement and still stands behind it. It does not say the domain is one to believe: anyone can run a server and attest anything. The attesting domain is part of the verdict so that the service compares it with the domains it accepts for that statement.
What a verdict should mean¶
| Outcome | Meaning | What to do |
|---|---|---|
| Verified | All four links hold. | Proceed. |
| Unverified | No DNS record, or no parent signature. | Allow with an explicit warning — this is the default for a server that has not finished DNS setup. |
| Spoofed | DNS pin and served key disagree, or the signature fails. | Block. This is not a misconfiguration. |
| Revoked | Every signature holds, and the issuer has withdrawn the identity. | Block. Nothing was forged; the vouching stopped. |
A note on failing safe¶
A check that could not complete is an unverified identity, not a verified one and not an error to swallow. Timeouts, captive portals and unreachable resolvers must all land on a verdict, or the gate silently disengages exactly when the network is least trustworthy.