JOSE internals: JWS, JWE and JWK

RFC 7515’s first signed example is 179 characters long. The first 135 are a header and a payload that anyone can decode, and the last 43 are the signature that makes them worth believing. A verifier that lets the token’s own header pick the algorithm or the key has handed the decision to whoever wrote the token.

This lesson opens the format layer by layer. A JWSJWS: JSON Web Signature: a signed message made of a header, a payload and a signature. In its compact form these are three Base64url strings joined by dots. signs, and a JWEJWE: JSON Web Encryption: an encrypted message in which one layer protects a content key for the recipient and a second layer encrypts the data with it. The compact form has five parts. encrypts. A JWKJWK: JSON Web Key: a cryptographic key written as a JSON object, with members such as the key type, a key ID and the key material. writes a key as JSON, and a JWKS publishes a set of them. You will rebuild the RFC’s example with Web Crypto, see why a verifier checks the exact bytes it received, and learn the rule that closes most of the format’s known holes: the verifier chooses the algorithm and the key, never the token.

A JWS signs two Base64url strings joined by a dot

A JWS in its compact form is three Base64url strings joined by dots: header, payload and signature. The header is a JSON object that says how the signature was made (alg) and often which key made it (kid). The payload is any bytes; in a JWTJWT: JSON Web Token: a compact, URL-safe way to carry claims. The claims are a JSON object, usually the payload of a signed JWS, so anyone can read them and the signature shows whether they were changed. it is the JSON object of the claims. The signature covers the ASCII text of the first two strings with the dot between them, the signing inputsigning input: The ASCII text a JWS signature covers: the Base64url header, a dot and the Base64url payload, exactly as they appear in the token., and nothing else. RFC 7515 Appendix A.1 signs a header of 30 bytes and a payload of 70 with HMAC SHA-256. Step through how its 179 characters come about:

The program redoes the example with Web Crypto. It builds both parts from the RFC’s bytes, signs them with the RFC’s key, compares the result with the 43 characters printed in the RFC, and then tries the habit that most often breaks verification:

// RFC 7515 Appendix A.1: a JWS with HMAC SHA-256, built and checked with Web Crypto. A JWS signs the ASCII text of the
// Base64url header, a dot and the Base64url payload; the program shows that, then why a verifier must check the
// segments exactly as they arrived.
const subtle = globalThis.crypto.subtle;
const b64u = (bytes) => Buffer.from(bytes).toString('base64url');
const fromB64u = (text) => Buffer.from(text, 'base64url');
const text = (s) => new TextEncoder().encode(s);

// The header and payload of the RFC, byte for byte: each has a carriage return, a line feed and one space inside.
const header = '{"typ":"JWT",\r\n "alg":"HS256"}';
const payload = '{"iss":"joe",\r\n "exp":1300819380,\r\n "http://example.com/is_root":true}';
// The RFC's key as a JWK: "oct" means a raw secret, and "k" is its Base64url text.
const jwk = { kty: 'oct', k: 'AyM1SysPpbyDfgZld3umj1qzKObwVMkoqQ-EstJQLr_T-1qS0gZH75aKtMN3Yj0iPS4hcgUuTwjAzZr1Z9CAow' };
const published = 'dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk'; // the signature printed in the RFC

const key = await subtle.importKey('jwk', jwk, { name: 'HMAC', hash: 'SHA-256' }, false, ['sign', 'verify']);
const signingInput = `${b64u(text(header))}.${b64u(text(payload))}`;
const signature = b64u(await subtle.sign('HMAC', key, text(signingInput)));

console.log(`header    ${text(header).length} bytes  ${b64u(text(header))}`);
console.log(`payload   ${text(payload).length} bytes  ${b64u(text(payload)).slice(0, 40)}…`);
console.log(`signed    ${signingInput.length} characters: the two segments and the dot between them`);
console.log(`HMAC      ${signature}`);
console.log(`RFC 7515  ${published}   same: ${signature === published}`);
console.log(`compact   ${signingInput.split('.').length + 1} parts, ${signingInput.length + 1 + signature.length} characters in all`);

