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)
    .keyIDFromThumbprint()
    .build();

Example RSA JWK with a thumbprint-based identifier:

{
  "kty" : "RSA",
  "n"   : "0vx7agoebGcQSuuPiLJXZptN9nndrQmbXEps2aiAFbWhM78LhWx4cbbfAAt
           VT86zwu1RK7aPFFxuhDR1L6tSoc_BJECPebWKRXjBZCiFV4n3oknjhMstn6
           4tZ_2W-5JsGY4Hc5n9yBXArwl93lqt7_RN5w6Cf0h4QyQ5v-65YGjQR0_FD
           W2QvzqY368QQMicAtaSqzs8KJZgnYb9c7d0zgdAZHzu6qMQvRL5hajrn1n9
           1CbOpbISD08qNLyrdkt-bFTWhAI4vMQFh6WeZu0fM4lFd2NcRwr3XPksINH
           aQ-G_xBniIqbw0Ls1jF44-csFCur-kEgU8awapJzKnqDKgw",
  "e"   : "AQAB",
  "alg" : "RS256",
  "kid" : "NzbLsXh8uDCcd-6MNwXF4W_7noWXFZAfHkxZsRGC9Xs"
}