Docs Navigation

How It Works

Sigil creates a chain of proof between a person (or bot) and a domain. It doesn’t rely on any central authority. Instead, it layers multiple independent verification methods on top of each other, each one making forgery harder.

Sigil isn’t absolutely foolproof, but its goal is to prove, cryptographically, that the subject controls a domain and that it is highly likely a real human or declared bot.

The core idea

Anyone can copy someone’s public key and stick it on their website. That alone proves nothing. So Sigil goes further. It makes you:

  1. Sign a unique challenge with your private key (proving you hold the key).
  2. Place the signed challenge on your website (proving you control the domain).
  3. Complete a hardware attestation ceremony bound to the signed challenge (proving that you have physical access to hardware).
  4. Publish the signed results on your domain.

A visitor’s browser checks all four in sequence with no servers involved. The extension’s job is simply to ensure that all signatures are valid.

PGP signature layer

Sigil generates a challenge that includes a random UUID and metadata about you and your domain. You sign this challenge with your private key. The signed result is placed in a human-proof.json file under .well-known/ on your site.

When a visitor arrives, the extension fetches your public key and verifies the signature. If the signature is valid and the fingerprint matches, that’s enough to establish an initial trust layer.

You gain 25 points if your key is also found on a common keyserver, but it doesn’t prove a human is involved, as this process can be scripted.

WebAuthn attestation layer

During the registration ceremony, Sigil triggers a WebAuthn challenge. On most devices this is a fingerprint scan, Face ID or a Windows Hello prompt. On Linux with a TPM (including fTPM) it usually works out of the box as well. You can also use a Yubikey or connect your phone via Bluetooth.

The WebAuthn response includes hardware attestation. This is a cryptographic proof that a physical authenticator was involved. It’s the same standard that banks use for 2FA, but here it’s being used to prove presence, not to log in.

The response is bundled into the same human-proof.json file. The UUID from the PGP challenge is reused as the WebAuthn challenge, so the two are cryptographically linked.

If you really can’t do WebAuthn (older hardware, no authenticator available), you can skip this step. You’ll end up with partial trust instead of high trust.

Spoofing a proper hardware attestation is very complex for an attacker. Sigil ensures that a valid attStmt is present and also uses the amount of time spent on the attestation as a metric to detect forgery attempts.

Timing analysis

The ceremony is timed. The human-proof.json file records ceremonyStart and ceremonyEnd timestamps. A real human can complete the WebAuthn prompt in well under half a minute. Forgery or replay attacks usually require half a minute or more.

If you finish in under 15 seconds, you keep all 50 points. The penalty grows as the time increases, but it caps out at 35 so you never lose everything just because your device was a bit slow. Don’t worry, you can make up for the losses through the web of trust.

Web of trust

On top of all this, Sigil uses GPG’s existing web of trust. Users can sign each other’s keys, vouching for their identity. When a high-trust user vouches for someone, that vouch is worth up to 10 points.

This is the same mechanism GPG has used for decades. Sigil just reads the existing trust signatures and factors them into the score. You don’t need to do anything special beyond normal GPG key signing.

Client-side verification

When a visitor with the Sigil extension lands on a site, the following steps take place:

  1. The extension fetches /.well-known/human-proof.json
  2. It reads the GPG public key and verifies the signature over the challenge
  3. It checks that the WebAuthn challenge UUID matches the one in the signed data
  4. It verifies that the WebAuthn rpId matches the domain
  5. It validates the hardware attestation certificates
  6. It checks the ceremony timing
  7. It queries configured keyservers for the public key
  8. It computes a final trust score from all these signals

What about revocation?

The human-proof.json format supports a validUntil date and a revocationFingerprint field. If you need to rotate keys or revoke trust, you update the file. The extension re-checks on its cache timeout (default is 60 minutes).