Verifying a report

A compliance report is signed by the cluster that produced it. This page is how someone who has never heard of us checks that signature, without asking us anything.

What the signature claims

Exactly two things, and it is worth being precise because the value of the claim is in its narrowness:

• the report has not changed since it was signed — alter one character, even inside a timestamp, and the check fails;
• it was signed by a key that Attestkeep vouched for as belonging to that installation.

Two things it does not claim. It is not a legal electronic signature: no qualified certificate is involved and no e-signature statute applies to it. And it does not prove when the report was signed — the timestamps are the installation’s own declaration, read from its own clock, with no timestamping authority involved. If your process needs the time proven, that proof has to come from elsewhere.

The signature also vouches for the document, not for the world. It proves the report is exactly what that installation produced. It does not prove that the events the report describes happened as described.

The three files

An operator hands you three things, all from the evidence screen in their console:

The chain

You trust one key. Everything else follows from it.

1. Attestkeep’s signing key (below) verifies the certificate.
2. The certificate’s cnf.jwk claim names the installation’s key.
3. That key verifies the attestation.
4. The attestation’s subject digest matches the report.

The middle step is the one that matters. Without it you would have to be handed a public key by the same person handing you the report, and a forger would simply supply both: a key they made, and a report they signed with it. The certificate breaks that, because it is signed by a key the customer does not hold.

One cross-check belongs in any verifier: the installation.fingerprint in the attestation must equal the fpr claim in the certificate. Otherwise a genuine certificate can be presented alongside an attestation from a different installation.

Attestkeep’s signing key

This is the one value you must obtain from a source you trust rather than from the documents themselves. There are two independent places to read it: this page, and any Attestkeep installation — the same key is compiled into every operator binary, so a customer can read it out of their own cluster and compare it with what is printed here. A key that appeared in only one of those two places would be worth asking about.

The easy way

attestkeep.com/verify.html does all of this in the browser. The page carries the key above and the arithmetic; nothing is uploaded, and you can disconnect from the network after loading it and get the same answer. It is a convenience, not the authority — which is the point of publishing the format at all.

Doing it yourself

The format is DSSE carrying an in-toto statement, both public specifications, so any tool that reads them can read ours. The predicate is documented field by field at attestkeep.com/attestation/compliance-evidence/v1.

What DSSE signs is not the payload but its pre-authentication encoding, which binds the payload to its type so a signature cannot be replayed under a different one:

PAE = "DSSEv1" SP LEN(payloadType) SP payloadType SP LEN(payload) SP payload

where SP is one space and LEN is the length in bytes, in decimal. The script below is the whole verification, and it is short on purpose: you should be able to read it and satisfy yourself that the answer does not depend on us.

#!/usr/bin/env python3
# Verify an Attestkeep compliance report. Standard library plus `cryptography`.
#   python3 verify-report.py report.json attestation.json certificate.jwt
import base64, hashlib, json, sys
from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey
from cryptography.exceptions import InvalidSignature

ROOT_KEY_HEX = "e287aabe4712197cfa5b6fdf9ea8f2d7f0333ce16ca69aac7e4a3f1e84c04179"
PREDICATE_TYPE = "https://attestkeep.com/attestation/compliance-evidence/v1"

def check(key_hex, message, signature):
    try:
        Ed25519PublicKey.from_public_bytes(bytes.fromhex(key_hex)).verify(signature, message)
        return True
    except (InvalidSignature, ValueError):
        return False

def b64url(s): return base64.urlsafe_b64decode(s + "=" * (-len(s) % 4))
def die(m): sys.exit("REJECTED: " + m)

report = open(sys.argv[1], "rb").read()
envelope = json.load(open(sys.argv[2]))
head_b64, body_b64, sig_b64 = open(sys.argv[3]).read().strip().split(".")

# 1. Our key signed the certificate, so what it says about the cluster's key is
#    not something the cluster could have decided for itself.
if json.loads(b64url(head_b64)).get("alg") != "EdDSA":
    die("certificate algorithm is not EdDSA")
if not check(ROOT_KEY_HEX, (head_b64 + "." + body_b64).encode(), b64url(sig_b64)):
    die("the certificate was not signed by Attestkeep")
claims = json.loads(b64url(body_b64))
installation_key = (claims.get("cnf") or {}).get("jwk", "")
if len(installation_key) != 64:
    die("the certificate names no installation key")

# 2. The envelope, against the key the certificate named. DSSE signs the
#    pre-authentication encoding, which binds the payload to its type.
payload = base64.b64decode(envelope["payload"])
ptype = envelope["payloadType"].encode()
pae = b"DSSEv1 %d %s %d %s" % (len(ptype), ptype, len(payload), payload)
if not any(check(installation_key, pae, base64.b64decode(s["sig"]))
           for s in envelope["signatures"]):
    die("no signature was made by the key the certificate names")
statement = json.loads(payload)
if statement["predicateType"] != PREDICATE_TYPE:
    die("not a compliance evidence attestation")

# 3. Both halves must describe the same installation, or a genuine certificate
#    could be presented alongside an attestation from somewhere else.
if statement["predicate"]["installation"]["fingerprint"] != claims.get("fpr"):
    die("the attestation and the certificate describe different installations")

# 4. And the report in your hands must be the one that was signed.
if statement["subject"][0]["digest"]["sha256"] != hashlib.sha256(report).hexdigest():
    die("this report is not the one the attestation covers")

p = statement["predicate"]
print("VERIFIED", statement["subject"][0]["name"])
print("  framework   ", p["framework"])
print("  period      ", p["period"]["start"], "->", p["period"]["end"])
print("  installation", p["installation"]["fingerprint"])
print("  generated   ", p["generated_at"], "by", p.get("generated_by", "-"))

Run it against the three files:

python3 verify-report.py report.json attestation.json certificate.jwt

A pass prints the report identity, framework, period and installation. Any failure prints why and exits non-zero: a report that does not match its attestation, an attestation not signed by the key the certificate names, a certificate not signed by us, or a certificate and attestation describing different installations.

Certificates expire; reports do not

A licence certificate is short-lived by design — it rotates every thirty days, which is what stops an unreachable licence server from keeping a lapsed licence alive. A verifier should therefore not reject an expired certificate: it was valid when it vouched for the key, and the report it covers is from that period. Check the expiry, report it, and let the reader weigh it. Refusing outright would make every report older than a month unverifiable, which is the opposite of the point.