Key id and thumbprint

What this check verifies

For each structurally valid key, the checker computes the RFC 7638 JWK thumbprint: a SHA-256 hash over the key’s required members in a fixed order (crv, kty, x for an Ed25519 key), base64url-encoded. It then compares each key’s kid with that thumbprint:

• Every kid present equals its key’s thumbprint: pass. The message shows a sample thumbprint.
• A key has no kid: that key passes.
• A key has a kid that differs from its thumbprint: warning. The message names the first such kid and the thumbprint it should be.

A passing key looks like this:

{ "kty": "OKP", "crv": "Ed25519", "x": "JrQLj5P_89iXES9-vFgrIy29clF9CC_oPPsw3c5D0bs", "kid": "poqkLGiymh_W0uP6PZFw-dvez3QJT5SolqXBCW38r0U" }

(This is the RFC 9421 Ed25519 example key. It passes here, but the test key check warns about it.)

The check is advisory. A mismatched kid lowers the score but never caps the grade and never changes the verdict.

Why it matters

The protocol draft (draft-ietf-webbotauth-httpsig-protocol-00, section 5.5) says that a JWK served at the well-known path may carry a kid, and if it does, the kid must be the thumbprint. A verifier can then select the key by matching the signature’s keyid against kid, and it can check the directory’s labels itself instead of trusting them.

A signature’s keyid is always the thumbprint of the signing key (section 5.2). A verifier that matches keyid against kid finds no key when the kid is a custom label such as key-2026-a, and the signature goes unverified. This checker resolves keyid by computing thumbprints, so your signatures still verify here; that is why the result is a warning and not a failure.

The rule applies to the well-known path. A JWK Set reached through a jwks_uri or a Signature Agent Card may serve other consumers, where kid is the operator’s own label, and the draft tells verifiers to compute thumbprints there.

How to fix it

Do one of two things for each key:

1. Set kid to the thumbprint the checker reports.
2. Remove kid.

Then confirm your signing agent sends the same thumbprint as the keyid parameter in Signature-Input. If it sends something else, the signature does not resolve to this key.

References

• RFC 7638 defines the JWK thumbprint and its hash input.
• RFC 7517 defines the kid member.
• The Web Bot Auth protocol draft (draft-ietf-webbotauth-httpsig-protocol-00): section 5.2 defines keyid as the thumbprint, and the note in section 5.5 requires kid at the well-known path to equal it.
• How grading works explains how advisory warnings affect the score.