JWT RS256 Key Generator

A JSON Web Token looks like a secret. It is not one. It is a short note that anyone can read, with a seal on it, and everything it is worth depends on how carefully the seal is checked.

The specification describes a token as a compact, URL-safe way to carry claims: a JSON object of statements such as who issued it, whom it is about, whom it is for and when it stops being acceptable. In its usual signed form it travels as three runs of Base64url text joined by two periods, which are a header, a payload and a signature. Base64url is an encoding, not a lock. Anyone holding the token can turn the first two parts back into JSON without a key, and the specification’s own privacy advice is blunt: leaving sensitive information out is the simplest protection.

What RS256 actually signs

The signature covers one exact string, called the signing input: the first part, a period, and the second part, as ASCII characters. Nothing else is signed and nothing in that string may move. Change a single character of the header or the payload and the check fails, because the verifier recomputes over the characters it received.

The header says which algorithm made the signature, in a member named “alg”. RS256 stands for the RSA signature scheme of PKCS #1 version 1.5 with the SHA-256 hash. The algorithm registry marks it as recommended, and the profile for access tokens goes further: servers that follow it must support RS256. One rule comes with it. The key must be 2,048 bits or larger.

An RSA key is a handful of whole numbers. The modulus n is the product of two secret primes, the public exponent e is small and known, and the private exponent d is chosen so that e times d leaves a remainder of 1 when divided by the least common multiple of the two primes each reduced by one. Signing raises a number m to the power d and keeps the remainder after division by n. Verifying raises the result to the power e, and the same m comes back. The federal signature standard asks for an odd public exponent above two to the sixteenth power, and 65537, which is one more than that, is the usual choice.

Small numbers show the whole machine. Take the primes 61 and 53, so n is 3233, and the least common multiple of 60 and 52 is 780. Choose e as 17. Then d is 413, because 17 times 413 is 7021, which is nine times 780 plus 1. To sign the number 65, compute 65 to the power 413 modulo 3233: the signature is 588. The verifier computes 588 to the power 17 modulo 3233 and gets 65 again. Anyone can do that second sum with public numbers. Only the holder of 413 could have produced 588. The walk-through in the tool above opens on exactly these numbers.

In a real token, m is not the message. It is the SHA-256 digest of the signing input, 32 octets long, placed after a short fixed prefix that names the hash and behind a run of padding octets that fills the block out to the length of the modulus. The scheme has no random part, so the same key and the same input always give the same signature. With a 2,048-bit key every signature is 256 octets, whatever the size of the token it protects.

A private key file carries five numbers beyond n, e and d: the two primes and three values derived from them. They let the signer do two half-size computations and join the results, an optimization that changes nothing about the answer. In the example they are 53, 49 and 38, and they produce 588 again. They are every bit as secret as d, since either prime gives away the rest.

Two halves with different jobs

The private half signs. The public half verifies and can do nothing else. A token service keeps one private key; every interface that receives tokens needs only the public one, and holding it gives no power to mint tokens. A browser can even make the pair itself, since the Web Cryptography interface generates keys and lets a page say whether a private key may ever be exported. A shared-secret algorithm such as HS256 cannot offer that, because the key that checks a token is the key that makes one. The access token profile recommends asymmetric signing for this practical reason: it simplifies how the receiving servers obtain what they need to validate.

The same key wears several costumes. In PEM form it is Base64 text between a BEGIN line and an END line. The label PRIVATE KEY marks the general container known as PKCS #8, PUBLIC KEY marks the matching public structure, and the older RSA PRIVATE KEY label holds the bare list of RSA numbers with no container around it. Converting between them moves the same numbers into a different wrapper. Nothing about the key changes. A private key file can also be locked with a passphrase, which the password standard stretches through many rounds of hashing, as many as the wait allows, before it becomes a cipher key.

