JSON Web Key (JWK) thumbprints

JWK thumbprints are secure hashes for uniquely identifying key material. Their computation is specified in RFC 7638.

Computing JWK thumbprints

The library can compute thumbprints for all supported JWK types - RSA, EC, OKP and octet sequence (symmetric keys). The default hash algorithm is SHA-256, but you can use any other hash function that is supported by the underlying JCA provider.

To compute the SHA-256 thumbprint of an RSA key:

RSAKey rsaKey = RSAKey.parse("{ ... }");

// Produces "NzbLsXh8uDCcd-6MNwXF4W_7noWXFZAfHkxZsRGC9Xs"
Base64URL thumbprint = rsaKey.computeThumbprint();

The thumbprints are returned as a base64-url safe string.

To compute the using another hash algorith use the alternative method:

RSAKey rsaKey = RSAKey.parse("{ ... }");

Base64URL thumbprint = rsaKey.computeThumbprint("SHA-1");

Using JWK thumbprints as key identifiers

A JWK thumbprint can also be used as a key identifier which is practically guaranteed to be unique. This can have use in JWK sets where the keys are assigned IDs for roll-over purposes.

To set the SHA-256 thumbprint as the key ID:

RSAKey rsaKey = new RSAKey.Builder(mod, exp)

Example RSA JWK with a thumbprint-based identifier:

  "kty" : "RSA",
  "n"   : "0vx7agoebGcQSuuPiLJXZptN9nndrQmbXEps2aiAFbWhM78LhWx4cbbfAAt
  "e"   : "AQAB",
  "alg" : "RS256",
  "kid" : "NzbLsXh8uDCcd-6MNwXF4W_7noWXFZAfHkxZsRGC9Xs"