Verify an Identity

You have an inbound connection from an IPv6 address and you want to know whose it is. This page runs the whole proof chain in one keyless call. No account, no key, no agent on the far end.

1. Ask for the verdict

Pass the address, or the name it claims, as ip.

curl -s "https://rdap.whisper.online/verify-identity?ip=2a04:2a01:b69a:6717:e3b0:51ff:3bf7:f478" | jq .

{
  "is_whisper_agent": true,
  "fqdn": "ae3b051ff3bf7f478.t<tenant>.agents.whisper.online",
  "operator": "<operator label>",
  "tenant": "t<tenant>",
  "dane_ok": true,
  "jws_ok": true,
  "verified_at": "<epoch milliseconds>",
  "evidence": {
    "address": "2a04:2a01:b69a:6717:e3b0:51ff:3bf7:f478",
    "ptr": "ae3b051ff3bf7f478.t<tenant>.agents.whisper.online",
    "forward_aaaa": "2a04:2a01:b69a:6717:e3b0:51ff:3bf7:f478",
    "agent": "<agent id>",
    "allocated_at": "<epoch milliseconds>",
    "posture": "tier1.5",
    "dane_tlsa_sha256": "<hex digest>",
    "dane": {
      "usage": 3,
      "selector": 1,
      "matching": 1,
      "strong_pin": true,
      "served_leaf_matches": true
    },
    "rdap": {},
    "identity_doc": {}
  }
}

2. Read the three fields that matter

is_whisper_agent says the reverse and forward records agree and the allocation is current. dane_ok says the certificate served on the name hashes to the TLSA record published under it. jws_ok says the signed identity document on the name checks out against the key the pin names.

Inside evidence, ptr and forward_aaaa are the two halves of the two-way lock, and posture is the connectivity tier the identity is running on.

3. Read the other statuses

An address that is not a Whisper identity comes back as 200 with is_whisper_agent set to false and a detail line saying why. Malformed input comes back as 400, also with detail. The endpoint does not answer 500, so treat any other status as a transport problem and retry.

4. Gate on the verdict, not on the address

Verifying is not authorising. The verdict tells you which identity is calling and that the identity is real. What that identity is allowed to do is your decision, so match fqdn against a list you keep, at whichever granularity you need: one name, one account, or the whole identity zone.

# in your own authorisation step
test "$(jq -r .is_whisper_agent <<<"$verdict")" = true || exit 1
case "$(jq -r .fqdn <<<"$verdict")" in
  *.t<tenant>.agents.whisper.online) : ;;
  *) exit 1 ;;
esac

If you want to see the individual records behind the verdict, the proof chain walks each one with the command that reads it. If you would rather not take Whisper's word for the answer at all, re-derive it on your own machine.