A JSON Web Key writes those numbers as JSON instead. An RSA public key is an object whose key type is RSA with two members, n and e, each the Base64url text of the number in the fewest octets that hold it. The usual exponent, 65537, always comes out as the four characters AQAB. The specification adds a warning learned from experience: some libraries put an extra zero octet in front of the modulus, giving 257 octets for a 2,048-bit key, and that octet must be removed. A private key adds d and the five helper numbers.

A JWK Set is an object with one member, an array named keys. It is how a service publishes its public keys: the server metadata format has an entry pointing at the set, which must be served over https and which clients use to validate signatures. Private keys must be protected from disclosure to unintended parties, in the words of the key format itself, so a published set holds public members only.

The key ID and the day the key changes

When a set holds more than one key, the verifier has to pick. The header member “kid” exists for that. It is a hint about which key secured the token, it lets the signer signal a change of key explicitly, and the key format describes it as the way to choose among the keys of a set during key rollover. Keys in one set should carry different values.

The identifier can be any string, but there is a good default. The thumbprint method takes only the members a key must have, orders them by name, writes them with no white space and hashes the result. With SHA-256 the Base64url form is 43 characters. Because it is computed from the public numbers alone, anyone holding the key derives the same identifier, and the private key shares it with its public half.

Keys should not live forever. NIST recommends that a private signing key be used for about one to three years at most, and notes that the public half may stay in service longer, since signatures made earlier still need checking. The pieces above turn that into a routine. Add the new public key to the set beside the old one, start signing with the new private key under its own identifier, and remove the old public key once the last token it signed has expired.

One caution belongs here. The identifier arrives inside the token, so it is written by whoever sent the token. The best-practice guidance treats it as untrusted input: it is used for a lookup, and a lookup built carelessly from attacker-supplied text is an injection waiting to happen.

How verifiers get it wrong

The arithmetic has held up. The published attacks on tokens target the checking code, and the guidance lists them plainly. In the first, the attacker changes “alg” to “none”, which means no signature at all, and removes the third part. Some libraries trusted the header and declared the token valid. A sound verifier refuses an unsigned token unless its caller has explicitly asked for one.

The second is subtler. The attacker changes RS256 to HS256 and computes a shared-secret tag using the RSA public key as the secret. A library that lets the token choose the algorithm then verifies that tag with the very same public key, and the forgery passes, because a public key is known to everyone. The cure is a rule: the caller names the algorithms it accepts, and each key is used with exactly one. Writing the algorithm into the JWK is a simple way to pin it.

The third mistake needs no cryptography. A valid signature shows that the holder of a key wrote the token. It does not show that the key belongs to the issuer named inside, that the token was meant for this service, or that it is still current. The application must check the issuer against the keys it trusts, confirm that the audience names it, and enforce the expiry time. Without the audience check a service that honestly receives a token can replay it against another.

Signing has limits of its own, and it helps to say them aloud. It hides nothing. It cannot recall a token: among the registered claims the only controls on lifetime are times, so a token stays good until it expires. And it cannot tell an honest signer from a thief who copied the private key, which is why short token lives and regular rotation matter more than a longer modulus.

When a curve is the better key

ES256 signs with an elliptic curve named P-256 instead of RSA. The algorithm specification says elliptic curves give equivalent security with shorter keys and faster processing for many operations, and the sizes bear it out: an ES256 signature is 64 octets, two 32-octet numbers, against 256 for the smallest RSA key. NIST’s comparison table places a 256-bit curve in the same row as a 3,072-bit RSA key, at 128 bits of strength, and 2,048-bit RSA one row lower at 112.

The curve asks for something RSA does not. Every ECDSA signature needs a fresh, unpredictable number, and the guidance warns that if even a few bits of it can be predicted across messages, the private key may be recovered. RS256 uses no randomness when it signs. It is also the algorithm every conforming access token server must accept, so it remains the safe choice when the far side is unknown. ES256 is the better key when tokens must be small and both ends are under one roof.

Neither choice settles the larger matter. Making a key takes a moment. Publishing it, naming it, retiring it on schedule and refusing every token that does not check out in full is the real work, and it belongs to the verifier.