// A verifier checks the signature over the segments as received. Parsing the header and writing it out again
// changes its bytes, so the signature no longer fits, although the JSON means the same.
const received = `${signingInput}.${signature}`;
const [h, p, s] = received.split('.');
const verifyOn = async (a, b) => subtle.verify('HMAC', key, fromB64u(s), text(`${a}.${b}`));
const rewritten = b64u(text(JSON.stringify(JSON.parse(fromB64u(h).toString()))));
console.log('');
console.log(`verify on the segments as received          ${await verifyOn(h, p)}`);
console.log(`header read as JSON and written out again   ${JSON.stringify(JSON.parse(fromB64u(h).toString()))}`);
console.log(`  same Base64url text as received: ${rewritten === h}, verify on it: ${await verifyOn(rewritten, p)}`);

header    30 bytes  eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9
payload   70 bytes  eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkz…
signed    135 characters: the two segments and the dot between them
HMAC      dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk
RFC 7515  dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk   same: true
compact   3 parts, 179 characters in all

verify on the segments as received          true
header read as JSON and written out again   {"typ":"JWT","alg":"HS256"}
  same Base64url text as received: false, verify on it: false

The signature is the RFC’s. Now the last three lines. The RFC’s header has a carriage return, a line feed and a space inside it, so the text that was signed is not the compact JSON a parser writes back. Reading the header as JSON and writing it out again gave a different Base64url string, and the signature check on it failed, although the JSON means the same thing. A verifier therefore checks the signature over the two strings exactly as they arrived, and reads their contents afterwards.

The verifier chooses the algorithm and the key, never the token

The header’s alg says which algorithm the issuer used, and until the signature has been checked it is text that anyone could have written. RFC 8725, the best current practice for JWTs, therefore says that a verifier takes its set of algorithms from its own configuration and uses each key with exactly one algorithm, checking that the header agrees. When the header is allowed to choose, a token can pick the weakest check that will accept it. An alg of none means no signature at all. Algorithm confusionalgorithm confusion: A flaw in which a verifier lets the token's header choose the algorithm, so a token made for the wrong kind of check is accepted, such as an HMAC keyed with an RSA public key. One algorithm per key prevents it. means an RSA public key, which everyone has, used as the key of an HMAC check: a verifier that follows the header accepts a token that anyone holding the public key could have built. ASVS 5.0 requirement 9.1.2 asks for the same rule in its own words, an allowlist of algorithms for each context that never includes none.

Four headers show the difference between a verifier that follows the header and one that pins one algorithm to each key:

Keys follow the same rule. RFC 7515 calls the kid header a hint about which key was used, so a verifier uses it only to pick among keys it already trusts. A header that points at a key, such as jku, x5u or jwk, is never followed to wherever the token says.

Two more pieces complete the picture. A JWE encrypts instead of signing: one layer protects a content key, and a second layer encrypts the data with it. A JWK writes a key as JSON, and a JWKS is a set of them that a service publishes so that others can find its public keys by kid.

Verifying under a policy, with the failures reproduced Pro: opens with a Pro, Premium or Ultimate pass

JWE: two layers, five parts and what the tag covers Pro: opens with a Pro, Premium or Ultimate pass

Keys in rotation: JWKS, kid and current algorithm names Pro: opens with a Pro, Premium or Ultimate pass

Practise: signed bytes and the verifier’s rule

The session below asks about the first two ideas of the lesson: what a JWS signs, and who decides the algorithm. It starts with the one you know less and brings back what you miss:

Interview questions

Key takeaways

• A compact JWS is three Base64url parts, and its signature covers the first two with the dot between them: 135 of the 179 characters of RFC 7515’s example.
• Verify the signature over the two strings exactly as they arrived and read their contents afterwards, because the RFC’s own header does not survive being read and written back.
• The verifier, not the token, chooses the algorithm and the key, and each key is used with exactly one algorithm.
• A header-trusting verifier accepts alg: none and an HMAC check keyed with a public key.