JWKS (JSON Web Key Set)
A JWKS (JSON Web Key Set) is a list of public keys in JSON format following RFC 7517 that verifying parties use to check an issuer's signatures.
Each key in the set is a JSON Web Key with key type, parameters such as curve and coordinates, a key ID (kid) and usually algorithm and intended use. Issuers publish their JWKS at a fixed HTTPS address; signed tokens name the kid in the header so the verifying party finds the matching key. A JWKS never contains private keys.
The JWKS allows keys to be rotated without reconfiguring verifying parties: new keys are added, old ones stay until the evidence signed with them has expired.
Example
A mandate service publishes its JWKS with two keys: a current one for new mandates and an older one that still applies to running mandates. A bank loads the JWKS once and provides it; every mandate names in the kid which key it was signed with.
How it differs
A JWKS is a list of public keys with no statement about whom to trust. A trust anchor is the verifying party's decision to trust a key or certificate. An X.509 certificate additionally links a key with a verified identity.
In practice
- Publish your JWKS at a fixed HTTPS address and name it in your documentation.
- Set the kid in every piece of evidence so verifying parties find the right key.
- Before every publication, check that no private part is in the JWKS.
Role in KYA
KYA accepts the verifying party's keys as JWK or JWKS. Only a key provided this way makes the issuer a proven fact; a merely embedded key counts as self-asserted.
Related check: Issuer (issuer_resolution). Is the key bound to the issuer – through a DID or because the verifying party trusts it?
Frequently asked questions
What is a JWKS?
A list of public keys in JSON format following RFC 7517. Verifying parties use it to check an issuer's signatures.
What is the kid for?
The key ID links a signed token with the matching key in the JWKS, even if the set contains several keys.
Where is a JWKS published?
At a fixed HTTPS address of the issuer, often under /.well-known/. The issuer defines and documents the exact address.
May a JWKS contain private keys?
No. A JWKS contains only public keys. A private part, such as the d field, must never appear in it.
Does KYA load the JWKS itself?
No. The verifying party loads the JWKS from a trusted source and provides it. This keeps verification reproducible and independent of the network.