Skip to main content

Verify an AiHint File

This guide explains how to fetch an AiHint file from a domain, validate its structure, and verify its cryptographic signature.

Quick Verification​

To verify a domain's AiHint file using standard command-line tools:

# Fetch the hint
curl -sf https://example.com/.well-known/aihint.json -o aihint.json

# Extract canonical payload (remove signature field)
jq 'del(.signature)' aihint.json > payload.json

# Decode the signature
jq -r '.signature' aihint.json | base64 -d > signature.bin

# Fetch the issuer's public key
curl -sf $(jq -r '.public_key_url' aihint.json) -o pubkey.pem

# Verify
openssl dgst -sha256 -verify pubkey.pem -signature signature.bin payload.json

If the output is Verified OK, the hint is authentic and has not been tampered with.

Step-by-Step Process​

1. Fetch the AiHint File​

AiHint files are always located at /.well-known/aihint.json:

curl -sf https://example.com/.well-known/aihint.json -o aihint.json

If the request returns a 404 or non-JSON response, the domain does not publish an AiHint file.

2. Validate the Structure​

Before verifying the signature, check that the document has the correct structure:

# Check required fields exist
jq 'has("version", "type", "target", "issuer", "score", "method",
     "issued_at", "expires_at", "signature", "public_key_url")' aihint.json
# Should output: true

# Check type is "global"
jq -r '.type' aihint.json
# Should output: global

# Check score is in range
jq '.score >= 0 and .score <= 1' aihint.json
# Should output: true

For automated validation, use the JSON Schema.

3. Check Expiration​

A hint that has expired should not be trusted:

EXPIRES=$(jq -r '.expires_at' aihint.json)
NOW=$(date -u +"%Y-%m-%dT%H:%M:%SZ")

if [[ "$NOW" > "$EXPIRES" ]]; then
  echo "EXPIRED: This hint is no longer valid."
else
  echo "Valid: Hint has not expired."
fi

4. Verify the Signature​

This is the critical step. The signature proves the document was created by the claimed issuer and has not been modified.

# Extract canonical payload
jq 'del(.signature)' aihint.json > payload.json

# Decode the Base64 signature
jq -r '.signature' aihint.json | base64 -d > signature.bin

# Fetch the issuer's public key
curl -sf $(jq -r '.public_key_url' aihint.json) -o pubkey.pem

# Verify using RSA-SHA256
openssl dgst -sha256 -verify pubkey.pem -signature signature.bin payload.json

Possible outcomes:

OutputMeaning
Verified OKSignature is valid. The document is authentic.
Verification FailureSignature does not match. The document may have been tampered with, or the wrong public key was used.

5. Evaluate the Hint​

Once verified, examine the hint's contents:

# Display a summary
jq '{target, issuer, score, method, issued_at, expires_at}' aihint.json

Consider:

  • Who is the issuer? A well-known issuer carries more weight than a self-signed hint (where issuer = target).
  • What is the score? See Trust Scoring for score interpretation.
  • When was it issued? More recent hints reflect more current assessments.
  • What method was used? The method field tells you how the score was calculated.

Verification Checklist​

A fully verified AiHint file must pass all of these checks:

CheckHow
File exists at /.well-known/aihint.jsonHTTP 200 with Content-Type: application/json
Valid JSON structureAll required fields present, correct types
Not expiredCurrent time is before expires_at
Signature validRSA-SHA256 verification succeeds with issuer's public key
Public key accessiblepublic_key_url returns a valid PEM public key over HTTPS

Common Issues​

"Verification Failure" with a valid-looking document​

  • The document may have been modified after signing (even whitespace changes invalidate the signature).
  • The public key at public_key_url may have been rotated since the hint was signed.
  • The canonical payload reconstruction may not match the original (ensure you remove only the signature field).

Public key URL returns 404​

The issuer may have rotated their keys. If the hint has not expired, this is a problem — contact the issuer.

Self-signed hints​

When issuer equals target (e.g., both are https://example.com), the hint is self-signed. This means the domain is vouching for itself. Self-signed hints are structurally valid but carry no third-party trust.

Next Steps​