JSON Web Key (JWK)

A JSON Web Key (JWK) is a JSON data structure that represents a cryptographic key. It provides a standardised way to describe a key and its associated parameters, such as the key type (kty), the intended use (use), and a unique key identifier (kid). JWKs are typically used for asymmetric keys, where a public key is represented in JSON format, allowing it to be easily shared and used for tasks like verifying digital signatures.

JWK and Associated Cryptographic Standards

JSON Web Keys are designed to be flexible and work with a variety of cryptographic algorithms and standards. The parameters within a JWK object specify these details, ensuring that the key is used correctly.

Key Types and Algorithms

Key Type (kty): This parameter specifies the family of cryptographic algorithms used with the key. Common values include RSA for RSA keys and EC for Elliptic Curve keys.
Algorithm (alg): This identifies the specific algorithm used to sign or encrypt data with the key. For example, RS256 is a widely used algorithm that stands for RSA Signature with SHA-256. This means the key is an RSA key and the hash algorithm used for the signature is SHA-256.

X.509 Certificates

While a JWK can represent a raw public key, it can also be associated with an X.509 certificate. The X.509 standard defines a public key certificate format. A JWK can include parameters that link it to a certificate, such as:

x5c: This parameter contains the entire X.509 certificate or certificate chain.
x5t: This provides a SHA-1 thumbprint of the X.509 certificate, which acts as a unique identifier.

Using these parameters allows systems to verify the key's authenticity not just through its inherent properties, but also by validating the associated certificate chain. This is particularly useful for establishing a chain of trust in secure communication protocols.

JSON Web Key Set (JWKS)

A JSON Web Key Set (JWKS) is a JSON object that acts as a container for a set of JWKs. It contains an array of JWK objects, which is particularly useful for scenarios that require key rotation. Instead of manually updating keys, a client can retrieve the JWKS from a publicly available endpoint (often a .well-known/jwks.json URL) and find the correct key to use by matching the kid from a JWT header with a kid in the JWKS. This makes key management more flexible, scalable, and secure.

Signing JSON Web Tokens (JWTs)

The primary purpose of a JWK and JWKS is to sign and verify securely JSON Web Tokens (JWTs). A JWT is a compact, URL-safe means of representing claims to be transferred between two parties. It's composed of three parts, separated by dots (.): a header, a payload, and a signature.

The Signature's Role

The signature is what makes a JWT trustworthy. It's created by taking the encoded header and payload and applying a cryptographic algorithm to them using a private key. This signature proves two things:

The JWT's content hasn't been tampered with.
The owner of the private key issued the JWT.

The Signing Process

When a server (the issuer) wants to create a signed JWT, it first defines the key to use in the JWT's header using the kid (Key ID) parameter. It then uses the corresponding private key from its internal keystore to generate the signature.

When another party (the verifier) receives this JWT, it reads the kid from the header. It then retrieves the issuer's JWKS (often from a public endpoint) and finds the matching public key using that same kid. The verifier uses this public key to check the signature mathematically. If the signature is valid, the verifier can trust the JWT's contents. This entire process is a core part of modern authentication and authorisation protocols.